mCtrl 0.8.2
Data Structures | Functions

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

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).
Control Styles
#define MC_HS_NOCONTEXTMENU   (0x00000001L)
 Disables context menu.
Control Messages
#define MC_HM_GOTOURLW   (WM_USER + 10)
 Displays a document specified by the given URL (unicode variant).
#define MC_HM_GOTOURLA   (WM_USER + 11)
 Displays a document specified by the given URL (ANSI variant).
#define MC_HM_SETTAGCONTENTSW   (WM_USER + 12)
 Set contents of the HTML tag with given attribute "id" (Unicode variant).
#define MC_HM_SETTAGCONTENTSA   (WM_USER + 13)
 Set contents of the HTML tag with given attribute "id" (ANSI variant).
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.
Unicode Resolution
#define MC_WC_HTML   MC_WC_HTMLW
 Unicode-resolution alias.
#define MC_HM_GOTOURL   MC_HM_GOTOURLW
 Unicode-resolution alias.
#define MC_HM_SETTAGCONTENTS   MC_HM_SETTAGCONTENTSW
 Unicode-resolution alias.
#define MC_NMHTMLURL   MC_NMHTMLURLW
 Unicode-resolution alias.

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 is intended to display HTML documents. Actually the control is thin wrapper of Internet Explorer COM object, so it can do much more: display a plethory of multimedia files, take use of javascript etc.

The easiest way how to show some document 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:

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 resources addessable by the control must be of type RT_HTML. You can link to such resources 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".

Of course, HTML documents stored in the resources then can also use relative URLs to link to other documents and resources in the same module (.EXE or .DLL).

Application Protocol

MCTRL.DLL 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.

Generated Contents

Generating HTML contents programatically is also possibly to some degree. Note however that the application is nut supposed to generate whole documents but only smaller snippets of them.

The application can set contents of almost any tag (identified by HTML attribute "id") with any custom string with the message MC_HM_SETTAGCONTENTS. The message takes ID. Then, if the currently loaded page has a tag with the given ID, the text of the tag is changed and set to the given string. Any previous content of that tag is removed. Remember the string has to follow HTML syntax and it can contain nested HTML tags.

Note the application should use the message MC_HM_SETTAGCONTENTS only after the HTML document intended ot be changed is completely loaded, i.e. anytime after the notification MC_HN_DOCUMENTCOMPLETE is fired.

Attention:
Please note that for limitations of Internet Explorer, contents of these tags can not be modified:
COL, COLGROUP, FRAMESET, HEAD, HTML, STYLE, TABLE, TBODY, TFOOT, THEAD, TITLE, TR.

We recommend to use tags DIV or SPAN for the dynamic contents injected by application code into the HTML pages.

Gotchas


Define Documentation

#define MC_HM_GOTOURLW   (WM_USER + 10)

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

Parameters:
wParamReserved, set to zero.
[in]lParam(const WCHAR*) The URL.
Returns:
(BOOL) TRUE on success, FALSE otherwise.
#define MC_HM_GOTOURLA   (WM_USER + 11)

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

Parameters:
wParamReserved, set to zero.
[in]lParam(const char*) The URL.
Returns:
(BOOL) TRUE on success, FALSE otherwise.
#define MC_HM_SETTAGCONTENTSW   (WM_USER + 12)

Set contents of the HTML tag with given attribute "id" (Unicode variant).

Parameters:
[in]wParam(const WCHAR*) ID of the tag.
[in]lParam(const WCHAR*) New contents of the tag.
Returns:
(BOOL) TRUE on success, FALSE otherwise.
See also:
Generated Contents
#define MC_HM_SETTAGCONTENTSA   (WM_USER + 13)

Set contents of the HTML tag with given attribute "id" (ANSI variant).

Parameters:
[in]wParam(const char*) ID of the tag.
[in]lParam(const char*) New contents of the tag.
Returns:
(BOOL) TRUE on success, FALSE otherwise.
See also:
Generated Contents
#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.
#define MC_WC_HTML   MC_WC_HTMLW

Unicode-resolution alias.

See also:
MC_WC_HTMLW MC_WC_HTMLA
#define MC_HM_GOTOURL   MC_HM_GOTOURLW

Unicode-resolution alias.

See also:
MC_HM_GOTOURLW MC_HM_GOTOURLA
#define MC_HM_SETTAGCONTENTS   MC_HM_SETTAGCONTENTSW

Unicode-resolution alias.

See also:
MC_HM_SETTAGCONTENTSW MC_HM_SETTAGCONTENTSA
#define MC_NMHTMLURL   MC_NMHTMLURLW

Unicode-resolution alias.

See also:
MC_NMHTMLURLW MC_NMHTMLURLA

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