mCtrl  0.9.2
Data Structures
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 notifications with URL parameter (unicode variant). More...
 
struct  MC_NMHTMLURLA
 Structure used for notifications with URL parameter (ANSI variant). More...
 
struct  MC_NMHTMLPROGRESS
 Structure used for notification about download progress. More...
 
struct  MC_NMHTMLTEXTW
 Structure used for notifications with textual parameter (unicode variant). More...
 
struct  MC_NMHTMLTEXTA
 Structure used for notifications with textual parameter (ANSI variant). More...
 
struct  MC_NMHTMLHISTORY
 Structure used for notification about history navigation. More...
 

Initialization Functions

BOOL mcHtml_Initialize (void)
 
void mcHtml_Terminate (void)
 

Window Class

#define MC_WC_HTMLW   L"mCtrl.html"
 
#define MC_WC_HTMLA   "mCtrl.html"
 

Control Styles

#define MC_HS_NOCONTEXTMENU   0x0001
 Disables context menu. More...
 

Control Messages

#define MC_HM_GOTOURLW   (MC_HM_FIRST + 10)
 Displays a document specified by the given URL (unicode variant). More...
 
#define MC_HM_GOTOURLA   (MC_HM_FIRST + 11)
 Displays a document specified by the given URL (ANSI variant). More...
 
#define MC_HM_SETTAGCONTENTSW   (MC_HM_FIRST + 12)
 Set contents of the HTML tag with given attribute "id" (Unicode variant). More...
 
#define MC_HM_SETTAGCONTENTSA   (MC_HM_FIRST + 13)
 Set contents of the HTML tag with given attribute "id" (ANSI variant). More...
 
#define MC_HM_GOBACK   (MC_HM_FIRST + 14)
 Navigates the HTML control back or forward in history. More...
 
#define MC_HM_CANBACK   (MC_HM_FIRST + 15)
 Tests whether going back or forward in history is possible. More...
 

Control Notifications

#define MC_HN_APPLINK   (MC_HN_FIRST + 0)
 Fired when the browser should navigates to to URL with application protocol. More...
 
#define MC_HN_DOCUMENTCOMPLETE   (MC_HN_FIRST + 1)
 Fired when loading of a document is complete. More...
 
#define MC_HN_PROGRESS   (MC_HN_FIRST + 2)
 Fired to inform application about download progress. More...
 
#define MC_HN_STATUSTEXT   (MC_HN_FIRST + 3)
 Fired when the browser would like to change status text. More...
 
#define MC_HN_TITLETEXT   (MC_HN_FIRST + 4)
 Fired when the browser changes title of the HTML page. More...
 
#define MC_HN_HISTORY   (MC_HN_FIRST + 5)
 Fired when possibility of going back or foward in history changes. More...
 
#define MC_HN_NEWWINDOW   (MC_HN_FIRST + 6)
 Fired when the browser would open a new window. More...
 

Unicode Resolution

#define MC_WC_HTML   MCTRL_NAME_AW(MC_WC_HTML)
 
#define MC_HM_GOTOURL   MCTRL_NAME_AW(MC_HM_GOTOURL)
 
#define MC_HM_SETTAGCONTENTS   MCTRL_NAME_AW(MC_HM_SETTAGCONTENTS)
 
#define MC_NMHTMLURL   MCTRL_NAME_AW(MC_NMHTMLURL)
 
#define MC_NMHTMLTEXT   MCTRL_NAME_AW(MC_NMHTMLTEXT)
 

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.

All resources addessable by the control must be of type RT_HTML. This includes not just the HTML document themselves but also all their files, images, stylesheets, javascript files and any other resources linked from the HTML pages, or URL passed to the control.

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).

Alhtough it can be both string or number identifier, we recommend to prefer string identifiers which end with dummy "file extension", hence making a hint to the browser about the image type. Without this the browser tries to guess what type of the data the resource is, and that may be unrealiable. Remember the heuristics also differ in various verisons of MSIE.

For example if you have a HTML file named some_page.html and an image file image.png which can be linked from the HTML page, add the following lines into your resource script:

"some_page.html" HTML some_page.html
"image.png" HTML image.png

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/some_page.html".

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 possible to some degree. Note however that the application is not 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 using the message MC_HM_SETTAGCONTENTS. The message takes the ID and the string as its arguments. Then, if the currently loaded page has a tag with the given ID, the content of the tag is replaced and set to the given string. Any previous content of that tag is removed. Remember the string has to follow HTML syntax and keep integrity of the HTML document.

Note the application should use the message MC_HM_SETTAGCONTENTS only after the HTML document intended to 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

Standard Messages

These standard messages are handled by the control:

These standard notifications are sent by the control:


Data Structure Documentation

struct MC_NMHTMLURLW

Structure used for notifications with URL parameter (unicode variant).

See Also
MC_HN_APPLINK MC_HN_DOCUMENTCOMPLETE
Data Fields
NMHDR hdr

Common notification structure header.

LPCWSTR pszUrl

String representation of the URL.

struct MC_NMHTMLURLA

Structure used for notifications with URL parameter (ANSI variant).

See Also
MC_HN_APPLINK MC_HN_DOCUMENTCOMPLETE
Data Fields
NMHDR hdr

Common notification structure header.

LPCSTR pszUrl

String representation of the URL.

struct MC_NMHTMLPROGRESS

Structure used for notification about download progress.

