Différences entre les versions de « Les scripts de Maxthon v2.0 »

De Wiki Francophone de Maxthon
Aller à la navigation Aller à la recherche
 
Ligne 1 : Ligne 1 :
Version: 2.0.1
Version: 2.0.1<br /> Last Modified: 2006-07-17 4:24 PM
Last Modified: 2006-07-17 4:24 PM
 
===Overview===


==Overview==
Maxthon Browser has extended the DHTML support of IE by adding several new extensions which can be called by scripting language such as Javascript and VBScript.
Maxthon Browser has extended the DHTML support of IE by adding several new extensions which can be called by scripting language such as Javascript and VBScript.


These APIs can be called via the window.external object in a HTML page or a script plugin made for Maxthon Browser.  
These APIs can be called via the <span class="keyword">window</span>.<span class="keyword">external</span> object in a HTML page or a script plugin made for Maxthon Browser.
 
Some functions will require a <span class="flag">security_id</span> as first parameter. These Functions can only be used by Plugins.<br /> In order to get a <span class="flag">security_id</span> for your plugin, you can do the following:
 
=====Button Plugins=====
 
Put a <span class="flag">%max_security_id</span> in your script, such as:


Some functions will require a security_id as first parameter. These Functions can only be used by Plugins.
<span class="keyword">var</span> security_id=<span class="flag">%max_security_id</span><nowiki>;</nowiki>
In order to get a security_id for your plugin, you can do the following:


Then you can use the variable <span class="flag">security_id</span> in your script.


==Button Plugins==
=====Sidebar Plugins=====
Put a %max_security_id in your script, such as:
var security_id=%max_security_id;


Then you can use the variable security_id in your script.
A file named <span class="flag">max.src</span> will be created in your plugin's folder, include this file in your HTML file:


==Sidebar Plugins==
<<span class="keyword">script</span> <span class="flag">type</span><nowiki>=</nowiki><span class="string">"text/javascript"</span> <span class="flag">src</span><nowiki>=</nowiki><span class="string">"max.src"</span>></<span class="keyword">script</span>>
A file named max.src will be created in your plugin's folder, include this file in your HTML file:


<script type="text/javascript" src="max.src"></script>
Then use variable <span class="flag">max_security_id</span> for security id parameter in your script.


Then use variable max_security_id for security id parameter in your script.
===Index===


=====Extended Properties=====


