Applet (class)
public final Applet {inherits AppletRemoteInterface}
Package: CURL.ENGINE.APPLET

An object representing the current applet, and all of its state, and which can be used to interact with the current browser.

Notes

The current Applet is accessible via {get-the-applet}.

Note that some of the state for the current applet is actually split out into a Document object, which is accessible via {get-the-applet}.document.

Properties
applet-id:An integer identifying an applet that is unique across applets with a given Applet.helper-id.
field public constant Applet.applet-id:int
document:The Document used by this applet.
accessor public Applet.document:Document
effective-url:
accessor public Applet.effective-url:Url
helper-id:An integer identifying a helper engine that is globally unique across engines in the Curl® Runtime Environment.
field public constant Applet.helper-id:int
inline-remote-connection:
accessor public final Applet.inline-remote-connection:RemoteConnection
inline-remote-connection-or-null:
field public-get private-set Applet.inline-remote-connection-or-null:#RemoteConnection
launch-handler:A handler which will be invoked each time the launching of this instance of this detached applet is requested.
field public Applet.launch-handler:#{proc-type {url:Url}:void} =null
parent-invoke-ready-callback:Callback that is called when Applet.parent-invoke-async is ready to be called.
accessor public Applet.parent-invoke-ready-callback:#{proc-type {}:void}
setter public Applet.parent-invoke-ready-callback:#{proc-type {}:void}
parent-invoke-ready?:Indicates if Applet.parent-invoke-async is ready to be called.
accessor public Applet.parent-invoke-ready?:bool
parent-url:The Url of the page which contains the applet.
accessor public Applet.parent-url:#Url
url:The Url used by this applet.
field public-get private-set Applet.url:Url ={url "curl://string/"}
Class Procedures
applet-invoke-handler-for-object:Create a handler to use with Applet.register-applet-invoke-handler that will allow JavaScript in a web browser to call the methods defined on an Object.
public {Applet.applet-invoke-handler-for-object
    object:Object
}:{proc-type {name:String, ...:JsonValue}:JsonValue}
default-applet-invoke-verifier:Implement the default verifier used when a null is passed to Applet.register-applet-invoke-handler.
public {Applet.default-applet-invoke-verifier}:bool
Methods
abort:Cancels applet elaboration without killing the applet.
public {Applet.abort}:void
allow-multiple-instances:Allow multiple instances of this detached applet to be launched.
public {Applet.allow-multiple-instances}:void
become-sticky:Mark this applet as sticky.
public {Applet.become-sticky}:void
browse-backward:Ask the browser to move backward in its history list.
public {Applet.browse-backward
    offset:int = 1,
    target:String = "_self"
}:void
browse-forward:Ask the browser to move forward in its history list.
public {Applet.browse-forward
    offset:int = 1,
    target:String = "_self"
}:void
browse-offset:Ask the browser to move forward or backward in its history list.
public {Applet.browse-offset offset:int, target:String = "_self"}:void
browse-url:Ask the browser to browse a given Url.
public {Applet.browse-url url:Url, target:String = "_self"}:void
browse-url-post:Ask the browser to browse a given Url, doing a post, submitting the given data in the process.
public {Applet.browse-url-post
    target:String = "_self",
    http-url:Url,
    request-data:HttpRequestData,
    request-headers:#HttpRequestHeaders = null
}:void
flush:Pauses applet elaboration to allow events to be processed.
public {Applet.flush}:void
parent-invoke-async:Call a function in the parent of this applet.
public {Applet.parent-invoke-async
    finish-proc:#{proc-type {exception:#Exception, result:JsonValue}:void} = null,
    method-name:String,
    ...:JsonValue
}:void
register-applet-invoke-handler:Register a handler for 'applet_invoke' JavaScript calls from the web browser or parent applet.
public {Applet.register-applet-invoke-handler
    handler:#{proc-type {name:String, ...:JsonValue}:JsonValue},
    verifier:#{proc-type {}:bool} = null
}:void
register-resume-proc:
deprecated public {Applet.register-resume-proc
    new-proc:{proc-type {}:void}
}:void
register-suspend-proc:
deprecated public {Applet.register-suspend-proc
    new-proc:{proc-type {}:void}
}:void
set-purge-factor:
public {Applet.set-purge-factor purge-factor:Percent}:void
set-status:Ask the browser to change the contents of its status bar.
public {Applet.set-status status:String}:void
set-title:Ask the browser to change the contents of its title bar.
public {Applet.set-title title:String}:void
unregister-resume-proc:
deprecated public {Applet.unregister-resume-proc
    old-proc:{proc-type {}:void}
}:void
unregister-suspend-proc:
deprecated public {Applet.unregister-suspend-proc
    old-proc:{proc-type {}:void}
}:void
Methods inherited from Object: object-describe, object-describe-for-debugging, object-serialize