See Also
MC_HN_PROGRESS
Data Fields
NMHDR hdr

Common notification structure header.

LONG lProgress

Current progress.

LONG lProgressMax

Progress maximum.

struct MC_NMHTMLTEXTW

Structure used for notifications with textual parameter (unicode variant).

See Also
MC_HN_STATUSTEXT MC_HN_TITLETEXT
Data Fields
NMHDR hdr

Common notification structure header.

LPCWSTR pszText

The string.

struct MC_NMHTMLTEXTA

Structure used for notifications with textual parameter (ANSI variant).

See Also
MC_HN_STATUSTEXT MC_HN_TITLETEXT
Data Fields
NMHDR hdr

Common notification structure header.

LPCSTR pszText

The string.

struct MC_NMHTMLHISTORY

Structure used for notification about history navigation.

See Also
MC_HN_HISTORY
Data Fields
NMHDR hdr

Common notification structure header.

BOOL bCanBack

TRUE if going back in history is possible.

BOOL bCanForward

TRUE if going forward in history is possible.

Macro Definition Documentation

#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_HS_NOCONTEXTMENU   0x0001

Disables context menu.

#define MC_HM_GOTOURLW   (MC_HM_FIRST + 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   (MC_HM_FIRST + 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   (MC_HM_FIRST + 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   (MC_HM_FIRST + 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_HM_GOBACK   (MC_HM_FIRST + 14)

Navigates the HTML control back or forward in history.

Parameters
[in]wParam(BOOL) Set to TRUE to go back in history or FALSE to go forward.
lParamReserved, set to zero.
Returns
(BOOL) TRUE on success, FALSE otherwise.
See Also
MC_HM_CANBACK
#define MC_HM_CANBACK   (MC_HM_FIRST + 15)

Tests whether going back or forward in history is possible.

Parameters
[in]wParam(BOOL) Set to TRUE to test going back in history or FALSE to going forward.
lParamReserved, set to zero.
Returns
(BOOL) TRUE if can go back or forward respectivelly, FALSE otherwise.
See Also
MC_HM_GOBACK
#define MC_HN_APPLINK   (MC_HN_FIRST + 0)

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   (MC_HN_FIRST + 1)

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_HN_PROGRESS   (MC_HN_FIRST + 2)

Fired to inform application about download progress.

This allows example for example to show a progress indicator.

Parameters
[in]wParam(int) Id of the control sending the notification.
[in]lParam(MC_NMHTMLPROGRESS*) Pointer to a structure specifying details about the progress.
Returns
Application should return zero if it processes the notification.
#define MC_HN_STATUSTEXT   (MC_HN_FIRST + 3)

Fired when the browser would like to change status text.

IE usually shows this text in its statusbar.

Parameters
[in]wParam(int) Id of the control sending the notification.
[in]lParam(MC_NMHTMLTEXT*) Pointer to a structure specifying the text.
Returns
Application should return zero if it processes the notification.
#define MC_HN_TITLETEXT   (MC_HN_FIRST + 4)

Fired when the browser changes title of the HTML page.

IE usually shows this in window caption or tab label.

Parameters
[in]wParam(int) Id of the control sending the notification.
[in]lParam(MC_NMHTMLTEXT*) Pointer to a structure specifying the text.
Returns
Application should return zero if it processes the notification.
#define MC_HN_HISTORY   (MC_HN_FIRST + 5)

Fired when possibility of going back or foward in history changes.

This allow application to enable or disable the corresponding command buttons.

Parameters
[in]wParam(int) Id of the control sending the notification.
[in]lParam(MC_NMHTMLURL*) Pointer to a structure specifying the text.
Returns
Application should return zero if it processes the notification.
See Also
MC_HM_GOBACK MC_HM_CANBACK
#define MC_HN_NEWWINDOW   (MC_HN_FIRST + 6)

Fired when the browser would open a new window.

This happens for exaple if user clicks on a link while holding SHIFT.

MC_NMHTMLURL::pszUrl is URL to be opened in the new window. Note however that prior to Windows XP SP2, the URL is not filled.

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 non-zero to allow opening the new window, or zero to deny it.
#define MC_WC_HTML   MCTRL_NAME_AW(MC_WC_HTML)

Unicode-resolution alias.

See Also
MC_WC_HTMLW MC_WC_HTMLA
#define MC_HM_GOTOURL   MCTRL_NAME_AW(MC_HM_GOTOURL)

Unicode-resolution alias.

See Also
MC_HM_GOTOURLW MC_HM_GOTOURLA
#define MC_HM_SETTAGCONTENTS   MCTRL_NAME_AW(MC_HM_SETTAGCONTENTS)

Unicode-resolution alias.

See Also
MC_HM_SETTAGCONTENTSW MC_HM_SETTAGCONTENTSA
#define MC_NMHTMLURL   MCTRL_NAME_AW(MC_NMHTMLURL)

Unicode-resolution alias.

See Also
MC_NMHTMLURLW MC_NMHTMLURLA
#define MC_NMHTMLTEXT   MCTRL_NAME_AW(MC_NMHTMLTEXT)

Unicode-resolution alias.

See Also
MC_NMHTMLTEXTW MC_NMHTMLTEXTA

Function Documentation

BOOL mcHtml_Initialize ( void  )

Registers window class of the control.

Returns
TRUE on success, FALSE on failure.
void mcHtml_Terminate ( void  )

Unregisters window class of the control.