Interface for rendering and interacting with HTML pages.

You can use this interface to render and display HTML pages directly inside your game or application. You must call Init prior to using this interface, and Shutdown when you're done using it.

It is built upon the Chromium Embedded Framework and supports HTML5 markup.

See Steam HTML Surface for more information.

Member Functions

Member functions for ISteamHTMLSurface are called through the global accessor function SteamHTMLSurface().

AddHeader

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface to add the header to.
pchKey	const char *	The header name to add.
pchValue	const char *	The header value to associate with the key.

Add a header to any HTTP requests from this browser.

A full list of standard request fields are available here on wikipedia.

AllowStartRequest

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface that is navigating.
bAllowed	bool	Allow or deny the navigation to the current start request.

Sets whether a pending load is allowed or if it should be canceled.
You can use this feature to limit the valid pages allowed in your HTML surface.

CopyToClipboard

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface to copy the text from.

Copy the currently selected text from the current page in an HTML surface into the local clipboard.

CreateBrowser

Name	Type	Description
pchUserAgent	const char *	Appends the string to the general user agent string of the browser, allowing you to detect your client on webservers. Use NULL if you do not require this functionality.
pchUserCSS	const char *	This allows you to set a CSS style to every page displayed by this browser. Use NULL if you do not require this functionality.

Create a browser object for displaying of an HTML page.
You will want to call SetSize and LoadURL to start using your display surface.

Returns: SteamAPICall_t to be used with a HTML_BrowserReady_t call result.

ExecuteJavascript

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface that is navigating.
pchScript	const char *	The javascript script to run.

Run a javascript script in the currently loaded page.

FileLoadDialogResponse

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface that wants to spawn a file open dialog.
pchSelectedFiles	const char **	This should be an array of absolute file paths to the files that the user has selected. NULL if the user did not select any files.

Allows you to react to a page wanting to open a file load dialog.

Find

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface to find the string in.
pchSearchStr	const char *	The string to search for.
bCurrentlyInFind	bool	Set this to true on subsequent calls to cycle through to the next matching string.
bReverse	bool	Search from the bottom up?

Find a string in the current page of an HTML surface.

This is the equivalent of "ctrl+f" in your browser of choice. It will highlight all of the matching strings.

You should call StopFind when the input string has changed or you want to stop searching.

Returns: void
Triggers a HTML_SearchResults_t callback.

GetLinkAtPosition

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface to get a link from.
x	int	The X (width) position in pixels within the surface. (0, 0) is the top left corner.
y	int	The Y (height) position in pixels within the surface. (0, 0) is the top left corner.

Retrieves details about a link at a specific position on the current page in an HTML surface.

Returns: void
Triggers a HTML_LinkAtPosition_t callback.

GoBack

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface to navigate back on.

Navigate back in the page history.

GoForward

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface to navigate forward on.

Navigate forward in the page history

Init

Initializes the HTML Surface API.

This must be called prior to using any other functions in this interface.

You MUST call Shutdown when you are done using the interface to free up the resources associated with it. Failing to do so will result in a memory leak!

Returns: bool
true if the API was successfully initialized; otherwise, false.

JSDialogResponse

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface that is spawning a dialog.
bResult	bool	Set this to true to simulate pressing the "OK" button, otherwise false for "Cancel".

Allows you to react to a page wanting to open a javascript modal dialog notification.

KeyChar

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface to send the interaction to.
cUnicodeChar	uint32	The unicode character point for this keypress; and potentially multiple characters per press.
eHTMLKeyModifiers	EHTMLKeyModifiers	This should be set to a bitmask of the modifier keys that the user is currently pressing.

cUnicodeChar is the unicode character point for this keypress (and potentially multiple chars per press)

KeyDown

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface to send the interaction to.
nNativeKeyCode	uint32	This is the virtual keycode value from the OS.
eHTMLKeyModifiers	EHTMLKeyModifiers	This should be set to a bitmask of the modifier keys that the user is currently pressing.

keyboard interactions, native keycode is the virtual key code value from your OS

KeyUp

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface to send the interaction to.
nNativeKeyCode	uint32	This is the virtual keycode value from the OS.
eHTMLKeyModifiers	EHTMLKeyModifiers	This should be set to a bitmask of the modifier keys that the user is currently pressing.