Property Details
applet-id (field)
public constant Applet.applet-id:int

An integer identifying an applet that is unique across applets with a given Applet.helper-id.


document (accessor)
accessor public Applet.document:Document

The Document used by this applet.

Description

An applet contains one Document representing the instantiated output of the applet's source code.

effective-url (accessor)
accessor public Applet.effective-url:Url
This item is unsupported and reserved for internal use.

helper-id (field)
public constant Applet.helper-id:int

An integer identifying a helper engine that is globally unique across engines in the Curl® Runtime Environment.


inline-remote-connection (accessor)
accessor public final Applet.inline-remote-connection:RemoteConnection
This item is unsupported and reserved for internal use.

inline-remote-connection-or-null (field)
public-get private-set Applet.inline-remote-connection-or-null:#RemoteConnection
This item is unsupported and reserved for internal use.

launch-handler (field)
public Applet.launch-handler:#{proc-type {url:Url}:void} =null

A handler which will be invoked each time the launching of this instance of this detached applet is requested.

Description

Normally, only a single instance of any given detached applet will exist at any one time. However, each launch attempt will cause this handler to be invoked in that instance.

Notes

Only meaningful for detached applets.

parent-invoke-ready-callback (accessor)
accessor public Applet.parent-invoke-ready-callback:#{proc-type {}:void}
setter public Applet.parent-invoke-ready-callback:#{proc-type {}:void}

Callback that is called when Applet.parent-invoke-async is ready to be called.

Notes

If Applet.parent-invoke-ready? is already true when this is set, the callback will be called immediately.
Introduced in: version 6.0

parent-invoke-ready? (accessor)
accessor public Applet.parent-invoke-ready?:bool

Indicates if Applet.parent-invoke-async is ready to be called.

Notes

When this becomes true the callback in Applet.parent-invoke-ready-callback will be called.
Introduced in: version 6.0

parent-url (accessor)
accessor public Applet.parent-url:#Url

The Url of the page which contains the applet.

Notes

This will be null if the applet is contained in a browser with no parent applet or parent HTML page.
Introduced in: version 6.0

url (field)
public-get private-set Applet.url:Url ={url "curl://string/"}

The Url used by this applet.

Description

An applet is elaborated based on the contents of a Url, relative to which all non-absolute paths are resolved.

Class Procedure Details
applet-invoke-handler-for-object (class proc)
public {Applet.applet-invoke-handler-for-object
    object:Object
}:{proc-type {name:String, ...:JsonValue}:JsonValue}

Create a handler to use with Applet.register-applet-invoke-handler that will allow JavaScript in a web browser to call the methods defined on an Object.

object: Object that it will call methods on. Only public methods in the leaf class type will be callable.
Introduced in: version 6.0

default-applet-invoke-verifier (class proc)
public {Applet.default-applet-invoke-verifier}:bool

Implement the default verifier used when a null is passed to Applet.register-applet-invoke-handler.

Description

This returns true only if the Applet.parent-url is an http: or https: Url and it is for the same web server as the Applet.url.
Introduced in: version 6.0

Method Details
abort (method)
public {Applet.abort}:void

Cancels applet elaboration without killing the applet.


allow-multiple-instances (method)
public {Applet.allow-multiple-instances}:void

Allow multiple instances of this detached applet to be launched.

Description

Normally, only a single instance of any given detached applet will exist at any one time. After this method is called by that instance, however, each subsequent launch attempt will launch a new instance of the detached applet.

Notes

Only meaningful for detached applets.

become-sticky (method)
public {Applet.become-sticky}:void

Mark this applet as sticky.

Description

A sticky applet, if suspended, will sometimes be used by a browser when it attempts to navigate to the url used by that sticky applet. This allows the use of hyperlinks as navigation buttons.

