## calpa.html
Class CalHTMLManager

    java.lang.Object
      |
      +--calpa.html.CalHTMLManager

public class CalHTMLManager
extends java.lang.Object

A class with static members and methods which primarily controls the caching of data which will be available to all current instances of `CalHTMLPane`.

See Also:
  `CalHTMLPane`

Method Summary
`static void` | `addUserComponent(javax.swing.JComponent component)` Adds a JComponent to the Manager's component cache.
`static void` | `addUserComponentArray(javax.swing.JComponent[] componentArray, java.lang.String classname)` Adds an array of JComponents to the Manager's component cache.
`static void` | `addUserImage(java.awt.Image img, java.lang.String name)` Adds an Image to the Manager's image cache.
`static void` | `emptyDocumentCache()` Empties the Manager's document cache.
`static int` | `getDocumentCacheCurrentSize()` Returns the Manager's estimate of the current memory being taken up by cached documents.
`static int` | `getDocumentCacheMaximumSize()` Returns the max size of the document cache used by the Manager.
`static javax.swing.JComponent` | `getUserComponent(java.lang.String classname, java.lang.String name)` Retrieves a JComponent from the Manager's component cache.
`static java.awt.Image` | `getUserImage(java.lang.String name)` Retrieves an Image from the Manager's image cache.
`static boolean` | `isCacheDocumentsEnabled()` Indicates whether document caching is currently enabled.
`static boolean` | `isCalFocusManagerEnabled()` Indicates whether a CalFocusManager is currently enabled.
`static void` | `removeOldestDocumentFromCache()` Removes the oldest document from the Manager's document cache.
`static void` | `removeUserComponent(java.lang.String name)` Removes a JComponent from the Manager's component cache.
`static void` | `removeUserComponentArray(java.lang.String classname)` Removes a JComponent array from the Manager's component cache.
`static void` | `removeUserImage(java.lang.String name)` Removes an Image from the Manager's image cache.
`static void` | `setCacheDocuments(boolean enabled)` Enables or disables the caching of documents by the Manager.
`static void` | `setCalFocusManagerEnabled(boolean enabled)` Enables or disables the `CalFocusManager`.
`static void` | `setDocumentCacheMaximumSize(int size)` Sets the size of the document cache used by the Manager.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Method Detail

### addUserComponent

    public static void addUserComponent(javax.swing.JComponent component)

  Adds a JComponent to the Manager's component cache. The component can then be incorporated into an HTML document using the <OBJECT> tag.
  The component must have an assigned name (set by calling the `AWT Component setName()` method). JComponents sent to this method which do not have a name will not be cached by the Manager.
  Parameters:
    `component` - the JComponent to be added.

### removeUserComponent

    public static void removeUserComponent(java.lang.String name)

  Removes a JComponent from the Manager's component cache.
  Parameters:
    `name` - the name of the JComponent to be removed.

### addUserComponentArray

    public static void addUserComponentArray(javax.swing.JComponent[] componentArray,
                                             java.lang.String classname)

  Adds an array of JComponents to the Manager's component cache. Individual components from this array can then be incorporated into an HTML document using the <OBJECT> tag.
  The component array must have an assigned class name. Arrays sent to this method which do not have a class name will not be cached by the Manager.
  Parameters:
    `componentArray` - the JComponent array to be added.
    `classname` - a class identifier for the JComponent array.

### removeUserComponentArray

    public static void removeUserComponentArray(java.lang.String classname)

  Removes a JComponent array from the Manager's component cache.
  Parameters:
    `classname` - the class identifier of the JComponent array to be removed.

### getUserComponent

    public static javax.swing.JComponent getUserComponent(java.lang.String classname,
                                                          java.lang.String name)

  Retrieves a JComponent from the Manager's component cache. If the JComponent was added to the cache as part of a component array then the class name of the array must be sent to this method in order to retrieve it.
  Parameters:
    `classname` - the class identifier of the array the JComponent resides in (may be null).
    `name` - the name of the target JComponent.
  Returns:
    the requested JComponent or `null` if no JComponent matching the sent parameters can be found
  See Also:
    `addUserComponent(javax.swing.JComponent)`, `addUserComponentArray(javax.swing.JComponent[], java.lang.String)`

