用於渲染 HTML 網頁並與其互動之介面。

您可直接在您的遊戲或應用程式中使用此介面來渲染並顯示 HTML 頁面。 使用此介面前必須呼叫 Init，使用結束後則呼叫 Shutdown。

此 API 建立在 Chromium 嵌入式架構之上，並支援 HTML5 標記。

詳細資訊請參閱 Steam HTML Surface 一文。

成員函式

ISteamHTMLSurface 的成員函式可透過全域存取子函式 SteamHTMLSurface() 呼叫。

AddHeader

名稱	型別	說明
unBrowserHandle	HHTMLBrowser	要新增標題的 Surface 的控制代碼。
pchKey	const char *	要新增的標題名稱。
pchValue	const char *	要與索引碼關聯的標題值。

為來自此瀏覽器的任何 HTTP 請求新增標題。

如果需要標準請求欄位的列表，請參閱 Wikipedia。

AllowStartRequest

名稱	型別	說明
unBrowserHandle	HHTMLBrowser	正在導向的 Surface 的控制代碼。
bAllowed	bool	允許或拒絕前往目前的開始請求。

設定是否允許或取消待處理的載入。
可使用此功能來限制您 HTML Surface 中允許的有效頁面數。

CopyToClipboard

名稱	型別	說明
unBrowserHandle	HHTMLBrowser	要從中複製文字的 Surface 的控制代碼。

從 HTML surface 中的目前頁面將選取的文字複製到本機剪貼簿。

CreateBrowser

名稱	型別	說明
pchUserAgent	const char *	將字串附加至瀏覽器的一般使用者代理程式字串，允許您在網頁伺服器上偵測您的用戶端。 如果不需要此功能，則使用 NULL。
pchUserCSS	const char *	這允許您將此瀏覽器顯式的每個頁面設定為 CSS 樣式。 如果不需要此功能，則使用 NULL。

為顯示一個 HTML 頁面建立一個瀏覽其物件。
您可能需要呼叫 SetSize 和 LoadURL 以開始使用您的顯示 Surface。

傳回： 用於 HTML_BrowserReady_t 呼叫結果的 SteamAPICall_t。

ExecuteJavascript

名稱	型別	說明
unBrowserHandle	HHTMLBrowser	正在導向的 Surface 的控制代碼。
pchScript	const char *	要執行的 JavaScript 指令碼。

在目前已載入的頁面執行 JavaScript 指令碼。

FileLoadDialogResponse

名稱	型別	說明
unBrowserHandle	HHTMLBrowser	要叫出開啟檔案對話方塊的 Surface 的控制代碼。
pchSelectedFiles	const char **	應為使用者所選擇的檔案的絕對檔案路徑陣列。 若使用者未選擇任何檔案，則為 NULL。

讓您對要開啟下載檔案對話方塊的頁面做出回應。

Find

名稱	型別	說明
unBrowserHandle	HHTMLBrowser	要在其中找到字串的 Surface 的控制代碼。
pchSearchStr	const char *	要搜尋的字串。
bCurrentlyInFind	bool	在後續呼叫中將此設為 true，才能找到下一個相符的字串。
bReverse	bool	從下往上搜尋嗎？

在 HTML Surface 的目前頁面尋找字串。

這在您選擇的瀏覽器中相當於「ctrl+f」。 將凸顯所有相符的字串。

當輸入的字串已改變或您想停止搜尋時，應呼叫 StopFind。

傳回： void
觸發 HTML_SearchResults_t 回呼。

GetLinkAtPosition

名稱	型別	說明
unBrowserHandle	HHTMLBrowser	要從中取得連結的 Surface 的控制代碼。
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 EMouseCursor 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.

EMouseCursor

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

Name	Value	Description
dc_user	0
dc_none	1
dc_arrow	2
dc_ibeam	3
dc_hourglass	4
dc_waitarrow	5
dc_crosshair	6
dc_up	7
dc_sizenw	8
dc_sizese	9
dc_sizene	10
dc_sizesw	11
dc_sizew	12
dc_sizee	13
dc_sizen	14
dc_sizes	15
dc_sizewe	16
dc_sizens	17
dc_sizeall	18
dc_no	19
dc_hand	20
dc_blank	21	Don't show any custom cursor, just use your default.
dc_middle_pan	22
dc_north_pan	23
dc_north_east_pan	24
dc_east_pan	25
dc_south_east_pan	26
dc_south_pan	27
dc_south_west_pan	28
dc_west_pan	29
dc_north_west_pan	30
dc_alias	31
dc_cell	32
dc_colresize	33
dc_copycur	34
dc_verticaltext	35
dc_rowresize	36
dc_zoomin	37
dc_zoomout	38
dc_help	39
dc_custom	40
dc_last	41	Only used to iterate over all cursors. Custom cursors start from this value and up.

Typedefs

以下為定義來用於 ISteamHTMLSurface 中的 typedefs 。

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

Constants

以下為定義來用於 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"