mCtrl/html.h File Reference

HTML control (MC_WC_HTML). More...

Go to the source code of this file.

Data Structures
struct	MC_NMHTMLURLW
	Structure used for some HTML control notifications (unicode variant). More...
struct	MC_NMHTMLURLA
	Structure used for some HTML control notifications (ANSI variant). More...
Defines
#define	MC_NMHTMLURL   MC_NMHTMLURLW
	Unicode-resolution alias.
Window Class
#define	MC_WC_HTMLW   L"mCtrl.html"
	Window class name (unicode variant).
#define	MC_WC_HTMLA   "mCtrl.html"
	Window class name (ANSI variant).
#define	MC_WC_HTML   MC_WC_HTMLW
	Unicode-resolution alias.
Control Styles
#define	MC_HS_NOCONTEXTMENU   (0x00000001L)
	Disables context menu.
Control Messages
#define	MC_HM_GOTOURLW   (WM_USER + 10)
	Displays a contents specified by the given URL (unicode variant).
#define	MC_HM_GOTOURLA   (WM_USER + 11)
	Displays a contents specified by the given URL (ANSI variant).
#define	MC_HM_GOTOURL   MC_HM_GOTOURLW
	Unicode-resolution alias.
Control Notifications
#define	MC_HN_APPLINK   ((0U-2000U) + 0x0001)
	Fired when the browser should navigates to to URL with application protocol.
#define	MC_HN_DOCUMENTCOMPLETE   ((0U-2000U) + 0x0002)
	Fired when loading of a document is complete.
Functions
BOOL MCTRL_API	mcHtml_Initialize (void)
	Registers window class of the HTML control.
void MCTRL_API	mcHtml_Terminate (void)
	Unregisters window class of the HTML control.

---

Detailed Description

HTML control (MC_WC_HTML).

As the control name suggests, the control displays a HTML documents. In fact the control embeds Internet Explorer in it, so it can display a plethory of multimedia files, use javascript etc. The easiest way how to show some HTML is to specify URL of target document as control's window name. For example when created with CreateWindow(), use the 2nd argument as the URL. This allows easy use of the control in dialog templates.

URL can also be set anytime later with message MC_HM_GOTOURL.

The control accepts any protocol understood by the Internet Explorer, for example:

• http://www.example.org
• file://C:/page.html
• res://some_dll/id_of_resource
• its:helpFile.chm::page.htm

Resource Protocol

The res: protocol is especially useful. It allows you to embed some resources like HTML pages, cascading stylesheets (CSS), images (PNG, JPG etc.), javascripts into binary of your application or any DLL it uses.

The resource must be of type RT_HTML. Then you can link to that resource with url in format "res://modname/res_id" where modname is name of the binary module (usually filename of your program or any DLL it loads) and res_id is ID of the resource in the resource script (RC). It can be both string or number identifier.

For example if you have a HTML file named some_page.html and add the following line into your resource script

 my_html_id HTML some_page.html

which is used to build a MYLIBRARY.DLL used by your application then your application can simply send the message MC_HM_GOTOURL with URL "res://mylibrary.dll/my_html_id".

Application Protocol

The control implements a simple application protocol app: which is intended for integration of HTML contents into your application logic.

Whenever user clicks on a link with URL starting with the "app:" the control sends notification MC_HN_APPLINK to its parent window which is supposed to react programatically. The control itself does not interpret application link URLs in any way.

Note that for sake of easy use it's recommended the application URLs do not contain non-ASCII characters, spaces, and some other characters the browser can encode.

Gotchas

• The HTML control implementation is based on OLE and COM technologies. During creation of the control OleInitialize() is called. I.e. the OLE subsystem is initialized for every thread which creates the HTML control. OleUninitialize() is similarly called when the control is destroyed. If you want to send some messages to the control from another thread then where it has been created, you have to initialize OLE subsystem in that thread manually.

• Remember that the control is a wrapper of embedded MS Internet Explorer so exact behavior depends on the version of MS IE installed.

• You make get URLs in notification slightly different from strings you used to navigate the control. The IE sometimes added slash ('/') after URLs having two slashes after protocol and of there is no slash after. Furthermore IE can encode some special characters into their hexadecimal representation (i.e. space ' ' becomes "%20").

---

Define Documentation

#define MC_HM_GOTOURLW   (WM_USER + 10)

Displays a contents specified by the given URL (unicode variant).

Parameters:

	wParam	Reserved, set to zero.
[in]	lParam	(const WCHAR*) Pointer to URL string.

Returns:

(BOOL) TRUE on success, FALSE otherwise.

#define MC_HM_GOTOURLA   (WM_USER + 11)

Displays a contents specified by the given URL (ANSI variant).

Parameters:

	wParam	Reserved, set to zero.
[in]	lParam	(const char*) Pointer to URL string.

Returns:

(BOOL) TRUE on success, FALSE otherwise.

#define MC_HN_APPLINK   ((0U-2000U) + 0x0001)

Fired when the browser should navigates to to URL with application protocol.

Parameters:

[in]	wParam	(int) Id of the control sending the notification.
[in]	lParam	(MC_NMHTMLURL*) Pointer to a structure specifying details about the URL.

Returns:

Application should return zero if it processes the notification.

#define MC_HN_DOCUMENTCOMPLETE   ((0U-2000U) + 0x0002)

Fired when loading of a document is complete.

Parameters:

[in]	wParam	(int) Id of the control sending the notification.
[in]	lParam	(MC_NMHTMLURL*) Pointer to a structure specifying details about the URL.

Returns:

Application should return zero if it processes the notification.

---

Function Documentation

BOOL MCTRL_API mcHtml_Initialize

(

void

)

Registers window class of the HTML control.

Returns:

TRUE on success, FALSE on failure.

See also:

About Initialization and Termination

void MCTRL_API mcHtml_Terminate

(

void

)

Unregisters window class of the HTML control.

See also:

About Initialization and Termination