LoadURL

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface to load this URL in.
pchURL	const char *	The URL to load.
pchPostData	const char *	Optionally send a POST request with this data, set this to NULL to not send any data.

Navigate to a specified URL.

If you send POST data with pchPostData then the data should be formatted as: name1=value1&name2=value2.

You can load any URI scheme supported by Chromium Embedded Framework including but not limited to: http://, https://, ftp://, and file:///. If no scheme is specified then http:// is used.

Returns: void
Triggers a HTML_StartRequest_t callback.

MouseDoubleClick

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface to send the interaction to.
eMouseButton	EHTMLMouseButton	The mouse button which was double clicked.

Tells an HTML surface that a mouse button has been double clicked.

The click will occur where the surface thinks the mouse is based on the last call to MouseMove.

MouseDown

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface to send the interaction to.
eMouseButton	EHTMLMouseButton	The mouse button which was pressed.

Tells an HTML surface that a mouse button has been pressed.

The click will occur where the surface thinks the mouse is based on the last call to MouseMove.

MouseMove

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface to send the interaction to.
x	int	X (width) coordinate in pixels relative to the position of the HTML surface. (0, 0) is the top left.
y	int	Y (height) coordinate in pixels relative to the position of the HTML surface. (0, 0) is the top left.

Tells an HTML surface where the mouse is.

MouseUp

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface to send the interaction to.
eMouseButton	EHTMLMouseButton	The mouse button which was released.

Tells an HTML surface that a mouse button has been released.

The click will occur where the surface thinks the mouse is based on the last call to MouseMove.

MouseWheel

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface to send the interaction to.
nDelta	int32	The number of pixels to scroll.

Tells an HTML surface that the mouse wheel has moved.

PasteFromClipboard

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface to paste into.

Paste from the local clipboard to the current page in an HTML surface.

Reload

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface to reload.

Refreshes the current page.

The reload will most likely hit the local cache instead of going over the network. This is equivalent to F5 or Ctrl+R in your browser of choice.

RemoveBrowser

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The browser handle to release.

You MUST call this when you are done with an HTML surface, freeing the resources associated with it.

Failing to call this will result in a memory leak!

SetBackgroundMode

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface set background mode on.
bBackgroundMode	bool	Toggle background mode on or off.

Enable/disable low-resource background mode, where javascript and repaint timers are throttled, resources are more aggressively purged from memory, and audio/video elements are paused.

When background mode is enabled, all HTML5 video and audio objects will execute ".pause()" and gain the property "._steam_background_paused = 1".
When background mode is disabled, any video or audio objects with that property will resume with ".play()".

SetCookie

Name	Type	Description
pchHostname	const char *	The hostname of the server to set the cookie for. ('Host' attribute)
pchKey	const char *	The cookie name to set.
pchValue	const char *	The cookie value to set.
pchPath	const char *	Sets the 'Path' attribute on the cookie. You can use this to restrict the cookie to a specific path on the domain. e.g. "/accounts"
nExpires	RTime32	Sets the 'Expires' attribute on the cookie to the specified timestamp in Unix epoch format (seconds since Jan 1st 1970).
bSecure	bool	Sets the 'Secure' attribute.
bHTTPOnly	bool	Sets the 'HttpOnly' attribute.

Set a webcookie for a specific hostname.

You can read more about the specifics of setting cookies here on wikipedia.

SetHorizontalScroll

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface to set the horizontal scroll position.
nAbsolutePixelScroll	uint32	The absolute pixel position to scroll to. 0 is the left and HTML_HorizontalScroll_t.unScrollMax is the right side.

Scroll the current page horizontally.

Returns: void
Triggers a HTML_HorizontalScroll_t callback.


See Also: HTML_HorizontalScroll_t, SetVerticalScroll, HTML_VerticalScroll_t

SetKeyFocus

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface to set key focus on.
bHasKeyFocus	bool	Turn key focus on or off?

Tell a HTML surface if it has key focus currently, controls showing the I-beam cursor in text controls amongst other things.

