adobe::metrics Namespace Reference

Functions
extents_t	compose_measurements (const SIZE *widget_size, const MARGINS *widget_margins, const TEXTMETRIC *font_metrics, const RECT *text_extents, const int *border)
void	draw_parent_background (HWND window, HDC dc)
bool	get_button_text_margins (int widget_type, RECT &out_margins)
bool	get_font (int widget_type, LOGFONTW &out_font)
bool	get_font_metrics (int widget_type, TEXTMETRIC &out_metrics)
bool	get_integer (int widget_type, int measurement, int &out_val)
bool	get_margins (int widget_type, MARGINS &out_margins)
bool	get_size (int widget_type, THEMESIZE measurement, SIZE &out_size)
bool	get_text_extents (int widget_type, std::wstring text, RECT &out_extents, const RECT *in_extents=NULL)
extents_t	measure (HWND window, int platform_placeable_type)
extents_t	measure_text (const std::string &text, HWND window, int platform_placeable_type)
void	set_theme_name (const WCHAR *theme_name)
bool	set_window (HWND window)
bool	using_styles ()

---

Detailed Description

The adobe::metrics suite of functions can fetch information on ideal widget sizes. The design of this suite is to provide simple metric and text information for a particular widget, and require clients of the function suite to compose the metrics information in a way that is meaningful for them.

All of the functions which return metrics require the widget type and state of the widget. A table of all the part and state names is available in the "Parts and States" documentation here: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/shellcc/platform/commctls/userex/topics/partsandstates.asp

---

Function Documentation

extents_t adobe::metrics::compose_measurements	(	const SIZE *	widget_size,
		const MARGINS *	widget_margins,
		const TEXTMETRIC *	font_metrics,
		const RECT *	text_extents,
		const int *	border
	)

This function uses the given metrics to calculate the optimal bounds of a widget. This code isn't in metrics::measure because some controls need to do a little more work to get the correct metrics (e.g.: popups have a list of text which it needs space for, so it will have to get the text extents for all of its items and pass the longest width extent to this function).

If any of the arguments which this function takes are unknown (i.e.: metrics_t wouldn't return a value) then pass NULL.

Parameters:

widget_size	the size of the widget, reported by metrics_t::get_size.
widget_margins	the margins of the widget, reported by metrics_t::get_margins.
font_metrics	the metrics of the font used by this widget, reported by metrics_t::get_font_metrics.
text_extents	the extents of the text in the widget, reported by metrics_t::get_text_extents.
border	the border of the widget, reported by metrics_t::get_integer.

Returns:

the optimal bounds for this widget, based on the given information.

void adobe::metrics::draw_parent_background	(	HWND	window,
		HDC	dc
	)

Use the current style to draw the background of the parent control of the given window using the given DC. This function is useful for drawing the background of controls which appear on top of tab controls, or other places where the color isn't regulation.

Parameters:

window	the window to draw the parent background of.
dc	the DC to draw with. This DC does not have to be drawing onto the given window.

bool adobe::metrics::get_button_text_margins	(	int	widget_type,
		RECT &	out_margins
	)

Get the text margins for a button widget. This call is specific to a button widget, but is only available with Visual Styles on Windows XP (hence is grouped in with the other metrics functions of similar availability).

Parameters:

widget_type	the UXTheme type of button
out_margins	a rectangle containing the margins

Returns:

true if the margins were returned successfully, false if the margins could not be found.

bool adobe::metrics::get_font	(	int	widget_type,
		LOGFONTW &	out_font
	)

Get the correct font to use for the given widget. This font must be used for the font metrics to be correct.

Parameters:

widget_type	the type of the widget.
out_font	a reference filled with the requested font.

Returns:

true if the font was returned successfully, false if the font could not be returned.

bool adobe::metrics::get_font_metrics	(	int	widget_type,
		TEXTMETRIC &	out_metrics
	)

Get the metrics for the font which should be used in the given widget.

Parameters:

widget_type	the type of the widget.
out_metrics	a reference filled with the text metrics.

Returns:

true if the font metrics were returned successfully, false if the metrics could not be returned.

bool adobe::metrics::get_integer	(	int	widget_type,
		int	measurement,
		int &	out_val
	)

Get the specified measurement for the given widget when in the given state.

Parameters:

widget_type	the type of the widget.
measurement	the required measurement.
out_val	a reference filled with the requested value.

Returns:

true if the value was returned successfully, false if the value could not be found.

bool adobe::metrics::get_margins	(	int	widget_type,
		MARGINS &	out_margins
	)

Get the margins for the specified widget. Typically the margins describe space which must be added around the text rectangle for controls with a caption.

Parameters:

widget_type	the type of the widget.
out_margins	a reference filled with the margins of the widget.

Returns:

true if the margins were returned successfully, false if the margins could not be found.

bool adobe::metrics::get_size	(	int	widget_type,
		THEMESIZE	measurement,
		SIZE &	out_size
	)

Get the size of the specified widget.

Parameters:

widget_type	the type of the widget.
measurement	the size to get: TS_MIN, TS_TRUE, or TS_DRAW.
out_size	a reference filled with the requested rectangle.

Returns:

true if the rectangle was returned successfully, false if the rectangle could not be found.

bool adobe::metrics::get_text_extents	(	int	widget_type,
		std::wstring	text,
		RECT &	out_extents,
		const RECT *	in_extents = NULL
	)

Get the extents for the given text string, to be contained in the specified widget.

Parameters:

widget_type	the type of the widget.
text	the string to return the extents for.
out_extents	a reference filled with the text extents.

Returns:

true if the text extents were returned successfully, false if the metrics could not be returned.

extents_t adobe::metrics::measure	(	HWND	window,
		int	platform_placeable_type
	)

Measure the window (given a platform placeable type) and return the optimal extents. See the "Parts and States" documentation for more information on the platform placeable type. Takes the name of the window into consideration when measuring.

extents_t adobe::metrics::measure_text	(	const std::string &	text,
		HWND	window,
		int	platform_placeable_type
	)

Measure text (given a window and platform placeable type) and return the optimal extents. See the "Parts and States" documentation for more information on the platform placeable type. Takes the text passed in lieu of the name of the window into consideration when measuring.

void adobe::metrics::set_theme_name

(

const WCHAR *

theme_name )

Before any of the other functions can be called, the theme name must be set. Alternatively, set_window can be used.

Parameters:

the	name of the theme to use.

bool adobe::metrics::set_window

(

HWND

window )

Before any of the other functions can be called, the theme data must be loaded from the window. This function should also be called any time the window recieves a WM_THEMECHANGED message. Alternatively, set_theme_name can be used.

Parameters:

window

the window to get the theme from. Note that it is not important which window is used, it does not have to be the same window every time.

Returns:

true if the theme was obtained from the window, false if the theme could not be obtained from the window.

bool adobe::metrics::using_styles

(

)

Return true if visual styles are currently in use, false if they are not being used.

Returns:

true if visual styles are in use, false otherwise.