Notes

This functionality is not supported by all browsers, but it is supported by all supported web browsers.

Currently, all applets running inside a Mozilla web browser are actually assumed to be sticky, to work around certain Mozilla bugs.

browse-backward (method)
public {Applet.browse-backward
    offset:int = 1,
    target:String = "_self"
}:void

Ask the browser to move backward in its history list.

offset: The number of positions to move backward in the history list. This must be a positive integer. Defaults to one.
target: The target window in which the resulting applet should be browsed. For more information on targets, see Applet.browse-url.

Notes

This functionality is not supported by all browsers.

browse-forward (method)
public {Applet.browse-forward
    offset:int = 1,
    target:String = "_self"
}:void

Ask the browser to move forward in its history list.

offset: The number of positions to move forward in the history list. This must be a positive integer. Defaults to one.
target: The target window in which the resulting applet should be browsed. For more information on targets, see Applet.browse-url.

Notes

This functionality is not supported by all browsers.

browse-offset (method)
public {Applet.browse-offset offset:int, target:String = "_self"}:void

Ask the browser to move forward or backward in its history list.

offset: The number of positions to move forward (if positive) or backward (if negative) in the history list.
target: The target window in which the resulting applet should be browsed. For more information on targets, see Applet.browse-url.

Notes

This functionality is not supported by all browsers. Many browsers can only support the offsets 1 and -1.

browse-url (method)
public {Applet.browse-url url:Url, target:String = "_self"}:void

Ask the browser to browse a given Url.

url: The Url to be browsed. If the url denotes a file of a type that the browser does not know how to handle, the browser may instead display an error dialog of some kind.
target: The target window in which the url should be browsed. The target is either the name of a browser window, or a special target name starting with a leading underscore (see below). By default, uses the current browser window ("_self").

Notes

Various methods take a special target keyword argument. The target is either the name of a "browser frame" (which may be a top level browser window), or a a special target name starting with a leading underscore.

Browser frame names are names that are internally associated with a browser frame. There is normally no correlation between the contents of a browser frame or the contents of its title bar, and its name. Browser frame names must start with an ASCII letter and may contain only alphanumeric characters and spaces. If there is no browser frame whose name matches a specified target, a new browser window with that name will normally be created, and can then be referenced by that target in the future.

Special target names, starting with an underscore, let you identify a specific frame without having to know its name. They include:

Target Name Description
"_blank" Use a new, unnamed, browser window.
"_self" Use the current frame, if possible. If there are no frames, then use the current window, if possible.
"_parent" Use the immediate parent of the current frame, if possible. If there are no frames, this is normally treated just like "_self".
"_top" Use the window containing the current frame, if possible. If there are no frames, this is normally treated just like "_self".


Note that, if the browser decides to load a new page in the same frame, or window, where the current applet is running, as it will normally do, for example, when "_self" is used (as it is, by default), then, at some point, the browser will suspend the current applet. Note also that some browsers may simply ignore the target completely, so using "_blank" will normally, though not always, allow such suspension to be avoided.

Notes

This functionality is not supported by all browsers.

browse-url-post (method)
public {Applet.browse-url-post
    target:String = "_self",
    http-url:Url,
    request-data:HttpRequestData,
    request-headers:#HttpRequestHeaders = null
}:void

Ask the browser to browse a given Url, doing a post, submitting the given data in the process.

target: The target window in which the http-url should be browsed. For more information on targets, see Applet.browse-url.
http-url: The Url to be browsed. If posting http-url results in data of a type that the browser does not know how to handle, the browser may instead display an error dialog of some kind.
request-data: An HttpRequestData containing the data you wish to post.
request-headers: An HttpRequestHeaders containing any additional headers to include in the post.

Description

The procedure effects the same basic behavior as Applet.browse-url, except that a form must be specified, and the http-url must be of the form "http://" or "https://".

The HttpRequestData has the data to be posted, and the content type of that data, and if it is a HttpFormData then it represents the fields and values of a form. Its form data will be extracted and encoded (based on its encoding type) and posted to http-url.

If you make a request to the browser to load a new page in the same window/frame where your applet is located, your applet will continue to run until the browser acts and suspends your applet. This means that, in that case, you should not have your applet do anything after the call to Applet.browse-url-post other than to return to the event loop.

