<doc>
	<legacy_id>3047</legacy_id>
	<name>revBrowserSet</name>
	<type>command</type>

	<syntax>
		<example>revBrowserSet <i>instanceId</i>, <i>propertyName</i>,
<i>propertyValue</i></example>
		<example>XBrowser_Set<i> propertyName, propertyValue ,</i>[<i> instanceid
</i>]</example>
	</syntax>

	<synonyms>
		<synonym>XBrowser_Set</synonym>
	</synonyms>

	<summary>Sets a given property of a specified browser.</summary>

	<examples>
<example>revBrowserSet tBrowserId, "url", "http://www.runrev.com"</example>
<example><p>answer file "Please choose a file to display"</p><p>if theresult
is not "cancel" then</p><p>  put it into tFile</p><p>  put revBrowserSet
tBrowserID,"url","file://" &amp; tFile     </p><p>end
if</p></example>
	</examples>

	<history>
		<introduced version="2.8.1">Added.</introduced>
		<deprecated version=""></deprecated>
		<removed version=""></removed>
		<changed version="4.6.2">userAgent property added for Mac</changed>
		<experimental version=""></experimental>
		<nonexperimental version=""></nonexperimental>
	</history>

	<objects>
	</objects>

	<platforms>
		<mac/>
		<windows/>
	</platforms>

	<classes>
		<desktop/>
	</classes>

	<security>
		<network/>
	</security>


	<classification>
	</classification>

	<references>
		<function tag="revBrowserGet">revBrowserGet function</function>
		<function tag="revBrowserOpen">revBrowserOpen function</function>
		<function tag="revBrowserInstances">revBrowserInstances
function</function>
		<command tag="revBrowserSnapshot">revBrowserSnapshot command</command>
		<message tag="queryRecordChanged">queryRecordChanged message</message>
		<message tag="browserOver">browserOver message</message>
		<message tag="browserNewInstance">browserNewInstance message</message>
		<message tag="browserNewUrlWindow">browserNewUrlWindow message</message>
	</references>

	<description>
	<overview>The <b>revBrowserSet</b> command sets the value of the property
<i>propertyName</i> to the value <i>propertyValue</i> for the browser
specified by the <i>instanceId</i>.</overview>

		<parameters>
  <parameter>
    <name>instanceId</name>
    <description>The integer identifier of a browser object.</description>
  </parameter>
  <parameter>
    <name>propertyName</name>
    <description>The name of the property to set. See below for a full
list.</description>
    <options title="">
      <option>
        <item>url</item>
        <description>The url being displayed by the browser. The default is
empty. The URL can be a web page, beginning "http://", or a local file,
beginning "file://"</description>
      </option>
      <option>
        <item>rect</item>
        <description>The rect of the browser object. The default is 0,0,0,0
so it is necessary to set the rect of a newly created browser before it will
appear to be visible.</description>
      </option>
      <option>
        <item>selected</item>
        <description>The selected text of the browser. The default is empty.
Repeatedly setting the selected allows you to iterate through the matches in
the browser document. See the note below for more information.</description>
      </option>
      <option>
        <item>messages</item>
        <description>Whether the browser sends "advanced" callback messages.
See the note below for more information. The default is false.</description>
      </option>
      <option>
        <item>offline</item>
        <description>true if the browser should run in offline mode, ie it
does not retrieve information from the internet. The default is
false.</description>
      </option>
      <option>
        <item>contextmenu</item>
        <description>true if the browser should show a right-click context
menu. The default is false.</description>
      </option>
      <option>
        <item>visible</item>
        <description>true if the browser is visible. The default is
true.</description>
      </option>
      <option>
        <item>newwindow</item>
        <description>true if the browser should allow pages to open new
windows. The default is false.</description>
      </option>
      <option>
        <item>htmltext</item>
        <description>Sets the html source of the document being displayed.
The default is empty.</description>
      </option>
      <option>
        <item>scrollbars</item>
        <description>true if the browser should display scrollbars. The
default is true.</description>
      </option>
      <option>
        <item>showborder</item>
        <description>true if the browser should be drawn with a border. The
default is false.</description>
      </option>
      <option>
        <item>browser</item>
        <description>Which browser should be used. Currently this can be
