Name: revBrowserSet

Synonyms: xbrowser_set

Type: command

Syntax: revBrowserSet <instanceId>, <propertyName>, <propertyValue>

Syntax: XBrowser_Set <propertyName>, <propertyValue> ,[<instanceid>]

Summary:
Sets a given property of a specified browser.

Introduced: 2.8.1

OS: mac, windows

Platforms: desktop

Security: network

Example:
revBrowserSet tBrowserId, "url", "http://www.livecode.com"

Example:
answer file "Please choose a file to display"
if the result is not "cancel" then
  put it into tFile
  put revBrowserSet tBrowserID,"url","file://" & tFile     
end if

Parameters:
instanceId:
The integer identifier of a browser object.

propertyName (enum):
The name of the property to set. See below for a full list.

-   "url": 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://"
-   "rect": 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.
-   "selected": 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. 
-   "messages": Whether the browser sends "advanced" callback messages.
    See the note below for more information. The default is false.
-   "offline": true if the browser should run in offline mode, ie it
    does not retrieve information from the internet. The default is
    false. 
-   "contextmenu": true if the browser should show a right-click context
    menu. The default is false.
-   "visible": true if the browser is visible. The default is true.
-   "newwindow": true if the browser should allow pages to open new
    windows. The default is false.
-   "htmltext": Sets the html source of the document being displayed.
    The default is empty.
-   "scrollbars": true if the browser should display scrollbars. The
    default is true.
-   "showborder": true if the browser should be drawn with a border. The
    default is false.
-   "browser": Which browser should be used. Currently this can be "IE"
    on Windows and "Safari" on OS X.
-   "hscroll": The number of pixels to the right that the browser is
    scrolled. The default is zero.
-   "vscroll": The number of pixels down that the browser is scrolled.
    The default is zero.
-   "instance": 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.
-   "useragent": 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).
-   "windowID": Attaches an instance of a browser to a stack


propertyValue:
The value to set the property to.

The result:
The <revBrowserSet> command puts empty into the result if successful.

Description:
The <revBrowserSet> command sets the value of the property
<propertyName> to the value <propertyValue> for the browser specified by
the <instanceId>.

>*Note:*  The "advanced" callback messages are: <browserClick> ,
> <browserOut> and <browserOver> . These messages are only sent when the
> "messages" property is set to true. The other callback messages are
> always sent.

>*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 <find> <command>.

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. 

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.

For example, to toggle the resizable property of a stack hosting a
browser use the following code:

    revBrowserSet pBrowserId, "windowId", 0
    set the resizable of stack pBrowserStack to pNewResizeableValue
    revBrowserSet pBrowserId, "windowId", the windowId of stack
    pBrowserStack 

Cross Platform Caution: 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:

    local sBrowserId

    on browserOpen
        put revBrowserOpen(the windowId \
          of me, http://www.livecode.com) into sBrowserId
        if the platform is MacOS then
            send browserDisableScrollbars to me in 1 second
        else
            revBrowserSet sBrowserId, scrollbars, false
        end if
    end browserOpen

    on browserDisableScrollbars
        revBrowserSet sBrowserId, scrollbars, false
    end browserDisableScrollbars

    on browserToggleScrollbars
        revBrowserSet sBrowserId, scrollbars, \
          (not(revBrowserGet(sBrowserId, scrollbars))) 
    end browserToggleScrollbars


>*Note:*  For general information on using the browser library, see the
> notes in the <revBrowserOpen> <function> reference.

Changes:
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.

References: revBrowserSnapshot (command), find (command), command (glossary),
function (glossary), revBrowserInstances (function),
revBrowserOpen (function), revBrowserGet (function),
browserOver (message), browserClick (message),
browserNewInstance (message), queryRecordChanged (message),
browserNewUrlWindow (message), browserOut (message)