Notes

This functionality is not supported by all browsers.

flush (method)
public {Applet.flush}:void

Pauses applet elaboration to allow events to be processed.


parent-invoke-async (method)
public {Applet.parent-invoke-async
    finish-proc:#{proc-type {exception:#Exception, result:JsonValue}:void} = null,
    method-name:String,
    ...:JsonValue
}:void

Call a function in the parent of this applet.

finish-proc: If a proc is provided, it will be called when the call completes with an Exception if the call failed, or if the call succeeded, with the result value which can be any legal JsonValue.
method-name: Name of the function to be called. If the parent is JavaScript in an HTML page, this can be a string that evaluates to a function. If the parent is a Curl applet, then it can interpret this string however it wishes.
...: The parameters to pass to the parent. The values must be JsonValues that JsonValue-write and JsonValue-parse can handle.

Description

This method will try to call a function in the parent of this applet, only sub-applets and applets embedded in an HTML page have a parent.

If the parent is an applet, then it will handle the call if it wants to by setting AppletData.parent-invoke-handler. If the parent has not set a handler, then calls to Applet.parent-invoke-async will result in an exception being passed to finish-proc.

If the parent is an HTML page, the call will be made in JavaScript in the web browser.

In all cases Applet.parent-invoke-ready? must be true before making a Applet.parent-invoke-async call.

Notes

Different web browsers may return slightly different return values for the same JavaScript, and may report errors differently. Some web browsers may just return null or JsonVoid when a call has failed.
Introduced in: version 6.0

register-applet-invoke-handler (method)
public {Applet.register-applet-invoke-handler
    handler:#{proc-type {name:String, ...:JsonValue}:JsonValue},
    verifier:#{proc-type {}:bool} = null
}:void

Register a handler for 'applet_invoke' JavaScript calls from the web browser or parent applet.

handler: This is a proc that will get called when an 'applet_invoke' call from the web browser or parent applet is made. It will get a String and any number of other arguments. Applet.applet-invoke-handler-for-object can be used to make a handler based on a class.
verifier: This is a proc which will be called when the web browser or parent applet has provided the Url of the parent page, to check if 'applet_invoke' calls should be allowed. If this function returns false then 'applet_invoke' calls will not be allowed.

If verifier is null then Applet.default-applet-invoke-verifier is used.

The verifier may be called while inside of register-applet-invoke-handler and may be called again when the applet has been suspended and resumed.

Notes

All arguments and return values from the handler must be JsonValues that JsonValue-write and JsonValue-parse can handle.
Introduced in: version 6.0

register-resume-proc (method)
deprecated public {Applet.register-resume-proc
    new-proc:{proc-type {}:void}
}:void

Deprecated

Use register-resume-proc instead.

register-suspend-proc (method)
deprecated public {Applet.register-suspend-proc
    new-proc:{proc-type {}:void}
}:void

Deprecated

Use register-suspend-proc instead.

set-purge-factor (method)
public {Applet.set-purge-factor purge-factor:Percent}:void
This item is unsupported and reserved for internal use.

set-status (method)
public {Applet.set-status status:String}:void

Ask the browser to change the contents of its status bar.

status: The desired status bar contents.

Notes

The browser usually displays a status bar at the bottom of the browser window.

This method normally has no effect unless this Applet is active.

This functionality is not supported by all browsers.

set-title (method)
public {Applet.set-title title:String}:void

Ask the browser to change the contents of its title bar.

title: The desired title bar contents.

Notes

The browser usually displays a title bar at the top of the browser window.

This method normally has no effect unless this Applet is active.

This method normally has no effect unless this Applet is the only thing being browsed by the browser, for example, if the Applet is embedded in an HTML page, this method normally has no effect.

This method may only affect part of the complete browser window title, for example, the title may also contain the name of the browser, or a description of the Applet, or some such.

This functionality is not supported by all browsers.

unregister-resume-proc (method)
deprecated public {Applet.unregister-resume-proc
    old-proc:{proc-type {}:void}
}:void

Deprecated

Use unregister-resume-proc instead.

unregister-suspend-proc (method)
deprecated public {Applet.unregister-suspend-proc
    old-proc:{proc-type {}:void}
}:void

Deprecated

Use unregister-suspend-proc instead.