HtmlViewerCustomGui Class Reference

#include <customgui_htmlviewer.h>

Inheritance diagram for HtmlViewerCustomGui:

Detailed Description

Provides a custom GUI for displaying HTML content within Cinema 4D and interacting with it via JavaScript.

Note

See the py-cmd_gui_html_2027 example in the Cinema 4D Python SDK for a practical demonstration of how to use this custom GUI.

Warning

HTML viewer custom GUI cannot be used in modal dialogs.

Public Member Functions
void	ExecuteJavaScript (const maxon::String &script)
void	PostWebMessage (const maxon::String &message)
void	SetRequestHeader (const maxon::String &name, const maxon::String &value, const maxon::String &hostname, Bool httpsOnly=true)
void	SetWebMessageCallback (HtmlViewerCustomGuiWebMessageCallback *callback, const maxon::String &urlPartial, void *user_data)
void	SetUrl (const maxon::String &url, Int32 encoding)
void	SetText (const maxon::String &url)
void	DoAction (Int32 action)
void	SetURLCallback (HtmlViewerCustomGuiURLCallback *callback, void *user_data)
String	GetTextArea (const maxon::String &id)
void	SetResourceRequestInterceptCallback (HtmlViewerCustomGuiResourceRequestInterceptCallback *callback, void *user_data)
Public Member Functions inherited from BaseCustomGui< 200000114 >
Int32	GetWidth ()
Int32	GetHeight ()
void	Redraw ()
Bool	LayoutChanged ()
Bool	Activate ()
Bool	SetDefaultForResEdit ()
Bool	SetData (const TriState< GeData > &tristate)
TriState< GeData >	GetData ()
void	SetLayoutMode (Int32 mode)
Int32	GetLayoutMode ()
Bool	SupportLayoutSwitch ()
Public Member Functions inherited from _BaseCustomGui
Int32	GetWidth (Int32 plugid)
Int32	GetHeight (Int32 plugid)
void	Redraw (Int32 plugid)
Bool	LayoutChanged (Int32 plugid)
Bool	Activate (Int32 plugid)
Bool	SetDefaultForResEdit (Int32 plugid)
Bool	SetData (Int32 plugid, const TriState< GeData > &tristate)
TriState< GeData >	GetData (Int32 plugid)
void	SetLayoutMode (Int32 plugid, Int32 mode)
Int32	GetLayoutMode (Int32 plugid)
Bool	SupportLayoutSwitch (Int32 plugid)

Static Public Member Functions
static String	FilenameToURL (const Filename &f, Int32 *encoding)

Private Member Functions
	HtmlViewerCustomGui ()
	~HtmlViewerCustomGui ()

Additional Inherited Members
Static Public Attributes inherited from BaseCustomGui< 200000114 >
static constexpr Int32	VALUE

Constructor & Destructor Documentation

HtmlViewerCustomGui()

HtmlViewerCustomGui ( )

private

~HtmlViewerCustomGui()

~HtmlViewerCustomGui ( )

private

Member Function Documentation

ExecuteJavaScript()

void ExecuteJavaScript

(

const maxon::String &

script

)

Private.

Parameters

[in]

script

Private.

PostWebMessage()

void PostWebMessage

(

const maxon::String &

message

)

Posts a web message to the HTML viewer's JavaScript context.

The message is delivered to window.maxon.messageListener, the cross-platform receive hook that behaves identically on Windows and MacOS. The page assigns a function to it; the host invokes that function with the message.

Warning

We strongly recommend to only send JSON-encoded strings as messages to ensure proper parsing and handling. On MacOS, plain text messages containing double quotes, control characters, or other special characters may not be parsed correctly, leading to unexpected behavior. Sending pure alphanumeric strings will work on all platforms, for complex data structures, you must use JSON.

Note

Sending the empty string as a message is not supported and will be ignored.

// Receiving the message in the web page (same code on Windows and MacOS).
window.maxon.messageListener = (message) => {
  if (!message || typeof message !== 'string')
    return;
 
  try {
    var data = JSON.parse(message);
  }
  catch (error) {
    return;
  }
  // Do something with the data ...
};