SetPageScaleFactor

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface to scale.
flZoom	float	The amount to zoom, this can range from 1 (100% and the default) to 2 (200%).
nPointX	int	The X point in pixels to zoom around. Use 0 if you don't care.
nPointY	int	The Y point in pixels to zoom around. Use 0 if you don't care.

Zoom the current page in an HTML surface.

The current scale factor is available from HTML_NeedsPaint_t.flPageScale, HTML_HorizontalScroll_t.flPageScale, and HTML_VerticalScroll_t.flPageScale.

SetSize

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface to set the size of.
unWidth	uint32	The width of the surface in pixels.
unHeight	uint32	The height of the surface in pixels.

Sets the display size of a surface in pixels.

SetVerticalScroll

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface to set the vertical scroll position.
nAbsolutePixelScroll	uint32	The absolute pixel position to scroll to. 0 is the top and HTML_VerticalScroll_t.unScrollMax is the bottom.

Scroll the current page vertically.

Returns: void
Triggers a HTML_VerticalScroll_t callback.


See Also: HTML_VerticalScroll_t, SetHorizontalScroll, HTML_HorizontalScroll_t

Shutdown

Shutdown the ISteamHTMLSurface interface, releasing the memory and handles.

You MUST call this when you are done using this interface to prevent memory and handle leaks. After calling this then all of the functions provided in this interface will fail until you call Init to reinitialize again.

Returns: bool
This function currently always returns true.

StopFind

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface to stop the find results.

Cancel a currently running find.

See Also: Find

StopLoad

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface to stop loading.

Stop the load of the current HTML page.

ViewSource

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface to view its current pages source.

Open the current pages HTML source code in default local text editor, used for debugging.

Callbacks

These are callbacks which can be fired by calling SteamAPI_RunCallbacks. Many of these will be fired directly in response to the member functions of ISteamHTMLSurface.

HTML_BrowserReady_t

A new browser was created and is ready for use.

Name	Type	Description
unBrowserHandle	HHTMLBrowser	This is the handle to the browser that was just created, which you can use with future calls to ISteamHTMLSurface.

Associated Functions: CreateBrowser

HTML_CanGoBackAndForward_t

Called when page history status has changed the ability to go backwards and forward.

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface that this callback is for.
bCanGoBack	bool	Returns whether you can navigate backwards.
bCanGoForward	bool	Returns whether you can navigate forward.

HTML_ChangedTitle_t

Called when the current page in a browser gets a new title.

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface that this callback is for.
pchTitle	const char *	The new title of the page.

HTML_CloseBrowser_t

Called when the browser has been requested to close due to user interaction; usually because of a javascript window.close() call.

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface that this callback is for.

HTML_FileOpenDialog_t

Called when a browser surface has received a file open dialog from a <input type="file"> click or similar, you must call FileLoadDialogResponse with the file(s) the user selected.

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface that is navigating.
pchTitle	const char *	The name of the dialog. (eg. "Upload Images")
pchInitialFile	const char *	The filename that the page wants you to set by default. It may be expecting a file with that name or that was the file the user previously uploaded.

HTML_FinishedRequest_t

Called when a browser has finished loading a page.

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface that this call was for.
pchURL	const char *	The URL that was loaded.
pchPageTitle	const char *	The title of the page that got loaded.

HTML_HideToolTip_t

Called when a a browser wants to hide a tooltip.

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface that this callback is for.

HTML_HorizontalScroll_t

Provides details on the visibility and size of the horizontal scrollbar.

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface that this callback is for.
unScrollMax	uint32	The maximum amount you can scroll horizontally.
unScrollCurrent	uint32	The current horizontal scroll position.
flPageScale	float	The current page scale.
bVisible	bool	Whether the horizontal scrollbar is visible.
unPageSize	uint32	The total width of the page in pixels.

Associated Functions: SetHorizontalScroll

HTML_JSAlert_t

Called when the browser wants to display a Javascript alert dialog, call JSDialogResponse when the user dismisses this dialog; or right away to ignore it.

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface that this call was for.
pchMessage	const char *	The message associated with the dialog.

HTML_JSConfirm_t

Called when the browser wants to display a Javascript confirmation dialog, call JSDialogResponse when the user dismisses this dialog; or right away to ignore it.

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface that this call was for.
pchMessage	const char *	The message associated with the dialog.