### addUserImage

    public static void addUserImage(java.awt.Image img,
                                    java.lang.String name)

  Adds an Image to the Manager's image cache. The Image can then be incorporated into an HTML document by naming the image within an <IMG> tag. Incorporating images into documents via the Manager allows the programmer to ensure that a fully loaded image is always available. In addition the image will always be displayed, even if `loadImages` in `CalHTMLPreferences` has been disabled. This can be useful when images are being displayed in buttons and other form controls.

  See the README.TXT file accompanying this documentation for further details.

  Parameters:
    `img` - the Image to be cached.
    `name` - a name given to the Image for retrieval purposes.
  See Also:
    `getUserImage(java.lang.String)`

### getUserImage

    public static java.awt.Image getUserImage(java.lang.String name)

  Retrieves an Image from the Manager's image cache.
  Parameters:
    `name` - the name of the target Image.
  Returns:
    the requested Image or `null` if no Image matching the sent name can be found
  See Also:
    `addUserImage(java.awt.Image, java.lang.String)`

### removeUserImage

    public static void removeUserImage(java.lang.String name)

  Removes an Image from the Manager's image cache.
  Parameters:
    `name` - the name of the Image to be removed.

### setCacheDocuments

    public static void setCacheDocuments(boolean enabled)

  Enables or disables the caching of documents by the Manager. The default setting is true (enabled).
  Parameters:
    `enabled` - a flag indicating whether the Manager should cache documents.

### isCacheDocumentsEnabled

    public static boolean isCacheDocumentsEnabled()

  Indicates whether document caching is currently enabled.
  Returns:
    a flag indicating whether the Manager is currently able to cache documents.

### setDocumentCacheMaximumSize

    public static void setDocumentCacheMaximumSize(int size)

  Sets the size of the document cache used by the Manager. The size value represents Kilobytes and should be greater than 0. The default value is 8000 (8Mb). Note that this can only be a guide to the Manager as to how many documents to cache. It is possible that the cache size figure may be exceeded due to the difficulty of calculating the memory usage of a fully-parsed HTML document.

  Once the cache size has been exceeded the Manager will empty the oldest document from the cache and repeat this process until the memory taken up by documents in the cache falls below the cache size.

  Documents in the Manager's cache do not contain images. These are cached by the JVM and will take up additional memory (sometimes far in excess of the memory taken by documents).

  Note: Kilobytes have been used in order to allow for the creation of very small cache sizes. A cache size of 50K will be meaningless when dealing with normal HTML documents, but it allows for the caching of mini 'documents' which have been created via Strings rather than URLs.

  Parameters:
    `size` - the required size in kilobytes of the Manager's document cache.

### getDocumentCacheMaximumSize

    public static int getDocumentCacheMaximumSize()

  Returns the max size of the document cache used by the Manager.
  Returns:
    the size in kilobytes of the Manager's document cache.

### getDocumentCacheCurrentSize

    public static int getDocumentCacheCurrentSize()

  Returns the Manager's estimate of the current memory being taken up by cached documents. The return value represents Kilobytes.

  The estimate does not include memory which is being taken up by cached document images. These are managed separately by the JVM. Note also that a call to `Runtime.getRuntime().freeMemory()` will invariably show a memory usage greater than indicated by this method. This is due to the additional memory being used by any `CalHTMLPane` objects and subsidiary objects related to the current document view they are displaying.

  Returns:
    an estimate of the current memory (in kilobytes) being used by cached documents.

### removeOldestDocumentFromCache

    public static void removeOldestDocumentFromCache()

  Removes the oldest document from the Manager's document cache.

### emptyDocumentCache

    public static void emptyDocumentCache()

  Empties the Manager's document cache.

### setCalFocusManagerEnabled

    public static void setCalFocusManagerEnabled(boolean enabled)

  Enables or disables the `CalFocusManager`. When a `CalHTMLPane` is first instantiated it will replace the incumbent `FocusManager` with a `CalFocusManager` unless disabled from doing so by this method. The `CalFocusManager` should function identically to Swing's `DefaultFocusManager` outside a `CalHTMLPane` but extends functionality when a `CalHTMLPane` has keyboard focus (e.g. it enables tabbing between hyperlinks).
  See the README.TXT file accompanying this documentation for more details on why the `CalFocusManager` has been implemented in this way.

  (Note that this method will neither install nor uninstall the CalFocusManager.)

  Parameters:
    `enabled` - a flag indicating whether a CalFocusManager should handle keyboard control within a `CalHTMLPane`.

### isCalFocusManagerEnabled

    public static boolean isCalFocusManagerEnabled()

  Indicates whether a CalFocusManager is currently enabled.
  Returns:
    a flag indicating whether a `CalFocusManager` should handle keyboard traversal
  See Also:
    `setCalFocusManagerEnabled(boolean)`