Applicet Framework for Applets and Applications v2.03

be.arci.applet
Class Applicet.Context

java.lang.Object
  |
  +--be.arci.applet.Applicet.Context
All Implemented Interfaces:
java.applet.AppletContext
Enclosing class:
Applicet

public class Applicet.Context
extends java.lang.Object
implements java.applet.AppletContext

The execution environment for Applicet applications (implementing the java.applet.AppletContext interface); also adds functionality, specific for Applicet applications, that need not be distributed with Applicet applets.

The methods in this class can be used by an Applicet to obtain information about its environment.

Note:
If the Applicet is loaded as an applet by a web browser, the AppletContext will not be of this class type. The methods in this class that we added in addition the AppletContext implementation will not be available for Applicet applets. These extra methods were selected so that you should only want to call them in the 'as-application' part of your code, typically the main method or it's callees; in that part of it will be safe to blindly typecast ((Applicet.Context)getAppletContext()). If you do have to call them from other parts of your code (like init() and start() and their callees), you will have to test for isApplication() before casting, and may have to publish the Applicet$Context.class file together with your applet on your website, because some browser JVM will try to load Applicet.Context for bytecode verification if they find a typecast in an executed method. You can avoid this by dedoubling that part of code as follows:

 void methodA() {
     if (isApplication())
         ((Applicet.Context)getAppletContext()).doSomeThing();
 void methodB() {
     if (isApplication())
         methodC();
 }
 void methodC() {
     ((Applicet.Context)getAppletContext()).doSomeThing();
 }
 
When the browser executes methodA, it might try to load the file Applicet$Context.class to verify the typecast, though it will never be used because isApplication() will always be false in a browser. methodB + methodC give you the same functionality, but methodC will never be executed by the browser because of the isApplication() test in methodB. So the bytecode for methodC will not be verified and Applicet$Context.class will not be loaded.


Method Summary
 java.applet.Applet getApplet(java.lang.String sName)
          Finds and returns the applet with the given name in this execution context.
 java.util.Enumeration getApplets()
          Finds all the applets in this execution context.
 java.applet.AudioClip getAudioClip(java.net.URL url)
          Creates an audio clip.
 java.awt.Image getImage(java.net.URL url)
          Returns an Image object that can then be painted on the screen.
 java.awt.TextField getStatusField()
          Returns the status field of the Applicet applition's AppletContext.
 java.io.InputStream getStream(java.lang.String key)
           
 java.util.Iterator getStreamKeys()
           
 void setActive(boolean swActive)
          Activates or deactivates the Applicet application.
 void setBrowser(Browser browser)
          Sets the Browser for showing HTML and other documents from the Applicet application.
 void setStatusField(java.awt.TextField tfStatus)
          Sets the status field of the Applicet applition's AppletContext; all subsequent showStatus() messages are directed to this field.
 void setStream(java.lang.String key, java.io.InputStream stream)
           
 void showDocument(java.net.URL urlDocument)
          Equivalent to showDocument(url, "_top");.
 void showDocument(java.net.URL urlDocument, java.lang.String sTarget)
          Requests to show local document or the Web page indicated by the url argument.
 void showStatus(java.lang.String status)
          You should not call this method: call Applicet.showStatus() instead. This method is public only because it is defined in an interface (java.applet.AppletContext).
 void showUsage(java.lang.String sMessage, boolean swExit)
          Convenience method to pop up a 'typical use' dialog with parameter help, and exit.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getAudioClip

public java.applet.AudioClip getAudioClip(java.net.URL url)
Creates an audio clip. We prefer to use Applicet's getAudioClip(String) however.
Specified by:
getAudioClip in interface java.applet.AppletContext
Parameters:
url - an absolute URL giving the location of the audio clip.
Returns:
the audio clip at the specified URL.
See Also:
Applicet.getAudioClip(String sName)

getImage

public java.awt.Image getImage(java.net.URL url)
Returns an Image object that can then be painted on the screen. The url argument that is passed as an argument must specify an absolute URL. We prefer to use Applicet's getImage(String) however.

This method always returns immediately, whether or not the image exists. When the applet attempts to draw the image on the screen, the data will be loaded. The graphics primitives that draw the image will incrementally paint on the screen.

Specified by:
getImage in interface java.applet.AppletContext
Parameters:
url - an absolute URL giving the location of the image.
Returns:
the image at the specified URL.
See Also:
Applicet.getImage(String sName)

getApplet

public java.applet.Applet getApplet(java.lang.String sName)
Finds and returns the applet with the given name in this execution context. The execution context can be seen as the ensemble of Applicet applications activated from the same main() method; a Applicet application enters this execution context during the explicit or implicit call to setActive(true), immediately before the init() method is called, and leaves it again during the explicit or implicit call to setActive(false), immediately after the destroy() method is called. The name can be set in the call to runAsApplication that is necessary to run an Applicet application.
Specified by:
getApplet in interface java.applet.AppletContext
Parameters:
sName - an applet name.
Returns:
the applet with the given name, or null if not found.
See Also:
Applicet.runAsApplication

getApplets

public java.util.Enumeration getApplets()
Finds all the applets in this execution context. The execution context can be seen as the ensemble of Applicet applications activated from the same main() method; a Applicet application enters this execution context during the explicit or implicit call to setActive(true), immediately before the init() method is called, and leaves it again during the explicit or implicit call to setActive(false), immediately after the destroy() method is called.
Specified by:
getApplets in interface java.applet.AppletContext
Returns:
an enumeration of all applets in this execution context.

showDocument

public void showDocument(java.net.URL urlDocument)
Equivalent to showDocument(url, "_top");.
Specified by:
showDocument in interface java.applet.AppletContext
See Also:
showDocument(URL urlDocument, String sTarget)

showDocument

public void showDocument(java.net.URL urlDocument,
                         java.lang.String sTarget)
Requests to show local document or the Web page indicated by the url argument. The target argument indicates in which HTML frame or window the document is to be displayed. The target argument is interpreted as follows:

"_self" Not applicable when running as application; acts the same as _top.
"_parent"Not applicable when running as application; acts the same as _top.
"_top" Show in the top-level frame of the current Browser window.
"_blank" Show in a new, unnamed top-level window.
name Show in the frame or window named name. If a target named name does not already exist, a new top-level window with the specified name is created, and the document is shown there.

Applicet.Context delegates the display of documents to an implementation of the Browser interface, that can be set by a call to setBrowser(Browser). The default Browser implementation is DummyBrowser, that does nothing at all. A Browser is free to ignore sTarget (just as it is free to ignore the complete showDocument() request).

Specified by:
showDocument in interface java.applet.AppletContext
Parameters:
urlDocument - an absolute URL giving the location of the document.
sTarget - a String indicating where to display the page.
See Also:
Browser, setBrowser, Applicet.getResource, Viewing HTML documents

showStatus

public void showStatus(java.lang.String status)
You should not call this method: call Applicet.showStatus() instead. This method is public only because it is defined in an interface (java.applet.AppletContext).

Requests that the argument string be displayed in the status field. The status field for Applicet application is normally placed in the Frame containing the Applicet panel, though subclasses can access the field and place it elsewhere.

Specified by:
showStatus in interface java.applet.AppletContext
Parameters:
status - a string to display in the status window.
See Also:
getStatusField, "java.applet.Applet.showStatus(status)"

setActive

public void setActive(boolean swActive)
               throws java.lang.IllegalStateException
Activates or deactivates the Applicet application. Activating includes calling your Applicet's init() and start() methods. Deactivating includes calling your Applicet's stop() and destroy() methods. As for any Applet, you need never call any of these 4 methods yourself, as they are called under control of the execution environment (your browser or Applicet.Context), and calling them from within the applet or from another applet via intra-applet communication will not influence the 'active' state as reflected by isActive().

You only need to call this method if you initialized the Applicet's application execution context with either or both swSetActive or swCreateFrame set to false in the call to runAsApplication.

Throws:
java.lang.IllegalStateException - if the Applicet's isActive() state already equals the specified swActive paramater.
See Also:
Applicet.runAsApplication, "java.applet.Applet.isActive()"

getStatusField

public java.awt.TextField getStatusField()
Returns the status field of the Applicet applition's AppletContext. You can put this field in your own container if you do not let Applicet create the application Frame for you.

Use as follows:
((Applicet.Context)getAppletContext).getStatusField();

Do not call this method if runAsApplication() has not been invoked.

See Also:
showStatus

setStatusField

public void setStatusField(java.awt.TextField tfStatus)
Sets the status field of the Applicet applition's AppletContext; all subsequent showStatus() messages are directed to this field.

Normally when running as an application, this AppletContext will have added it's own status field to the parenting Frame it created. If the user creates his own parenting Container, this AppletContext will not have created a status field, and the user can create one himself. It is the user's responsibility to add the status field Component to a container.

Use as follows:
((Applicet.Context)getAppletContext).setStatusField(myTextField);

Do not call this method if runAsApplication() has not been invoked.

See Also:
showStatus

setBrowser

public void setBrowser(Browser browser)
Sets the Browser for showing HTML and other documents from the Applicet application.

Use as follows:
((Applicet.Context)getAppletContext).setBrowser(new MyBrowser());

Do not call this method if runAsApplication() has not been invoked.

See Also:
Browser, showDocument

showUsage

public void showUsage(java.lang.String sMessage,
                      boolean swExit)
Convenience method to pop up a 'typical use' dialog with parameter help, and exit.

The parameter help will contain the return value of getAppletInfo(), followed by sMessage, if not null, followed by the return value of getUsage(), if you override this method in your Applicet. The default getUsage() implementation returns null, causing the display of the return values of getParameterInfo() and getReservedParameterInfo(), formatted according to the MessageFormat pattern definitions called "usage01" and "usage02" in Applicet_locale.properties.

Parameter help is shown in a modal Dialog .

Parameters:
sMessage - Extra message to show in the usage dialog.
swExit - if true, this method calls System.exit(-1) to stop execution immediately after disposal of the usage dialog.
See Also:
Applicet.getUsage, formatI18NString, Applicet.getI18NParameterInfo, Applicet.getReservedParameterInfo

setStream

public void setStream(java.lang.String key,
                      java.io.InputStream stream)
               throws java.io.IOException

getStream

public java.io.InputStream getStream(java.lang.String key)

getStreamKeys

public java.util.Iterator getStreamKeys()

Applicet Framework for Applets and Applications v2.03