<doc>
  <legacy_id>3033</legacy_id>
  <name>revBrowserOpen</name>
  <type>function</type>
  <syntax>
    <example>revBrowserOpen(<i>windowId</i> [, <i>url</i> ] )</example>
    <example>XBrowser_Open <i>windowId </i>[, <i>url </i>]</example>
  </syntax>
  <library>Browser Library</library>
  <objects>
  </objects>
  <synonyms>
    <synonym>XBrowser_Open</synonym>
  </synonyms>
  <classification>
  </classification>
  <references>
    <command tag="revBrowserNavigate">revBrowserNavigate Command</command>
    <command tag="revBrowserStop">revBrowserStop Command</command>
    <command tag="XBrowser_Focus">XBrowser_Focus Command</command>
    <command tag="revBrowserPrint">revBrowserPrint Command</command>
    <command tag="revBrowserMakeTextBigger">revBrowserMakeTextBigger Command</command>
    <command tag="revBrowserSet">revBrowserSet Command</command>
    <command tag="revBrowserClose">revBrowserClose Command</command>
    <command tag="XBrowser_Init">XBrowser_Init Command</command>
    <message tag="browserOver">browserOver Message</message>
    <message tag="browserNewInstance">browserNewInstance Message</message>
    <message tag="browserDownloadRequest">browserDownloadRequest Message</message>
    <message tag="browserNavigateCompleteFrame">browserNavigateCompleteFrame Message</message>
    <message tag="browserNewUrlWindow">browserNewUrlWindow Message</message>
  </references>
  <history>
    <introduced version="2.8.1">Added.</introduced>
  </history>
  <platforms>
    <mac/>
    <windows/>
  </platforms>
  <classes>
    <desktop/>
  </classes>
  <security>
    <network/>
  </security>
  <summary>Opens and initialises a new browser</summary>
  <examples>
    <example>local tBrowserId</p><p>put revBrowserOpen(the windowId of this stack, "http://www.runrev.com") into tBrowserId</p><p>if tBrowserId is not an integer then</p><p>  answer "Failed to open browser"</p><p>end if</p><p/><p>-- Using the old XBrowser syntax</p><p>XBrowser_Open the windowId of this stack, "http://www.runrev.com"</p><p>put the result into tBrowserId</example>
  </examples>
  <description>
    <p>The <b>revBrowserOpen</b> function opens a new browser in the window with the given <i>windowId</i>. If a <i>url</i> is given, the new browser immediately navigates to this url.</p><p/><p><b>Parameters:</b></p><p>The <i>windowId </i>is the operating system's ID for a stack window as given in the <property tag="windowID">windowID property</property>.</p><p>The <i>url </i>is any url that can be accessed by the browser object in use.</p><p/><p><b>Value:</b></p><p>The <b>revBrowserOpen</b> function returns a value. If successful this will be an integer browser instance id, if unsuccessful, the result will be empty.</p><p/><p><img src="202652"/> <b>Cross-platform note:</b> On Windows systems, the Internet Explorer browser is used by the <b>revBrowserOpen</b> function while on OS X Systems the Safari browser is used. To ensure cross-platform compatibility, don't use features that are not supported by both browsers, eg "ftp://" urls, which are only supported by Internet Explorer. </p><p/><p>It is no longer necessary to initialise the Browser using<b> XBrowser_Init</b>, and this command now does nothing, but is still included to prevent legacy code causing script errors.</p><p/><p>There is a <b>sample stack</b> for revBrowser at the following location in the LiveCode folder: Resources/Examples/Browser Samper.rev. This stack demonstrates, with many examples, how to use browser objects in an application.</p><p/><p><b>General Notes on Using the Browser Library</b></p><p/><p>The older <b>XBrowser</b> forms of all Browser library commands, functions and messages have been retained for backwards compatiblity and these are documented as synonyms. The XBrowser functions are <b>deprecated</b>, this means that they should not normally be used in new code except for the maintainance of older applications that depend on them.</p><p/><p>The <b>syntax</b> of these older functions differs slightly from that documented and used in the new functions. </p><p/><p>The <b>revBrowser</b> functions (with the exception of <b>revBrowserOpen</b>) all require a browser id, which tells LiveCode which browser object to act upon. This id is returned by the revBrowserOpen function and should be saved in the calling application. The browser id is <b>always the first parameter</b> given to any revBrowser function and always the first parameter passed to any browser callback.</p><p/><p>The deprecated <b>XBrowser</b> functions can <b>optionally</b> take a browser id parameter. If the browser id is not given, then the last browser created by the <b>XBrowser_Open</b> command is used. The browser id is always the <b>last parameter</b> passed to an XBrowser function.</p><p/><p>Do not <b>mix the revBrowser and XBrowser functions</b> in an application. The two sets of functions have not been designed to be compatible with each other and mixing them will almost certainly cause unexpected results.</p><p/><p>The default rect of a new browser instance is 0,0,0,0. To change this, set the "rect" property using the <command tag="revBrowserSet">revBrowserSet</command> command.</p><p/><p>The <b>callbacks</b> sent by the browser depend on whether the browser was opened using revBrowserOpen or XBrowser_Open. If revBrowserOpen was used, the callbacks prefixed with "browser" are used, otherwise, those prefixed by "XBrowser_" are used.</p><p/><p>It is currently possible to cancel browser operations by setting the <b>browserCancel</b> global variable to true. If using the XBrowser functions, then the global variable <b>XBrowserCancel</b> should be used instead.</p><p/><p>The browser library functions will throw an execution error if they encounter a problem. These can be caught by handling the <message tag="errorDialog">errorDialog message</message> or by using a <control_st tag="try">try / catch block</control_st>. In general there is no need to check the <function tag="result">result</function>, as nearly all the commands and functions put empty into it. </p>
  </description>
</doc>