"IE" on Windows and "Safari" on OS X.</description>
      </option>
      <option>
        <item>hscroll</item>
        <description>The number of pixels to the right that the browser is
scrolled. The default is zero.</description>
      </option>
      <option>
        <item>vscroll</item>
        <description>The number of pixels down that the browser is scrolled.
The default is zero. </description>
      </option>
      <option>
        <item>instance</item>
        <description>Set the active browser instance. This property is
deprecated and is only available when using the XBrowser_Set synonym. There
is no longer a concept of "active browser instance" as the instance id is
required by all revBrowser functions.</description>
      </option>
      <option>
        <item>useragent</item>
        <description>MAC ONLY. If propertyValue is non-empty the browser
instance uses that string instead of the default for the User-Agent header
transmitted to the web server. If propertyValue is empty the browser
instance uses the default user agent string (which is determined by the
browser the URL that is being requested).</description>
      </option>
      <option>
        <item>windowID</item>
        <description>Attaches an instance of a browser to a
stack</description>
      </option>
    </options>
  </parameter>
  <parameter>
    <name>propertyValue</name>
    <description>The value to set the property to.</description>
  </parameter>		</parameters>

	<value>The <b>revBrowserSet</b> command puts empty into the result if
successful. </value>
	<comments><note> The "advanced" callback messages are: <message tag="browserClick">browserClick</message>
, <message tag="browserOut">browserOut</message> and <message tag="browserOver">browserOver</message>
. These messages are only sent when
the "messages" property is set to true. The other callback messages are
always sent.<p></note><p></p><note> Setting the selected property selects
the first instance of that text. Setting the property repeatedly to the same
value will cycle through each occurrence of the value. Setting the selected
to empty or to a string not present in the current document  will reset the
selected text, ie subsequently setting the selected to any string will
select the first occurrence again. This behavior is similar to that of the
<command tag="find">find
command</command>.</note><p></p><p></p><change>There is a long standing
issue with revBrowser that causes browser instances to be lost whenever the
stack it is attached to has its window re-created. Previously, cases where
this would occur had to be avoided when a browser was present on a
stack.<p></change><p>To resolve this problem a new property was added in
version 4.5.1 to browser instances  windowId. The windowId property allows
the stack to which a browser instance is attached to be changed after it has
been created.</p><p></p><p>If the windowId is set to 0, the browser instance
is temporary hidden. If the windowId is set to a valid stack windowId, the
browser instance will move to that stack.</p><p></p><p>For example, to
toggle the resizable property of a stack hosting a browser use the following
code:</p><p></p><p>&#9;revBrowserSet pBrowserId, "windowId", 0</p><p>&#9;set
the resizable of stack pBrowserStack to
pNewResizeableValue</p><p>&#9;revBrowserSet pBrowserId, "windowId", the
windowId of stack pBrowserStack</p><p></p><p><b>Cross Platform Caution</b>:
Due to a limitation in the current browser implementation, the behavior of
the scrollbars property is slightly different on Windows and OS X. In
particular, under OS X, when navigating to a page for the first time after
disabling scrollbars, revBrowser won't allow you to turn scrollbars back on.
The way to work around this and create a browser that allows scrollbars to
be toggled on both platforms is like this:</p><p></p><p>local
sBrowserId</p><p></p><p>on browserOpen</p><p>  put revBrowserOpen(the
windowId of me, http://www.runrev.com) into sBrowserId</p><p>  if the
platform is MacOS then</p><p>    send browserDisableScrollbars to me in 1
second</p><p>  else</p><p>    revBrowserSet sBrowserId, scrollbars,
false</p><p>  end if</p><p>end browserOpen</p><p></p><p>on
browserDisableScrollbars</p><p>  revBrowserSet sBrowserId, scrollbars,
false</p><p>end browserDisableScrollbars</p><p></p><p>on
browserToggleScrollbars</p><p>  revBrowserSet sBrowserId, scrollbars,
(not(revBrowserGet(sBrowserId, scrollbars)))</p><p>end
browserToggleScrollbars</p><p></p><p></p><p></p><note> For general
information on using the browser library, see the notes in the <function tag="revBrowserOpen">revBrowserOpen function</function>
reference.</note><p>&#9;</p></comments>
	</description>
</doc>