Parameters

[in]

message

The message to send to JavaScript. Cannot be the empty string. We strongly recommend to send JSON-encoded strings to ensure proper parsing and handling.

SetRequestHeader()

void SetRequestHeader	(	const maxon::String &	name,
		const maxon::String &	value,
		const maxon::String &	hostname,
		Bool	httpsOnly = true
	)

Sets an HTTP request header that is injected on requests to hostname.

Any HTTP request header can be set this way, be it a standard one (e.g. "Accept-Language") or an application-specific one. Set it before navigating with SetUrl(). Call the function repeatedly to register several headers. Calling it again for the same name (case-insensitive) and hostname replaces the previously registered value; there is no way to unregister a header.

Note

The header is applied to main-frame navigations only, i.e. to top-level document loads, and not to the sub-resource or API requests the loaded page issues (images, scripts, fetch/XHR, ...). A page that needs a header on its own API requests has to set it in JavaScript.

On macOS the header is applied to plain page loads only, and not to form submissions, reloads, or back/forward navigation. Windows has no such restriction.

Registered headers are discarded when the viewer's window is destroyed (e.g. a layout switch), so set them again from the dialog's InitValues().

This function is not implemented on Linux (no-op).

Parameters

[in]	name	The header name, e.g. "Accept-Language".
[in]	value	The header value, e.g. "de-DE".
[in]	hostname	The host the header applies to, e.g. "example.com". Required; bare host only, no scheme, port or path. Matched exactly and case-insensitively, so a subdomain like "api.example.com" needs its own registration.
[in]	httpsOnly	Send the header only over HTTPS. Default is true; pass false for a host served over plain HTTP, e.g. a local development server.

Warning

The header is sent on every navigation to hostname, including those the page triggers itself.

SetWebMessageCallback()

void SetWebMessageCallback	(	HtmlViewerCustomGuiWebMessageCallback *	callback,
		const maxon::String &	urlPartial,
		void *	user_data
	)

Sets a callback for web messages sent from the HTML viewer's JavaScript context.

The callback is triggered when JavaScript calls window.maxon.postMessage(msg):

function postMessage(payload) {
  window.maxon.postMessage(payload);
};

Parameters

[in]	callback	The callback function to handle web messages.
[in]	urlPartial	A partial URL to filter which messages trigger the callback.
[in]	user_data	User data pointer passed to the callback.

SetUrl()

void SetUrl	(	const maxon::String &	url,
		Int32	encoding
	)

Sets the HTML viewer URL.

Parameters

[in]	url	The new URL.
[in]	encoding	The URL encoding: URL_ENCODING

SetText()

void SetText

(

const maxon::String &

url

)

Sets the HTML viewer text.

Parameters

[in]

url

The new text.

DoAction()

void DoAction

(

Int32

action

)

Do an action in the HTML viewer.

Parameters

[in]

action

The action: WEBPAGE

SetURLCallback()

void SetURLCallback	(	HtmlViewerCustomGuiURLCallback *	callback,
		void *	user_data
	)

Registers the URL callback.

Parameters

[in]	callback	The callback, or nullptr to disable it.
[in]	user_data	The user data. The caller owns the pointed data.

GetTextArea()

String GetTextArea

(

const maxon::String &

id

)

Deprecated. Always return an empty string.

FilenameToURL()

static String FilenameToURL ( const Filename &  f, Int32 *  encoding  )

static

Converts a filename into an URL string.

Parameters

[in]	f	The filename.
[out]	encoding	Assigned the URL encoding: URL_ENCODING

Returns

The URL of the filename.

SetResourceRequestInterceptCallback()

void SetResourceRequestInterceptCallback	(	HtmlViewerCustomGuiResourceRequestInterceptCallback *	callback,
		void *	user_data
	)

Registers the resource request interception callback.

Parameters

[in]	callback	The callback, or nullptr to disable it.
[in]	user_data	The user data. The caller owns the pointed data.