HTML_LinkAtPosition_t

Result of a call to GetLinkAtPosition

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface that this call was for.
x	uint32	Unused.
y	uint32	Unused.
pchURL	const char *	The URL found at this position. NULL if no link was found.
bInput	bool	Was the position an input field?
bLiveLink	bool

Associated Functions: GetLinkAtPosition

HTML_NeedsPaint_t

Called when a browser surface has a pending paint. This is where you get the actual image data to render to the screen.

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface that this callback is for.
pBGRA	const char *	A pointer to the B8G8R8A8 image data for this surface, valid until SteamAPI_RunCallbacks is next called.
unWide	uint32	The total width of the pBGRA texture.
unTall	uint32	The total height of the pBGRA texture.
unUpdateX	uint32	The offset in X for the damage rect for this update.
unUpdateY	uint32	The offset in Y for the damage rect for this update.
unUpdateWide	uint32	The width of the damage rect for this update.
unUpdateTall	uint32	The height of the damage rect for this update.
unScrollX	uint32	The horizontal scroll position the browser was at when this texture was rendered.
unScrollY	uint32	The veritcal scroll position the browser was at when this texture was rendered.
flPageScale	float	The scale factor the browser was at when this texture was rendered.
unPageSerial	uint32	Incremented on each new page load, you can use this to reject draws while navigating to new pages.

HTML_NewWindow_t

A browser has created a new HTML window.

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface that this callback is for.
pchURL	const char *	The URL to load in the new window.
unX	uint32	The x pos into the page to display the popup.
unY	uint32	The y pos into the page to display the popup.
unWide	uint32	The total width of the pBGRA texture.
unTall	uint32	The total height of the pBGRA texture.
unNewWindow_BrowserHandle	HHTMLBrowser	The handle of the new window surface.

HTML_OpenLinkInNewTab_t

The browser has requested to load a url in a new tab.

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface that this callback is for.
pchURL	const char *	The URL that the browser wants to load.

HTML_SearchResults_t

Results from a search.

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface that this callback is for.
unResults	uint32	The number of matching results found.
unCurrentMatch	uint32	The ordinal of the current match relative to unResults.

Associated Functions: Find

HTML_SetCursor_t

Called when a browser wants to change the mouse cursor.

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface that this callback is for.
eMouseCursor	uint32	The EHTMLMouseCursor to display.

HTML_ShowToolTip_t

Called when a browser wants to display a tooltip.

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface that this callback is for.
pchMsg	const char *	The text of the tooltip that wants to be displayed.

HTML_StartRequest_t

Called when a browser wants to navigate to a new page.

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface that is navigating.
pchURL	const char *	The url it wants to navigate to.
pchTarget	const char *	The html link target type (i.e _blank, _self, _parent, _top ).
pchPostData	const char *	Any posted data for the request.
bIsRedirect	bool	True if this was a http/html redirect from the last load request.

Associated Functions: LoadURL

HTML_StatusText_t

Called when a browser wants you to display an informational message. This is most commonly used when you hover over links.

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface that this callback is for.
pchMsg	const char *	The text of the status message to display.

HTML_UpdateToolTip_t

Called when the text of an existing tooltip has been updated.

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface that this callback is for.
pchMsg	const char *	The new text of the tooltip.

HTML_URLChanged_t

Called when the browser is navigating to a new url

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface that this callback is for.
pchURL	const char *	The url that the browser is navigating to.
pchPostData	const char *	Any posted data for the request, NULL if there was none.
bIsRedirect	bool	true if this was a http/html redirect from the last load request, otherwise false.
pchPageTitle	const char *	The title of the page.
bNewNavigation	bool	This is true if the page has changed rather than just a call to the browser history API.

HTML_VerticalScroll_t

Provides details on the visibility and size of the vertical scrollbar.

Name	Type	Description
unBrowserHandle	HHTMLBrowser	The handle of the surface that this callback is for.
unScrollMax	uint32	The maximum amount you can scroll vertically.
unScrollCurrent	uint32	The current vertical scroll position.
flPageScale	float	The current page scale.
bVisible	bool	Whether the vertical scrollbar is visible.
unPageSize	uint32	The total height of the page in pixels.

Associated Functions: SetVerticalScroll