==Index==
* [#max_version max_version] : Get current version of Maxthon Browser
Extended Properties
* [#max_language_id max_language_id] : Get current language id of Maxthon UI
max_version : Get current version of Maxthon Browser  
* [#current_tab current_tab (cur_sel)] : Get current tab's index
max_language_id : Get current language id of Maxthon UI  
* [#tab_count tab_count] : Get current opened tabs' count
current_tab (cur_sel) : Get current tab's index  
tab_count : Get current opened tabs' count  
General Methods
addFavorite() : Call the Add Favorites dialog
addProxy() : Call the Add Proxy dialog
addFilter() : Call the Add Filter dialog
max_addProxyProvider() : Call the Add Proxy Provider dialog
m2_run_cmd() : Execute Maxthon functions by Command ID
m2_search_text() : Get search string in Maxthon's Search Box
m2_plugin_folder() : Get local folder path of a plugin
Tab Related Methods
get_tab() : Get a tab's window object by index
activate_tab() : Activate a tab by index
close_tab() : Close a tab by index
File Related Methods
readFile() : Read a file's content
writeFile() : Write data to a file
m2_readIni() : Read an INI file
m2_writeIni() : Write to an INI file


Extended Properties  
=====General Methods=====
max_version  
 
Remarks:
* [#addFavorite addFavorite()] : Call the Add Favorites dialog
This property will return a string of Maxthon Browser Version Number.
* [#addProxy addProxy()] : Call the Add Proxy dialog
The return string is formatted like "2.1.0.600".  
* [#addFilter addFilter()] : Call the Add Filter dialog
* [#max_addProxyProvider max_addProxyProvider()] : Call the Add Proxy Provider dialog
* [#m2_run_cmd m2_run_cmd()] : Execute Maxthon functions by Command ID
* [#m2_search_text m2_search_text()] : Get search string in Maxthon's Search Box
* [#m2_plugin_folder m2_plugin_folder()] : Get local folder path of a plugin
 
=====Tab Related Methods=====
 
* [#get_tab get_tab()] : Get a tab's window object by index
* [#activate_tab activate_tab()] : Activate a tab by index
* [#close_tab close_tab()] : Close a tab by index
 
=====File Related Methods=====
 
* [#readFile readFile()] : Read a file's content
* [#writeFile writeFile()] : Write data to a file
* [#m2_readIni m2_readIni()] : Read an INI file
* [#m2_writeIni m2_writeIni()] : Write to an INI file
 
===Extended Properties===
 
====max_version====
 
<div class="indent">
 
=====Remarks:=====
 
This property will return a string of Maxthon Browser Version Number.<br /> The return string is formatted like <span class="string">"2.1.0.600"</span>.


It's sugguested use this property to determine whether Maxthon Browser is running.
It's sugguested use this property to determine whether Maxthon Browser is running.


Requirements:
=====Requirements:=====
Maxthon Version 2.0+
 
Maxthon Version 2.0+<br /><br />
 
=====Example:=====
 
[javascript:v() [Demo 1]]


<div class="codeblock"><span class="keyword">alert</span>(<span class="string">'Maxthon Version: '</span>+<span class="keyword">external</span>.<span class="keyword">max_version</span>);</div></div>


Example:
====max_language_id====
[Demo 1]


alert('Maxthon Version: '+external.max_version);
<div class="indent">
 
=====Remarks:=====


max_language_id
Remarks:
This property will return current language id of Maxthon Browser.
This property will return current language id of Maxthon Browser.


The Language ID has change to use Language Identifiers defined in Microsoft Windows since Maxthon Browser 2.0.  
The Language ID has change to use Language Identifiers defined in Microsoft Windows since Maxthon Browser 2.0. <br /> A list of Maxthon's Language IDs can be found at:<br />http://msdn.microsoft.com/library/?url=/library/en-us/intl/nls_238z.asp
A list of Maxthon's Language IDs can be found at:
 
http://msdn.microsoft.com/library/?url=/library/en-us/intl/nls_238z.asp  
=====Requirements:=====
 
Maxthon Version 1.0+<br /><br />
 
=====Example:=====
 
[javascript:v() [Demo 1]]
 
<span class="keyword">alert</span>(<span class="string">'Language ID='</span>+<span class="keyword">external</span>.<span class="keyword">max_language_id</span>);
 
</div>
 
====current_tab '''(formerly''' cur_sel ''')''' <span class="note">Not Implemented</span>====
 
<div class="indent">
 
=====Remarks:=====
 
This property will return an integer number as the index of the tab which is activated.<br /><span class="flag">null</span> will be returned if there is no tab opened.<br /><span class="keyword">current_tab</span><span class="warn"> is introduced in Maxthon 2.0 as a replacement of </span><span class="keyword">cur_sel</span><span class="warn"> because the old property name is too obscure to understand.</span><br /><br />
 
=====Requirements:=====
 
Maxthon Version 2.0+ (use <span class="keyword">cur_sel</span> for 1.x versions)<br /><br />
 
=====Example:=====
 
[javascript:v() [Demo 1]]
 
<div class="codeblock"><span class="keyword">alert</span>(<span class="string">'Current Tab Index: '</span>+<span class="keyword">external</span>.<span class="keyword">current_tab</span>);</div></div>
 
====tab_count====
 
<div class="indent">
 
=====Remarks:=====
 
This property will return current tab count as an integer.<br /><br />
 
=====Requirements:=====
 
Maxthon Version 1.0+<br /><br />
 
=====Example:=====
 
[javascript:v() [Demo 1]]
 
<span class="keyword">alert</span>(<span class="string">'Tabs Count: '</span>+<span class="keyword">external</span>.<span class="keyword">tab_count</span>);


Requirements:
</div>
Maxthon Version 1.0+


<br /><br />


Example:
===General Methods===
[Demo 1]


alert('Language ID='+external.max_language_id);
====addFavorite(''url'' '''[''', ''title''''']''')====


<div class="indent">


current_tab (formerly cur_sel ) Not Implemented
=====Parameters:=====
Remarks:
This property will return an integer number as the index of the tab which is activated.
null will be returned if there is no tab opened.
current_tab is introduced in Maxthon 2.0 as a replacement of cur_sel because the old property name is too obscure to understand.


''url'' : string<br /> The url to add.<br /><br />''title'' : string<br /> Optional. The title of the url.<br /><br />


Requirements:
=====Remarks:=====
Maxthon Version 2.0+ (use cur_sel for 1.x versions)


Show the Add Favorite dialog to ask user to add a new Favorites Item.<br /> This function will return <span class="bool">false</span> if user cancelled this operation.<br /><br />


Example:
=====Requirements:=====
[Demo 1]


alert('Current Tab Index: '+external.current_tab);
Maxthon Version 1.0+<br /><br />


tab_count
=====Example:=====
Remarks:
This property will return current tab count as an integer.


[javascript:v() [Demo 1]]


Requirements:
<span class="keyword">external</span>.<span class="keyword">addFavorite</span>(<span class="string">"http://www.maxthon.com"</span>);
Maxthon Version 1.0+


[javascript:v() [Demo 2]]


Example:
<span class="keyword">external</span>.<span class="keyword">addFavorite</span>(<span class="string">"http://www.maxthon.com"</span>, <span class="string">"Maxthon Official Site"</span>);
[Demo 1]


alert('Tabs Count: '+external.tab_count);
</div>


====addProxy(''name'', ''address'', ''type'')====


<div class="indent">


=====Parameters:=====


General Methods
''name'' : string<br /> The display name of proxy.<br /><br />''address'' : string<br /> The IP address or Domain name of proxy.<br /><br />''type'' : integer<br /> A number indicates the speed rating of proxy.<br /> = HTTP Proxy, <span class="number">1</span> = SOCKS4A Proxy, <span class="number">2</span> = SOCKS5 Proxy<br /><br />
addFavorite(url [, title])
Parameters:
url : string
The url to add.


title : string
=====Remarks:=====
Optional. The title of the url.


Add a new proxy into Maxthon's proxy list. A dialog will be shown to the user.<br /> This function will return <span class="bool">false</span> if user cancelled this operation.<br /><br />


Remarks:
=====Requirements:=====
Show the Add Favorite dialog to ask user to add a new Favorites Item.
This function will return false if user cancelled this operation.


Maxthon Version 2.0+<br /><br />


Requirements:
=====Example:=====
Maxthon Version 1.0+


[javascript:v() [Demo 1]]


Example:
<span class="keyword">external</span>.<span class="keyword">addProxy</span>(<span class="string">"My proxy"</span>,<span class="string">"192.168.1.0:8080"</span>, <span class="number">1</span>);
[Demo 1]


external.addFavorite("http://www.maxthon.com");
</div>


[Demo 2]
====addFilter(''url_mask'', ''type'')====


external.addFavorite("http://www.maxthon.com", "Maxthon Official Site");
<div class="indent">


=====Parameters:=====


addProxy(name, address, type)
''url_mask'' : string<br /> Address mask to match blocked addresses. Supports Regular Expression.<br /><br />''type'' : integer<br /> A number indicates which Filter list to add.<br /> = Popup Filter, <span class="number">1</span> = Content Filter<br /><br />
Parameters:
name : string
The display name of proxy.


address : string
=====Remarks:=====
The IP address or Domain name of proxy.


type : integer
Add a new filter policy into Maxthon. A dialog will be shown to the user.<br /> This function will return '''false''' if user cancelled this operation.<br /><br />
A number indicates the speed rating of proxy.
0 = HTTP Proxy, 1 = SOCKS4A Proxy, 2 = SOCKS5 Proxy


=====Requirements:=====


Remarks:
Maxthon Version 2.0+<br /><br />
Add a new proxy into Maxthon's proxy list. A dialog will be shown to the user.
This function will return false if user cancelled this operation.


=====Example:=====


Requirements:
[javascript:v() [Demo 1]]
Maxthon Version 2.0+


<span class="keyword">external</span>.<span class="keyword">addFilter</span>(<span class="string">"http://www.advertisement.com/img/*"</span>, );


Example:
</div>
[Demo 1]


external.addProxy("My proxy","192.168.1.0:8080", 1);
====max_addProxyProvider(''URL'')====


<div class="indent">


addFilter(url_mask, type)
=====Parameters:=====
Parameters:
url_mask : string
Address mask to match blocked addresses. Supports Regular Expression.


type : integer
''URL'' : string<br /> The URL of proxy list file. File format please refer to [proxyprovider.htm this document].<br /><br />
A number indicates which Filter list to add.
0 = Popup Filter, 1 = Content Filter


=====Remarks:=====


Remarks:
Add a new Proxy Provider into Maxthon Broser. A dialog will be shown to the user.<br /> This function will return <span class="bool">false</span> if user cancelled this operation.<br /><br />
Add a new filter policy into Maxthon. A dialog will be shown to the user.
This function will return false if user cancelled this operation.


=====Requirements:=====


Requirements:
Maxthon Version 2.0+<br /><br />
Maxthon Version 2.0+


=====Example:=====


Example:
[javascript:v() [Demo 1]]
[Demo 1]


external.addFilter("http://www.advertisement.com/img/*", 0);  
<span class="keyword">external</span>.<span class="keyword">max_addProxyProvider</span>(<span class="string">"http://www.freeproxy.cn/m2proxy/proxylist.xml"</span>);


</div>


max_addProxyProvider(URL)
====m2_run_cmd(''security_id'', ''command_id'')====
Parameters:
URL : string
The URL of proxy list file. File format please refer to this document.


<div class="indent">


Remarks:
=====Parameters:=====
Add a new Proxy Provider into Maxthon Broser. A dialog will be shown to the user.
This function will return false if user cancelled this operation.


''security_id'' : string<br /> Maxthon's Security ID.<br /><br />''command_id'' : integer<br /> The internal command ID of Maxthon.<br /><br />


Requirements:
=====Remarks:=====
Maxthon Version 2.0+


This function will call a Maxthon's command with specified ''command_id''.<br /> Most usable Command IDs can be found in the language file inside Maxthon's language folder.<br /><span class="warn">Command ID might be different between versions. Please do not use this function if not required.</span><br /><br />


Example:
=====Requirements:=====
[Demo 1]


external.max_addProxyProvider("http://www.freeproxy.cn/m2proxy/proxylist.xml");
Maxthon Version 1.0+<br /><br />


=====Example:=====


m2_run_cmd(security_id, command_id)
<span class="keyword">external</span>.<span class="keyword">m2_run_cmd</span>(<span class="string">security_id</span>, <span class="number">32772</span>); // Open a Blank Page
Parameters:
security_id : string
Maxthon's Security ID.


command_id : integer
</div>
The internal command ID of Maxthon.


====m2_search_text(''security_id'')====


Remarks:
<div class="indent">
This function will call a Maxthon's command with specified command_id.
Most usable Command IDs can be found in the language file inside Maxthon's language folder.
Command ID might be different between versions. Please do not use this function if not required.


=====Parameters:=====


Requirements:
''security_id'' : string<br /> Maxthon's Security ID.<br /><br />
Maxthon Version 1.0+


=====Remarks:=====


Example:
This function will return the text in Maxthon's Search Box as a string.<br /><br />
external.m2_run_cmd(security_id, 32772); // Open a Blank Page


=====Requirements:=====


m2_search_text(security_id)
Maxthon Version 1.2+<br /><br />
Parameters:
security_id : string
Maxthon's Security ID.


=====Example:=====


Remarks:
<span class="keyword">var</span> searchText=<span class="keyword">external</span>.<span class="keyword">m2_search_text</span>(<span class="string">security_id</span>);
This function will return the text in Maxthon's Search Box as a string.


</div>


Requirements:
====m2_plugin_folder(''security_id'', ''plugin_name'')====
Maxthon Version 1.2+


<div class="indent">


Example:
=====Parameters:=====
var searchText=external.m2_search_text(security_id);


 
''security_id'' : string<br /> Maxthon's Security ID.<br /><br />''plugin_name'' : string<br /> The name of the plugin as defined in plugin.ini.<br /><br />


m2_plugin_folder(security_id, plugin_name)
=====Remarks:=====
Parameters:
security_id : string
Maxthon's Security ID.


plugin_name : string
This function will return the local folder path of specified plugin as a string.<br /><br />
The name of the plugin as defined in plugin.ini.


=====Requirements:=====


Remarks:
Maxthon Version 1.2+<br /><br />
This function will return the local folder path of specified plugin as a string.


=====Example:=====


Requirements:
<span class="keyword">var</span> pluginPath=<span class="keyword">external</span>.<span class="keyword">m2_plugin_folder</span>(<span class="string">security_id</span>, <span class="string">"ViewSource!"</span>);
Maxthon Version 1.2+


</div>


Example:
====m2_callerName(''security_id'', ''plugin_name'')====
var pluginPath=external.m2_plugin_folder(security_id, "ViewSource!");


<div class="indent">


m2_callerName(security_id, plugin_name)
=====Parameters:=====
Parameters:
security_id : string
Maxthon's Security ID.


plugin_name : string
''security_id'' : string<br /> Maxthon's Security ID.<br /><br />''plugin_name'' : string<br /> The name of the plugin as defined in plugin.ini.<br /><br />
The name of the plugin as defined in plugin.ini.


=====Remarks:=====


Remarks:
This function will tell Maxthon the next function call is from a plugin.<br /> This function is usually used before the <span class="keyword">window</span>.<span class="keyword">open</span>() method to bypass the Popup Blocker of Maxthon for the plugin.<br /><br />
This function will tell Maxthon the next function call is from a plugin.
This function is usually used before the window.open() method to bypass the Popup Blocker of Maxthon for the plugin.


=====Requirements:=====


Requirements:
Maxthon Version 1.2+<br /><br />
Maxthon Version 1.2+


=====Example:=====


Example:
<span class="keyword">external</span>.<span class="keyword">m2_callerName</span>(<span class="string">security_id</span>, <span class="string">"ViewSource!"</span>);<br /><span class="keyword">window</span>.<span class="keyword">open</span>(<span class="string">"about:blank"</span>);
external.m2_callerName(security_id, "ViewSource!");
window.open("about:blank");  


</div>


max_actSideBarItem(plugin_name)
====max_actSideBarItem(''plugin_name'')====
Parameters:
plugin_name : string
The name of the plugin as defined in plugin.ini.


Remarks:
<div class="indent">
This function will activate the sidebar plugins with the given name.


=====Parameters:=====


Requirements:
''plugin_name'' : string<br /> The name of the plugin as defined in plugin.ini.
Maxthon Version 1.2+


=====Remarks:=====


Example:
This function will activate the sidebar plugins with the given name. <br /><br />
[Demo 1]


external.max_actSideBarItem("Calculator++");
=====Requirements:=====


Maxthon Version 1.2+<br /><br />


=====Example:=====


[javascript:v() [Demo 1]]


max_modelessDialog(security_id, url, arguments, features, parent_window)
<span class="keyword">external</span>.<span class="keyword">max_actSideBarItem</span>(<span class="string">"Calculator++"</span>);
Parameters:
security_id : string
Maxthon's Security ID.


url : string
</div>
The url of modeless dialog content.


arguments : variant
<br /><br />
The arguments pass to the modeless dialog's window.dialogArguments object.


features : string
====max_modelessDialog(''security_id'', ''url'', ''arguments'', ''features'', ''parent_window'')====
A String that specifies the window ornaments for the dialog box.


parent_window : object
<div class="indent">
The parent window object of the dialog.


Remarks:
=====Parameters:=====
This function is almost the same as window.showModelessDialog() but with two more parameters.
With the security_id your plugin can bypass Maxthon's Popup Blocker.
With the parent_window you can make the dialog being a child of another tab's window.


''security_id'' : string<br /> Maxthon's Security ID.<br /><br />''url'' : string<br /> The url of modeless dialog content.<br /><br />''arguments'' : variant<br /> The arguments pass to the modeless dialog's '''window.dialogArguments''' object.<br /><br />''features'' : string<br /> A String that specifies the window ornaments for the dialog box.<br /><br />''parent_window'' : object<br /> The parent '''window''' object of the dialog.


Requirements:
=====Remarks:=====
Maxthon Version 1.2+


This function is almost the same as '''window.showModelessDialog()''' but with two more parameters.<br /> With the ''security_id'' your plugin can bypass Maxthon's Popup Blocker.<br /> With the ''parent_window'' you can make the dialog being a child of another tab's '''window'''.<br /><br />


Example:
=====Requirements:=====
external.max_modelessDialog(security_id, "about:blank", {"userid": 7, "key": "d3fe3asd"}, "status:no; help:no; resizable:yes; scroll:yes;", window);


Maxthon Version 1.2+<br /><br />


=====Example:=====


<span class="keyword">external</span>.<span class="keyword">max_modelessDialog</span>(<span class="string">security_id</span>, <span class="string">"about:blank"</span>, {"userid": 7, "key": "d3fe3asd"}, <span class="string">"status:no; help:no; resizable:yes; scroll:yes;"</span>, window);


get_tab(security_id, index)
</div>
Parameters:
security_id : string
Maxthon's Security ID.


index : integer
<br /><br />
The index of the tab to get.


====get_tab(''security_id'', ''index'')====


Remarks:
<div class="indent">
This function will get the window object of specified tab in Maxthon.
null will be returned if the tab does not exist.


=====Parameters:=====


Requirements:
''security_id'' : string<br /> Maxthon's Security ID.<br /><br />''index'' : integer<br /> The index of the tab to get.<br /><br />
Maxthon Version 1.0+


=====Remarks:=====


Example:
This function will get the '''window''' object of specified tab in Maxthon.<br /><span class="flag">null</span> will be returned if the tab does not exist.<br /><br />
var objTab=external.get_tab(security_id, 5);


=====Requirements:=====


Maxthon Version 1.0+<br /><br />


=====Example:=====


activate_tab(security_id, index)
<span class="keyword">var</span> objTab=<span class="keyword">external</span>.<span class="keyword">get_tab</span>(<span class="string">security_id</span>, <span class="number">5</span>);
Parameters:
security_id : string
Maxthon's Security ID.


index : integer
</div>
The index of the tab to be activated.


<br /><br />


Remarks:
====activate_tab(''security_id'', ''index'')====
This function will activate the specified tab in Maxthon.
Nothing will happen if the tab does not exist.


<div class="indent">


Requirements:
=====Parameters:=====
Maxthon Version 1.0+


''security_id'' : string<br /> Maxthon's Security ID.<br /><br />''index'' : integer<br /> The index of the tab to be activated.<br /><br />


Example:
=====Remarks:=====
external.activate_tab(security_id, 1);


This function will activate the specified tab in Maxthon.<br /> Nothing will happen if the tab does not exist.<br /><br />


=====Requirements:=====


Maxthon Version 1.0+<br /><br />


close_tab(security_id, index)
=====Example:=====
Parameters:
security_id : string
Maxthon's Security ID.


index : integer
<span class="keyword">external</span>.<span class="keyword">activate_tab</span>(<span class="string">security_id</span>, <span class="number">1</span>);
Integer. The index of the tab to close.


</div>


Remarks:
<br /><br />
This function will close the tab which index represents.
Nothing will happen if the tab does not exist.


====close_tab(''security_id'', ''index'')====


Requirements:
<div class="indent">
Maxthon Version 1.0+


=====Parameters:=====


Example:
''security_id'' : string<br /> Maxthon's Security ID.<br /><br />''index'' : integer<br /> Integer. The index of the tab to close.<br /><br />
external.close_tab(security_id, 0);


=====Remarks:=====


This function will close the tab which ''index'' represents.<br /> Nothing will happen if the tab does not exist.<br /><br />


=====Requirements:=====


readFile(security_id, plugin_name, file_name)
Maxthon Version 1.0+<br /><br />
Parameters:
security_id : string
Maxthon's Security ID.


plugin_name : string
=====Example:=====
The name of calling plugin as defined in plugin.ini


file_name : string
<span class="keyword">external</span>.<span class="keyword">close_tab</span>(<span class="string">security_id</span>, );
The file to read.


</div>


Remarks:
<br /><br />
This function can only be used in a plugin.
The function will return the file content in string when success.
If the plugin is not enabled or the plugin_name is not found, the function will fail and return null.


====readFile(''security_id'', ''plugin_name'', ''file_name'')====


Requirements:
<div class="indent">
Maxthon Version 1.0+


=====Parameters:=====


Example:
''security_id'' : string<br /> Maxthon's Security ID.<br /><br />''plugin_name'' : string<br /> The name of calling plugin as defined in plugin.ini<br /><br />''file_name'' : string<br /> The file to read.<br /><br />
var strFile=external.readFile(security_id, "Test plugin", "plugin.ini");


=====Remarks:=====


This function can only be used in a plugin.<br /> The function will return the file content in string when success.<br /> If the plugin is not enabled or the ''plugin_name'' is not found, the function will fail and return '''null'''.<br /><br />


=====Requirements:=====


Maxthon Version 1.0+<br /><br />


writeFile(security_id, plugin_name, file_name, content)
=====Example:=====
Parameters:
security_id : string
Maxthon's Security ID.


plugin_name : string
<span class="keyword">var</span> strFile=<span class="keyword">external</span>.<span class="keyword">readFile</span>(<span class="string">security_id</span>, <span class="string">"Test plugin"</span>, <span class="string">"plugin.ini"</span>);<br />
The name of calling plugin as defined in plugin.ini


file_name : string
</div>
The file to write.


content : string
<br /><br />
File content string to write.


====writeFile(''security_id'', ''plugin_name'', ''file_name'', ''content'')====


Remarks:
<div class="indent">
This function can only be used in a plugin.
This function will return true when success.
If the file is not found, the plugin is not enabled or the plugin_name is not found, the function will fail and return false.
If a file with the same name exists, it will be overwritten.


=====Parameters:=====


Requirements:
''security_id'' : string<br /> Maxthon's Security ID.<br /><br />''plugin_name'' : string<br /> The name of calling plugin as defined in plugin.ini<br /><br />''file_name'' : string<br /> The file to write.<br /><br />''content'' : string<br /> File content string to write.<br /><br />
Maxthon Version 1.0+


=====Remarks:=====


Example:
This function can only be used in a plugin.<br /> This function will return <span class="bool">true</span> when success.<br /> If the file is not found, the plugin is not enabled or the ''plugin_name'' is not found, the function will fail and return <span class="bool">false</span>.<br /><span class="warn">If a file with the same name exists, it will be overwritten.</span><br /><br />
external.writeFile(security_id, "Test plugin", "setting.ini", "username=abc\npass=qwrxcv");


=====Requirements:=====


Maxthon Version 1.0+<br /><br />


=====Example:=====


m2_readIni(security_id, plugin_name, file_name, section_name, key, default_value)
<span class="keyword">external</span>.<span class="keyword">writeFile</span>(<span class="string">security_id</span>, <span class="string">"Test plugin"</span>, <span class="string">"setting.ini"</span>, <span class="string">"username=abc\npass=qwrxcv"</span>);
Parameters:
security_id : string
Maxthon's Security ID.


plugin_name : string
</div>
The name of calling plugin as defined in plugin.ini.


file_name : string
<br /><br />
The name of the INI file to read.


section_name : string
====m2_readIni(''security_id'', ''plugin_name'', ''file_name'', ''section_name'', ''key'', ''default_value'')====
The INI section to read, without brackets [ ].


key : string
<div class="indent">
The key of the entry to read.


default_value : string
=====Parameters:=====
The default value to return if the key does not exist.


''security_id'' : string<br /> Maxthon's Security ID.<br /><br />''plugin_name'' : string<br /> The name of calling plugin as defined in plugin.ini.<br /><br />''file_name'' : string<br /> The name of the INI file to read.<br /><br />''section_name'' : string<br /> The INI section to read, without brackets [ ].<br /><br />''key'' : string<br /> The key of the entry to read.<br /><br />''default_value'' : string<br /> The default value to return if the key does not exist.<br /><br />


Remarks:
=====Remarks:=====
This function will read the value of key under section section_name in INI file file_name.
The INI file must be placed inside the folder of plugin plugin_name.
The value will be returned as a string if success.
If the file does not exist, the section does not exist or the key does not exist, the default_value will be returned.


This function will read the value of ''key'' under section ''section_name'' in INI file ''file_name''.<br /> The INI file must be placed inside the folder of plugin ''plugin_name''.<br /> The value will be returned as a '''string''' if success.<br /> If the file does not exist, the section does not exist or the key does not exist, the ''default_value'' will be returned.<br /><br />


Requirements:
=====Requirements:=====
Maxthon Version 1.0+


Maxthon Version 1.0+<br /><br />


Example:
=====Example:=====
var saveCount = external.m2_readIni(security_id, "TestPlugin", "settings.ini", "general", "saveCount", "0");


<span class="keyword">var</span> saveCount = <span class="keyword">external</span>.<span class="keyword">m2_readIni</span>(<span class="string">security_id</span>, <span class="string">"TestPlugin"</span>, <span class="string">"settings.ini"</span>, <span class="string">"general"</span>, <span class="string">"saveCount"</span>, <span class="string">"0"</span>);


</div>


<br /><br />


m2_writeIni(security_id, plugin_name, file_name, section_name, key, value)
====m2_writeIni(''security_id'', ''plugin_name'', ''file_name'', ''section_name'', ''key'', ''value'')====
Parameters:
security_id : string
Maxthon's Security ID.


plugin_name : string
<div class="indent">
The name of calling plugin as defined in plugin.ini.


file_name : string
=====Parameters:=====
The name of the INI file to write.


section_name : string
''security_id'' : string<br /> Maxthon's Security ID.<br /><br />''plugin_name'' : string<br /> The name of calling plugin as defined in plugin.ini.<br /><br />''file_name'' : string<br /> The name of the INI file to write.<br /><br />''section_name'' : string<br /> The INI section to write, without brackets [ ].<br /><br />''key'' : string<br /> The key of the entry to write.<br /><br />''value'' : string/integer<br /> The value to write.<br /><br />
The INI section to write, without brackets [ ].


key : string
=====Remarks:=====
The key of the entry to write.


value : string/integer
This function will write a ''key'' and ''value'' pair entry under section ''section_name'' in INI file ''file_name''.<br /> The INI file can only be writen inside the folder of plugin ''plugin_name''.<br /> If the file does not exist, the section does not exist or the key does not exist, they will be created automatically.<br /> This function will return <span class="bool">true</span> when success and <span class="bool">false</span> when failed.<br /><br />
The value to write.


=====Requirements:=====


Remarks:
Maxthon Version 1.0+<br /><br />
This function will write a key and value pair entry under section section_name in INI file file_name.
The INI file can only be writen inside the folder of plugin plugin_name.
If the file does not exist, the section does not exist or the key does not exist, they will be created automatically.
This function will return true when success and false when failed.


=====Example:=====


Requirements:
<span class="keyword">external</span>.<span class="keyword">m2_writeIni</span>(<span class="string">security_id</span>, <span class="string">"TestPlugin"</span>, <span class="string">"settings.ini"</span>, <span class="string">"general</span>", <span class="string">"saveCount"</span>, <span class="number">25</span>);
Maxthon Version 1.0+


</div>


Example:
<br /><br />
external.m2_writeIni(security_id, "TestPlugin", "settings.ini", "general", "saveCount", 25);

Version du 15 août 2006 à 18:32

Version: 2.0.1
Last Modified: 2006-07-17 4:24 PM

Overview

Maxthon Browser has extended the DHTML support of IE by adding several new extensions which can be called by scripting language such as Javascript and VBScript.

These APIs can be called via the window.external object in a HTML page or a script plugin made for Maxthon Browser.

Some functions will require a security_id as first parameter. These Functions can only be used by Plugins.
In order to get a security_id for your plugin, you can do the following:

Button Plugins

Put a %max_security_id in your script, such as:

var security_id=%max_security_id;

Then you can use the variable security_id in your script.

Sidebar Plugins

A file named max.src will be created in your plugin's folder, include this file in your HTML file:

<script type="text/javascript" src="max.src"></script>

Then use variable max_security_id for security id parameter in your script.

Index

Extended Properties
  • [#max_version max_version] : Get current version of Maxthon Browser
  • [#max_language_id max_language_id] : Get current language id of Maxthon UI
  • [#current_tab current_tab (cur_sel)] : Get current tab's index
  • [#tab_count tab_count] : Get current opened tabs' count
General Methods
  • [#addFavorite addFavorite()] : Call the Add Favorites dialog
  • [#addProxy addProxy()] : Call the Add Proxy dialog
  • [#addFilter addFilter()] : Call the Add Filter dialog
  • [#max_addProxyProvider max_addProxyProvider()] : Call the Add Proxy Provider dialog
  • [#m2_run_cmd m2_run_cmd()] : Execute Maxthon functions by Command ID
  • [#m2_search_text m2_search_text()] : Get search string in Maxthon's Search Box
  • [#m2_plugin_folder m2_plugin_folder()] : Get local folder path of a plugin
Tab Related Methods
  • [#get_tab get_tab()] : Get a tab's window object by index
  • [#activate_tab activate_tab()] : Activate a tab by index
  • [#close_tab close_tab()] : Close a tab by index
File Related Methods
  • [#readFile readFile()] : Read a file's content
  • [#writeFile writeFile()] : Write data to a file
  • [#m2_readIni m2_readIni()] : Read an INI file
  • [#m2_writeIni m2_writeIni()] : Write to an INI file

Extended Properties

max_version

Remarks:

This property will return a string of Maxthon Browser Version Number.
The return string is formatted like "2.1.0.600".

It's sugguested use this property to determine whether Maxthon Browser is running.

Requirements:
Maxthon Version 2.0+

Example:

[javascript:v() [Demo 1]]

alert('Maxthon Version: '+external.max_version);

max_language_id

Remarks:

This property will return current language id of Maxthon Browser.

The Language ID has change to use Language Identifiers defined in Microsoft Windows since Maxthon Browser 2.0.
A list of Maxthon's Language IDs can be found at:
http://msdn.microsoft.com/library/?url=/library/en-us/intl/nls_238z.asp

Requirements:
Maxthon Version 1.0+

Example:

[javascript:v() [Demo 1]]

alert('Language ID='+external.max_language_id);

current_tab (formerly cur_sel ) Not Implemented

Remarks:
This property will return an integer number as the index of the tab which is activated.
null will be returned if there is no tab opened.
current_tab is introduced in Maxthon 2.0 as a replacement of cur_sel because the old property name is too obscure to understand.

Requirements:
Maxthon Version 2.0+ (use cur_sel for 1.x versions)

Example:

[javascript:v() [Demo 1]]

alert('Current Tab Index: '+external.current_tab);

tab_count

Remarks:
This property will return current tab count as an integer.

Requirements:
Maxthon Version 1.0+

Example:

[javascript:v() [Demo 1]]

alert('Tabs Count: '+external.tab_count);



General Methods

addFavorite(url [, title])

Parameters:

url : string
The url to add.

title : string
Optional. The title of the url.

Remarks:
Show the Add Favorite dialog to ask user to add a new Favorites Item.
This function will return false if user cancelled this operation.

Requirements:
Maxthon Version 1.0+

Example:

[javascript:v() [Demo 1]]

external.addFavorite("http://www.maxthon.com");

[javascript:v() [Demo 2]]

external.addFavorite("http://www.maxthon.com", "Maxthon Official Site");

addProxy(name, address, type)

Parameters:

name : string
The display name of proxy.

address : string
The IP address or Domain name of proxy.

type : integer
A number indicates the speed rating of proxy.
= HTTP Proxy, 1 = SOCKS4A Proxy, 2 = SOCKS5 Proxy

Remarks:
Add a new proxy into Maxthon's proxy list. A dialog will be shown to the user.
This function will return false if user cancelled this operation.

Requirements:
Maxthon Version 2.0+

Example:

[javascript:v() [Demo 1]]

external.addProxy("My proxy","192.168.1.0:8080", 1);

addFilter(url_mask, type)

Parameters:

url_mask : string
Address mask to match blocked addresses. Supports Regular Expression.

type : integer
A number indicates which Filter list to add.
= Popup Filter, 1 = Content Filter

Remarks:
Add a new filter policy into Maxthon. A dialog will be shown to the user.
This function will return false if user cancelled this operation.

Requirements:
Maxthon Version 2.0+

Example:

[javascript:v() [Demo 1]]

external.addFilter("http://www.advertisement.com/img/*", );

max_addProxyProvider(URL)

Parameters:

URL : string
The URL of proxy list file. File format please refer to [proxyprovider.htm this document].

Remarks:
Add a new Proxy Provider into Maxthon Broser. A dialog will be shown to the user.
This function will return false if user cancelled this operation.

Requirements:
Maxthon Version 2.0+

Example:

[javascript:v() [Demo 1]]

external.max_addProxyProvider("http://www.freeproxy.cn/m2proxy/proxylist.xml");

m2_run_cmd(security_id, command_id)

Parameters:

security_id : string
Maxthon's Security ID.

command_id : integer
The internal command ID of Maxthon.

Remarks:
This function will call a Maxthon's command with specified command_id.
Most usable Command IDs can be found in the language file inside Maxthon's language folder.
Command ID might be different between versions. Please do not use this function if not required.

Requirements:
Maxthon Version 1.0+

Example:

external.m2_run_cmd(security_id, 32772); // Open a Blank Page

m2_search_text(security_id)

Parameters:

security_id : string
Maxthon's Security ID.

Remarks:
This function will return the text in Maxthon's Search Box as a string.

Requirements:
Maxthon Version 1.2+

Example:

var searchText=external.m2_search_text(security_id);

m2_plugin_folder(security_id, plugin_name)

Parameters:

security_id : string
Maxthon's Security ID.

plugin_name : string
The name of the plugin as defined in plugin.ini.

Remarks:
This function will return the local folder path of specified plugin as a string.

Requirements:
Maxthon Version 1.2+

Example:

var pluginPath=external.m2_plugin_folder(security_id, "ViewSource!");

m2_callerName(security_id, plugin_name)

Parameters:

security_id : string
Maxthon's Security ID.

plugin_name : string
The name of the plugin as defined in plugin.ini.

Remarks:
This function will tell Maxthon the next function call is from a plugin.
This function is usually used before the window.open() method to bypass the Popup Blocker of Maxthon for the plugin.

Requirements:
Maxthon Version 1.2+

Example:

external.m2_callerName(security_id, "ViewSource!");
window.open("about:blank");

max_actSideBarItem(plugin_name)

Parameters:

plugin_name : string
The name of the plugin as defined in plugin.ini.

Remarks:
This function will activate the sidebar plugins with the given name. 

Requirements:
Maxthon Version 1.2+

Example:

[javascript:v() [Demo 1]]

external.max_actSideBarItem("Calculator++");



max_modelessDialog(security_id, url, arguments, features, parent_window)

Parameters:

security_id : string
Maxthon's Security ID.

url : string
The url of modeless dialog content.

arguments : variant
The arguments pass to the modeless dialog's window.dialogArguments object.

features : string
A String that specifies the window ornaments for the dialog box.

parent_window : object
The parent window object of the dialog.

Remarks:
This function is almost the same as window.showModelessDialog() but with two more parameters.
With the security_id your plugin can bypass Maxthon's Popup Blocker.
With the parent_window you can make the dialog being a child of another tab's window.

Requirements:
Maxthon Version 1.2+

Example:

external.max_modelessDialog(security_id, "about:blank", {"userid": 7, "key": "d3fe3asd"}, "status:no; help:no; resizable:yes; scroll:yes;", window);



get_tab(security_id, index)

Parameters:

security_id : string
Maxthon's Security ID.

index : integer
The index of the tab to get.

Remarks:
This function will get the window object of specified tab in Maxthon.
null will be returned if the tab does not exist.

Requirements:
Maxthon Version 1.0+

Example:

var objTab=external.get_tab(security_id, 5);



activate_tab(security_id, index)

Parameters:

security_id : string
Maxthon's Security ID.

index : integer
The index of the tab to be activated.

Remarks:
This function will activate the specified tab in Maxthon.
Nothing will happen if the tab does not exist.

Requirements:
Maxthon Version 1.0+

Example:

external.activate_tab(security_id, 1);



close_tab(security_id, index)

Parameters:

security_id : string
Maxthon's Security ID.

index : integer
Integer. The index of the tab to close.

Remarks:
This function will close the tab which index represents.
Nothing will happen if the tab does not exist.

Requirements:
Maxthon Version 1.0+

Example:

external.close_tab(security_id, );



readFile(security_id, plugin_name, file_name)

Parameters:

security_id : string
Maxthon's Security ID.

plugin_name : string
The name of calling plugin as defined in plugin.ini

file_name : string
The file to read.

Remarks:
This function can only be used in a plugin.
The function will return the file content in string when success.
If the plugin is not enabled or the plugin_name is not found, the function will fail and return null.

Requirements:
Maxthon Version 1.0+

Example:

var strFile=external.readFile(security_id, "Test plugin", "plugin.ini");



writeFile(security_id, plugin_name, file_name, content)

Parameters:

security_id : string
Maxthon's Security ID.

plugin_name : string
The name of calling plugin as defined in plugin.ini

file_name : string
The file to write.

content : string
File content string to write.

Remarks:
This function can only be used in a plugin.
This function will return true when success.
If the file is not found, the plugin is not enabled or the plugin_name is not found, the function will fail and return false.
If a file with the same name exists, it will be overwritten.

Requirements:
Maxthon Version 1.0+

Example:

external.writeFile(security_id, "Test plugin", "setting.ini", "username=abc\npass=qwrxcv");



m2_readIni(security_id, plugin_name, file_name, section_name, key, default_value)

Parameters:

security_id : string
Maxthon's Security ID.

plugin_name : string
The name of calling plugin as defined in plugin.ini.

file_name : string
The name of the INI file to read.

section_name : string
The INI section to read, without brackets [ ].

key : string
The key of the entry to read.

default_value : string
The default value to return if the key does not exist.

Remarks:
This function will read the value of key under section section_name in INI file file_name.
The INI file must be placed inside the folder of plugin plugin_name.
The value will be returned as a string if success.
If the file does not exist, the section does not exist or the key does not exist, the default_value will be returned.

Requirements:
Maxthon Version 1.0+

Example:

var saveCount = external.m2_readIni(security_id, "TestPlugin", "settings.ini", "general", "saveCount", "0");



m2_writeIni(security_id, plugin_name, file_name, section_name, key, value)

Parameters:

security_id : string
Maxthon's Security ID.

plugin_name : string
The name of calling plugin as defined in plugin.ini.

file_name : string
The name of the INI file to write.

section_name : string
The INI section to write, without brackets [ ].

key : string
The key of the entry to write.

value : string/integer
The value to write.

Remarks:
This function will write a key and value pair entry under section section_name in INI file file_name.
The INI file can only be writen inside the folder of plugin plugin_name.
If the file does not exist, the section does not exist or the key does not exist, they will be created automatically.
This function will return true when success and false when failed.

Requirements:
Maxthon Version 1.0+

Example:

external.m2_writeIni(security_id, "TestPlugin", "settings.ini", "general", "saveCount", 25);