<commit_before>/*
 * Copyright (c) 2008-2015 <NAME>
 *
 * This library is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; either version 2.1 of the License, or
 * (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this library; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 */

#ifndef MCTRL_HTML_H
#define MCTRL_HTML_H

#include <mCtrl/_defs.h>
#include <mCtrl/_common.h>

#ifdef __cplusplus
extern "C" {
#endif


/**
 * @file
 * @brief HTML control (@c 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 plethora 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
 * @c 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 @ref 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
 *
 *
 * @section html_proto_res Resource Protocol
 *
 * The @c res: protocol is especially useful. It allows you to embed some
 * resources like HTML pages, cascading style sheets (CSS), images (PNG, JPG
 * etc.) or JavaScript files into binary of your application or any DLL it
 * uses.
 *
 * You can link to such resources with URL in format
 * "res://modname/res_type/res_id" where @c modname is name of the binary
 * module (usually filename of your program or any DLL it loads; or a full path
 * to other .EXE or .DLL file), @c res_type is type of the resource and @c
 * res_id is ID of the resource in the resource script (RC).
 *
 * The type can be omitted in the URL. The control then assumes type 23
 * (@c RT_HTML).
 *
 * Although @c res_id can be both string or number identifier, we recommend
 * to prefer string identifiers which end with dummy &quot;file extension&quot;,
 * 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 unreliable. Remember the heuristics also differ in various versions of
 * MSIE.
 *
 * For example if you have a HTML file named @c some_page.html and an image
 * file @c image.png which can be linked from the HTML page, add the following
 * lines into your resource script:
 * @code
 * some_page.html HTML path/to/some_page.html
 * image.png HTML path/to/image.png
 * @endcode
 * which is used to build a @c MYLIBRARY.DLL used by your application then
 * your application can simply send the message @ref MC_HM_GOTOURL with URL
 * @c "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 (@c .EXE or @c .DLL).
 *
 *
 * @section html_proto_app Application Protocol
 *
 * @c MCTRL.DLL implements a simple application protocol @c app: which is
 * intended for integration of HTML contents into your application logic.
 *
 * Whenever user clicks on a link with URL starting with the @c "app:"
 * the control sends notification @ref MC_HN_APPLINK to its parent window
 * which is supposed to react programmatically. The control itself does not
 * interpret application link URLs in any way.
 *
 *
 * @section html_generated_contents Dynamically Generated Contents
 *
 * Generating HTML contents programmatically 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 @c "id") with any custom string using the message @ref 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 @ref MC_HM_SETTAGCONTENTS
 * only after the HTML document intended to be changed is completely loaded,
 * i.e. anytime after the notification @ref MC_HN_DOCUMENTCOMPLETE is fired.
 *
 * @attention
 * Please note that for limitations of Internet Explorer, contents of these
 * tags can <b>not</b> be modified:<br>
 * @c COL, @c COLGROUP, @c FRAMESET, @c HEAD, @c HTML, @c STYLE, @c TABLE,
 * @c TBODY, @c TFOOT, @c THEAD, @c TITLE, @c TR.
 *
 * We recommend to use tags @c DIV or @c SPAN for the dynamic contents
 * injected by application code into the HTML pages.
 *
 *
 * @section html_script Calling Script Function
 *
 * The control supports also invoking a script (e.g. JavaScript) function
 * within the HTML page from the application's code.
 *
 * There are actually two messages for this very purpose. The message @ref
 * MC_HM_CALLSCRIPTFUNCEX is more powerful, and can call any script function,
 * with any number of arguments of any type, and returning any type, but using
 * this message requires manual setup of OLE variadic type (@c VARIANT) type
 * and it requires more coding.
 *
 * The other message, @ref MC_HM_CALLSCRIPTFUNC, is easier to use but its use
 * imposes some limitations: It can only deal with script functions with up
 * to four arguments, and all arguments, as well as any return value, must be
 * of string or integer type.
 *
 *
 * @section html_gotchas Gotchas
 *
 * - Keep in mind that the control is relatively thin wrapper of embedded MS
 *   Internet Explorer so exact behavior depends on the version of MS IE
 *   installed.
 *
 * - The value of the URL in notifications might not match the URL that was
 *   originally given to the HTML control, because the URL might be converted
 *   to a qualified form. For example, the IE sometimes may add a slash ('/')
 *   at the end of some URLs. Furthermore IE can encode some special characters
 *   into their hexadecimal representation (e.g. space ' ' becomes "%20").
 *
 *
 * @section chtml_std_msgs Standard Messages
 *
 * These standard messages are handled by the control:
 * - @c CCM_GETUNICODEFORMAT
 * - @c CCM_SETNOTIFYWINDOW
 * - @c CCM_SETUNICODEFORMAT
 *
 * These standard notifications are sent by the control:
 * - @c NM_OUTOFMEMORY
 */


/**
 * @name Initialization Functions
 */
/*@{*/

/**
 * Registers window class of the control.
 * @return @c TRUE on success, @c FALSE on failure.<commit_msg>HTML: Add docs about IE compatibility modes.<commit_after>/*
 * Copyright (c) 2008-2015 <NAME>
 *
 * This library is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; either version 2.1 of the License, or
 * (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this library; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 */

#ifndef MCTRL_HTML_H
#define MCTRL_HTML_H

#include <mCtrl/_defs.h>
#include <mCtrl/_common.h>

#ifdef __cplusplus
extern "C" {
#endif


/**
 * @file
 * @brief HTML control (@c 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 plethora 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
 * @c 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 @ref 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
 *
 *
 * @section html_proto_res Resource Protocol
 *
 * The @c res: protocol is especially useful. It allows you to embed some
 * resources like HTML pages, cascading style sheets (CSS), images (PNG, JPG
 * etc.) or JavaScript files into binary of your application or any DLL it
 * uses.
 *
 * You can link to such resources with URL in format
 * "res://modname/res_type/res_id" where @c modname is name of the binary
 * module (usually filename of your program or any DLL it loads; or a full path
 * to other .EXE or .DLL file), @c res_type is type of the resource and @c
 * res_id is ID of the resource in the resource script (RC).
 *
 * The type can be omitted in the URL. The control then assumes type 23
 * (@c RT_HTML).
 *
 * Although @c res_id can be both string or number identifier, we recommend
 * to prefer string identifiers which end with dummy &quot;file extension&quot;,
 * 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 unreliable. Remember the heuristics also differ in various versions of
 * MSIE.
 *
 * For example if you have a HTML file named @c some_page.html and an image
 * file @c image.png which can be linked from the HTML page, add the following
 * lines into your resource script:
 * @code
 * some_page.html HTML path/to/some_page.html
 * image.png HTML path/to/image.png
 * @endcode
 * which is used to build a @c MYLIBRARY.DLL used by your application then
 * your application can simply send the message @ref MC_HM_GOTOURL with URL
 * @c "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 (@c .EXE or @c .DLL).
 *
 *
 * @section html_proto_app Application Protocol
 *
 * @c MCTRL.DLL implements a simple application protocol @c app: which is
 * intended for integration of HTML contents into your application logic.
 *
 * Whenever user clicks on a link with URL starting with the @c "app:"
 * the control sends notification @ref MC_HN_APPLINK to its parent window
 * which is supposed to react programmatically. The control itself does not
 * interpret application link URLs in any way.
 *
 *
 * @section html_generated_contents Dynamically Generated Contents
 *
 * Generating HTML contents programmatically 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 @c "id") with any custom string using the message @ref 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 @ref MC_HM_SETTAGCONTENTS
 * only after the HTML document intended to be changed is completely loaded,
 * i.e. anytime after the notification @ref MC_HN_DOCUMENTCOMPLETE is fired.
 *
 * @attention
 * Please note that for limitations of Internet Explorer, contents of these
 * tags can <b>not</b> be modified:<br>
 * @c COL, @c COLGROUP, @c FRAMESET, @c HEAD, @c HTML, @c STYLE, @c TABLE,
 * @c TBODY, @c TFOOT, @c THEAD, @c TITLE, @c TR.
 *
 * We recommend to use tags @c DIV or @c SPAN for the dynamic contents
 * injected by application code into the HTML pages.
 *
 *
 * @section html_script Calling Script Function
 *
 * The control supports also invoking a script (e.g. JavaScript) function
 * within the HTML page from the application's code.
 *
 * There are actually two messages for this very purpose. The message @ref
 * MC_HM_CALLSCRIPTFUNCEX is more powerful, and can call any script function,
 * with any number of arguments of any type, and returning any type, but using
 * this message requires manual setup of OLE variadic type (@c VARIANT) type
 * and it requires more coding.
 *
 * The other message, @ref MC_HM_CALLSCRIPTFUNC, is easier to use but its use
 * imposes some limitations: It can only deal with script functions with up
 * to four arguments, and all arguments, as well as any return value, must be
 * of string or integer type.
 *
 *
 * @section html_gotchas Gotchas
 *
 * - Keep in mind that the control is relatively thin wrapper of embedded MS
 *   Internet Explorer so exact behavior depends on the version of MS IE
 *   installed.
 *
 * - The value of the URL in notifications might not match the URL that was
 *   originally given to the HTML control, because the URL might be converted
 *   to a qualified form. For example, the IE sometimes may add a slash ('/')
 *   at the end of some URLs. Furthermore IE can encode some special characters
 *   into their hexadecimal representation (e.g. space ' ' becomes "%20").
 *
 *
 * @section html_ie_versions IE Versions
 *
 * As noted in the introduction, the control is implemented as a thin wrapper
 * of Internet Explorer COM object (COM interface @c IWebBrowser2).
 *
 * Because of the compatibility reasons, Microsoft has decided that by default
 * the control will behave as Internet Explorer version 7 (assuming IE 7
 * or newer is installed in the computer).
 *
 * This has some impact on how the HTML pages are rendered and, more
 * importantly, on java-script dialect understood by it. Unfortunately the API
 * does not allow reasonable to change the compatibility mode on a per-control
 * (or rather on a per-COM-object-instance) manner.
 *
 * Furthermore, the switched is done through a change in the registry, which
 * should likely be done during installation phase of the application (and
 * possibly undone when it is uninstalled). Therefore the mCtrl does not offer
 * any API to change this and instead you are on your own to deal with the
 * registry keys.
 *
 * To change the behavior, you need to create the following registry key
 * "HKEY_CURRENT_USER\Software\Microsoft\Internet Explorer\Main\FeatureControl\"
 * if it does not already exist, and in it, create a DWORD value named as a
 * binary name of your application (e.g. "MyApplication.exe"). The DWORD value
 * then determines the compatibility version (taken from MSDN documentation):
 *
 * - 7000 (0x1b58): IE 7 mode (the default).
 * - 8000 (0x1f40): IE 8 mode or IE 10 mode depending on !DOCTYPE directives
 *                  within HTML document.
 * - 8888 (0x22b8): IE 8 mode, regardless of the declared !DOCTYPE directives.
 * - 9000 (0x2328): IE 9 mode or IE 10 mode depending on !DOCTYPE directives
 *                  within HTML document.
 * - 9999 (0x270f): IE 9 mode, regardless of the declared !DOCTYPE directives.
 * - 10000 (0x2710): IE 10 mode for HTML documents with !DOCTYPE directives.
 * - 10001 (0x2711): IE 10 mode, regardless of the declared !DOCTYPE directives.
 * - 11000 (0x2af8): IE 11 mode.
 * - 11001 (0x2af9): IE 11 mode, regardless of the declared !DOCTYPE directives.
 *                   Failing to declare a !DOCTYPE directive causes the page to
 *                   load in Quirks mode.
 *
 * Note that only IE version 8 and newer can understand this registry value and,
 * of course, the maximal value understood by it is limited by version of IE
 * installed on the system. E.g. asking IE 8 to behave as IE 10 won't work.
 *
 * Further recommendations:
 *  - When using this, you should consider to make name of your .exe file as
 *    unique as possible to mitigate possible conflicts with other applications.
 *  - When creating the registry key/value within your exe before creating the
 *    control, you may consider to create it volatile to not leave waste in the
 *    persistent registry storage.
 *  - Application can only switch all @c IWebBrowser2 instances to the given
 *    compatibility mode, or none of them.
 *
 *
 * @section html_std_msgs Standard Messages
 *
 * These standard messages are handled by the control:
 * - @c CCM_GETUNICODEFORMAT
 * - @c CCM_SETNOTIFYWINDOW
 * - @c CCM_SETUNICODEFORMAT
 *
 * These standard notifications are sent by the control:
 * - @c NM_OUTOFMEMORY
 */


/**
 * @name Initialization Functions
 */
/*@{*/

/**
 * Registers window class of the control.
 * @return @c TRUE on success, @c FALSE on failure.
{'fraction_non_alphanumeric': 0.06719007794276612, 'fraction_numerical': 0.008761449621664676, 'mean_word_length': 3.6613630336780694, 'pattern_counts': {'":': 0, '<': 15, '<?xml version=': 0, '>': 15, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2840545', 'n_tokens_mistral': 4935, 'n_tokens_neox': 4653, 'n_words': 2549}