Enums

These are enums which are defined for use with ISteamHTMLSurface.

EHTMLKeyModifiers

Used to let the browser know what keys are pressed with: KeyChar, KeyUp and KeyDown. These flags can be added together using bitwise OR.

Name	Value	Description
k_eHTMLKeyModifier_None	0	No modifiers are pressed.
k_eHTMLKeyModifier_AltDown	1 << 0	One of the alt keys are pressed.
k_eHTMLKeyModifier_CtrlDown	1 << 1	One of the ctrl keys are pressed.
k_eHTMLKeyModifier_ShiftDown	1 << 2	One of the shift keys are pressed.

EHTMLMouseButton

Used to let the browser know when a mouse button is pressed with: MouseUp, MouseDown and MouseDoubleClick.

Name	Value	Description
eHTMLMouseButton_Left	0	The left button is pressed.
eHTMLMouseButton_Right	1	The right button is pressed.
eHTMLMouseButton_Middle	2	The middle button is pressed.

EHTMLMouseCursor

This lists the mouse cursors that the HTML surface will tell you to render.

Name	Value	Description
k_EHTMLMouseCursor_SizeNESW	0
k_EHTMLMouseCursor_None	1
k_EHTMLMouseCursor_Arrow	2
k_EHTMLMouseCursor_IBeam	3
k_EHTMLMouseCursor_Hourglass	4
k_EHTMLMouseCursor_WaitArrow	5
k_EHTMLMouseCursor_Crosshair	6
k_EHTMLMouseCursor_Up	7
k_EHTMLMouseCursor_SizeNW	8
k_EHTMLMouseCursor_SizeSE	9
k_EHTMLMouseCursor_SizeNE	10
k_EHTMLMouseCursor_SizeSW	11
k_EHTMLMouseCursor_SizeW	12
k_EHTMLMouseCursor_SizeE	13
k_EHTMLMouseCursor_SizeN	14
k_EHTMLMouseCursor_SizeS	15
k_EHTMLMouseCursor_SizeWE	16
k_EHTMLMouseCursor_SizeNS	17
k_EHTMLMouseCursor_SizeAll	18
k_EHTMLMouseCursor_No	19
k_EHTMLMouseCursor_Hand	20
k_EHTMLMouseCursor_Blank	21	Don't show any custom cursor, just use your default.
k_EHTMLMouseCursor_MiddlePan	22
k_EHTMLMouseCursor_NorthPan	23
k_EHTMLMouseCursor_NorthEastPan	24
k_EHTMLMouseCursor_EastPan	25
k_EHTMLMouseCursor_SouthEastPan	26
k_EHTMLMouseCursor_SouthPan	27
k_EHTMLMouseCursor_SouthWestPan	28
k_EHTMLMouseCursor_WestPan	29
k_EHTMLMouseCursor_NorthWestPan	30
k_EHTMLMouseCursor_Alias	31
k_EHTMLMouseCursor_Cell	32
k_EHTMLMouseCursor_ColResize	33
k_EHTMLMouseCursor_CopyCur	34
k_EHTMLMouseCursor_VerticalText	35
k_EHTMLMouseCursor_RowResize	36
k_EHTMLMouseCursor_ZoomIn	37
k_EHTMLMouseCursor_ZoomOut	38
k_EHTMLMouseCursor_Help	39
k_EHTMLMouseCursor_Custom	40
k_EHTMLMouseCursor_SizeNWSE	41
k_EHTMLMouseCursor_SizeNESW	42
k_EHTMLMouseCursor_last	43	Only used to iterate over all cursors. Custom cursors start from this value and up.

Typedefs

These are typedefs which are defined for use with ISteamHTMLSurface.

Name	Base type	Description
HHTMLBrowser	uint32	Represents a unique handle to an HTML surface.

Constants

These are constants which are defined for use with ISteamHTMLSurface.

Name	Type	Value	Description
INVALID_HTMLBROWSER	uint32	0	Indicates that a browser handle is invalid. You should initialize your own HHTMLBrowser handles to this value and then set it back to this when the page closes.
STEAMHTMLSURFACE_INTERFACE_VERSION	const char *	"STEAMHTMLSURFACE_INTERFACE_VERSION_003"