WFC and Java Reference

The WFC and Java Reference contains the following topics:

  • Windows Foundation Classes for Java (WFC)

  • Java API

  • Java Language Specification


Windows Foundation Classes for Java

The following packages are included in the Windows Foundation Classes for Java (WFC):

Package com.ms.wfc.app

Provides classes that encapsulate Windows application operations, such as threads, messaging, and access to the Clipboard and registry.

Package com.ms.wfc.core

Provides core component model classes.

Package com.ms.wfc.data

Provides basic data access using the ActiveX Data Objects (ADO) object model.

Package com.ms.wfc.data.ui

Provides classes that implement and support data-bound controls.

Package com.ms.wfc.html

Provides classes for accessing Dynamic HTML.

Package com.ms.wfc.io

Provides classes for working with data streams.

Package com.ms.wfc.ui

Provides user interface component classes.

Package com.ms.wfc.util

Provides miscellaneous utility classes.

The following packages are used internally by WFC and are not documented:

Package com.ms.wfc.ax

Provides classes that represent the ActiveX interfaces.

Package com.ms.wfc.ole32

Provides Java wrapper classes for OLE services.

Package com.ms.wfc.win32

Provides Java wrapper classes for the Win32 API.


Package com.ms.wfc.app

Provides classes that encapsulate Windows application operations, such as threads, messaging, and access to the Clipboard and the registry.

Classes

Application

Provides static methods typically used in an application.

CharacterSet

Encapsulates the different character sets a Font object can use.

Clipboard

Encapsulates the Win32 system Clipboard.

DataFormats

Translates between WFC text-based Clipboard formats and Win32 integer-based Clipboard formats.

DataFormats.Format

Stores a format type.

DataObject

Defines a basic data transfer object.

Locale

Encapsulates the Win32 Locale Identifier (LCID).

Locale.CalendarType

Provides fields that represent the different calendars that can be used in a locale.

Locale.DateFormatOrder

Provides fields that specify various formats for ordering dates.

Locale.Languages

Provides fields that represent defined languages for Locale objects.

Locale.LeadingZeros

Provides fields for evaluating and specifying the leading zero settings for the Locale class.

Locale.MeasurementSystem

Provides fields for determining the measurement system used in a locale.

Locale.NegativeNumberMode

Provides fields that specify different ways to represent negative numbers.

Locale.OptionalCalendarType

Provides fields that specify optional calendar types.

Locale.PositiveCurrencyMode

Provides fields that specify different ways to represent positive currency.

Locale.Sort

Provides fields that specify different sorting IDs.

Locale.SubLanguages

Provides fields that specify different sublanguage IDs.

Message

Implements a Windows message.

Registry

Provides a set of constants for the root keys in the system registry.

RegistryKey

Provides methods that allow you to read and write to the system registry.

SendKeys

Provides methods for sending keystrokes to an application.

SpecialFolder

Provides fields that represent special system folders.

SystemInformation

Provides information about the operating system.

SystemInformation.ArrangeDirection

Defines constants used to denote the direction the operating system uses to arrange minimized windows.

SystemInformation.ArrangeStartingPosition

Defines constants used to denote the starting position the system uses to arrange minimized windows.

ThreadExceptionDialog

Implements a dialog box that is displayed when an unhandled exception occurs in a thread.

ThreadExceptionEvent

Implements a ThreadExceptionEvent object.

Time

Represents an element of time.

Timer

Implements the Timer control.

Version

Retrieves version information about the underlying operating system.

Window

Provides a low-level encapsulation of a window handle and a window procedure.

Interfaces

IDataObject

Provides a generic data transfer mechanism interface.

IMessageFilter

Defines a message filter interface.

Delegates

MethodInvoker

Invokes the handler method for the event that has occurred.

ThreadExceptionEventHandler

Invokes the handler method for the event that has occurred.


Application Class

Provides static methods typically used in an application.

package com.ms.wfc.app

public final class Application

Remarks

An instance of this class cannot be created. Use the methods in this class to run and quit an application, start and stop Windows message loops, and hook up global application-level events.


 Application Methods

Application Methods

Methods | Description
addMessageFilter | Adds a message filter to the application's message pump.
addOnApplicationExit | Adds an applicationExit event handler to the application.
addOnIdle | Adds an idle event handler to the application.
addOnSettingChange | Adds a settingChange event handler to the application.
addOnSystemShutdown | Adds a systemShutdown event handler to the application.
addOnThreadException | Adds a threadException event handler to the application.
allocThreadStorage | Allocates a slot of per-thread storage space and returns an index to it.
createThread | Executes the specified delegate on its own thread asyncronously.
doEvents | Processes Windows messages currently in the message queue.
exit | Quits the message loops of all threads in the application.
exitThread | Quits the message loop on the current thread and closes all windows on the thread.
freeThreadStorage | Frees the specified thread's storage slot.
getActiveForm | Retrieves a reference to the currently active form for the application.
getCurrentLocale | Retrieves a Locale object that represents the locale settings for the current thread.
getStartupPath | Retrieves the path that the application was run from.
getThreadStorage | Retrieves an object that has been stored in the specified thread's storage slot.
OLERequired | Initializes OLE in your application.
removeMessageFilter | Removes a message filter previously added through addMessageFilter.
removeOnApplicationExit | Removes an applicationExit event handler that was previously added with addOnApplicationExit.
removeOnIdle | Removes an idle event handler previously added through addOnIdle.
removeOnSettingChange | Removes a settingChange event handler that was previously added with addSettingChangeHandler.
removeOnSystemShutdown | Removes a systemShutdown event handler from the application that was previously added with addOnSystemShutdown.
removeOnThreadException | Removes a threadException event handler that was previously added through addOnThreadException.
run | Begins running a standard application and its associated message loop in the current thread.
setCurrentLocale | Sets the locale for the current thread.
setThreadStorage | Sets an object in a specific thread's storage slot.


 Application.addMessageFilter

Application.addMessageFilter

Adds a message filter to the application's message pump.

Syntax

public static void addMessageFilter( IMessageFilter value )

Parameters

value

An object that implements the IMessageFilter interface to be used as a message filter.

Remarks

A message filter allows a program to monitor Windows messages as they are routed to their appropriate destinations. Message filters are unique to a specific thread. You can use a message filter to prevent events from being triggered for a specified object or to perform special operations for an event before it is passed to an event handler.

Note Adding message filters to an application's message pump can cause performance degradation in your application.

See Also removeMessageFilter


 Application.addOnApplicationExit

Application.addOnApplicationExit

Adds an applicationExit event handler to the application.

Syntax

public static void addOnApplicationExit( EventHandler value )

Parameters

value

A com.ms.wfc.core.EventHandler that is called when an application quits.

Remarks

An application exit event is triggered just before the application quits. This gives an application the chance to clean up any objects that may not otherwise be released through garbage collection. The closing of an application cannot be prevented in an event handler for the applicationExit event. Instead, to prevent the closing of an application, you can handle the closing event of the main form of your application.

See Also removeOnApplicationExit, addOnClosing, removeOnClosing


 Application.addOnIdle

Application.addOnIdle

Adds an idle event handler to the application.

Syntax

public static void addOnIdle( EventHandler value )

Parameters

value

The com.ms.wfc.core.EventHandler for the idle event.

Remarks

An idle event is triggered each time an application's message queue is empty. An event handler for the idle event can be defined for each thread. You can use it to perform background operations and general application cleanup while a thread is in an idle state.

Note Because the application cannot process messages until the event handler for a thread's idle event returns, do not perform lengthy tasks using this method.

See Also removeOnIdle


 Application.addOnSettingChange

Application.addOnSettingChange

Adds a settingChange event handler to the application.

Syntax

public static void addOnSettingChange( EventHandler value )

Parameters

value

A com.ms.wfc.core.EventHandler object for the settingChange event.

Remarks

A settingChange event is triggered when the user has changed one or more Windows settings. Windows Foundation Classes for Java (WFC) handles this event internally and appropriately updates all brush, pen, color, and font objects used in your application. You can use this event to make additional changes to your application based on changes made to the user's system settings.

See Also removeOnSettingChange


 Application.addOnSystemShutdown

Application.addOnSystemShutdown

Adds a systemShutdown event handler to the application.

Syntax

public static void addOnSystemShutdown( CancelEventHandler value )

Parameters

value

A com.ms.wfc.core.CancelEventHandler that is called before the system shuts down.

Remarks

A systemShutdown event is triggered just before the user logs off or shuts down the computer through Windows. This event can be canceled, which causes the shutdown request to be aborted. This is typically the last notice an application receives before being terminated. As a result, you should save any files that are open at the time this event occurs.

See Also removeOnSystemShutdown


 Application.addOnThreadException

Application.addOnThreadException

Adds a threadException event handler to the application.

Syntax

public static void addOnThreadException( ThreadExceptionEventHandler value )

Parameters

value

The ThreadExceptionEventHandler object for the threadException event.

Remarks

A threadException event handler is triggered when an untrapped Java exception has been thrown. This event allows an application to handle the exception correctly, rather than abruptly closing the application. An event handler for the threadException event can be defined for each thread.

See Also removeOnThreadException


 Application.allocThreadStorage

Application.allocThreadStorage

Allocates a slot of per-thread storage space and returns an index to it.

Syntax

public static int allocThreadStorage()

Return Value

Returns an index of the newly allocated thread storage slot.

Remarks

Each thread in an application can allocate a slot of memory for storing data that is specific to the thread. Use this per-thread storage to define and store global variables for the thread or other information that is important to the thread. The index returned by allocThreadStorage is always greater than zero.

The following example demonstrates how to use the allocThreadStorage, setThreadStorage, freeThreadStorage, and getThreadStorage methods to allocate, store, retrieve, and free thread storage.

int storeIndex;

public void createStorage()
{
    //Create thread storage for the current thread
    storeIndex = Application.allocThreadStorage();
    //Store a value in the thread storage
    Application.setThreadStorage(storeIndex, "A String Value");
}

public void getStorage()
{
    System.out.println("The value of the thread storage= " + Application.getThreadStorage(storeIndex));
    Application.freeThreadStorage(storeIndex);
}


 Application.createThread

Application.createThread

Executes the specified delegate on its own thread asyncronously.

Syntax

public static Thread createThread( Delegate callback )

public static Thread createThread( Delegate callback, int priority )

Parameters

callback

A delegate that is called as the entry point to the thread.

priority

The priority level of the thread.

Return Value

Returns a Thread object representing the new thread.

Remarks

Calling the createThread method makes it unnecessary to design a class that implements java.lang.Runnable or extends java.lang.Thread. The second version of this method allows you to define a thread priority level for the new thread. You can pass any delegate to the createThread method or use the MethodInvoker class to call a method that contains no parameters.

The following example illustrates how to use the createThread method to start a new thread within an application.

public class MyForm extends Form
{
    public MyForm()
    {
        initForm();
        //Start the thread that counts to 2000
        Application.createThread(new MethodInvoker (MyThread), Thread.NORM_PRIORITY);
    }

    /**This thread runs concurrently with form loading and counts to 2000*/
    private void MyThread{
        for (int i = 0; i <= 2000; i++){
            System.out.println("The value is currently equal to " + i);
        }
    }
    //More Form Code Here
}


 Application.doEvents

Application.doEvents

Processes Windows messages currently in the message queue.

Syntax

public static void doEvents()

public static void doEvents( int message )

public static void doEvents( int messageStart, int messageEnd )

Parameters

message

The message to process.

messageStart

The starting range for messages to process.

messageEnd

The ending range for messages to process.

Remarks

Warning Calling the doEvents method disposes of Graphics objects that are defined for a paint event or created using the createGraphics method.

The doEvents method allows for pending Windows messages to be processed. This method is typically used in looping code to allow messages to be processed. Calling the first version of this overloaded method causes all events to be processed. The second version processes only messages that are of type message. This version is useful when you want to allow only certain messages (such as WM_PAINT) to be processed while other messages are left pending. The third version processes only messages in the range starting with messageStart and ending with messageEnd. This version of doEvents is typically used to allow only a narrow range of messages, such as WM_MOUSEFIRST to WM_MOUSELAST, to be processed.

Note Care must be taken when calling this method because it can cause code to be re-entered if a message causes an event to be triggered.


 Application.exit

Application.exit

Quits the message loops of all threads in the application.

Syntax

public static synchronized void exit()

Remarks

The exit method revokes all running message loops on all threads and closes all windows. If you want only to exit a message loop for the current thread, call the exitThread method instead. Because the application's thread is started within the main method of the startup form, calling the exit method does not actually force the application to quit. Instead, it causes all calls to run to return. If you have any code after the call to run in the main method, this code is executed.


 Application.exitThread

Application.exitThread

Quits the message loop on the current thread and closes all windows on the thread.

Syntax

public static void exitThread()

Remarks

The exitThread method allows you to terminate a specified thread's message loop and any windows that are open in the thread. If you want to quit the application and all threads that are currently open for the thread, call the exit method.

See Also exit, run


 Application.freeThreadStorage

Application.freeThreadStorage

Frees the specified thread's storage slot.

Syntax

public static void freeThreadStorage( int index )

Parameters

index

The index to the thread storage slot. This index must have been previously obtained by calling allocThreadStorage.

Remarks

The freeThreadStorage method allows you to free a thread storage allocation. If an object is currently stored in the slot, the slot will be set to null before freeing it. For an example of using this method, see allocThreadStorage.

See Also getThreadStorage, setThreadStorage


 Application.getActiveForm

Application.getActiveForm

Retrieves a reference to the currently active form for the application.

Syntax

public static Form getActiveForm()

Return Value

Returns a Form object if there is an active form; otherwise, returns null.

Remarks

Use the getActiveForm method to retrieve the form that is currently active to perform actions on the form or its controls. If you are writing a Multiple Document Interface (MDI) application and want to get the active child form, use the Form.getActiveMDIChild method. Conversely, to gain access to an MDI child form's parent, use the getMDIParent method.


 Application.getCurrentLocale

Application.getCurrentLocale

Retrieves a Locale object that represents the locale settings for the current thread.

Syntax

public static Locale getCurrentLocale()

Return Value

Returns a Locale object with the locale settings for the thread.

Remarks

Use the getCurrentLocale to retrieve a Locale object that represents the current world locale for the thread. You can use this method to determine the language, currency, and date system to use in your application based on the locale defined in the user's Control Panel settings.

See Also setCurrentLocale


 Application.getStartupPath

Application.getStartupPath

Retrieves the path that the application was run from.

Syntax

public static String getStartupPath()

Return Value

Returns a String object that contains the full path to the executable file that started the application.

Remarks

The path returned by getStartupPath can differ depending on how the application is started. If you start your application within Visual J++, the path returned by getStartupPath will be the location of the WJView.exe or JView.exe files that are used to run your application within Visual J++. If you start your application using an .exe file, this method returns the path to the .exe file.


 Application.getThreadStorage

Application.getThreadStorage

Retrieves an object that has been stored in the specified thread's storage slot.

Syntax

public static Object getThreadStorage( int index )

Parameters

index

The index to the thread's storage slot. This index must have been obtained previously by calling allocThreadStorage.

Return Value

Returns an object that the caller has previously stored in the slot, or returns null if an object is not stored in the slot.

Remarks

To retrieve an object from a specified thread's storage slot, you must have a valid index to the storage slot. This index is provided by calling allocThreadStorage. When retrieving information from the storage slot, ensure that you have the appropriate type cast applied to the call to getThreadStorage. To store information in a specified thread's storage slot, you can call the setThreadStroage method. For an example of how use this method, see allocThreadStorage.

See Also freeThreadStorage


 Application.OLERequired

Application.OLERequired

Initializes OLE in your application.

Syntax

public static void OLERequired()

Remarks

The OLERequired method is used to verify that OLE has been initialized on the current thread. The Application object automatically removes OLE initialization when the thread is closed.

Note Unless you are calling OLE functions directly, you do not need to call this method.


 Application.removeMessageFilter

Application.removeMessageFilter

Removes a message filter previously added through addMessageFilter.

Syntax

public static void removeMessageFilter( IMessageFilter value )

Parameters

value

An object that implements the IMessageFilter interface that you want to remove from the message pump.

Remarks

A message filter allows a program to monitor Windows messages as they are routed to their appropriate destinations. Message filters are unique to a specific thread. Use a message filter to prevent events from being triggered for a specified object or to perform special operations for an event before it is passed to an event handler.

See Also addMessageFilter


 Application.removeOnApplicationExit

Application.removeOnApplicationExit

Removes an applicationExit event handler that was previously added with addOnApplicationExit.

Syntax

public static void removeOnApplicationExit( EventHandler value )

Parameters

value

The com.ms.wfc.core.EventHandler delegate to remove.

Remarks

An application exit event is triggered just before the application quits. This gives an application the chance to clean up any objects that may not otherwise be released through garbage collection. The closing of an application cannot be prevented in an event handler for the applicationExit event. To prevent the closing of an application, you can handle the closing event of the Form class for the main form of your application.

See Also addOnApplicationExit


 Application.removeOnIdle

Application.removeOnIdle

Removes an idle event handler previously added through addOnIdle.

Syntax

public static void removeOnIdle( EventHandler value )

Parameters

value

The com.ms.wfc.core.EventHandler delegate to remove.

Remarks

An idle event is triggered each time an application's message queue is empty. An event handler for the idle event can be defined for each thread. You can use the idle event to perform background operations and general application cleanup while a thread is in an idle state.

Note Because the application cannot process messages until the event handler for a thread's idle event returns, do not perform lengthy tasks with this method.

See Also addOnIdle


 Application.removeOnSettingChange

Application.removeOnSettingChange

Removes a settingChange event handler that was previously added with addSettingChangeHandler.

Syntax

public static void removeOnSettingChange( EventHandler value )

Parameters

value

The com.ms.wfc.core.EventHandler delegate to remove.

Remarks

A settingChange event is triggered when the user has changed one or more Windows settings. WFC handles this event internally and appropriately updates all brush, pen, color, and font objects used in your application. Use this event to make additional changes to your application based on changes made to the user's system settings.

See Also addOnSettingChange


 Application.removeOnSystemShutdown

Application.removeOnSystemShutdown

Removes a systemShutdown event handler from the application that was previously added with addOnSystemShutdown.

Syntax

public static void removeOnSystemShutdown( CancelEventHandler value )

Parameters

value

A com.ms.wfc.core.CancelEventHandler delegate to remove.

Remarks

A systemShutdown event is triggered just before the user logs off or shuts down the computer through Windows. This event can be canceled, which causes the shutdown request to be aborted. This is typically the last notice an application receives before being terminated. As a result, you should save any files that are open when this event occurs.


 Application.removeOnThreadException

Application.removeOnThreadException

Removes a threadException event handler that was previously added through addOnThreadException.

Syntax

public static void removeOnThreadException( ThreadExceptionEventHandler value )

Parameters

value

The ThreadExceptionEventHandler to remove.

Remarks

A threadException event handler is triggered when an untrapped Java exception has been thrown. This event allows an application to handle the exception correctly, rather than abruptly terminating the application. An event handler for the threadException event can be defined for each thread.

See Also addOnThreadException


 Application.run

Application.run

Begins running a standard application and its associated message loop in the current thread.

Syntax

public static void run()

public static void run( Form mainForm )

Parameters

mainForm

A Form object that represents the main form of the application being run. If this is null, it is the same as calling the run method without any specified parameters.

Remarks

If a Form object is specified in a call to run, the form's visible property is set to true, and a closing event handler is added to the form. The closing event handler calls the exit method for you, which cleans up the application. If you do not pass a form to this call, the message loop runs until the exit or exitThread method is called. Typically, the main function of an application calls the run method with the main window of the application specified as the parameter.


 Application.setCurrentLocale

Application.setCurrentLocale

Sets the locale for the current thread.

Syntax

public static void setCurrentLocale( Locale locale )

Parameters

locale

A Locale object that represents the new locale for the current thread.

Remarks

To change the locale information for the current thread, use the setCurrentLocale method and provide it with a Locale object. The locale information allows a thread to determine the language, currency, and date system to use in an application. To retrieve the thread's current locale setting, use the getCurrentLocale method.


 Application.setThreadStorage

Application.setThreadStorage

Sets an object in a specific thread's storage slot.

Syntax

public static void setThreadStorage( int index, Object object )

Parameters

index

The index to the thread's storage slot. This index must have been previously obtained by calling allocThreadStorage.

object

The object to store. This can be null to clear the object currently stored in the specified storage slot.

Remarks

You can use the setThreadStorage method to store thread-specific information, such as global objects or variables, that are needed by the thread. To retrieve the information from the thread's storage slot, you must preallocate a slot and have an index to that slot. To do this, use the allocThreadStorage method. For an example of how use this method, see allocThreadStorage.

See Also freeThreadStorage, getThreadStorage


CharacterSet Class

Encapsulates the different character sets a Font object can use.

Enum
  |
  +--CharacterSet

package com.ms.wfc.app

public class CharacterSet
extends Enum

Remarks

The CharacterSet class provides a number of enumerated values that are used when defining the character set that a Font object will use.


 CharacterSet Methods

CharacterSet Methods

Methods | Description
valid | Determines whether the value assigned to the method is a valid number for the class's enumerated values.


 CharacterSet.valid

CharacterSet.valid

Determines whether the value assigned to the method is a valid number for the class's enumerated values.

Syntax

public static boolean valid( int value )

Parameters

value

The number being evaluated.

Return Value

Returns true if the value is valid; otherwise, returns false.

Remarks

The valid method is used to determine whether a specific integer value is within the range of numbers for the enumerated members of this class. Use this value to determine if a value returned from a method is a valid enumerated value for this class.


 CharacterSet Fields

CharacterSet Fields

Fields | Description
ANSI | Specifies the standard Windows American National Standards Institute (ANSI) character set.
ARABIC | Specifies the Arabic character set.
BALTIC | Specifies the Baltic character set.
CHINESEBIG5 | Specifies the Chinese BIG 5 character set.
DEFAULT | Specifies the default character set.
EASTEUROPE | Specifies the Eastern Europe character set.
GB2312 | Specifies the Great Britain 2312 character set.
GREEK | Specifies the Greek character set.
HANGEUL | Specifies the Korean Hangeul character set.
HEBREW | Specifies the Hebrew character set.
JOHAB | Specifies the Johab character set.
MAC | Specifies the Macintosh character set.
OEM | Specifies the original equipment manufacturer (OEM) character set.
RUSSIAN | Specifies the Russian character set.
SHIFTJIS | Specifies the Shift JIS character set.
SYMBOL | Specifies the Symbol character set.
THAI | Specifies the Thai character set.
TURKISH | Specifies the Turkish character set.
VIETNAMESE | Specifies the Vietnamese character set.


 CharacterSet.ANSI

CharacterSet.ANSI

Specifies the standard Windows American National Standards Institute (ANSI) character set.

Syntax

public static final int ANSI;


 CharacterSet.ARABIC

CharacterSet.ARABIC

Specifies the Arabic character set.

Syntax

public static final int ARABIC;


 CharacterSet.BALTIC

CharacterSet.BALTIC

Specifies the Baltic character set.

Syntax

public static final int BALTIC;


 CharacterSet.CHINESEBIG5

CharacterSet.CHINESEBIG5

Specifies the Chinese BIG 5 character set.

Syntax

public static final int CHINESEBIG5;


 CharacterSet.DEFAULT

CharacterSet.DEFAULT

Specifies the default character set.

Syntax

public static final int DEFAULT;

Remarks

Uses the default character set for the thread.


 CharacterSet.EASTEUROPE

CharacterSet.EASTEUROPE

Specifies the Eastern Europe character set.

Syntax

public static final int EASTEUROPE;


 CharacterSet.GB2312

CharacterSet.GB2312

Specifies the Great Britain 2312 character set.

Syntax

public static final int GB2312;


 CharacterSet.GREEK

CharacterSet.GREEK

Specifies the Greek character set.

Syntax

public static final int GREEK;


 CharacterSet.HANGEUL

CharacterSet.HANGEUL

Specifies the Korean Hangeul character set.

Syntax

public static final int HANGEUL;


 CharacterSet.HEBREW

CharacterSet.HEBREW

Specifies the Hebrew character set.

Syntax

public static final int HEBREW;


 CharacterSet.JOHAB

CharacterSet.JOHAB

Specifies the Johab character set.

Syntax

public static final int JOHAB;


 CharacterSet.MAC

CharacterSet.MAC

Specifies the Macintosh character set.

Syntax

public static final int MAC;


 CharacterSet.OEM

CharacterSet.OEM

Specifies the original equipment manufacturer (OEM) character set.

Syntax

public static final int OEM;

Remarks

This is the character set that is built into the read-only memory (ROM) of most computers.


 CharacterSet.RUSSIAN

CharacterSet.RUSSIAN

Specifies the Russian character set.

Syntax

public static final int RUSSIAN;


 CharacterSet.SHIFTJIS

CharacterSet.SHIFTJIS

Specifies the Shift JIS character set.

Syntax

public static final int SHIFTJIS;


 CharacterSet.SYMBOL

CharacterSet.SYMBOL

Specifies the Symbol character set.

Syntax

public static final int SYMBOL;

Remarks

This character set contains common symbols that you can use in your text.


 CharacterSet.THAI

CharacterSet.THAI

Specifies the Thai character set.

Syntax

public static final int THAI;


 CharacterSet.TURKISH

CharacterSet.TURKISH

Specifies the Turkish character set.

Syntax

public static final int TURKISH;


 CharacterSet.VIETNAMESE

CharacterSet.VIETNAMESE

Specifies the Vietnamese character set.

Syntax

public static final int VIETNAMESE;


Clipboard Class

Encapsulates the Win32 system Clipboard.

package com.ms.wfc.app

public final class Clipboard

Remarks

The Clipboard class provides a number of static methods that allow you to set and retrieve data from the Windows Clipboard. An instance of the Clipboard class cannot be instantiated.


 Clipboard Methods

Clipboard Methods

Methods | Description
getDataObject | Retrieves any data that is currently on the Clipboard.
setDataObject | Sends data to the system Clipboard.


 Clipboard.getDataObject

Clipboard.getDataObject

Retrieves any data that is currently on the Clipboard.

Syntax

public static IDataObject getDataObject()

Return Value

Returns an object that implements the IDataObject class representing the data retrieved from the Clipboard.

Remarks

Because the data type of the object returned from the Clipboard can vary, you must use an IDataObject object to store the retrieved data. Once the data has been stored in the object, you can use methods from the IDataObject class to extract the data to its proper data type.

The following code illustrates how to use the getDataObject method to retrieve data that is currently on the Clipboard. It also shows how to use the methods of the IDataObject class to assign an Edit control's text with the contents of the IDataObject.

    private void mnuPaste_click(Object sender, Event e) {
            IDataObject d = Clipboard.getDataObject();
            if (d.isDataPresent(String.class) {
                edit1.setText((String)d.getData(String.class));
            }
    }

See Also DataObject, setDataObject


 Clipboard.setDataObject

Clipboard.setDataObject

Sends data to the system Clipboard.

Syntax

public static void setDataObject( Object data )

public static void setDataObject( Object data, boolean copy)

Parameters

data

The data to place on the Clipboard.

copy

A boolean value that determines whether the data that is being sent to the Clipboard is copied or referenced.

Remarks

The setDataObject method allows you to assign data to the system Clipboard. If the second version of this method is called, and the copy value is set to true, the data being sent to the Clipboard is copied and persisted on the Clipboard when the application quits. If the value of copy is set to false, a reference to the data is placed on Clipboard.

The following example illustrates using the setDataObject method to store data on the Clipboard from selected text in an Edit control on a form.

private void mnuCopy_click(Object sender, Event e)
{
    //Send the currently selected text to the Clipboard
        Clipboard.setDataObject(edit1.getText());
}

See Also IDataObject, DataObject, getDataObject


DataFormats Class

Translates between Windows Foundation Classes for Java (WFC) text-based Clipboard formats and Win32 integer-based Clipboard formats.

package com.ms.wfc.app

public class DataFormats

Remarks

Use the enumerated values in the DataFormats class to determine the type of data that is currently found on the system Clipboard. WFC converts many Clipboard types to valid Java and WFC objects.


 DataFormats Methods

DataFormats Methods

Methods | Description
getFormat | Retrieves the DataFormats.Format object associated with the specified format.


 DataFormats.getFormat

DataFormats.getFormat

Retrieves the DataFormats.Format object associated with the specified format.

Syntax

public static Format getFormat( String format )

public static Format getFormat( int id )

Parameters

format

The string format type.

id

The Windows Clipboard format ID.

Return Value

Returns a DataFormats.Format object. If the specified format is new, this method creates a new format and returns it.


 DataFormats Fields

DataFormats Fields

Fields | Description
CF_BITMAP | Specifies a Windows bitmap format.
CF_CSV | Specifies a comma-separated value (CSV) format.
CF_DIB | Specifies the Windows Device Independent Bitmap (DIB) format.
CF_DIF | Specifies the Windows data interchange format.
CF_ENHMETAFILE | Specifies the Windows enhanced metafile format.
CF_HDROP | Specifies the Windows file drop format.
CF_HTML | Specifies text consisting of Hypertext Markup Language (HTML) data.
CF_LOCALE | Specifies the Windows locale format.
CF_METAFILEPICT | Specifies the Windows metafile format.
CF_OEMTEXT | Specifies the standard Windows original equipment manufacturer (OEM) text format.
CF_PALETTE | Specifies the Windows palette format.
CF_PENDATA | Specifies the Windows pen data format.
CF_RIFF | Specifies the Resource Interchange File Format (RIFF) audio format.
CF_RTFTEXT | Specifies text consisting of Microsoft rich text format (RTF) data.
CF_STRINGCLASS | Specifies the standard java.lang.String class format.
CF_SYLK | Specifies the Windows symbolic link format.
CF_TEXT | Specifies the standard American National Standards Institute (ANSI) text format.
CF_TIFF | Specifies the Tagged Image File Format (TIFF).
CF_UNICODETEXT | Specifies the standard Windows Unicode text format.
CF_WAVE | Specifies the wave audio format.
CF_WFCOBJECT | Specifies a format that encapsulates a WFC object.


 DataFormats.CF_BITMAP

DataFormats.CF_BITMAP

Specifies a Windows bitmap format.

Syntax

public static final String CF_BITMAP;

Remarks

In WFC, you can pass in the Bitmap class; WFC performs the conversion to the Win32 bitmap Clipboard format for you.


 DataFormats.CF_CSV

DataFormats.CF_CSV

Specifies a comma-separated value (CSV) format.

Syntax

public static final String CF_CSV;

Remarks

CSV is a common interchange format used by applications such as spreadsheets. The CSV format is not used directly by WFC.


 DataFormats.CF_DIB

DataFormats.CF_DIB

Specifies the Windows Device Independent Bitmap (DIB) format.

Syntax

public static final String CF_DIB;

Remarks

If you assign a Bitmap object to the Clipboard, WFC automatically performs the conversion to the Win32 bitmap Clipboard format for you.


 DataFormats.CF_DIF

DataFormats.CF_DIF

Specifies the Windows data interchange format.

Syntax

public static final String CF_DIF;

Remarks

This format is not used directly by WFC.


 DataFormats.CF_ENHMETAFILE

DataFormats.CF_ENHMETAFILE

Specifies the Windows enhanced metafile format.

Syntax

public static final String CF_ENHMETAFILE;

Remarks

If you assign a Metafile object to the Clipboard, WFC performs the conversion to the Win32 enhanced metafile Clipboard format for you.


 DataFormats.CF_HDROP

DataFormats.CF_HDROP

Specifies the Windows file drop format.

Syntax

public static final String CF_HDROP;

Remarks

This format is not used directly by WFC. However, you can use it during drag-and-drop operations to interact with file drag operations initiated by Windows.


 DataFormats.CF_HTML

DataFormats.CF_HTML

Specifies text consisting of Hypertext Markup Language (HTML) data.

Syntax

public static final String CF_HTML;

Remarks

Use the HTML format to determine whether HTML string data versus other types of text data is on the Clipboard.


 DataFormats.CF_LOCALE

DataFormats.CF_LOCALE

Specifies the Windows locale format.

Syntax

public static final String CF_LOCALE;

Remarks

The locale format is not used directly by WFC.


 DataFormats.CF_METAFILEPICT

DataFormats.CF_METAFILEPICT

Specifies the Windows metafile format.

Syntax

public static final String CF_METAFILEPICT;

Remarks

The metafile format is not used directly by WFC.


 DataFormats.CF_OEMTEXT

DataFormats.CF_OEMTEXT

Specifies the standard Windows original equipment manufacturer (OEM) text format.

Syntax

public static final String CF_OEMTEXT;

Remarks

In WFC, you can pass in a String object; WFC performs the conversion to the Win32 OEM text Clipboard format for you.


 DataFormats.CF_PALETTE

DataFormats.CF_PALETTE

Specifies the Windows palette format.

Syntax

public static final String CF_PALETTE;

Remarks

WFC does not use the palette format directly. You can use the format with a Bitmap object.


 DataFormats.CF_PENDATA

DataFormats.CF_PENDATA

Specifies the Windows pen data format.

Syntax

public static final String CF_PENDATA;

Remarks

This format consists of pen strokes for handwriting software and is not used by WFC.


 DataFormats.CF_RIFF

DataFormats.CF_RIFF

Specifies the Resource Interchange File Format (RIFF) audio format.

Syntax

public static final String CF_RIFF;

Remarks

RIFF is not used directly by WFC.


 DataFormats.CF_RTFTEXT

DataFormats.CF_RTFTEXT

Specifies text consisting of Microsoft rich text format (RTF) data.

Syntax

public static final String CF_RTFTEXT;

Remarks

You can use RTF to retrieve RTF data from the Clipboard. Typically, you use this format to retrieve RTF data that you want to place into a RichEdit control.


 DataFormats.CF_STRINGCLASS

DataFormats.CF_STRINGCLASS

Specifies the standard java.lang.String class format.

Syntax

public static final String CF_STRINGCLASS;

Remarks

This format is used by WFC to store String objects. Use this format to retrieve data from the Clipboard and assign it to a String object or a property that accepts a String object.


 DataFormats.CF_SYLK

DataFormats.CF_SYLK

Specifies the Windows symbolic link format.

Syntax

public static final String CF_SYLK;

Remarks

The symbolic link format is not used directly by WFC.


 DataFormats.CF_TEXT

DataFormats.CF_TEXT

Specifies the standard American National Standards Institute (ANSI) text format.

Syntax

public static final String CF_TEXT;

Remarks

If you assign a String object to the Clipboard, WFC performs the conversion to the Win32 text Clipboard format for you.


 DataFormats.CF_TIFF

DataFormats.CF_TIFF

Specifies the Tagged Image File Format (TIFF).

Syntax

public static final String CF_TIFF;

Remarks

TIFF is not used directly by WFC.


 DataFormats.CF_UNICODETEXT

DataFormats.CF_UNICODETEXT

Specifies the standard Windows Unicode text format.

Syntax

public static final String CF_UNICODETEXT;

Remarks

In WFC, you can pass in String object; WFC performs the conversion to the Win32 Unicode Clipboard format for you.


 DataFormats.CF_WAVE

DataFormats.CF_WAVE

Specifies the wave audio format.

Syntax

public static final String CF_WAVE;

Remarks

The wave format is not used directly by WFC.


 DataFormats.CF_WFCOBJECT

DataFormats.CF_WFCOBJECT

Specifies a format that encapsulates a WFC object.

Syntax

public static final String CF_WFCOBJECT;

Remarks

Any object can be stored here.


DataFormats.Format Class

Stores a format type.

package com.ms.wfc.app

public static class DataFormats.Format

Remarks

A format is a String/ID pair that defines a Clipboard format. In addition to the String object and ID, a flag is stored that specifies whether the format is expecting a Win32 handle instead of an HGLOBAL.

See Also DataFormats, IDataObject, DataObject


 DataFormats.Format Methods

DataFormats.Format Methods

Constructors | Description
Format | Creates a Format object.


 DataFormats.Format.Format

DataFormats.Format.Format

Creates a Format object.

Syntax

public Format( String n, int i )

public Format( String n, int i, boolean fHandle )

Parameters

n

A String object that represents the name of the format.

i

An integer value that represents the ID of the format.

fHandle

A boolean value that determines whether a Win32 handle is expected with the format.


 DataFormats.Format Fields

DataFormats.Format Fields

Fields | Description
id | Specifies the identifier of the Format object.
name | Specifies the name of the format.
win32Handle | Specifies a boolean value that determines whether the format is expecting a Win32 handle.


 DataFormats.Format.id

DataFormats.Format.id

Specifies the identifier of the Format object.

Syntax

public final int id;

Remarks

This id field is equivalent to the Win32 Clipboard format ID.


 DataFormats.Format.name

DataFormats.Format.name

Specifies the name of the format.

Syntax

public final String name;


 DataFormats.Format.win32Handle

DataFormats.Format.win32Handle

Specifies a boolean value that determines whether the format is expecting a Win32 handle.

Syntax

public final boolean win32Handle;


DataObject Class

Defines a basic data transfer object.

package com.ms.wfc.app

public class DataObject
implements IDataObject, IOleDataObject

Remarks

The DataObject class takes any object that implements the IDataObject interface and provides the implementation for the IOleDataObject interface. The DataObject class also takes any object that implements the IOleDataObject interface and exposes a IDataObject object for it. You can use this class to store arbitrary data and expose both the IDataObject and IOleDataObject interfaces. The DataObject class is typically used to retrieve and store data on the Clipboard and also in drag-and-drop operations.


 DataObject Methods

DataObject Methods

Constructors | Description
DataObject | Creates a DataObject object.

Methods | Description
getData | Retrieves the data associated with the specific data format.
getDataPresent | Determines whether a specific data format is stored in the data object.
getFormats | Retrieves an array of all format types that are supported by the data stored in this Data object.
setData | Sets the data to be stored in the Data object.


 DataObject.DataObject

DataObject.DataObject

Creates a DataObject object.

Syntax

public DataObject()

public DataObject( IDataObject data )

public DataObject( IOleDataObject data )

public DataObject( Object data )

public DataObject( String format, Object data )

Parameters

data

An object that represents the object that will be wrapped either as an IOleDataObject or IDataObject or referenced in the Data object.

format

A String object that represents the format to store the data as.

Remarks

The DataObject provides several constructors for creating a DataObject object. The first version creates a DataObject object that can be used to store arbitrary data. The second and third versions create a DataObject object that wraps an interface object passed as a parameter to the constructor. The fourth version attempts to bind the object passed to the constructor as either an IOleDataObject object or an IDataObject object. Or it stores a reference to the object in the DataObject object. The fifth version provides a way to store the data specified in the data parameter in the format specified in the format parameter.


 DataObject.getData

DataObject.getData

Retrieves the data associated with the specific data format.

Syntax

public Object getData( String format )

public Object getData( Class format )

Parameters

format

A String object or class that represents the format of the data to retrieve.

Return Value

Returns an object that represents the data associated with the specific format.

Remarks

Use the getData method to retrieve the data stored in the Data object. You can define the format that the data should be stored in using either a String object that defines that data type or the class for the data format. You can use the fields of the DataFormats class to define the proper data format. To determine the format of the data before calling this method, use the getDataPresent method.

The following code demonstrates how to use the getData method to retrieve data that is currently on the Clipboard. It also shows how to use the methods of the DataObject interface to assign an Edit control's text with the contents of the DataObject.

    private void mnuPaste_click(Object sender, Event e) {
            DataObject d = Clipboard.getDataObject();
            if (d.isDataPresent(String.class) {
                edit1.setText((String)d.getData(String.class));
            }
    }

See Also IDataObject, setData


 DataObject.getDataPresent

DataObject.getDataPresent

Determines whether a specific data format is stored in the data object.

Syntax

public boolean getDataPresent( Class format )

public boolean getDataPresent( String format )

Parameters

format

A String object or class that represents the format of the data to check for.

Return Value

Returns true if there is data stored in the Data object of the type specified in format; otherwise, returns false.

Remarks

Use the getDataPresent method to determine the type of data that is currently stored in the Data object. You can use this method before retrieving data from the Data object to ensure that the data is in the correct format.

See Also IDataObject, getData


 DataObject.getFormats

DataObject.getFormats

Retrieves an array of all format types that are supported by the data stored in this Data object.

Syntax

public String[] getFormats()

Return Value

Returns an array of String objects that represent the list of all formats that are supported by the data stored in the Data object.

Remarks

This method is provided to assist in debugging your application. The fields in the DataFormats class can be used to define the format of the data to retrieve.

See Also IDataObject


 DataObject.setData

DataObject.setData

Sets the data to be stored in the Data object.

Syntax

public void setData( String format, Object data )

public void setData( Class format, Object data )

public void setData( Object data )

Parameters

format

A String object or class that represents the format of the data to store.

data

An object that represents the data to store.

Remarks

Use the first and second versions of this method to define the format of the data being stored in the Data object. Use the third version to assign the object without supplying format information. The fields in the DataFormats class can be used to define the format of the data being stored.

See Also IDataObject, getData


IDataObject Interface

Provides a generic data transfer mechanism interface.

package com.ms.wfc.app

public interface IDataObject

Remarks

The IDataObject interface is used with the Clipboard class to retrieve and store data on the Clipboard and also in drag-and-drop operations. The DataObject class provides a basic implementation of this interface.


 IDataObject Methods

IDataObject Methods

Methods | Description
getData | Retrieves the data associated with the specific data format.
getDataPresent | Determines whether a specific data format is stored in the Data object.
getFormats | Retrieves an array of all format types that are supported by the data stored in this Data object.
setData | Sets the data to be stored in the Data object.


 IDataObject.getData

IDataObject.getData

Retrieves the data associated with the specific data format.

Syntax

public Object getData( String format )

public Object getData( Class format )

Parameters

format

A String object or class that represents the format of the data to retrieve.

Return Value

Returns an object that represents the data associated with the specific format.

Remarks

Use the getData method to retrieve data stored in the Data object. You can define the format that the data should be stored in using either a String object that defines that data type or the class for the data format. You can use the fields in the DataFormats class to define the proper data format. To determine the format of the data before calling this method, use the getDataPresent method.

See Also DataObject, setData


 IDataObject.getDataPresent

IDataObject.getDataPresent

Determines whether a specific data format is stored in the Data object.

Syntax

public boolean getDataPresent( Class format )

public boolean getDataPresent( String format )

Parameters

format

A String object or class that represents the format of the data to check for.

Return Value

Returns true if there is data stored in the Data object of the type specified in format; otherwise, returns false.

Remarks

Use the getDataPresent method to determine the type of data that is currently stored in the Data object. You can use this method before retrieving data from the Data object to ensure that it is in the correct format.

See Also DataObject, getData


 IDataObject.getFormats

IDataObject.getFormats

Retrieves an array of all format types that are supported by the data stored in this Data object.

Syntax

public String[] getFormats()

Return Value

Returns an array of String objects that represent the list of all formats that are supported by the data stored in the Data object.

Remarks

This method is provided to assist in debugging your application. The fields in the DataFormats class can be used to define the format of the data to retrieve.

See Also DataObject


 IDataObject.setData

IDataObject.setData

Sets the data to be stored in the Data object.

Syntax

public void setData( String format, Object data )

public void setData( Class format, Object data )

public void setData( Object data )

Parameters

format

A String object or class that represents the format of the data to store.

data

An object that represents the data to store.

Remarks

Use the first and second versions of this method to define the format of the data being stored in the Data object. Use the third version to assign the object without supplying format information. The fields in the DataFormats class can be used to define the format of the data being stored.

See Also DataObject, getData


IMessageFilter Interface

Defines a message filter interface.

package com.ms.wfc.app

public interface IMessageFilter

Remarks

A class that implements the IMessageFilter interface can be added to the application's message pump to filter out a message or perform other operations before or after the message is dispatched to a form or control. To add the message filter to an application's message pump, use the addMessageFilter method in the Application class.


 IMessageFilter Methods

IMessageFilter Methods

Methods | Description
postFilterMessage | Filters out a message after it has been dispatched.
preFilterMessage | Filters out a message before it is dispatched.


 IMessageFilter.postFilterMessage

IMessageFilter.postFilterMessage

Filters out a message after it has been dispatched.

Syntax

public void postFilterMessage( Message m )

Parameters

m

The message that has just been processed.

Remarks

The postFilterMessage method is called after a message has been dispatched to the form or control to handle. Use this method to perform operations that must occur after the message has been handled by the control or form. For example, if the message is the paint event for a form or control, you can use the postFilterMessage method to perform additional drawing routines. To prevent a message from being dispatched, use the preFilterMessage method.


 IMessageFilter.preFilterMessage

IMessageFilter.preFilterMessage

Filters out a message before it is dispatched.

Syntax

public boolean preFilterMessage( Message m )

Parameters

m

The message that is to be dispatched. The message cannot be modified.

Return Value

Returns true to filter the message and prevent it from being dispatched, or returns false to allow the message to continue to the next filter or to be dispatched.

Remarks

Use the preFilterMessage method to filter out a message before it is dispatched to a control or form. For example, to prevent the click event of a Button control from being dispatched to the control, you implement the preFilterMessage method and return a true value when the click message occurs. You can also use this method to perform code work that is needed before the message is dispatched. To work with the message after it has been dispatched, use the postFilterMessage method.


Locale Class

Encapsulates a Win32 Locale Identifier (LCID).

package com.ms.wfc.app

public final class Locale

Remarks

This class allows you to retrieve and store locale information for a given thread. You should always use the current thread's locale for all locale-specific operations. If you can't use the thread locale for some reason, then you must use the user locale.


 Locale Methods

Locale Methods

Constructors | Description
Locale | Creates a new Locale object with the calling thread's current locale.

Methods | Description
compareStrings | Compares two Strings for this locale.
equals | Compares the current Locale object to the object assigned in the obj parameter.
getAbbrevCountry | Retrieves the abbreviated name of the country from the ISO Standard 3166.
getAbbrevDayName | Retrieves the native abbreviated name for the specific day of the week.
getAbbrevLanguage | Retrieves the abbreviated name of the locale's language.
getAbbrevMonthName | Retrieves the native abbreviated name for a specific month.
getAMTimeMark | Retrieves a String that represents the AM designator.
getCalendarType | Retrieves the current calendar type.
getCenturyFormat | Determines if the year specifier is a 4-digit or a 2-digit century.
getCharacterSet | Retrieves the character set for this locale.
getCompareIgnoreCase | Determines if string comparisons will ignore case.
getCompareIgnoreKana | Determines if string comparisons will ignore kana.
getCompareIgnoreKashida | Determines if string comparisons will ignore kashida.
getCompareIgnoreNonSpace | Determines if string comparisons will ignore nonspacing characters.
getCompareIgnoreSymbols | Determines if string comparisons will ignore symbols.
getCompareIgnoreWidth | Determines if string comparisons will ignore the width of characters.
getCountry | Retrieves the fully localized name of the country.
getCountryCode | Retrieves the country code, based on international telephone codes.
getCurrencyDecimalGrouping | Retrieves sizes for each group of monetary digits to the left of the decimal.
getCurrencyDecimalSeparator | Retrieves the character used as the monetary decimal separator.
getCurrencyFractionalDigits | Retrieves the number of fractional digits for the local monetary format.
getCurrencyNegativePosition | Determines the position of the monetary symbol used for a negative monetary value.
getCurrencyNegativeSeparation | Determines if a space is provided between the negative monetary symbol and its monetary value.
getCurrencyPositivePosition | Determines the position of the monetary symbol used for a positive monetary value.
getCurrencyPositiveSeparation | Determines if a space is provided between the positive monetary symbol and its monetary value.
getCurrencySymbol | Retrieves the symbol used as the local monetary symbol.
getCurrencyThousandSeparator | Retrieves the symbol used as the monetary separator between groups of digits to the left of the decimal.
getCurrentThreadLocale | Retrieves the Locale object for the current thread.
getDateSeparator | Retrieves the symbol used as the locale's date separator.
getDayLeadingZero | Determines whether or not a leading zero is used for dates that have single digit days.
getDayName | Retrieves the native long name for the specific day of the week.
getDecimalGrouping | Retrieves sizes for each group of digits to the left of the decimal.
getDecimalSeparator | Retrieves the character used as the decimal separator.
getDefaultAnsiCodePage | Retrieves the American National Standards Institute (ANSI) code page associated with this locale.
getDefaultCountry | Retrieves the country code for the principal country in this locale.
getDefaultLanguage | Retrieves the language identifier for the principal language spoken in this locale.
getDefaultMacCodePage | Retrieves the Apple Macintosh code page associated with the locale.
getDefaultOEMCodePage | Retrieves the original equipment manufacturer (OEM) code page associated with the locale.
getEnglishCountry | Retrieves the full English name of the country.
getEnglishCurrencyName | Retrieves the full English name of the currency system associated with the locale.
getEnglishLanguage | Retrieves the full English name of the language as specified by the International Organization for Standardization (ISO) Standard 639.
getFirstDayOfWeek | Retrieves the day of the week that is considered the first day of the week in the current locale.
getFirstWeekOfYear | Retrieves a value representing the first week of the year for the current locale.
getFractionalDigits | Retrieves the number of fractional digits that can be specified for the current locale.
getInstalledLocales | Retrieves an array of Locale objects for all of the locales that are currently installed on the computer.
getIntlCurrencyFractionalDigits | Retrieves the number of fractional digits that are used in the local monetary format.
getIntlCurrencySymbol | Retrieves the three characters of the international monetary symbol specified in ISO 4217.
getISO3116CountryName | Retrieves the country name as defined by the International Standards Organization's (IS0) 3116 standard.
getISO639LanguageName | Retrieves the language name as defined by the International Standards Organization's (ISO) 639 standard.
getLanguage | Retrieves the full localized name of the language.
getLanguageId | Retrieves the language identifier indicating the language of the current locale.
getLCID | Retrieves the LCID that the Locale object represents.
getLeadingZero | Determines whether or not a leading zero is specified for decimal values.
getListSeparator | Retrieves the character used to separate list items in the current locale.
getLongDateFormatString | Retrieves the long date formatting string for this locale.
getLongDateOrder | Retrieves the long date format order.
getMeasurementSystem | Retrieves the system of measurement used in the current locale.
getMonthLeadingZero | Determines whether or not a leading zero is specified in month fields in a date.
getMonthName | Retrieves the native long name for a specific month.
getNativeCountry | Retrieves the native name of the country.
getNativeCurrencyName | Retrieves the native name of the currency system associated with the locale.
getNativeDigits | Retrieves the native equivalents to the ASCII characters 0 through 9 used in the current locale.
getNativeLanguage | Retrieves the native name of the language used in the current locale.
getNegativeCurrencyMode | Retrieves the negative currency format for the current locale.
getNegativeNumberMode | Retrieves the negative number format for the current locale.
getNegativePosition | Retrieves the formatting index for negative values.
getNegativeSign | Retrieves the value of the negative sign.
getOptionalCalendarType | Provides additional calendar types.
getParentLocale | Provides the parent locale for the thread calling this method.
getPMTimeMark | Retrieves the PM designator.
getPositiveCurrencyMode | Retrieves the positive currency mode.
getPositivePosition | Retrieves the formatting index for positive values.
getPositiveSign | Retrieves the value of the positive sign.
getShortDateFormatString | Retrieves a short date formatting string for this locale.
getShortDateOrder | Retrieves a short date format-ordering specifier.
getSortId | Retrieves the SortID for this locale.
getSupportedLocales | Retrieves an array of all the locales that are currently supported by the system.
getSystemDefaultLocale | Retrieves the system's default locale.
getThousandSeparator | Retrieves the symbol used to separate groups of digits to the left of the decimal.
getTimeFormat | Retrieves the time format specifier.
getTimeFormatString | Retrieves a String describing the time formatting for this thread's locale.
getTimeLeadingZero | Retrieves information that specifies whether or not there are leading zeros in the hour position for a time field.
getTimeMarkPosition | Retrieves an integer value indication where the TimeMark(AM/PM) is placed.
getTimeSeparator | Retrieves the symbol used for the time separator.
getUserDefaultLocale | Retrieves the symbol for the default user locale.
getYearMonthFormatString | Retrieves information for formatting the Year/Month for the locale.
setAMTimeMark | Sets a String with the AM designator.
setCalendarType | Sets the current calendar type.
setCompareIgnoreCase | Sets the case sensitivity of string comparisons.
setCompareIgnoreKana | Sets the kana sensitivity of string comparisons.
setCompareIgnoreKashida | Sets the kashida sensitivity of string comparisons.
setCompareIgnoreNonSpace | Sets the nonspacing character sensitivity of string comparisons.
setCompareIgnoreSymbols | Sets the symbol sensitivity of string comparisons.
setCompareIgnoreWidth | Sets the width sensitivity of string comparisons.
setCurrencyDecimalGrouping | Sets the size for each group of monetary digits to the left of the decimal.
setCurrencyDecimalSeparator | Sets the symbol to be used as the monetary decimal separator.
setCurrencyFractionalDigits | Sets the number of fractional digits used by the local monetary format.
setCurrencySymbol | Sets the symbol to be used as the local monetary symbol.
setCurrencyThousandSeparator | Sets the symbol used as the monetary separator between groups of digits to the left of the decimal.
setDateSeparator | Sets the String to be used as the date separator.
setDecimalGrouping | Set the number of digits for each group of digits to the left of the decimal.
setDecimalSeparator | Sets the value to be used for the decimal separator.
setFirstDayOfWeek | Sets which day to use as the first day in a week.
setFirstWeekOfYear | Sets the criteria for determing which week to use as the first week of the year.
setFractionalDigits | Sets the number of digits to the right of the decimal.
setLeadingZero | Sets whether or not leading zeros will be in the decimal fields.
setListSeparator | Sets the symbol to used to separate items in a list.
setLongDateFormatString | Sets the long date formatting string for this locale.
setMeasurementSystem | Sets the system of measurement to be used.
setNegativeCurrencyMode | Sets the mode to use when displaying negative currency values.
setNegativeNumberMode | Sets the format to use to display negative numbers.
setNegativeSign | Sets the value describing the negative sign.
setPMTimeMark | Sets the value to be used as the PM designator.
setPositiveCurrencyMode | Sets the format used to display positive currency values.
setPositiveSign | Sets a value that describes the positive sign.
setShortDateFormatString | Sets the short date formatting string for this locale.
setThousandSeparator | Sets the value used to separate groups of digits to the left of the decimal.
setTimeFormat | Sets the time-format specifier.
setTimeFormatString | Sets the format string used to display time for this locale.
setTimeSeparator | Sets the symbol to use for the time separator.
setYearMonthFormatString | Sets the Year/Month formatting string for the locale.


 Locale.compareStrings

Locale.compareStrings

Compares two Strings for this locale.

Syntax

public int compareStrings( String string1, String string2 )

Parameters

string1

The first String object to compare.

string2

The second String object to compare.

Return Value

Returns 0 if the strings are equal; -1 if string1 is less than string2; or 1 if string1 is greater than string2.

Remarks

Use this method to compare strings of the current locale. The string comparison can be controlled by adjusting the various setCompareIgnoreXXX methods of this class.

See Also setCompareIgnoreCase, setCompareIgnoreKana, setCompareIgnoreNonSpace, setCompareIgnoreSymbols, setCompareIgnoreWidth, setCompareIgnoreKashida


 Locale.equals

Locale.equals

Compares the current Locale object to the object assigned in the obj parameter.

Syntax

public boolean equals( Object obj )

Parameters

obj

The object to compare the current Locale object to.

Return Value

Returns true if the objects are logically equivalent; otherwise, returns false.

Remarks

Use this method to compare the object assigned to the obj parameter to the current Locale object. The method returns true if obj refers to a Locale object representing the same locale.


 Locale.getAbbrevCountry

Locale.getAbbrevCountry

Retrieves the abbreviated name of the country from the ISO Standard 3166.

Syntax

public String getAbbrevCountry()

Return Value

Returns a String object that represents the abbreviated name of the country for the locale.

Remarks

Use this method to obtain the abbreviated name of the country for the current locale. The abbreviated country name uses the ISO Standard 3166 convention for the name.

See Also getCountry, getCountryCode, getDefaultCountry, getNativeCountry, getEnglishCountry, getISO3116CountryName


 Locale.getAbbrevDayName

Locale.getAbbrevDayName

Retrieves the native abbreviated name for the specific day of the week.

Syntax

public String getAbbrevDayName( int day )

Parameters

day

An integer value representing the day of the week to retrieve the name for.

Return Value

Returns a String object that represents the native abbreviated name for day.

Remarks

Use this method to obtain the abbreviated day name in the current locale for the day number specified in the day parameter. A zero value assigned to day returns the current locale's abbreviation for Monday.

See Also getDayName, getFirstDayOfWeek, Days


 Locale.getAbbrevLanguage

Locale.getAbbrevLanguage

Retrieves the abbreviated name of the locale's language.

Syntax

public String getAbbrevLanguage()

Return Value

Returns a String object that represents the abbreviated name of the language for the locale.

Remarks

Use this method to obtain the abbreviated name of the language for the current thread. The abbreviation is created by taking the 2-letter language abbreviation from the ISO Standard 639 and adding a third letter, as appropriate, to indicate the sublanguage.

See Also getDefaultLanguage, getNativeLanguage, getLanguage, getEnglishLanguage, getISO639LanguageName, getLanguageId


 Locale.getAbbrevMonthName

Locale.getAbbrevMonthName

Retrieves the native abbreviated name for a specific month.

Syntax

public String getAbbrevMonthName( int month )

Parameters

month

An integer value that represents the month to retrieve the name for.

Return Value

Returns a String object that represents the native abbreviated name for month.

Remarks

Use this method to obtain the native abbreviated month name of the current locale for the month specified in the month parameter. A value of 1 assigned to the month parameter returns the current locale's abbreviation for January.

See Also getMonthName


 Locale.getAMTimeMark

Locale.getAMTimeMark

Retrieves a String that represents the AM designator.

Syntax

public String getAMTimeMark()

Return Value

Returns a String object containing the AM designator for the current locale.

Remarks

Use this method to obtain the AM designator used when displaying time values in non-military formats for the current locale.

See Also setAMTimeMark


 Locale.getCalendarType

Locale.getCalendarType

Retrieves the current calendar type.

Syntax

public int getCalendarType()

Return Value

Returns an integer value that represents the current calendar type.

Remarks

Use this method to obtain the current calendar type in use within this locale. The information returned from this method can be one of the following values:

Value | Calendar Description
1 | Gregorian (as used in the United States)
2 | Gregorian (using English strings)
3 | Era: Year of the Emperor (Japan)
4 | Era: Year of the Taiwan Region
5 | Tangun Era (Korea)

Use the fields of the Locale.CalendarType class to determine the type of calendar that was returned by this method.

See Also setCalendarType


 Locale.getCenturyFormat

Locale.getCenturyFormat

Determines if the year specifier is a 4-digit or a 2-digit century.

Syntax

public boolean getCenturyFormat()

Return Value

Returns true if a full 4-digit century is in use within this locale; otherwise, returns false (which denotes an abbreviated 2-digit century).


 Locale.getCharacterSet

Locale.getCharacterSet

Retrieves the character set for this locale.

Syntax

public int getCharacterSet()

Return Value

Returns an integer that represents the character set in use in this locale.

See Also CharacterSet


 Locale.getCompareIgnoreCase

Locale.getCompareIgnoreCase

Determines if string comparisons will ignore case.

Syntax

public boolean getCompareIgnoreCase()

Return Value

Returns true if string comparisons will ignore case; otherwise, returns false.

Remarks

Use this method to determine if the Locale object will ignore case when doing string comparisons. By default, this value will return true unless set otherwise by using the setCompareIgnoreCase method.

See Also setCompareIgnoreCase, getCompareIgnoreKana, setCompareIgnoreKana, getCompareIgnoreKashida, setCompareIgnoreKashida, getCompareIgnoreNonSpace, setCompareIgnoreNonSpace, getCompareIgnoreSymbols, setCompareIgnoreSymbols, getComapreIgnoreWidth, setCompareIgnoreWidth


 Locale.getCompareIgnoreKana

Locale.getCompareIgnoreKana

Determines if string comparisons will ignore kana.

Syntax

public boolean getCompareIgnoreKana()

Return Value

Returns true if string comparisons will ignore kana; otherwise, returns false.

Remarks

Use this method to determine if the Locale object will ignore kana when doing string comparisons. By default, this value will return true unless set otherwise by using the setCompareIgnoreKana method.

See Also setCompareIgnoreKana, getCompareIgnoreCase, setCompareIgnoreCase, getCompareIgnoreKashida, setCompareIgnoreKashida, getCompareIgnoreNonSpace, setCompareIgnoreNonSpace, getCompareIgnoreSymbols, setCompareIgnoreSymbols, getComapreIgnoreWidth, setCompareIgnoreWidth


 Locale.getCompareIgnoreKashida

Locale.getCompareIgnoreKashida

Determines if string comparisons will ignore kashida.

Syntax

public boolean getCompareIgnoreKashida()

Return Value

Returns true if string comparisons will ignore kashida; otherwise, returns false.

Remarks

Use this method to determine if the Locale object will ignore kashina when doing string comparisons. By default, this value will return true unless set otherwise by using the setCompareIngnoreKashida method.

See Also setCompareIgnoreKashida, getCompareIgnoreCase, setCompareIgnoreCase, getCompareIgnoreKana, setCompareIgnoreKana, getCompareIgnoreNonSpace, setCompareIgnoreNonSpace, getCompareIgnoreSymbols, setCompareIgnoreSymbols, getCompareIgnoreWidth, setCompareIgnoreWidth


 Locale.getCompareIgnoreNonSpace

Locale.getCompareIgnoreNonSpace

Determines if string comparisons will ignore nonspacing characters.

Syntax

public boolean getCompareIgnoreNonSpace()

Return Value

Returns true if string comparisons will ignore nonspacing characters; otherwise, returns false.

Remarks

Use this method to determine if the Locale object will ignore nonspacing characters when doing string comparisons. By default, this value will return true unless set otherwise by using the setCompareIgnoreNonSpace method.

See Also setCompareIgnoreNonSpace, getCompareIgnoreCase, setCompareIgnoreCase, getCompareIgnoreKana, setCompareIgnoreKana, getCompareIgnoreKashida, setCompareIgnoreKashida, getCompareIgnoreSymbols, setCompareIgnoreSymbols, getComapreIgnoreWidth, setCompareIgnoreWidth


 Locale.getCompareIgnoreSymbols

Locale.getCompareIgnoreSymbols

Determines if string comparisons will ignore symbols.

Syntax

public boolean getCompareIgnoreSymbols()

Return Value

Returns true if string comparisons will ignore symbols; otherwise, returns false.

Remarks

Use this method to determine if the Locale object will ignore symbols when doing string comparisons. By default, this value will return true unless set otherwise by using the setCompareIgnoreSymbols method.

See Also setCompareIgnoreSymbols, getCompareIgnoreCase, setCompareIgnoreCase, getCompareIgnoreKana, setCompareIgnoreKana, getCompareIgnoreKashida, setCompareIgnoreKashida, getCompareIgnoreNonSpace, setCompareIgnoreNonSpace, getComapreIgnoreWidth, setCompareIgnoreWidth


 Locale.getCompareIgnoreWidth

Locale.getCompareIgnoreWidth

Determines if string comparisons will ignore the width of characters.

Syntax

public boolean getCompareIgnoreWidth()

Return Value

Returns true if string comparisons will ignore the width of characters; otherwise, returns false.

Remarks

Use this method to determine if the Locale object will ignore the width of characters when doing string comparisons. By default, this value will return true unless set otherwise by using the setCompareIgnoreWidth method.

See Also setCompareIgnoreWidth, getCompareIgnoreCase, setCompareIgnoreCase, getCompareIgnoreKana, setCompareIgnoreKana, getCompareIgnoreKashida, setCompareIgnoreKashida, getCompareIgnoreNonSpace, setCompareIgnoreNonSpace, getCompareIgnoreSymbols, setCompareIgnoreSymbols


 Locale.getCountry

Locale.getCountry

Retrieves the fully localized name of the country.

Syntax

public String getCountry()

Return Value

Returns a String object denoting the fully localized name of the country.

See Also getDefaultCountry, getNativeCountry, getCountryCode, getEnglishCountry, getAbbrevCountry, getISO3116CountryName


 Locale.getCountryCode

Locale.getCountryCode

Retrieves the country code, based on international telephone codes.

Syntax

public int getCountryCode()

Return Value

Returns an integer value that denotes the country code for the current locale.

Remarks

Use this method to retrieve the country code for the current locale. You can use the country code to determine which country the current locale is in, as well as to display the appropriate country code when requesting telephone number information in an application.

See Also getCountry, getDefaultCountry, getNativeCountry, getEnglishCountry, getAbbrevCountry, getISO3116CountryName


 Locale.getCurrencyDecimalGrouping

Locale.getCurrencyDecimalGrouping

Retrieves sizes for each group of monetary digits to the left of the decimal.

Syntax

public String getCurrencyDecimalGrouping()

Return Value

Returns a String object that represents the description of monetary decimal grouping.

Remarks

Use this method to retrieve grouping information for currency within a specific local. An explicit size is needed for each group; sizes are separated by semicolons. If the last value is zero, the preceding value is repeated. For example, if values are grouped in thousands the return value of this method will be "3;0,".

See Also setCurrencyDecimalGrouping, getCurrencyDecimalSeparator, getDecimalGrouping


 Locale.getCurrencyDecimalSeparator

Locale.getCurrencyDecimalSeparator

Retrieves the character used as the monetary decimal separator.

Syntax

public String getCurrencyDecimalSeparator()

Return Value

Returns a String object that contains the character used as the monetary decimal separator.

See Also setCurrencyDecimalSeparator, getCurrencyDecimalGrouping, getCurrencyDecimalSeparator


 Locale.getCurrencyFractionalDigits

Locale.getCurrencyFractionalDigits

Retrieves the number of fractional digits for the local monetary format.

Syntax

public int getCurrencyFractionalDigits()

Return Value

Returns an integer value that represents the number of fractional digits for the local monetary format.

See Also setCurrencyFractionalDigits


 Locale.getCurrencyNegativePosition

Locale.getCurrencyNegativePosition

Determines the position of the monetary symbol used for a negative monetary value.

Syntax

public boolean getCurrencyNegativePosition()

Return Value

Returns true if the negative monetary symbol precedes the monetary value. A false value denotes that the negative monetary symbol follows the monetary value.

Remarks

Use this method to ensure that negative monetary values are correctly specified for the current locale.

See Also getCurrencyNegativeSeparation, getCurrencyPositivePosition, getCurrencyPositiveSeparation


 Locale.getCurrencyNegativeSeparation

Locale.getCurrencyNegativeSeparation

Determines if a space is provided between the negative monetary symbol and its monetary value.

Syntax

public boolean getCurrencyNegativeSeparation()

Return Value

Returns true if the monetary symbol is separated by a space from the negative monetary value; otherwise, returns false if no space is provided.

Remarks

Use this method to ensure that negative monetary values are correctly specified for the current locale.

See Also getCurrencyNegativePosition, getCurrencyPositivePosition, getCurrencyPositiveSeparation


 Locale.getCurrencyPositivePosition

Locale.getCurrencyPositivePosition

Determines the position of the monetary symbol used for a positive monetary value.

Syntax

public int getCurrencyPositivePosition()

Return Value

Returns an integer value that represents the position of the monetary symbol for a positive monetary value. A value of 1 denotes that the symbol precedes the monetary value while a 0 value denotes that the monetary symbol follows the monetary value.

Remarks

Use this method to ensure that positive monetary values are correctly specified for the current locale.

See Also getCurrencyNegativePosition, getCurrencyPositiveSeparation, getCurrencyNegativeSeparation


 Locale.

Locale.getCurrencyPositiveSeparation

Determines if a space is provided between the positive monetary symbol and its monetary value.

Syntax

public boolean getCurrencyPositiveSeparation()

Return Value

Returns true if the monetary symbol is separated by a space from the positive monetary value; otherwise, returns false if no space is provided.

Remarks

Use this method to ensure that positive monetary values are correctly specified for the current locale.

See Also getCurrencyPositivePosition, getCurrencyNegativeSeparation, getCurrencyNegativePosition


 Locale.getCurrencySymbol

Locale.getCurrencySymbol

Retrieves the symbol used as the local monetary symbol.

Syntax

public String getCurrencySymbol()

Return Value

Returns a String object that contains the symbol used as the local monetary symbol.

See Also setCurrencySymbol


 Locale.getCurrencyThousandSeparator

Locale.getCurrencyThousandSeparator

Retrieves the symbol used as the monetary separator between groups of digits to the left of the decimal.

Syntax

public String getCurrencyThousandSeparator()

Return Value

Returns a String object that contains the symbol used to separate monetary digit groups.

See Also setCurrencyThousandSeparator


 Locale.getCurrentThreadLocale

Locale.getCurrentThreadLocale

Retrieves the Locale object for the current thread.

Syntax

public static final Locale getCurrentThreadLocale()

Return Value

Returns a Locale object that represents the locale for the current thread.


 Locale.getDateSeparator

Locale.getDateSeparator

Retrieves the symbol used as the locale's date separator.

Syntax

public String getDateSeparator()

Return Value

Returns a String object that contains the symbol used as the date separator.

Remarks

Use this method to ensure that date values are correctly specified for the current locale.

See Also setDateSeparator


 Locale.getDayLeadingZero

Locale.getDayLeadingZero

Determines whether or not a leading zero is used for dates that have single digit days.

Syntax

public boolean getDayLeadingZero()

Return Value

Returns true if days should have leading zeros in dates; otherwise, returns false (denotes no leading zeros).

Remarks

Use this method to ensure that date values are correctly specified for the current locale.

See Also Locale.LeadingZeros, getMonthLeadingZero


 Locale.getDayName

Locale.getDayName

Retrieves the native long name for the specific day of the week.

Syntax

public String getDayName( int day )

Parameters

day

An integer value that corresponds to one of the Days values and represents the day of the week to retrieve the name for.

Return Value

Returns a String object that represents the native long name for the specified day.

Remarks

When calling this method, specifying a value of 0 for the day parameter will return the locale's string name for Monday.

See Also getFirstDayOfWeek, getAbbrevDayName


 Locale.getDecimalGrouping

Locale.getDecimalGrouping

Retrieves sizes for each group of digits to the left of the decimal.

Syntax

public String getDecimalGrouping()

Return Value

Returns a String object that represents the description of decimal grouping.

Remarks

An explicit size is needed for each group; sizes are separated by semicolons. If the last value is zero, the preceding value is repeated. For example, if values are grouped in thousands the return value of getDecimalGrouping will be "3;0".

See Also setDecimalGrouping, getDecimalSeparator


 Locale.getDecimalSeparator

Locale.getDecimalSeparator

Retrieves the character used as the decimal separator.

Syntax

public String getDecimalSeparator()

Return Value

Returns a String object containing the character used as the decimal separator.

See Also setDecimalSeparator, getDecimalGrouping


 Locale.getDefaultAnsiCodePage

Locale.getDefaultAnsiCodePage

Retrieves the American National Standards Institute (ANSI) code page associated with this locale.

Syntax

public int getDefaultAnsiCodePage()

Return Value

Returns an integer value representing the ANSI code page for this locale.

Remarks

Use this method to determine the ANSI code page number for a locale. A code page is a character set, which can include numbers, punctuation marks, and other glyphs. Different languages and locales may use different code pages. For example, ANSI code page 1252 is used for American English and most European languages; OEM code page 932 is used for Japanese Kanji. Many code pages share the ASCII character set for characters in the range 0x00 – 0x7F.

See Also getDefaultOEMCodePage, getDefaultMacCodePage


 Locale.getDefaultCountry

Locale.getDefaultCountry

Retrieves the country code for the principal country in this locale.

Syntax

public int getDefaultCountry()

Return Value

Returns an integer value that represents the default country code for this locale.

Remarks

This method is provided so that partially specified locales can be completed with default values.

See Also getCountryCode, getISO3116CountryName, getAbbrevCountry, getEnglishCountry, getNativeCountry


 Locale.getDefaultLanguage

Locale.getDefaultLanguage

Retrieves the language identifier for the principal language spoken in this locale.

Syntax

public int getDefaultLanguage()

Return Value

Returns an integer that represents the language identifier for the principal language in this locale.

Remarks

This method is provided so that partially specified locales can be completed with default values.

See Also getAbbrevLanguage, getNativeLanguage, getLanguage, getEnglishLanguage, getISO639LanguageName, getLanguageId


 Locale.getDefaultMacCodePage

Locale.getDefaultMacCodePage

Retrieves the Apple Macintosh code page associated with the locale.

Syntax

public int getDefaultMacCodePage()

Return Value

Returns an integer value that represents the code page for Apple Macintosh computers.

See Also getDefaultAnsiCodePage, getDefaultOEMCodePage


 Locale.getDefaultOEMCodePage

Locale.getDefaultOEMCodePage

Retrieves the original equipment manufacturer (OEM) code page associated with the locale.

Syntax

public int getDefaultOEMCodePage()

Return Value

Returns an integer value that represents the OEM code page for this locale.

See Also getDefaultAnsiCodePage, getDefaultMacCodePage


 Locale.getEnglishCountry

Locale.getEnglishCountry

Retrieves the full English name of the country.

Syntax

public String getEnglishCountry()

Return Value

Returns a String object that contains the full English name of the country.

Remarks

The return value of this method is always restricted to characters that can be mapped to the ASCII 127-character subset.

See Also getCountry, getCountryCode, getAbbrevCountry, getISO3116CountryName, getNativeCountry, getDefaultCountry


 Locale.getEnglishCurrencyName

Locale.getEnglishCurrencyName

Retrieves the full English name of the currency system associated with the locale.

Syntax

public String getEnglishCurrencyName()

Return Value

Returns a String object representing the full English name of the currency system associated with the locale.

See Also getCurrencySymbol, setCurrencySymbol


 Locale.getEnglishLanguage

Locale.getEnglishLanguage

Retrieves the full English name of the language as specified by the International Organization for Standardization (ISO) Standard 639.

Syntax

public String getEnglishLanguage()

Return Value

Returns a String object that represents the full English name of the language.

Remarks

The return value of this method is always restricted to characters that can be mapped to the ASCII 127-character subset.

See Also getAbbrevLanguage, getDefaultLanguage, getNativeLanguage, getLanguage, getISO639LanguageName, getLanguageId


 Locale.getFirstDayOfWeek

Locale.getFirstDayOfWeek

Retrieves the day of the week that is considered the first day of the week in the current locale.

Syntax

public int getFirstDayOfWeek()

Return Value

Returns an integer value that represents the day of the week that is considered the first day in a week.

Remarks

Use this method to retrieve the first day of a week for a locale. The value returned by the getFirstDayOfWeek method can be one of the following values:

Value | Day of the Week
0 | Monday
1 | Tuesday
2 | Wednesday
3 | Thursday
4 | Friday
5 | Saturday
6 | Sunday

See Also setFirstDayOfWeek, getDayName, getAbbrevDayName


 Locale.getFirstWeekOfYear

Locale.getFirstWeekOfYear

Retrieves a value representing the first week of the year for the current locale.

Syntax

public int getFirstWeekOfYear()

Return Value

Returns an integer that identifies the first week of the year for the current locale.

Remarks

Use this method to retrieve the first week of the year for a locale. The value returned by the getFirstWeekOfYear method can be one of the following values:

Values | Description
0 | The week that contains January 1st is the first week of that year.
1 | The first full week following January 1st is the first week of the year.
2 | The first week that contains at least four days is the first week of that year.

See Also setFirstWeekOfYear


 Locale.getFractionalDigits

Locale.getFractionalDigits

Retrieves the number of fractional digits that can be specified for the current locale.

Syntax

public int getFractionalDigits()

Return Value

Returns an integer value representing the number of fractional digits.

See Also setFractionalDigits


 Locale.getInstalledLocales

Locale.getInstalledLocales

Retrieves an array of Locale objects for all of the locales that are currently installed on the computer.

Syntax

public static Locale[] getInstalledLocales()

Return Value

Returns an array of Locale objects that represent all installed locales.

Remarks

Use this method to determine the locales that are available to your application.

See Also getSupportedLocales


 Locale.getIntlCurrencyFractionalDigits

Locale.getIntlCurrencyFractionalDigits

Retrieves the number of fractional digits that are used in the local monetary format.

Syntax

public int getIntlCurrencyFractionalDigits()

Return Value

Returns an integer that represents the number of fractional digits that are used in the local monetary format.

See Also getFractionalDigits, setFractionalDigits


 Locale.getIntlCurrencySymbol

Locale.getIntlCurrencySymbol

Retrieves the three characters of the international monetary symbol specified in ISO 4217.

Syntax

public String getIntlCurrencySymbol()

Return Value

Returns a String object containing the character's international currency symbol.

Remarks

The international monetary symbols returned by this method are defined in "Codes for the Representation of Currencies and Funds" as defined by the International Standards Organization (ISO) 4217 standard. The character that follows the first three characters of the monetary symbol defines the character that separates the monetary symbol from its monetary amount.

See Also getCurrencySymbol, setCurrencySymbol


 Locale.getISO3116CountryName

Locale.getISO3116CountryName

Retrieves the country name as defined by the International Standards Organization's (IS0) 3116 standard.

Syntax

public String getISO3116CountryName()

Return Value

Returns a String object that represents the IS0 3116 country name.

See Also getCountry, getCountryCode, getEnglishCountry, getAbbrevCountry, getNativeCountry, getDefaultCountry


 Locale.getISO639LanguageName

Locale.getISO639LanguageName

Retrieves the language name as defined by the International Standards Organization's (ISO) 639 standard.

Syntax

public String getISO639LanguageName()

Return Value

Returns a String object that represents the IS0 639 language name.

See Also getAbbrevLanguage, getDefaultLanguage, getNativeLanguage, getLanguage, getEnglishLanguage, getLanguageId


 Locale.getLanguage

Locale.getLanguage

Retrieves the full localized name of the language.

Syntax

public String getLanguage()

Return Value

Returns a String object that represents the fully localized name of the language for the current locale.

See Also getAbbrevLanguage, getDefaultLanguage, getNativeLanguage, getEnglishLanguage, getISO639LanguageName, getLanguageId


 Locale.getLanguageId

Locale.getLanguageId

Retrieves the language identifier indicating the language of the current locale.

Syntax

public int getLanguageId()

Return Value

Returns an integer value that represents the language identifier for the current locale.

See Also getAbbrevLanguage, getDefaultLanguage, getNativeLanguage, getLanguage, getEnglishLanguage, getISO639LanguageName


 Locale.getLCID

Locale.getLCID

Retrieves the LCID that the Locale object represents.

Syntax

public int getLCID()

Return Value

Returns an integer value that represents the Win32 LCID of this locale.

Remarks

Use this method to obtain the LCID for the current locale. The getLCID method provides for interoperability with Win32 API's.


 Locale.getLeadingZero

Locale.getLeadingZero

Determines whether or not a leading zero is specified for decimal values.

Syntax

public boolean getLeadingZero()

Return Value

Returns true if a leading zero is provided before all decimal fields; otherwise, returns false.

See Also setLeadingZeros, Locale.LeadingZeros


 Locale.getListSeparator

Locale.getListSeparator

Retrieves the character used to separate list items in the current locale.

Syntax

public String getListSeparator()

Return Value

Returns a String object containing the character used to separate list items.

Remarks

Use this method to determine the proper character to use for the current locale to separate items in a list of items. For example, a comma is used in many locales.

See Also setListSeparator


 Locale.getLongDateFormatString

Locale.getLongDateFormatString

Retrieves the long date formatting string for this locale.

Syntax

public String getLongDateFormatString()

Return Value

Returns a String object that contains the long date formatting string for this locale.

Remarks

The String returned by this method can consist of a combination of day, month, and year format pictures (as defined in the following table) and any string of characters enclosed in single quotes. Characters in single quotes remain as given.

Day Values | Description
d | The day of the month as digits without leading zeros for single digit days.
dd | The day of the month as digits with leading zeros for single digit days.
ddd | The day of the week as a three letter abbreviation.
dddd | The day of the week name.
Month Values | Description
m | The month as digits without leading zeros for single digit months.
mm | The month as digits with leading zeros for single digit months.
mmm | The month as a three letter abbreviation.
mmmm | The month name.
Year Values | Description
y | The year represented only as the last digit.
yy | The year represented only as the last two digits.
yyyy | The year represented by the full 4 digits.

See Also setLongDateFormatString, setShortDateFormatString, getShortDateFormatString


 Locale.getLongDateOrder

Locale.getLongDateOrder

Retrieves the long date format order.

Syntax

public int getLongDateOrder()

Return Value

Returns an integer value that represents the long date format order.

Remarks

This method allows you to determine the date format for long date formats. The value returned by the getLongDateOrder method can be one of the following values:

Value | Format
0 | Month-Day-Year
1 | Day-Month-Year
2 | Year-Month-Day

See Also Locale.DateFormatOrder


 Locale.getMeasurementSystem

Locale.getMeasurementSystem

Retrieves the system of measurement used in the current locale.

Syntax

public int getMeasurementSystem()

Return Value

Returns an integer value that represents the measurement system for the current locale.

Remarks

This method retrieves the measurement system used by a locale. A return value of 0 indicates the metric system is in use in the current locale while a value of 1 indicates that the United States measurement system is in use.

See Also Locale.MeasurementSystem, setMeasurementSystem


 Locale.getMonthLeadingZero

Locale.getMonthLeadingZero

Determines whether or not a leading zero is specified in month fields in a date.

Syntax

public boolean getMonthLeadingZero()

Return Value

Returns true if a leading zero is provided for months that that are single digits; otherwise, returns false.

See Also Locale.LeadingZeros, getDayLeadingZero, getLeadingZero, setLeadingZeros


 Locale.getMonthName

Locale.getMonthName

Retrieves the native long name for a specific month.

Syntax

public String getMonthName( int month )

Parameters

month

An integer value that represents the month to retrieve the name for. For example specifying a value of 1 will return "January".

Return Value

Returns a String object that represents the native long name for the month specified by the month parameter.

See Also getAbbrevMonthName


 Locale.getNativeCountry

Locale.getNativeCountry

Retrieves the native name of the country.

Syntax

public String getNativeCountry()

Return Value

Returns a String object that represents the native name of the country.

See Also getCountry, getCountryCode, getAbbrevCountry, getISO3116CountryName, getNativeCountry, getDefaultCountry


 Locale.getNativeCurrencyName

Locale.getNativeCurrencyName

Retrieves the native name of the currency system associated with the locale.

Syntax

public String getNativeCurrencyName()

Return Value

Returns a String object that represents the native name of the currency system associated with the locale.

See Also getCurrencySymbol, getEnglishCurrencyName, getISO3116CountryName


 Locale.getNativeDigits

Locale.getNativeDigits

Retrieves the native equivalents to the ASCII characters 0 through 9 used in the current locale.

Syntax

public String getNativeDigits()

Return Value

Returns a String object that contains the native equivalents to the ASCII characters 0 through 9.


 Locale.getNativeLanguage

Locale.getNativeLanguage

Retrieves the native name of the language used in the current locale.

Syntax

public String getNativeLanguage()

Return Value

Returns a String object that contains the native name of the language.

See Also getAbbrevLanguage, getDefaultLanguage, getLanguage, getEnglishLanguage, getISO639LanguageName, getLanguageId


 Locale.getNegativeCurrencyMode

Locale.getNegativeCurrencyMode

Retrieves the negative currency format for the current locale.

Syntax

public int getNegativeCurrencyMode()

Return Value

Returns an integer value that represents the negative currency format for the current locale.

Remarks

The return value of this method can be one of the following values:

Value | Format
0 | ($1.1)
1 | -$1.1
2 | $-1.1
3 | $1.1-
4 | (1.1$)
5 | -1.1$
6 | 1.1-$
7 | 1.1$-
8 | -1.1 $ (space before $)
9 | -$ 1.1 (space after $)
10 | 1.1 $- (space before $)
11 | $ 1.1- (space after $)
12 | $ -1.1 (space after $)
13 | 1.1- $ (space before $)
14 | ($ 1.1) (space after $)
15 | (1.1 $) (space before $)

See Also setNegativeCurrencyMode, getPositiveCurrencyMode, setPositiveCurrencyMode


 Locale.getNegativeNumberMode

Locale.getNegativeNumberMode

Retrieves the negative number format for the current locale.

Syntax

public int getNegativeNumberMode()

Return Value

Returns an integer value that represents the negative number format.

Remarks

The return value of this method can be one of the following values:

Value | Format
0 | (1.1)
1 | -1.1
2 | - 1.1
3 | 1.1-
4 | 1.1 -

You can compare the return value of the getNegativeNumberMode method against the fields of the Locale.NegativeNumberMode class to determine the negative number format for the current locale.

See Also setNegativeNumberMode


 Locale.getNegativePosition

Locale.getNegativePosition

Retrieves the formatting index for negative values.

Syntax

public int getNegativePosition()

Return Value

Returns an integer value that represents the formatting index for negative values.

Remarks

The index value returned by this method can be one of the following values:

Value | Description
0 | Parentheses surround the amount and the monetary symbol.
1 | The sign string precedes the amount and the monetary symbol.
2 | The sign string succeeds the amount and the monetary symbol.
3 | The sign string immediately precedes the monetary symbol.
4 | The sign string immediately succeeds the monetary symbol.

See Also getPostivePosition


 Locale.getNegativeSign

Locale.getNegativeSign

Retrieves the value of the negative sign.

Syntax

public String getNegativeSign()

Return Value

Returns a String object containing the value for the negative sign.

See Also setNegativeSign, getPositiveSign, setPositiveSign


 Locale.getOptionalCalendarType

Locale.getOptionalCalendarType

Provides additional calendar types.

Syntax

public int getOptionalCalendarType()

Return Value

Returns an integer value that represents additional calendar types.

Remarks

The return value of this method can be a zero-separated list of one or more of the following calendar-type values:

Value | Description
0 | No additional types valid
1 | Gregorian (as in United States)
2 | Gregorian (English strings always)
3 | Era: Year of the Emperor (Japan)
4 | Era: Year of the Taiwan Region
5 | Tangun Era (Korea)

Use the fields of the Locale.CalendarType class to determine the type of calendar that was returned by the getOptionalCalendarType method.

See Also Locale.OptionalCalendarType, setCalendarType


 Locale.getParentLocale

Locale.getParentLocale

Provides the parent locale for the thread calling this method.

Syntax

public Locale getParentLocale()

Return Value

Returns a Locale object that contains the parent locale.

Remarks

Use this method to determine the parent locale of the current locale. A parent locale is the more "neutral" version of a locale. For example, the parent of a U.S. English locale would be a Neutral English locale, the parent of that would be the base Neutral locale.

See Also getInstalledLocales


 Locale.getPMTimeMark

Locale.getPMTimeMark

Retrieves the PM designator.

Syntax

public String getPMTimeMark()

Return Value

Returns a String object that contains the PM designator.

See Also setPMTimeMark, getAMTimeMark, setAMTimeMark


 Locale.getPositiveCurrencyMode

Locale.getPositiveCurrencyMode

Retrieves the positive currency mode.

Syntax

public int getPositiveCurrencyMode()

Return Value

Returns an integer that represents the positive currency mode.

Remarks

The return value of the getPositiveCurrencyMode method can be one of the following values:

Value | Description
0 | Prefix, no separation
1 | Suffix, no separation
2 | Prefix, 1-character separation
3 | Suffix, 1-character separation

See Also Locale.PositiveCurrencyMode, setPositiveCurrencyMode, getNegativeCurrencyMode, setNegativeCurrencyMode


 Locale.getPositivePosition

Locale.getPositivePosition

Retrieves the formatting index for positive values.

Syntax

public int getPositivePosition()

Return Value

Returns an integer value that represents the formatting index for positive values.

Remarks

The formatting index returned by this method can be one of the following values:

Value | Description
0 | Parentheses surround the amount and the monetary symbol.
1 | The sign string precedes the amount and the monetary symbol.
2 | The sign string succeeds the amount and the monetary symbol.
3 | The sign string immediately precedes the monetary symbol.
4 | The sign string immediately succeeds the monetary symbol.

See Also TOPRIGHT


 Locale.getPositiveSign

Locale.getPositiveSign

Retrieves the value of the positive sign.

Syntax

public String getPositiveSign()

Return Value

Returns a String object containing the value of the positive sign.

See Also setPositiveSign, getNegativeSign, setNegativeSign


 Locale.getShortDateFormatString

Locale.getShortDateFormatString

Retrieves a short date formatting string for this locale.

Syntax

public String getShortDateFormatString()

Return Value

Returns a String object that represents the short date formatting string for this locale.

Remarks

The String can consist of a combination of day, month, and year format pictures defined in the Day, Month, Year, and Era Format Pictures table in the National Language Support Constants.

See Also setShortDateFormatString, getLongDateFormatString, setLongDateFormatString


 Locale.getShortDateOrder

Locale.getShortDateOrder

Retrieves a short date format-ordering specifier.

Syntax

public int getShortDateOrder()

Return Value

Returns an integer value that represents the short date format-ordering specifier.

Remarks

The value returned can be one of the following values:

Value | Description
0 | Month-Day-Year
1 | Day-Month-Year
2 | Year-Month-Day

See Also Locale.DateFormatOrder, getLongDateOrder


 Locale.getSortId

Locale.getSortId

Retrieves the SortID for this locale.

Syntax

public int getSortId()

Return Value

Returns an integer that represents a SortID value.

See Also Locale.Sort


 Locale.getSupportedLocales

Locale.getSupportedLocales

Retrieves an array of all the locales that are currently supported by the system.

Syntax

public static Locale[] getSupportedLocales()

Return Value

Returns an array of Locale objects representing all locales supported by the system.

See Also getInstalledLocales


 Locale.getSystemDefaultLocale

Locale.getSystemDefaultLocale

Retrieves the system's default locale.

Syntax

public static final Locale getSystemDefaultLocale()

Return Value

Returns a Locale object that represents the system's default locale.

See Also getParentLocale


 Locale.getThousandSeparator

Locale.getThousandSeparator

Retrieves the symbol used to separate groups of digits to the left of the decimal.

Syntax

public String getThousandSeparator()

Return Value

Returns a String object containing the symbol used to separate digit groups.

See Also setThousandSeparator


 Locale.getTimeFormat

Locale.getTimeFormat

Retrieves the time format specifier.

Syntax

public int getTimeFormat()

Return Value

Returns an integer value that represents the time format specifier.

Remarks

The specified can be one of the following values:

Value | Description
0 | AM / PM 12-hour format
1 | 24-hour format

See Also setTimeFormat


 Locale.getTimeFormatString

Locale.getTimeFormatString

Retrieves a String describing the time formatting for this thread's locale.

Syntax

public String getTimeFormatString()

Return Value

Returns a String object containing the time-formatting string for this locale.

Remarks

The String can consist of a combination of the hour, minute, and second format pictures defined in the Hour, Minute, and Second Format Pictures table in the National Language Support Constants.

See Also setTimeFormatString


 Locale.getTimeLeadingZero

Locale.getTimeLeadingZero

Retrieves information that specifies whether or not there are leading zeros in the hour position for a time field.

Syntax

public boolean getTimeLeadingZero()

Return Value

Returns true if the time field contains leading zeros for hours; otherwise, returns false if there are no leading zeros for hours.

See Also Locale.LeadingZeros


 Locale.getTimeMarkPosition

Locale.getTimeMarkPosition

Retrieves an integer value indication where the TimeMark(AM/PM) is placed.

Syntax

public int getTimeMarkPosition()

Return Value

Returns an integer value of 0 when the TimeMark(AM/PM) is at the end of the time String; otherwise, returns 1 indicating the TimeMark is at the beginning of the time String.


 Locale.getTimeSeparator

Locale.getTimeSeparator

Retrieves the symbol used for the time separator.

Syntax

public String getTimeSeparator()

Return Value

Returns a String object containing the symbol designated as the time separator.

See Also setTimeSeparator


 Locale.getUserDefaultLocale

Locale.getUserDefaultLocale

Retrieves the symbol for the default user locale.

Syntax

public static final Locale getUserDefaultLocale()

Return Value

Returns a Locale object that represents the user's default locale.

See Also getParentLocale


 Locale.getYearMonthFormatString

Locale.getYearMonthFormatString

Retrieves information for formatting the Year/Month for the locale.

Syntax

public String getYearMonthFormatString()

Return Value

Returns a String object containing the Year/Month formatting information for the locale.

Remarks

The information in the String shows the proper format for a date that contains only the year and the month.

See Also setYearMonthFormatString


 Locale.Locale

Locale.Locale

Creates a new Locale object with the calling thread's current locale.

Syntax

public Locale()

public Locale( Locale locale )

public Locale( int lcid )

public Locale( int language, int sublanguage )

public Locale( int language, int sublanguage, int sort )

Parameters

locale

An existing Locale object used to define the values of this Locale object.

lcid

The Win32 Locale ID that this Locale object represents.

language

An integer value that represents the LanguageId for this locale.

sublanguage

An integer value that represents the SubLanguageId for this locale.

sort

An integer value that represents the SortId for this locale.

Remarks

This class provides a number of constructors for creating a Locale object. To define the values for the language, sublanguage, and sort parameters, use the fields of the Locale.Languages, Locale.SubLanguages, Locale.Sort classes, respectively.


 Locale.setAMTimeMark

Locale.setAMTimeMark

Sets a String with the AM designator.

Syntax

public void setAMTimeMark( String value )

Parameters

value

A String object containing the AM designator.

See Also getAMTimeMark


 Locale.setCalendarType

Locale.setCalendarType

Sets the current calendar type.

Syntax

public void setCalendarType( int value )

Parameters

value

An integer value that represents a calendar type.

Remarks

A calendar type can be one of the following values:

Value | Description
1 | Gregorian (as in United States)
2 | Gregorian (English strings always)
3 | Era: Year of the Emperor (Japan)
4 | Era: Year of the Taiwan Region
5 | Tangun Era (Korea)

You can use the fields of the Locale.CalendarType class to determine the type of calendar that was returned by this method.

See Also getCalendarType


 Locale.setCompareIgnoreCase

Locale.setCompareIgnoreCase

Sets the case sensitivity of string comparisons.

Syntax

public void setCompareIgnoreCase( boolean value )

Parameters

value

The new value for the CompareIgnoreCase property.

Remarks

When set to true, string comparisons are done in a case-insensitive manner.

See Also getCompareIgnoreCase, getCompareIgnoreKana, setCompareIgnoreKana, getCompareIgnoreKashida, setCompareIgnoreKashida, getCompareIgnoreNonSpace, setCompareIgnoreNonSpace, getCompareIgnoreSymbols, setCompareIgnoreSymbols, getCompareIgnoreWidth, setCompareIgnoreWidth


 Locale.setCompareIgnoreKana

Locale.setCompareIgnoreKana

Sets the kana sensitivity of string comparisons.

Syntax

public void setCompareIgnoreKana( boolean value )

Parameters

value

The new value for the CompareIgnoreKana property.

Remarks

When set to true, string comparisons will not differentiate between Hiragana and Katakana characters.

See Also getCompareIgnoreKana, getCompareIgnoreCase, setCompareIgnoreCase, getCompareIgnoreKashida, setCompareIgnoreKashida, getCompareIgnoreNonSpace, setCompareIgnoreNonSpace, getCompareIgnoreSymbols, setCompareIgnoreSymbols, getCompareIgnoreWidth, setCompareIgnoreWidth


 Locale.setCompareIgnoreKashida

Locale.setCompareIgnoreKashida

Sets the kashida sensitivity of string comparisons.

Syntax

public void setCompareIgnoreKashida( boolean value )

Parameters

value

The new value for the CompareIgnoreKashida property.

Remarks

When set to true, string comparisons will not differentiate between lengthened and non-lengthened characters.

See Also getCompareIgnoreKashida, getCompareIgnoreCase, setCompareIgnoreCase, getCompareIgnoreKana, setCompareIgnoreKana, getCompareIgnoreNonSpace, setCompareIgnoreNonSpace, getCompareIgnoreSymbols, setCompareIgnoreSymbols, getCompareIgnoreWidth, setCompareIgnoreWidth


 Locale.setCompareIgnoreNonSpace

Locale.setCompareIgnoreNonSpace

Sets the nonspacing character sensitivity of string comparisons.

Syntax

public void setCompareIgnoreNonSpace( boolean value )

Parameters

value

The new value for the CompareIgnoreNonSpace property.

Remarks

When set to true, string comparisons will ignore nonspacing characters.

See Also getCompareIgnoreNonSpace, getCompareIgnoreCase, setCompareIgnoreCase, getCompareIgnoreKana, setCompareIgnoreKana, getCompareIgnoreKashida, setCompareIgnoreKashida, getCompareIgnoreSymbols, setCompareIgnoreSymbols, getCompareIgnoreWidth, setCompareIgnoreWidth


 Locale.setCompareIgnoreSymbols

Locale.setCompareIgnoreSymbols

Sets the symbol sensitivity of string comparisons.

Syntax

public void setCompareIgnoreSymbols( boolean value )

Parameters

value

The new value for the CompareIgnoreSymbols property.

Remarks

When set to true, string comparisons will ignore symbols.

See Also getCompareIgnoreSymbols, getCompareIgnoreCase, setCompareIgnoreCase, getCompareIgnoreKana, setCompareIgnoreKana, getCompareIgnoreKashida, setCompareIgnoreKashida, getCompareIgnoreNonSpace, setCompareIgnoreNonSpace, getCompareIgnoreWidth, setCompareIgnoreWidth


 Locale.setCompareIgnoreWidth

Locale.setCompareIgnoreWidth

Sets the width sensitivity of string comparisons.

Syntax

public void setCompareIgnoreWidth( boolean value )

Parameters

value

The new value for the CompareIgnoreWidth property.

Remarks

When set to true, string comparisons will not differentiate between a single-byte character and the same character as a double-byte character.

See Also getCompareIgnoreWidth, getCompareIgnoreCase, setCompareIgnoreCase, getCompareIgnoreKana, setCompareIgnoreKana, getCompareIgnoreKashida, setCompareIgnoreKashida, getCompareIgnoreNonSpace, setCompareIgnoreNonSpace, getCompareIgnoreSymbols, setCompareIgnoreSymbols, getCompareIgnoreWidth, setCompareIgnoreWidth


 Locale.setCurrencyDecimalGrouping

Locale.setCurrencyDecimalGrouping

Sets the size for each group of monetary digits to the left of the decimal.

Syntax

public void setCurrencyDecimalGrouping( String value )

Parameters

value

A String object that defines the monetary decimal grouping.

Remarks

An explicit size is needed for each group; sizes are separated by semicolons. If the last value is zero, the preceding value is repeated. To group thousands, for example, specify "3;0".

See Also getCurrencyDecimalGrouping


 Locale.setCurrencyDecimalSeparator

Locale.setCurrencyDecimalSeparator

Sets the symbol to be used as the monetary decimal separator.

Syntax

public void setCurrencyDecimalSeparator( String value )

Parameters

value

A String obect that defines the monetary decimal separator.

See Also getCurrencyDecimalSeparator


 Locale.setCurrencyFractionalDigits

Locale.setCurrencyFractionalDigits

Sets the number of fractional digits used by the local monetary format.

Syntax

public void setCurrencyFractionalDigits( int value )

Parameters

value

The number of fractional digits for the local monetary format.

See Also getCurrencyFractionalDigits


 Locale.setCurrencySymbol

Locale.setCurrencySymbol

Sets the symbol to be used as the local monetary symbol.

Syntax

public void setCurrencySymbol( String value )

Parameters

value

A String object defining the symbol to be used as the local monetary symbol.

See Also getCurrencySymbol


 Locale.setCurrencyThousandSeparator

Locale.setCurrencyThousandSeparator

Sets the symbol used as the monetary separator between groups of digits to the left of the decimal.

Syntax

public void setCurrencyThousandSeparator( String value )

Parameters

value

A String object defining the symbol used to separate monetary digit groups.

See Also getCurrencyThousandSeparator


 Locale.setDateSeparator

Locale.setDateSeparator

Sets the String to be used as the date separator.

Syntax

public void setDateSeparator( String value )

Parameters

value

A String object that defines the symbol to use for the date separator.

See Also getDateSeparator


 Locale.setDecimalGrouping

Locale.setDecimalGrouping

Set the number of digits for each group of digits to the left of the decimal.

Syntax

public void setDecimalGrouping( String value )

Parameters

value

A String object describing how to group digits to the left of the decimal.

Remarks

This method requires an explicit size for each group; sizes are separated by semicolons. If the last value is zero, the preceding value is repeated. For example, to group thousands, specify "3;0".

See Also getDecimalGrouping


 Locale.setDecimalSeparator

Locale.setDecimalSeparator

Sets the value to be used for the decimal separator.

Syntax

public void setDecimalSeparator( String value )

Parameters

value

A String object containing the value of the decimal separator.

See Also getDecimalSeparator


 Locale.setFirstDayOfWeek

Locale.setFirstDayOfWeek

Sets which day to use as the first day in a week.

Syntax

public void setFirstDayOfWeek( int value )

Parameters

value

An integer value that corresponds to the first day in a week.

Remarks

When using this method to designate the first day of the week, use the values from the following table:

Value | Description
0 | Monday
1 | Tuesday
2 | Wednesday
3 | Thursday
4 | Friday
5 | Saturday
6 | Sunday

See Also getFirstDayOfWeek


 Locale.setFirstWeekOfYear

Locale.setFirstWeekOfYear

Sets the criteria for determing which week to use as the first week of the year.

Syntax

public void setFirstWeekOfYear( int value )

Parameters

value

An integer value specifying which week to use as the first week of the year.

Remarks

When using this method to designate the first week of the year, use the values from the following table:

Value | Description
0 | Week containing 1/1 is the first week of that year.
1 | First full week following 1/1 is the first week of that year.
2 | First week contains at least 4 days is the first week of that year.

See Also getFirstWeekOfYear


 Locale.setFractionalDigits

Locale.setFractionalDigits

Sets the number of digits to the right of the decimal.

Syntax

public void setFractionalDigits( int value )

Parameters

value

An integer value specifying the number of digits to the right of the decimal.

See Also getFractionalDigits


 Locale.setLeadingZero

Locale.setLeadingZero

Sets whether or not leading zeros will be in the decimal fields.

Syntax

public void setLeadingZero( boolean value )

Parameters

value

A boolean value specifying whether or not leading zeros will be in the decimal fields.

Remarks

When using this method, specifying true in the value parameter denotes leading zeros are used; specifying false denotes leading zeros are not used.

See Also Locale.LeadingZeros, getLeadingZero


 Locale.setListSeparator

Locale.setListSeparator

Sets the symbol to used to separate items in a list.

Syntax

public void setListSeparator( String value )

Parameters

value

A String object containing the symbol used to separate list items.

Remarks

This method specifies which symbol to use to separate list items. For example, a comma is used in many locales.

See Also getListSeparator


 Locale.setLongDateFormatString

Locale.setLongDateFormatString

Sets the long date formatting string for this locale.

Syntax

public void setLongDateFormatString( String value )

Parameters

value

A String object containing the long date formatting string for this locale.

Remarks

The String can consist of a combination of day, month, and year format pictures defined in the Day, Month, Year, and Era Format Pictures table in the National Language Support Constants, and any string of characters enclosed in single quotes. Characters in single quotes will be used in the format they are given.

See Also getLongDateFormatString


 Locale.setMeasurementSystem

Locale.setMeasurementSystem

Sets the system of measurement to be used.

Syntax

public void setMeasurementSystem( int value )

Parameters

value

An integer value of 0 designates to use the metric system; a value of 1 designates to use the U.S. measurement system.

See Also Locale.MeasurementSystem, getMeasurementSystem


 Locale.setNegativeCurrencyMode

Locale.setNegativeCurrencyMode

Sets the mode to use when displaying negative currency values.

Syntax

public void setNegativeCurrencyMode( int value )

Parameters

value

An integer value specifying which negative currency mode to use.

Remarks

This method takes one of the negative currency modes from the following table:

Value | Description
0 | ($1.1)
1 | -$1.1
2 | $-1.1
3 | $1.1-
4 | (1.1$)
5 | -1.1$
6 | 1.1-$
7> | 1.1$-
8 | -1.1 $ (space before $)
9 | -$ 1.1 (space after $)
10 | 1.1 $- (space before $)
11 | $ 1.1- (space after $)
12 | $ -1.1 (space after $)
13 | 1.1- $ (space before $)
14 | ($ 1.1) (space after $)
15 | (1.1 $) (space before $)

See Also getNegativeCurrencyMode


 Locale.setNegativeNumberMode

Locale.setNegativeNumberMode

Sets the format to use to display negative numbers.

Syntax

public void setNegativeNumberMode( int value )

Parameters

value

An integer value representing one of the negative number modes.

Remarks

This method takes a negative number mode from the following table:

Value | Description
0 | (1.1)
1 | -1.1
2 | - 1.1
3 | 1.1-
4 | 1.1 -

See Also Locale.NegativeNumberMode, getNegativeNumberMode


 Locale.setNegativeSign

Locale.setNegativeSign

Sets the value describing the negative sign.

Syntax

public void setNegativeSign( String value )

Parameters

value

A String object containing the value for the negative size.

See Also getNegativeSign


 Locale.setPMTimeMark

Locale.setPMTimeMark

Sets the value to be used as the PM designator.

Syntax

public void setPMTimeMark( String value )

Parameters

value

A String object containing the value for the PM designator.

See Also getPMTimeMark, getAMTimeMark, setAMTimeMark


 Locale.setPositiveCurrencyMode

Locale.setPositiveCurrencyMode

Sets the format used to display positive currency values.

Syntax

public void setPositiveCurrencyMode( int value )

Parameters

value

An integer value representing one of the positive currency modes.

Remarks

This method takes a positive currency mode from the following table:

Value | Description
0 | Prefix, no separation
1 | Suffix, no separation
2 | Prefix, 1-character separation
3 | Suffix, 1-character separation>

See Also Locale.PositiveCurrencyMode, getPositiveCurrencyMode


 Locale.setPositiveSign

Locale.setPositiveSign

Sets a value that describes the positive sign.

Syntax

public void setPositiveSign( String value )

Parameters

value

A String object containing the value for the positive sign.

See Also getPositiveSign


 Locale.setShortDateFormatString

Locale.setShortDateFormatString

Sets the short date formatting string for this locale.

Syntax

public void setShortDateFormatString( String value )

Parameters

value

A String object containing the short date format for this locale.

Remarks

The String can consist of a combination of day, month, and year format pictures defined in the Day, Month, Year, and Era Format Pictures table in the National Language Support Constants.

See Also getShortDateFormatString, getLongDateFormatString, setLongDateFormatString


 Locale.setThousandSeparator

Locale.setThousandSeparator

Sets the value used to separate groups of digits to the left of the decimal.

Syntax

public void setThousandSeparator( String value )

Parameters

value

A String object containing the value used to separate groups of digits.

See Also getThousandSeparator


 Locale.setTimeFormat

Locale.setTimeFormat

Sets the time-format specifier.

Syntax

public void setTimeFormat( int value )

Parameters

value

An integer value containing a time-format specifier.

Remarks

This method takes one of the following time-format specifiers:

Value | Description
0 | AM / PM 12-hour format
1 | 24-hour format

See Also getTimeFormat


 Locale.setTimeFormatString

Locale.setTimeFormatString

Sets the format string used to display time for this locale.

Syntax

public void setTimeFormatString( String value )

Parameters

value

A String object containing a time-formatting string for this locale.

Remarks

The String can consist of a combination of the hour, minute, and second format pictures defined in the Hour, Minute, and Second Format Pictures table in the National Language Support Constants.

See Also getTimeFormatString


 Locale.setTimeSeparator

Locale.setTimeSeparator

Sets the symbol to use for the time separator.

Syntax

public void setTimeSeparator( String value )

Parameters

value

A String object specifying the symbol to use as the time separator.

See Also getTimeSeparator


 Locale.setYearMonthFormatString

Locale.setYearMonthFormatString

Sets the Year/Month formatting string for the locale.

Syntax

public void setYearMonthFormatString( String value )

Parameters

value

A String object specifying the Year/Month formatting string to be used for the locale.

Remarks

This String specifies the proper format for a date that contains only the year and the month.

See Also getYearMonthFormatString


Locale.CalendarType Class

Provides fields that represent the different calendars that can be used in a locale.

Enum
  |
  +--Locale.CalendarType

package com.ms.wfc.app

public static class Locale.CalendarType
extends Enum

Remarks

Use the CalendarType class with the various calendar-related methods in the Locale class.


 Locale.CalendarType Fields

Locale.CalendarType Fields

Fields | Description
ERA_EMPEROR | Specifies the Era: Year of the Emperor (Japan) calendar.
ERA_REPUB_CHINA | Specifies the Era: Year of the Taiwan Region calendar.
ERA_TANGUN | Specifies the Tangun Era (Korea) calendar.
GREGORIAN_ENGLISH | Specifies the Gregorian (using English strings) calendar.
GREGORIAN_US | Specifies the Gregorian (as used in the United States) calendar.


 Locale.CalendarType.ERA_EMPEROR

Locale.CalendarType.ERA_EMPEROR

Specifies the Era: Year of the Emperor (Japan) calendar.

Syntax

public static final int ERA_EMPEROR;


 Locale.CalendarType.ERA_REPUB_CHINA

Locale.CalendarType.ERA_REPUB_CHINA

Specifies the Era: Year of the Taiwan Region calendar.

Syntax

public static final int ERA_REPUB_CHINA;


 Locale.CalendarType.ERA_TANGUN

Locale.CalendarType.ERA_TANGUN

Specifies the Tangun Era (Korea) calendar.

Syntax

public static final int ERA_TANGUN;


 Locale.CalendarType.GREGORIAN_ENGLISH

Locale.CalendarType.GREGORIAN_ENGLISH

Specifies the Gregorian (using English strings) calendar.

Syntax

public static final int GREGORIAN_ENGLISH;


 Locale.CalendarType.GREGORIAN_US

Locale.CalendarType.GREGORIAN_US

Specifies the Gregorian (as used in the United States) calendar.

Syntax

public static final int GREGORIAN_US;


Locale.DateFormatOrder Class

Provides fields that specify various formats for ordering dates.

Enum
  |
  +--Locale.DateFormatOrder

package com.ms.wfc.app

public static final class Locale.DateFormatOrder
extends Enum

Remarks

Use the DateFormatOrder class to evaluate the return value of the Locale.getLongDateOrder or Locale.getShortDateOrder methods.


 Locale.DateFormatOrder Fields

Locale.DateFormatOrder Fields

Fields | Description
DAY_MONTH_YEAR | Specifies the day-month-year calendar ordering.
MONTH_DAY_YEAR | Specifies the month-day-year calendar ordering.
YEAR_MONTH_DAY | Specifies the year-month-day calendar ordering.


 Locale.DateFormatOrder.DAY_MONTH_YEAR

Locale.DateFormatOrder.DAY_MONTH_YEAR

Specifies the day-month-year calendar ordering.

Syntax

public static final int DAY_MONTH_YEAR;


 Locale.DateFormatOrder.MONTH_DAY_YEAR

Locale.DateFormatOrder.MONTH_DAY_YEAR

Specifies the month-day-year calendar ordering.

Syntax

public static final int MONTH_DAY_YEAR;


 Locale.DateFormatOrder.YEAR_MONTH_DAY

Locale.DateFormatOrder.YEAR_MONTH_DAY

Specifies the year-month-day calendar ordering.

Syntax

public static final int YEAR_MONTH_DAY;


Locale.Languages Class

Provides fields that represent defined languages for Locale objects.

package com.ms.wfc.app

public static final class Locale.Languages

Remarks

Use the Languages class with the various language-related methods in the Locale class.


 Locale.Languages Fields

Locale.Languages Fields

Fields | Description
ALBANIAN | Represents the Albanian language.
ARABIC | Represents the Arabic language.
BAHASA | Represents the Bahasa language.
BULGARIAN | Represents the Bulgarian language
CATALAN | Represents the Catalan language.
CHINESE | Represents the Chinese language.
CZECH | Represents the Czech language.
DANISH | Represents the Danish language.
DUTCH | Represents the Dutch language.
ENGLISH | Represents the English language.
FINNISH | Represents the Finnish language.
FRENCH | Represents the French language.
GERMAN | Represents the German language.
GREEK | Represents the Greek language.
HEBREW | Represents the Hebrew language.
HUNGARIAN | Represents the Hungarian language.
ICELANDIC | Represents the Icelandic language.
ITALIAN | Represents the Italian language.
JAPANESE | Represents the Japanese language.
KOREAN | Represents the Korean language.
NEUTRAL | Represents a neutral language.
NORWEGIAN | Represents the Norwegian language.
POLISH | Represents the Polish language.
PORTUGUESE | Represents the Portuguese language.
RHAETO_ROMAN | Represents the Rhaeto-Romance language.
ROMANIAN | Represents the Romanian language.
RUSSIAN | Represents the Russian language.
SERBO_CROATIAN | Represents the Serbo-Croatian language.
SLOVAK | Represents the Slovakian language.
SPANISH | Represents the Spanish language.
SWEDISH | Represents the Swedish language.
THAI | Represents the Thai language.
TURKISH | Represents the Turkish language.
URDU | Represents the Urdu language.


 Locale.Languages.ALBANIAN

Locale.Languages.ALBANIAN

Represents the Albanian language.

Syntax

public static final int ALBANIAN;


 Locale.Languages.ARABIC

Locale.Languages.ARABIC

Represents the Arabic language.

Syntax

public static final int ARABIC;


 Locale.Languages.BAHASA

Locale.Languages.BAHASA

Represents the Bahasa language.

Syntax

public static final int BAHASA;


 Locale.Languages.BULGARIAN

Locale.Languages.BULGARIAN

Represents the Bulgarian language

Syntax

public static final int BULGARIAN;


 Locale.Languages.CATALAN

Locale.Languages.CATALAN

Represents the Catalan language.

Syntax

public static final int CATALAN;


 Locale.Languages.CHINESE

Locale.Languages.CHINESE

Represents the Chinese language.

Syntax

public static final int CHINESE;


 Locale.Languages.CZECH

Locale.Languages.CZECH

Represents the Czech language.

Syntax

public static final int CZECH;


 Locale.Languages.DANISH

Locale.Languages.DANISH

Represents the Danish language.

Syntax

public static final int DANISH;


 Locale.Languages.DUTCH

Locale.Languages.DUTCH

Represents the Dutch language.

Syntax

public static final int DUTCH;


 Locale.Languages.ENGLISH

Locale.Languages.ENGLISH

Represents the English language.

Syntax

public static final int ENGLISH;


 Locale.Languages.FINNISH

Locale.Languages.FINNISH

Represents the Finnish language.

Syntax

public static final int FINNISH;


 Locale.Languages.FRENCH

Locale.Languages.FRENCH

Represents the French language.

Syntax

public static final int FRENCH;


 Locale.Languages.GERMAN

Locale.Languages.GERMAN

Represents the German language.

Syntax

public static final int GERMAN;


 Locale.Languages.GREEK

Locale.Languages.GREEK

Represents the Greek language.

Syntax

public static final int GREEK;


 Locale.Languages.HEBREW

Locale.Languages.HEBREW

Represents the Hebrew language.

Syntax

public static final int HEBREW;


 Locale.Languages.HUNGARIAN

Locale.Languages.HUNGARIAN

Represents the Hungarian language.

Syntax

public static final int HUNGARIAN;


 Locale.Languages.ICELANDIC

Locale.Languages.ICELANDIC

Represents the Icelandic language.

Syntax

public static final int ICELANDIC;


 Locale.Languages.ITALIAN

Locale.Languages.ITALIAN

Represents the Italian language.

Syntax

public static final int ITALIAN;


 Locale.Languages.JAPANESE

Locale.Languages.JAPANESE

Represents the Japanese language.

Syntax

public static final int JAPANESE;


 Locale.Languages.KOREAN

Locale.Languages.KOREAN

Represents the Korean language.

Syntax

public static final int KOREAN;


 Locale.Languages.NEUTRAL

Locale.Languages.NEUTRAL

Represents a neutral language.

Syntax

public static final int NEUTRAL;


 Locale.Languages.NORWEGIAN

Locale.Languages.NORWEGIAN

Represents the Norwegian language.

Syntax

public static final int NORWEGIAN;


 Locale.Languages.POLISH

Locale.Languages.POLISH

Represents the Polish language.

Syntax

public static final int POLISH;


 Locale.Languages.PORTUGUESE

Locale.Languages.PORTUGUESE

Represents the Portuguese language.

Syntax

public static final int PORTUGUESE;


 Locale.Languages.RHAETO_ROMAN

Locale.Languages.RHAETO_ROMAN

Represents the Rhaeto-Romance language.

Syntax

public static final int RHAETO_ROMAN;


 Locale.Languages.ROMANIAN

Locale.Languages.ROMANIAN

Represents the Romanian language.

Syntax

public static final int ROMANIAN;


 Locale.Languages.RUSSIAN

Locale.Languages.RUSSIAN

Represents the Russian language.

Syntax

public static final int RUSSIAN;


 Locale.Languages.SERBO_CROATIAN

Locale.Languages.SERBO_CROATIAN

Represents the Serbo-Croatian language.

Syntax

public static final int SERBO_CROATIAN;


 Locale.Languages.SLOVAK

Locale.Languages.SLOVAK

Represents the Slovakian language.

Syntax

public static final int SLOVAK;


 Locale.Languages.SPANISH

Locale.Languages.SPANISH

Represents the Spanish language.

Syntax

public static final int SPANISH;


 Locale.Languages.SWEDISH

Locale.Languages.SWEDISH

Represents the Swedish language.

Syntax

public static final int SWEDISH;


 Locale.Languages.THAI

Locale.Languages.THAI

Represents the Thai language.

Syntax

public static final int THAI;


 Locale.Languages.TURKISH

Locale.Languages.TURKISH

Represents the Turkish language.

Syntax

public static final int TURKISH;


 Locale.Languages.URDU

Locale.Languages.URDU

Represents the Urdu language.

Syntax

public static final int URDU;


Locale.LeadingZeros Class

Provides fields for evaluating and specifying the leading zero settings for the Locale class.

Enum
  |
  +--Locale.LeadingZeros

package com.ms.wfc.app

public static final class Locale.LeadingZeros
extends Enum

Remarks

Use the LeadingZeros class to evaluate the return value of the Locale.getDayLeadingZero, Locale.getMonthLeadingZero, Locale.getLeadingZero, and Locale.getTimeLeadingZero methods. You can also use this class to call the Locale.setLeadingZero method to specify the leading zero setting for a locale.


 Locale.LeadingZeros Fields

Locale.LeadingZeros Fields

Fields | Description
LEADING | Specifies that leading zeros are used.
NOLEADING | Specifies that leading zeros are not used.


 Locale.LeadingZeros.LEADING

Locale.LeadingZeros.LEADING

Specifies that leading zeros are used.

Syntax

public static final int LEADING;


 Locale.LeadingZeros.NOLEADING

Locale.LeadingZeros.NOLEADING

Specifies that leading zeros are not used.

Syntax

public static final int NOLEADING;


Locale.MeasurementSystem Class

Provides fields for determining the measurement system used in a locale.

Enum
  |
  +--Locale.MeasurementSystem

package com.ms.wfc.app

public static final class Locale.MeasurementSystem
extends Enum

Remarks

Use the MeasurementSystem class to evaluate the return value of the Locale.getMeasurementSystem method. You can also use it when calling the Locale.setMeasurementSystem method to specify the measurement system to use for a Locale object.


 Locale.MeasurementSystem Fields

Locale.MeasurementSystem Fields

Fields | Description
METRIC | Represents the metric measurement system.
US | Represents the United States measurement system.


 Locale.MeasurementSystem.METRIC

Locale.MeasurementSystem.METRIC

Represents the metric measurement system.

Syntax

public static final int METRIC;


 Locale.MeasurementSystem.US

Locale.MeasurementSystem.US

Represents the United States measurement system.

Syntax

public static final int US;


Locale.NegativeNumberMode Class

Provides fields that specify different ways to represent negative numbers.

Enum
  |
  +--Locale.NegativeNumberMode

package com.ms.wfc.app

public static final class Locale.NegativeNumberMode
extends Enum

Remarks

Use the NegativeNumberMode class to evaluate the return value of the Locale.getNegativeNumberMode method and as a parameter to the Locale.setNegativeNumberMode method.


 Locale.NegativeNumberMode Fields

Locale.NegativeNumberMode Fields

Fields | Description
PARENS | Specifies that negative numbers are displayed in parentheses.
PREFIX_NOSEP | Specifies that negative numbers are displayed without a separator prefix.
PREFIX_SEP | Specifies that negative numbers are displayed with a separator prefix.
SUFFIX_NOSEP | Specifies that negative numbers are displayed without a separator suffix.
SUFFIX_SEP | Specifies that negative numbers are displayed with a separator suffix.


 Locale.NegativeNumberMode.PARENS

Locale.NegativeNumberMode.PARENS

Specifies that negative numbers are displayed in parentheses.

Syntax

public static final int PARENS;


 Locale.NegativeNumberMode.PREFIX_NOSEP

Locale.NegativeNumberMode.PREFIX_NOSEP

Specifies that negative numbers are displayed without a separator prefix.

Syntax

public static final int PREFIX_NOSEP;


 Locale.NegativeNumberMode.PREFIX_SEP

Locale.NegativeNumberMode.PREFIX_SEP

Specifies that negative numbers are displayed with a separator prefix.

Syntax

public static final int PREFIX_SEP;


 Locale.NegativeNumberMode.SUFFIX_NOSEP

Locale.NegativeNumberMode.SUFFIX_NOSEP

Specifies that negative numbers are displayed without a separator suffix.

Syntax

public static final int SUFFIX_NOSEP;


 Locale.NegativeNumberMode.SUFFIX_SEP

Locale.NegativeNumberMode.SUFFIX_SEP

Specifies that negative numbers are displayed with a separator suffix.

Syntax

public static final int SUFFIX_SEP;


Locale.OptionalCalendarType Class

Provides fields that specify optional calendar types.

CalendarType
  |
  +--Locale.OptionalCalendarType

package com.ms.wfc.app

public static final class Locale.OptionalCalendarType
extends CalendarType

Remarks

Use the OptionalCalendarType class to evaluate the return value of the Locale.getOptionalCalendarType method.


 Locale.OptionalCalendarType Fields

Locale.OptionalCalendarType Fields

Fields | Description
NO_ADDITIONAL_TYPES_VALID | Specifies that no additional calendar types are valid.


 Locale.OptionalCalendarType.NO_ADDITIONAL_TYPES_VALID

Locale.OptionalCalendarType.NO_ADDITIONAL_TYPES_VALID

Specifies that no additional calendar types are valid.

Syntax

public static final int NO_ADDITIONAL_TYPES_VALID;


Locale.PositiveCurrencyMode Class

Provides fields that specify different ways to represent positive currency.

Enum
  |
  +--Locale.PositiveCurrencyMode

package com.ms.wfc.app

public static final class Locale.PositiveCurrencyMode
extends Enum

Remarks

Use the PositiveCurrencyMode class to evaluate the return value of the Locale.getPositiveCurrencyMode method and as a parameter to the Locale.setPositiveCurrencyMode method.


 Locale.PositiveCurrencyMode Fields

Locale.PositiveCurrencyMode Fields

Fields | Description
PREFIX_NOSEP | Specifies that positive currency is displayed without a prefix separator.
PREFIX_SEP | Specifies that positive currency is displayed with a prefix separator.
SUFFIX_NOSEP | Specifies that positive currency is displayed without a suffix separator.
SUFFIX_SEP | Specifies that positive currency is displayed with a suffix separator.


 Locale.PositiveCurrencyMode.PREFIX_NOSEP

Locale.PositiveCurrencyMode.PREFIX_NOSEP

Specifies that positive currency is displayed without a prefix separator.

Syntax

public static final int PREFIX_NOSEP;


 Locale.PositiveCurrencyMode.PREFIX_SEP

Locale.PositiveCurrencyMode.PREFIX_SEP

Specifies that positive currency is displayed with a prefix separator.

Syntax

public static final int PREFIX_SEP;


 Locale.PositiveCurrencyMode.SUFFIX_NOSEP

Locale.PositiveCurrencyMode.SUFFIX_NOSEP

Specifies that positive currency is displayed without a suffix separator.

Syntax

public static final int SUFFIX_NOSEP;


 Locale.PositiveCurrencyMode.SUFFIX_SEP

Locale.PositiveCurrencyMode.SUFFIX_SEP

Specifies that positive currency is displayed with a suffix separator.

Syntax

public static final int SUFFIX_SEP;


Locale.Sort Class

Provides fields that specify different sorting IDs.

package com.ms.wfc.app

public static final class Locale.Sort

Remarks

Use the Sort class to evaluate the return value of the Locale.getSortID method.


 Locale.Sort Fields

Locale.Sort Fields

Fields | Description
CHINESE_BIG5 | Specifies the Chinese BIG5 sort order.
CHINESE_PRC | Specifies the PRC Chinese Stroke Count sort order.
CHINESE_PRCP | Specifies the PRC Chinese Phonetic sort order.
CHINESE_UNICODE | Specifies the Chinese Unicode sort order.
DEFAULT | Specifies the default sort order.
GERMAN_PHONE_BOOK | Specifies the German Phone Book sort order.
JAPANESE_UNICODE | Specifies the Japanese Unicode sort order.
JAPANESE_XJIS | Specifies the Japanese XJIS sort order.
KOREAN_KSC | Specifies the Korean KSC sort order.
KOREAN_UNICODE | Specifies the Korean Unicode sort order.


 Locale.Sort.CHINESE_BIG5

Locale.Sort.CHINESE_BIG5

Specifies the Chinese BIG5 sort order.

Syntax

public static final int CHINESE_BIG5;


 Locale.Sort.CHINESE_PRC

Locale.Sort.CHINESE_PRC

Specifies the PRC Chinese Stroke Count sort order.

Syntax

public static final int CHINESE_PRC;


 Locale.Sort.CHINESE_PRCP

Locale.Sort.CHINESE_PRCP

Specifies the PRC Chinese Phonetic sort order.

Syntax

public static final int CHINESE_PRCP;


 Locale.Sort.CHINESE_UNICODE

Locale.Sort.CHINESE_UNICODE

Specifies the Chinese Unicode sort order.

Syntax

public static final int CHINESE_UNICODE;


 Locale.Sort.DEFAULT

Locale.Sort.DEFAULT

Specifies the default sort order.

Syntax

public static final int DEFAULT;


 Locale.Sort.GERMAN_PHONE_BOOK

Locale.Sort.GERMAN_PHONE_BOOK

Specifies the German Phone Book sort order.

Syntax

public static final int GERMAN_PHONE_BOOK;


 Locale.Sort.JAPANESE_UNICODE

Locale.Sort.JAPANESE_UNICODE

Specifies the Japanese Unicode sort order.

Syntax

public static final int JAPANESE_UNICODE;


 Locale.Sort.JAPANESE_XJIS

Locale.Sort.JAPANESE_XJIS

Specifies the Japanese XJIS sort order.

Syntax

public static final int JAPANESE_XJIS;


 Locale.Sort.KOREAN_KSC

Locale.Sort.KOREAN_KSC

Specifies the Korean KSC sort order.

Syntax

public static final int KOREAN_KSC;


 Locale.Sort.KOREAN_UNICODE

Locale.Sort.KOREAN_UNICODE

Specifies the Korean Unicode sort order.

Syntax

public static final int KOREAN_UNICODE;


Locale.SubLanguages Class

Provides fields that specify different sublanguage IDs.

package com.ms.wfc.app

public static final class Locale.SubLanguages

Remarks

The first part of a field name indicates which primary language ID that a sublanguage ID can be combined with to form a valid language ID.


 Locale.SubLanguages Fields

Locale.SubLanguages Fields

Fields | Description
CHINESE_SIMPLIFIED | Specifies the Chinese (Simplified) sublanguage.
CHINESE_TRADITIONAL | Specifies the Chinese (Traditional) sublanguage.
DEFAULT | Specifies the user default sublanguage.
DUTCH | Specifies the Dutch sublanguage.
DUTCH_BELGIAN | Specifies the Dutch (Belgian) sublanguage.
ENGLISH_AUS | Specifies the English (Australian) sublanguage.
ENGLISH_CAN | Specifies the English (Canadian) sublanguage.
ENGLISH_EIRE | Specifies the English (Irish) sublanguage.
ENGLISH_NZ | Specifies the English (New Zealand) sublanguage.
ENGLISH_UK | Specifies the English (United Kingdom) sublanguage.
ENGLISH_US | Specifies the English (United States) sublanguage.
FRENCH | Specifies the French sublanguage.
FRENCH_BELGIAN | Specifies the French (Belgian) sublanguage.
FRENCH_CANADIAN | Specifies the French (Canadian) sublanguage.
FRENCH_SWISS | Specifies the French (Swiss) sublanguage.
GERMAN | Specifies the German sublanguage.
GERMAN_AUSTRIAN | Specifies the German (Austrian) sublanguage.
GERMAN_SWISS | Specifies the German (Swiss) sublanguage.
ITALIAN | Specfies the Italian sublanguage.
ITALIAN_SWISS | Specifies the Italian (Swiss) sublanguage.
NEUTRAL | Specifies the neutral sublanguage.
NORWEGIAN_BOKMAL | Specifiest the Norwegian (Bokmal) sublanguage.
NORWEGIAN_NYNORSK | Specifies the Norwegian (Nynorsk) sublanguage.
PORTUGUESE | Specifies the Portuguese sublanguage.
PORTUGUESE_BRAZILIAN | Specifies the Portuguese (Brazilian) sublanguage.
SERBO_CROATIAN_CYRILLIC | Specifies the Serbo-Croatian (Cyrillic) sublanguage.
SERBO_CROATIAN_LATIN | Specifies the Serbo-Croatian (Latin) sublanguage.
SPANISH | Specifies the Spanish sublanguage.
SPANISH_MEXICAN | Specifies the Spanish (Mexican) sublanguage.
SPANISH_MODERN | Specifies the Spanish (modern) sublanguage.
SYS_DEFAULT | Specifies the system default sublanguage.


 Locale.SubLanguages.CHINESE_SIMPLIFIED

Locale.SubLanguages.CHINESE_SIMPLIFIED

Specifies the Chinese (Simplified) sublanguage.

Syntax

public static final int CHINESE_SIMPLIFIED;


 Locale.SubLanguages.CHINESE_TRADITIONAL

Locale.SubLanguages.CHINESE_TRADITIONAL

Specifies the Chinese (Traditional) sublanguage.

Syntax

public static final int CHINESE_TRADITIONAL;


 Locale.SubLanguages.DEFAULT

Locale.SubLanguages.DEFAULT

Specifies the user default sublanguage.

Syntax

public static final int DEFAULT;


 Locale.SubLanguages.DUTCH

Locale.SubLanguages.DUTCH

Specifies the Dutch sublanguage.

Syntax

public static final int DUTCH;


 Locale.SubLanguages.DUTCH_BELGIAN

Locale.SubLanguages.DUTCH_BELGIAN

Specifies the Dutch (Belgian) sublanguage.

Syntax

public static final int DUTCH_BELGIAN;


 Locale.SubLanguages.ENGLISH_AUS

Locale.SubLanguages.ENGLISH_AUS

Specifies the English (Australian) sublanguage.

Syntax

public static final int ENGLISH_AUS;


 Locale.SubLanguages.ENGLISH_CAN

Locale.SubLanguages.ENGLISH_CAN

Specifies the English (Canadian) sublanguage.

Syntax

public static final int ENGLISH_CAN;


 Locale.SubLanguages.ENGLISH_EIRE

Locale.SubLanguages.ENGLISH_EIRE

Specifies the English (Irish) sublanguage.

Syntax

public static final int ENGLISH_EIRE;


 Locale.SubLanguages.ENGLISH_NZ

Locale.SubLanguages.ENGLISH_NZ

Specifies the English (New Zealand) sublanguage.

Syntax

public static final int ENGLISH_NZ;


 Locale.SubLanguages.ENGLISH_UK

Locale.SubLanguages.ENGLISH_UK

Specifies the English (United Kingdom) sublanguage.

Syntax

public static final int ENGLISH_UK;


 Locale.SubLanguages.ENGLISH_US

Locale.SubLanguages.ENGLISH_US

Specifies the English (United States) sublanguage.

Syntax

public static final int ENGLISH_US;


 Locale.SubLanguages.FRENCH

Locale.SubLanguages.FRENCH

Specifies the French sublanguage.

Syntax

public static final int FRENCH;


 Locale.SubLanguages.FRENCH_BELGIAN

Locale.SubLanguages.FRENCH_BELGIAN

Specifies the French (Belgian) sublanguage.

Syntax

public static final int FRENCH_BELGIAN;


 Locale.SubLanguages.FRENCH_CANADIAN

Locale.SubLanguages.FRENCH_CANADIAN

Specifies the French (Canadian) sublanguage.

Syntax

public static final int FRENCH_CANADIAN;


 Locale.SubLanguages.FRENCH_SWISS

Locale.SubLanguages.FRENCH_SWISS

Specifies the French (Swiss) sublanguage.

Syntax

public static final int FRENCH_SWISS;


 Locale.SubLanguages.GERMAN

Locale.SubLanguages.GERMAN

Specifies the German sublanguage.

Syntax

public static final int GERMAN;


 Locale.SubLanguages.GERMAN_AUSTRIAN

Locale.SubLanguages.GERMAN_AUSTRIAN

Specifies the German (Austrian) sublanguage.

Syntax

public static final int GERMAN_AUSTRIAN;


 Locale.SubLanguages.GERMAN_SWISS

Locale.SubLanguages.GERMAN_SWISS

Specifies the German (Swiss) sublanguage.

Syntax

public static final int GERMAN_SWISS;


 Locale.SubLanguages.ITALIAN

Locale.SubLanguages.ITALIAN

Specfies the Italian sublanguage.

Syntax

public static final int ITALIAN;


 Locale.SubLanguages.ITALIAN_SWISS

Locale.SubLanguages.ITALIAN_SWISS

Specifies the Italian (Swiss) sublanguage.

Syntax

public static final int ITALIAN_SWISS;


 Locale.SubLanguages.NEUTRAL

Locale.SubLanguages.NEUTRAL

Specifies the neutral sublanguage.

Syntax

public static final int NEUTRAL;


 Locale.SubLanguages.NORWEGIAN_BOKMAL

Locale.SubLanguages.NORWEGIAN_BOKMAL

Specifiest the Norwegian (Bokmal) sublanguage.

Syntax

public static final int NORWEGIAN_BOKMAL;


 Locale.SubLanguages.NORWEGIAN_NYNORSK

Locale.SubLanguages.NORWEGIAN_NYNORSK

Specifies the Norwegian (Nynorsk) sublanguage.

Syntax

public static final int NORWEGIAN_NYNORSK;


 Locale.SubLanguages.PORTUGUESE

Locale.SubLanguages.PORTUGUESE

Specifies the Portuguese sublanguage.

Syntax

public static final int PORTUGUESE;


 Locale.SubLanguages.PORTUGUESE_BRAZILIAN

Locale.SubLanguages.PORTUGUESE_BRAZILIAN

Specifies the Portuguese (Brazilian) sublanguage.

Syntax

public static final int PORTUGUESE_BRAZILIAN;


 Locale.SubLanguages.SERBO_CROATIAN_CYRILLIC

Locale.SubLanguages.SERBO_CROATIAN_CYRILLIC

Specifies the Serbo-Croatian (Cyrillic) sublanguage.

Syntax

public static final int SERBO_CROATIAN_CYRILLIC;


 Locale.SubLanguages.SERBO_CROATIAN_LATIN

Locale.SubLanguages.SERBO_CROATIAN_LATIN

Specifies the Serbo-Croatian (Latin) sublanguage.

Syntax

public static final int SERBO_CROATIAN_LATIN;


 Locale.SubLanguages.SPANISH

Locale.SubLanguages.SPANISH

Specifies the Spanish sublanguage.

Syntax

public static final int SPANISH;


 Locale.SubLanguages.SPANISH_MEXICAN

Locale.SubLanguages.SPANISH_MEXICAN

Specifies the Spanish (Mexican) sublanguage.

Syntax

public static final int SPANISH_MEXICAN;


 Locale.SubLanguages.SPANISH_MODERN

Locale.SubLanguages.SPANISH_MODERN

Specifies the Spanish (modern) sublanguage.

Syntax

public static final int SPANISH_MODERN;


 Locale.SubLanguages.SYS_DEFAULT

Locale.SubLanguages.SYS_DEFAULT

Specifies the system default sublanguage.

Syntax

public static final int SYS_DEFAULT;


Message Class

Implements a Windows message.

package com.ms.wfc.app

public final class Message

Remarks

The Message class wraps messages that are sent by Windows. You can use this class to wrap a message and assign it to the window procedure to be dispatched. You can also use this class to get information about a message that is sent to your application or controls. The Message class cannot be created directly. To create or free a Message object, use the static methods create and free, respectively. To make creating Message objects more efficient, the Message class uses its pool of existing Message objects instead of instantiating a new one. If a Message object is not available in the pool, a new object is instantiated.


 Message Methods

Message Methods

Methods | Description
create | Creates a Message object.
free | Frees a Message object.
getLParam | Retrieves the lParam value, and converts the value to an object.


 Message.create

Message.create

Creates a Message object.

Syntax

public static synchronized Message create( int hWnd, int msg, int wParam, int lParam )

Parameters

hWnd

The window handle for the message.

msg

The message ID.

wParam

The message's wParam.

lParam

The message's lParam.

Return Value

Returns a Message object representing the message that was created.

Remarks

Use the create method to create a Message object to wrap a message sent by Windows. When your application is finished with the message, use the free method to free the object.

See Also free


 Message.free

Message.free

Frees a Message object.

Syntax

public static synchronized int free( Message m )

Parameters

m

The Message object that you want to free.

Return Value

Returns the value of the message's result field. The result field is the value that is typically returned to Windows in response to handling the message.

Remarks

Calling this method returns the message object back to the message pool for reuse.

See Also create


 Message.getLParam

Message.getLParam

Retrieves the lParam value, and converts the value to an object.

Syntax

public Object getLParam( Class cls )

Parameters

cls

The Class object to create an instance of.

Return Value

Returns an Object instance of cls filled with the data from the lParam field of the message. The class specified in cls must be a class that was declared using the @dll.struct directive.

Remarks

Use the getLParam method to retrieve information from the lParam field of a message and convert it to a Java object type. You can use this method to access objects passed in a message.

See Also lParam


 Message Fields

Message Fields

Fields | Description
hWnd | Specifies the window handle of the message.
lParam | Specifies the lParam of the message.
msg | Specifies the message identifier.
result | Specifies the return value of the message.
wParam | Specifies the wParam of the message.


 Message.hWnd

Message.hWnd

Specifies the window handle of the message.

Syntax

public int hWnd;


 Message.lParam

Message.lParam

Specifies the lParam of the message.

Syntax

public int lParam;

Remarks

The value of this field depends on the message. Use the lParam field to get information that is important to handling the message. It is typically used to store an object if it is needed by the message. Use the getLParam method to retrieve and convert information from the lParam field into an object.

See Also getLParam


 Message.msg

Message.msg

Specifies the message identifier.

Syntax

public int msg;


 Message.result

Message.result

Specifies the return value of the message.

Syntax

public int result;

Remarks

Specifies the value that will be returned to Windows in response to handling the message.


 Message.wParam

Message.wParam

Specifies the wParam of the message.

Syntax

public int wParam;

Remarks

The value of this field depends on the message. Use the wParam field to get information that is important to handling the message. This field is typically used to store small information such as flags.


MethodInvoker Delegate

Invokes the handler method for the event that has occurred.

package com.ms.wfc.app

public multicast delegate
void MethodInvoker( );

Remarks

Use the MethodInvoker delegate to invoke a method with a void parameter list. This delegate is typically used in a call to a control's invoke method or when you need a simple delegate. The MethodInvoker delegate is similar to Java's Runnable method, except that the invoked method can have any name and can be declared as private.

The following is an example of using a MethodInvoker delegate to start a new thread in an application:

private void threadRoutine(){
    //Thread code goes here
}

private void startThreadRoutine(){
    Application.createThread(new MethodInvoker(this.threadRoutine));
}

See Also Application.createThread


Registry Class

Provides a set of constants for the root keys in the system registry.

package com.ms.wfc.app

public class Registry

Remarks

The Registry class provides RegistryKey objects that represent the root keys of the system registry. Use these keys when creating subkeys within the registry or for accessing information within these keys. The following example illustrates how to create a new subkey for a company's application within the CURRENT_USER root key.

RegistryKey myKey = Registry.CURRENT_USER.createSubKey("Software\\MyCompany\\MyProduct");


 Registry Fields

Registry Fields

Fields | Description
CLASSES_ROOT | Represents the HKEY_CLASSES_ROOT root key.
CURRENT_CONFIG | Represents the HKEY_CURRENT_CONFIG root key.
CURRENT_USER | Represents the HKEY_CURRENT_USER root key.
DYN_DATA | Represents the HKEY_DYN_DATA root key.
LOCAL_MACHINE | Represents the HKEY_LOCAL_MACHINE root key.
PERFORMANCE_DATA | Represents the HKEY_PERFORMANCE root key.
USERS | Represents the HKEY_USERS root key.


 Registry.CLASSES_ROOT

Registry.CLASSES_ROOT

Represents the HKEY_CLASSES_ROOT root key.

Syntax

public static final RegistryKey CLASSES_ROOT;

Remarks

The CLASSES_ROOT key is the root key for OLE class information and file associations. Use this key to register your application's file extension or to change existing extensions.


 Registry.CURRENT_CONFIG

Registry.CURRENT_CONFIG

Represents the HKEY_CURRENT_CONFIG root key.

Syntax

public static final RegistryKey CURRENT_CONFIG;

Remarks

The CURRENT_CONFIG root key is where current configuration information is stored.


 Registry.CURRENT_USER

Registry.CURRENT_USER

Represents the HKEY_CURRENT_USER root key.

Syntax

public static final RegistryKey CURRENT_USER;

Remarks

Use the CURRENT_USER key to store user-specific settings. Your application must not require any of these settings to preexist. It should always provide meaningful default values within the application and/or within the registry.


 Registry.DYN_DATA

Registry.DYN_DATA

Represents the HKEY_DYN_DATA root key.

Syntax

public static final RegistryKey DYN_DATA;

Remarks

The DYN_DATA root key is where dynamic performance data is stored on Windows 95 and Windows 98 systems.


 Registry.LOCAL_MACHINE

Registry.LOCAL_MACHINE

Represents the HKEY_LOCAL_MACHINE root key.

Syntax

public static final RegistryKey LOCAL_MACHINE;

Remarks

The LOCAL_MACHINE root key is used as the root for all computer-specific settings. Your application must not require write access to this key because on many computers, the current user does not have write access to the key.


 Registry.PERFORMANCE_DATA

Registry.PERFORMANCE_DATA

Represents the HKEY_PERFORMANCE root key.

Syntax

public static final RegistryKey PERFORMANCE_DATA;

Remarks

The PERFORMANCE_DATA root key is used to store dynamic performance data on systems running Windows NT.


 Registry.USERS

Registry.USERS

Represents the HKEY_USERS root key.

Syntax

public static final RegistryKey USERS;

Remarks

The USERS root key is used to store information for all users of the system. To store information for the current user on the computer, use the CURRENT_USER key.


RegistryKey Class

Provides methods that allow you to read and write to the system registry.

package com.ms.wfc.app

public final class RegistryKey

Remarks

Use the RegistryKey class to create and delete subkeys and assign information to a registry value entry. You can use the registry to store information, such as application settings, recently opened file paths, and version information. To get an instance of a RegistryKey, use the static method getBaseKey, or use one of the Registry class's members. You cannot create an instance of the RegistryKey class using the new keyword.


 RegistryKey Methods

RegistryKey Methods

Methods | Description
close | Closes the current key and optionally flushes the registry key back to the registry if the contents have been modified.
createSubKey | Creates a new subkey.
deleteSubKey | Deletes the specified subkey.
deleteSubKeyTree | Recursively deletes a subkey and any child subkeys.
deleteValue | Deletes a value from a subkey.
finalize | Releases all resources associated with this object.
getBaseKey | Retrieves a new RegistryKey object that represents the requested key.
getSubKey | Retrieves the specified subkey.
getSubKeyCount | Retrieves the number of subkeys for a specified key.
getSubKeyNames | Retrieves an array of strings containing all the subkey names for the current key.
getValue | Retrieves the specified value from the registry.
getValueCount | Retrieves the number of values defined in the current key.
getValueNames | Retrieves an array of strings containing all the value names defined for the current key.
setValue | Sets the specified value in the registry.
toString | Retrieves a string representation of this key.


 RegistryKey.close

RegistryKey.close

Closes the current key and optionally flushes the registry key back to the registry if the contents have been modified.

Syntax

public void close()

public void close( boolean flushCache )

Parameters

flushCache

If set to true, the key is flushed to disk if it has been modified.

Remarks

The close method closes the registry key that is currently being referenced. If you use the second version of this method and assign a true value to the method's parameter, any information that is in the cache for the registry key is written back into the registry. Use this method to close a registry key assigned to a RegistryKey object so that the object can be assigned a different registry key. Calling the first version of the close method is the same as calling the second version and assigning a true value to the argument.

See Also createSubKey, deleteSubKey


 RegistryKey.createSubKey

RegistryKey.createSubKey

Creates a new subkey.

Syntax

public RegistryKey createSubKey( String subkey )

Parameters

subkey

A String object that represents the name or path of the subkey to create.

Return Value

Returns the subkey, or returns null if the operation fails.

Remarks

The createSubKey method is typically used to create a subkey of a RegistryKey object and assign it to a new RegistryKey object. If the key you are creating already exists, the key is opened and assigned to the RegistryKey object you are instantiating. To create a tree of subkeys, define each new subkey with a backslash (\). Remember, to use a double backslash (\\) with strings in quotation marks in the Java language. You can use the createSubKey method to create a location under one of the registry's root keys to store your application's information.

The following example illustrates how to create a RegistryKey object that creates new subkeys. It uses the Registry class members to access the CURRENT_USER root key.

RegistryKey myKey = Registry.CURRENT_USER.createSubKey("Software\\MyCompany\\MyApplication");


 RegistryKey.deleteSubKey

RegistryKey.deleteSubKey

Deletes the specified subkey.

Syntax

public void deleteSubKey( String subkey )

Parameters

subkey

A String object that represents the subkey to delete.

Exceptions

WFCException thrown if the subkey contains any child subkeys.

Remarks

Use the deleteSubKey method to remove a subkey from the registry. To delete a tree of subkeys, use the deleteSubKeyTree method. To delete a value assigned within a subkey, use the deleteValue method.


 RegistryKey.deleteSubKeyTree

RegistryKey.deleteSubKeyTree

Recursively deletes a subkey and any child subkeys.

Syntax

public void deleteSubKeyTree( String subkey )

Parameters

subkey

A String object that represents the subkey to delete.

Remarks

Use the deleteSubKeyTree method to delete an entire tree of subkeys from the registry. To ensure that an exception does not occur when deleting a key, use the deleteSubKeyTree method instead of the deleteSubKey method, which throws an exception if a subkey contains child subkeys.

See Also deleteSubKey, deleteValue


 RegistryKey.deleteValue

RegistryKey.deleteValue

Deletes a value from a subkey.

Syntax

public void deleteValue( String name )

Parameters

name

A String object that represents the name of value to delete.

Remarks

Use the deleteValue method to delete a value that you have assigned to a subkey. To remove all a subkey's values, use the deleteSubKey or deleteSubKeyTree methods to delete the entire key.


 RegistryKey.finalize

RegistryKey.finalize

Releases all resources associated with this object.

Syntax

protected void finalize()

Remarks

The finalize method releases the root key that is associated with the RegistryKey object.


 RegistryKey.getBaseKey

RegistryKey.getBaseKey

Retrieves a new RegistryKey object that represents the requested key.

Syntax

public static RegistryKey getBaseKey( int hKey )

Parameters

hKey

The HKEY_* to open.

Return Value

Returns the RegistryKey object that represents the requested key.

Remarks

Use the getBaseKey method to create a RegistryKey object based on a specific root registry key. You can also use the members of the Registry class to access a RegistryKey object for one of the root keys defined in the registry.

Valid values for hKey are: HKEY_CLASSES_ROOT, HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE, HKEY_USERS, HKEY_PERFORMANCE_DATA, HKEY_CURRENT_CONFIG, HKEY_DYN_DATA.


 RegistryKey.getSubKey

RegistryKey.getSubKey

Retrieves the specified subkey.

Syntax

public RegistryKey getSubKey( String name )

public RegistryKey getSubKey( String name, boolean readonly )

Parameters

name

The name and/or path of the subkey to open.

readonly

Set to true to provide read-only access to the specified subkey; set to false for read/write access. If this value is not specified, the key defaults to read-only access.

Return Value

Returns a RegistryKey object that represents the requested subkey, or returns null if the operation fails.

Remarks

Use the getSubKey method to open an existing subkey and assign it to a RegistryKey object. If the key does not exist, a null value is returned. To open an existing key or to create a key, use the createSubKey method. To read information from the specified registry key, use the second version of this method, and set the readonly parameter to true to open the registry key for read-only access. If you do not know the name of the subkey, use the getSubKeyNames method to return all the subkeys for a specified key.

See Also getSubKeyCount, getSubKeyNames


 RegistryKey.getSubKeyCount

RegistryKey.getSubKeyCount

Retrieves the number of subkeys for a specified key.

Syntax

public int getSubKeyCount()

Return Value

Returns the number of subkeys that are defined for the current key.

Remarks

Use the getSubKeyCount method to get the number of subkeys that are defined for the currently assigned key. Use this method to loop through all the subkeys in a for loop. To get an array containing all the names of the subkeys, use the getSubKeyNames method.


 RegistryKey.getSubKeyNames

RegistryKey.getSubKeyNames

Retrieves an array of strings containing all the subkey names for the current key.

Syntax

public String[] getSubKeyNames()

Return Value

Returns an array of strings containing all the subkey names.

Remarks

Use the getSubKeyNames method to determine the names of the subkeys defined for the current key. Use this method to get a list of all the subkey names and determine whether a specific subkey has been defined. To get a count of all the subkeys defined in the key, use the getSubKeyCount method. To retrieve a RegistryKey object representing one of the subkeys found using getSubKeyNames, use the getSubKey method.


 RegistryKey.getValue

RegistryKey.getValue

Retrieves the specified value from the registry.

Syntax

public Object getValue( String name )

public Object getValue( String name, Object defaultValue )

Parameters

name

A String object that contains the name of value to retrieve.

defaultValue

The value to return if name does not exist.

Return Value

Returns an object that represents the data associated with the value.

Remarks

Use the getValue method to retrieve data from the registry for the specified value. The data returned from the registry must be cast to the proper Java data type. Use the second version of this method to specify the data that will be returned if the specified value entry does not exist in the registry. If the first version of this method is used, null is returned if the value entry does not exist in the registry. To get a list of all the value names stored for the current key, use the getValueNames method.

The following example illustrates how to write a Font object to the registry using the setValue method and getTextFromValue method in the Font.Editor class. It also shows how to restore the Font object from the registry using the getValue method and the getValueFromText method in the Font.Editor class.

Font.Editor tempEditor = new Font.Editor()

RegistryKey myKey =
Registry.CURRENT_USER.createSubKey("Software\\MyCompany\\MyProduct");

//Store the Font to the registry
myKey.setValue("MyValue", tempEditor.getTextFromValue( new Font("Arial", 11.0f, FontSize.CHARACTERHEIGHT)));

//Restore the Font from the registry
Font myFont = (Font)tempEdit.getValueFromText((String) myKey.getValue("MyValue"));

See Also getValueCount


 RegistryKey.getValueCount

RegistryKey.getValueCount

Retrieves the number of values defined in the current key.

Syntax

public int getValueCount()

Return Value

Returns the number of values defined.

Remarks

Use the getValueCount method to get a count of the values defined for the currently opened key. Use this method to assist in looping through all the values in the current key. To get an array containing all the value names for the current key, use the getValueNames method.


 RegistryKey.getValueNames

RegistryKey.getValueNames

Retrieves an array of strings containing all the value names defined for the current key.

Syntax

public String[] getValueNames()

Return Value

An array of strings containing all the value names in the key.

Remarks

Use The getValueNames method to determine the names of the values defined for the current key. Use this method to get a list of all the value names and determine whether a specific value has been defined. To get a count of all the values defined in the key, use the getValueCount method. To retrieve a String object representing one of the values found using getValueNames, use the getValue method.


 RegistryKey.setValue

RegistryKey.setValue

Sets the specified value in the registry.

Syntax

public void setValue( String name, Object value )

Parameters

name

A String object that represents the name of value to store data in.

value

The data to store.

Remarks

Use the setValue method to store information in the specified value. Ensure that the object you assign to value can be restored to its original state. Many of the Windows Foundation Classes for Java provide Editor classes that so you can store the specified class as a string and restore the object from a string.

The following example illustrates how to write a Font object to the registry using the setValue method and the getTextFromValue method. It also shows how to restore the Font object from the registry using the getValue method and the getValueFromText method (Font Editor class).

Font.Editor tempEditor = new Font.Editor();

RegistryKey myKey = Registry.CURRENT_USER.createSubKey("Software\\MyCompany\\MyProduct");

//Store the Font to the registry
myKey.setValue("MyValue", tempEditor.getTextFromValue(new Font("Arial", 11.0f, FontSize.CHARACTERHEIGHT)));

//Restore the Font from the registry
Font myFont = (Font) tempEdit.getValueFromText((String)myKey.getValue("MyValue"));


 RegistryKey.toString

RegistryKey.toString

Retrieves a string representation of this key.

Syntax

public String toString()

Return Value

Returns a string representing the key.

Remarks

The toString method for the RegistryKey class returns the package and name of the class as well as the numerical representation of the key stored in the object.


SendKeys Class

Provides methods for sending keystrokes to an application.

package com.ms.wfc.app

public class SendKeys

Remarks

Use the SendKeys class to send keystrokes and keystroke combinations to the active application. This class cannot be instantiated. To send a keystroke to a class and immediately continue with the flow of your program, use the sendKeys method. To wait for any processes started by the keystroke, use the sendKeysWait method.


 SendKeys Methods

SendKeys Methods

Methods | Description
sendKeys | Sends keystrokes to the active application.
sendKeysWait | Sends keystrokes to the active application, and then waits for the messages to be processed.


 SendKeys.sendKeys

SendKeys.sendKeys

Sends keystrokes to the active application.

Syntax

public static void sendKeys( String keys )

Parameters

key

The string of keystrokes to send.

Remarks

Use the sendKeys method to send keystrokes or combinations of keystrokes to the currently active application or to control another application that your application has started or is using. The sendKeys method does not wait for any processes started by the keystroke to return before continuing with code execution.

Each key is represented by one or more characters. To specify a single keyboard character, use the character itself. For example, to represent the letter A, assign "A" to the method. To represent more than one character, append each additional character to the one preceding it. To represent the letters A, B, and C, assign "ABC" to the method.

The plus sign (+), caret (^), percent sign (%), tilde (~), and parentheses (( )) have special meanings to sendKeys. To specify one of these characters, enclose it in braces ({}). For example, to specify the plus sign, use {+}. Brackets ([ ]) have no special meaning to sendKeys, but you must enclose them in braces. To specify brace characters, use {{} and {}}.

To specify characters, such as ENTER or TAB, that aren't displayed when you press a key and keys that represent actions rather than characters, use the codes shown in the following table.

Key | Code
BACKSPACE | {BACKSPACE}, {BS}, or {BKSP}
BREAK | {BREAK}
CAPS LOCK | {CAPSLOCK}
DEL or DELETE | {DELETE} or {DEL}
DOWN ARROW | {DOWN}
END | {END}
ENTER | {ENTER}or ~
ESC | {ESC}
HELP | {HELP}
HOME | {HOME}
INS or INSERT | {INSERT} or {INS}
LEFT ARROW | {LEFT}
NUM LOCK | {NUMLOCK}
PAGE DOWN | {PGDN}
PAGE UP | {PGUP}
PRINT SCREEN | {PRTSC}
RIGHT ARROW | {RIGHT}
SCROLL LOCK | {SCROLLLOCK}
TAB | {TAB}
UP ARROW | {UP}
F1 | {F1}
F2 | {F2}
F3 | {F3}
F4 | {F4}
F5 | {F5}
F6 | {F6}
F7 | {F7}
F8 | {F8}
F9 | {F9}
F10 | {F10}
F11 | {F11}
F12 | {F12}

To specify keys combined with any combination of the SHIFT, CTRL, and ALT keys, precede the key code with one or more of the following codes.

Key | Code
SHIFT | +
CTRL | ^
ALT | %

To specify that any combination of SHIFT, CTRL, and ALT should be held down while several other keys are pressed, enclose the code for those keys in parentheses. For example, to specify to hold down SHIFT while E and C are pressed, use +(EC). To specify to hold down SHIFT while E is pressed, followed by C without SHIFT, use +EC.

See Also sendKeysWait


 SendKeys.sendKeysWait

SendKeys.sendKeysWait

Sends keystrokes to the active application, and then waits for the messages to be processed.

Syntax

public static void sendKeysWait( String keys )

Parameters

keys

The string of keystrokes to send.

Remarks

Use the sendKeysWait method to send keystrokes or combinations of keystrokes to the active application and wait for the keystroke messages to be processed. You can use this method to send keystrokes to an application and wait for any processes that are started by the keystrokes to be completed. This can be important if the other application must complete its work before your application can continue.

See Also sendKeys


SpecialFolder Class

Provides fields that represent special system folders.

Enum
  |
  +--SpecialFolder

package com.ms.wfc.app

public class SpecialFolder
extends Enum

Remarks

The SpecialFolder class provides a set of fields that are used when calling the SystemInformation.getSpecialFolderPath method to retrieve the path to the specified special folder.


 SpecialFolder Methods

SpecialFolder Methods

Methods | Description
valid | Determines whether the value assigned to the method is a valid number for the class's enumerated values.


 SpecialFolder.valid

SpecialFolder.valid

Determines whether the value assigned to the method is a valid number for the class's enumerated values.

Syntax

public static boolean valid( int value )

Parameters

value

The number being evaluated.

Return Value

Returns true if the value is valid; otherwise, returns false.

Remarks

The valid method determines whether a specific integer value is within the range of numbers for the enumerated members of this class. Use this method to determine whether a value returned from a method is a valid enumerated value of this class.


 SpecialFolder Fields

SpecialFolder Fields

Fields | Description
APPLICATION_DATA | Specifies the file system directory that serves as a common repository for application-specific data.
COOKIES | Specifies the file system directory that serves as a common repository for Internet cookies.
DESKTOP_DIRECTORY | Specifies the file system directory used to physically store file objects on the desktop.
FAVORITES | Specifies the file system directory that serves as a common repository for the user's favorite items.
HISTORY | Specifies the file system directory that serves as a common repository for Internet history items.
INTERNET_CACHE | Specifies the file system directory that serves as a common repository for temporary Internet files.
PROGRAMS | Specifies the file system directory that contains the user's program groups.
RECENT | Specifies the file system directory that contains shortcuts to the user's most recently used documents.
SENDTO | Specifies the file system directory that contains Send To menu items.
START_MENU | Specifies the file system directory containing Start menu items.
STARTUP | Specifies the file system directory that corresponds to the user's Startup program group.
TEMPLATES | Specifies the file system directory that serves as a common repository for document templates.
USER_DATA | Specifies the file system directory that serves as a common repository for documents.


 SpecialFolder.APPLICATION_DATA

SpecialFolder.APPLICATION_DATA

Specifies the file system directory that serves as a common repository for application-specific data.

Syntax

public static final int APPLICATION_DATA;


 SpecialFolder.COOKIES

SpecialFolder.COOKIES

Specifies the file system directory that serves as a common repository for Internet cookies.

Syntax

public static final int COOKIES;


 SpecialFolder.DESKTOP_DIRECTORY

SpecialFolder.DESKTOP_DIRECTORY

Specifies the file system directory used to physically store file objects on the desktop.

Syntax

public static final int DESKTOP_DIRECTORY;

Remarks

The DESKTOP_DIRECTORY field represents the directory that is used to store files on the desktop. This folder should not be confused with the desktop folder, which is a virtual folder.


 SpecialFolder.FAVORITES

SpecialFolder.FAVORITES

Specifies the file system directory that serves as a common repository for the user's favorite items.

Syntax

public static final int FAVORITES;


 SpecialFolder.HISTORY

SpecialFolder.HISTORY

Specifies the file system directory that serves as a common repository for Internet history items.

Syntax

public static final int HISTORY;


 SpecialFolder.INTERNET_CACHE

SpecialFolder.INTERNET_CACHE

Specifies the file system directory that serves as a common repository for temporary Internet files.

Syntax

public static final int INTERNET_CACHE;


 SpecialFolder.PROGRAMS

SpecialFolder.PROGRAMS

Specifies the file system directory that contains the user's program groups.

Syntax

public static final int PROGRAMS;

Remarks

The PROGRAMS field represents the directory that contains the current user's program groups. The program groups' directories are also file system directories.


 SpecialFolder.RECENT

SpecialFolder.RECENT

Specifies the file system directory that contains shortcuts to the user's most recently used documents.

Syntax

public static final int RECENT;


 SpecialFolder.SENDTO

SpecialFolder.SENDTO

Specifies the file system directory that contains Send To menu items.

Syntax

public static final int SENDTO;

Remarks

Use the SENDTO field when you want to create additional Send To locations in Windows.


 SpecialFolder.START_MENU

SpecialFolder.START_MENU

Specifies the file system directory containing Start menu items.

Syntax

public static final int START_MENU;


 SpecialFolder.STARTUP

SpecialFolder.STARTUP

Specifies the file system directory that corresponds to the user's Startup program group.

Syntax

public static final int STARTUP;

Remarks

The STARTUP field represents that path to programs that are run whenever a user logs on to Windows NT or starts Windows 95.


 SpecialFolder.TEMPLATES

SpecialFolder.TEMPLATES

Specifies the file system directory that serves as a common repository for document templates.

Syntax

public static final int TEMPLATES;


 SpecialFolder.USER_DATA

SpecialFolder.USER_DATA

Specifies the file system directory that serves as a common repository for documents.

Syntax

public static final int USER_DATA;

Remarks

The path specified for the USER_DATA field is typically where documents are stored. On most systems this is the path to the My Documents folder.


SystemInformation Class

Provides information about the operating system.

package com.ms.wfc.app

public class SystemInformation

Remarks

The SystemInformation class provides a number of static methods that can be used to get information such as Windows display element sizes, operating system settings, network availability, and the capabilities of hardware installed on the system. This class cannot be instantiated.


 SystemInformation Methods

SystemInformation Methods

Methods | Description
get3DBorderSize | Retrieves the dimensions, in pixels, of a three-dimensional border.
getArrange | Retrieves a flag specifying how the system arranges minimized windows.
getBorderSize | Retrieves the width and height, in pixels, of a window border.
getCaptionButtonSize | Retrieves the width and height, in pixels, of a button in a window's caption or title bar.
getCaptionHeight | Retrieves the height, in pixels, of the normal caption area of a window.
getCleanBoot | Retrieves a value that specifies how the system was started.
getComputerName | Retrieves the computer name of the current system.
getCursorSize | Retrieves the width and height, in pixels, of a cursor.
getDBCSEnabled | Determines whether the operating system supports the double-byte character set (DBCS).
getDebug | Determines whether your application is running on a debug version of the operating system.
getDoubleClickSize | Retrieves the width and height, in pixels, of the rectangle around the location of a first click in a double-click sequence.
getDoubleClickTime | Retrieves the current double-click time for the mouse.
getDragSize | Retrieves the width and height, in pixels, of a rectangle centered on a drag point to allow for limited movement of the mouse pointer before a drag operation begins.
getFixedFrameBorderSize | Retrieves the thickness, in pixels, of the frame around the perimeter of a window that is not sizable.
getFrameBorderSize | Retrieves the thickness, in pixels, of the sizing border around the perimeter of a window that can be resized.
getHorizScrollBarArrowWidth | Retrieves the width, in pixels, of the arrow on a horizontal scroll bar.
getHorizScrollBarHeight | Retrieves the height, in pixels, of the horizontal scroll bar.
getHorizScrollBarThumbWidth | Retrieves the width, in pixels, of the scroll box in a horizontal scroll bar.
getIconSize | Retrieves the default width and height, in pixels, of an icon.
getIconSpacingSize | Retrieves the dimensions, in pixels, of a grid cell for items in a large icon view.
getKanjiWindowHeight | For double-byte character set (DBCS) versions of Windows, retrieves the height, in pixels, of the Kanji window at the bottom of the screen.
getMaxWindowTrackSize | Retrieves the default maximum dimensions, in pixels, of a window that has a caption and sizing borders.
getMenuButtonSize | Retrieves the dimensions, in pixels, of menu bar buttons.
getMenuCheckSize | Retrieves the dimensions, in pixels, of the default menu check mark.
getMenuHeight | Retrieves the height, in pixels, of a single-line menu bar.
getMidEastEnabled | Determines if the operating system supports Hebrew and Arabic languages.
getMinimizedWindowSize | Retrieves the dimensions, in pixels, of a normal minimized window.
getMinimizedWindowSpacingSize | Retrieves the dimensions, in pixels, of a grid cell for minimized windows.
getMinimumWindowSize | Retrieves the minimum width and height, in pixels, of a window.
getMinWindowTrackSize | Retrieves the minimum tracking width and height, in pixels, of a window.
getMonitorCount | Retrieves the number of monitors that are connected to the system.
getMonitorsSameDisplayFormat | Determines if all monitors currently connected to the system have the same color format.
getMouseButtons | Retrieves the number of buttons on the mouse connected to the system.
getMouseButtonsSwapped | Determines whether the usage of the left and right mouse buttons has been swapped.
getMousePresent | Determines whether the system has a mouse installed.
getMouseWheelPresent | Determines whether the mouse that is currently installed on the system has a mouse wheel.
getMouseWheelScrollLines | Retrieves the number of lines to scroll when the mouse wheel is rotated.
getNativeMouseWheelSupport | Determines whether the operating system natively supports a mouse wheel.
getNetwork | Determines whether this computer is on a network.
getPenWindows | Determines whether the Microsoft Windows for Pen Computing extensions are installed.
getPrimaryMonitorMaximizedWindowSize | Retrieves the default dimensions, in pixels, of a maximized top-left window on the primary monitor.
getPrimaryMonitorSize | Retrieves the width and height, in pixels, of the screen of the primary display monitor when multiple monitors are installed.
getRightAlignedMenus | Determines whether drop-down menus are right-aligned.
getSecure | Determines whether security is present on this operating system.
getShowSounds | Determines whether the user requires an application to present information visually in situations where it would otherwise present the information audibly.
getSmallIconSize | Retrieves the recommended dimensions, in pixels, of a small icon.
getSpecialFolderPath | Retrieves the path to a specific special folder.
getToolWindowCaptionButtonSize | Retrieves the dimensions, in pixels, of small caption buttons.
getToolWindowCaptionHeight | Retrieves the height, in pixels, of a small caption.
getUserName | Retrieves the user name for the current thread.
getVertScrollBarArrowHeight | Retrieves the height, in pixels, of the arrow image on the vertical scroll bar.
getVertScrollBarThumbHeight | Retrieves the height, in pixels, of the scroll box on a vertical scroll bar.
getVertScrollBarWidth | Retrieves the width, in pixels, of the vertical scroll bar.
getVirtualScreen | Retrieves the bounds of the virtual screen.
getWorkingArea | Retrieves the size of the working area.


 SystemInformation.get3DBorderSize

SystemInformation.get3DBorderSize

Retrieves the dimensions, in pixels, of a three-dimensional border.

Syntax

public static final Point get3DBorderSize()

Return Value

Returns a Point object that represents the dimensions of the border.

Remarks

The get3DBorderSize method is the three-dimensional counterpart of the getBorderSize method. Use this method when creating a control that has a three-dimensional border to determine the proper sizing of the border.

See Also getBorderSize


 SystemInformation.getArrange

SystemInformation.getArrange

Retrieves a flag specifying how the system arranges minimized windows.

Syntax

public static final int getArrange()

Return Value

Returns an integer value that combines SystemInformation.ArrangeStartingPosition and SystemInformation.ArrangeDirection values.


 SystemInformation.getBorderSize

SystemInformation.getBorderSize

Retrieves the width and height, in pixels, of a window border.

Syntax

public static final Point getBorderSize()

Return Value

Returns a Point object that represents the size of a sizeable window border.

Remarks

The getBorderSize method is the non-three-dimensional counterpart of the get3DBorderSize method. Use this method when creating a control that has a border to determine the proper sizing of the border.

See Also get3DBorderSize


 SystemInformation.getCaptionButtonSize

SystemInformation.getCaptionButtonSize

Retrieves the width and height, in pixels, of a button in a window's caption or title bar.

Syntax

public static final Point getCaptionButtonSize()

Return Value

Returns a Point object that represents the dimensions of a caption bar button.

Remarks

Use the getCaptionButtonSize method to get the dimensions of a button in the caption bar of window, to place additional caption buttons in the caption of a window, and to ensure the button is properly sized.

See Also getCaptionHeight


 SystemInformation.getCaptionHeight

SystemInformation.getCaptionHeight

Retrieves the height, in pixels, of the normal caption area of a window.

Syntax

public static final int getCaptionHeight()

Return Value

Returns an integer value that represents the height of the caption area of a window.

Remarks

Use the getCaptionHeight method to determine the size of the standard window caption. You can also perform special display operations or add a caption button to the caption of a window.

See Also getCaptionButtonSize


 SystemInformation.getCleanBoot

SystemInformation.getCleanBoot

Retrieves a value that specifies how the system was started.

Syntax

public static final int getCleanBoot()

Return Value

Returns an integer value that indicates how the system was started.

Remarks

Use the getCleanBoot method to determine how the user started the system. For applications running on Windows 95/98, you can use this method to determine whether the system is in fail-safe mode. Your application uses this information to operate appropriately when accessing system services and hardware.

The value returned by getCleanBoot can be one of the following values.

Value | Description
0 | Normal boot
1 | Fail-safe boot
2 | Fail-safe boot with network connections

Note Fail-safe boot (also called SafeBoot) bypasses the user's startup files.


 SystemInformation.getComputerName

SystemInformation.getComputerName

Retrieves the computer name of the current system.

Syntax

public static final String getComputerName()

Return Value

Returns a String object representing the name of the computer.

Remarks

Use the getComputerName method to determine the name of the computer as it is displayed to other users on a network. This name is established at system startup when it is initialized from the registry.


 SystemInformation.getCursorSize

SystemInformation.getCursorSize

Retrieves the width and height, in pixels, of a cursor.

Syntax

public static final Point getCursorSize()

Return Value

Returns a Point object that represents the system cursor size.

Remarks

The operating system cannot create various sized cursors.


 SystemInformation.getDBCSEnabled

SystemInformation.getDBCSEnabled

Determines whether the operating system supports the double-byte character set (DBCS).

Syntax

public static final boolean getDBCSEnabled()

Return Value

Returns true if the operating system supports DBCS; otherwise, returns false.

Remarks

Use the getDBCSEnabled method to determine whether the operating system that your application is running on supports DBCS. Although an operating system may support DBCS, it does not mean that the locale for the application uses DBCS.


 SystemInformation.getDebug

SystemInformation.getDebug

Determines whether your application is running on a debug version of the operating system.

Syntax

public static final boolean getDebug()

Return Value

Returns true if the debug version of User.exe is installed; otherwise, returns false.


 SystemInformation.getDoubleClickSize

SystemInformation.getDoubleClickSize

Retrieves the width and height, in pixels, of the rectangle around the location of a first click in a double-click sequence.

Syntax

public static final Point getDoubleClickSize()

Return Value

Returns a Point object that represents the size of an imaginary rectangle around which a double-click must occur.

Remarks

Use the getDoubleClickSize method to determine the height and width of the rectangle that Windows uses to determine whether the second click in a double-click sequence is in a valid location. The second click must occur within this rectangle for the system to consider the two clicks to be a double-click. The two clicks must also occur within a specified time (determined using the getDoubleClickTime method).


 SystemInformation.getDoubleClickTime

SystemInformation.getDoubleClickTime

Retrieves the current double-click time for the mouse.

Syntax

public static final int getDoubleClickTime()

Return Value

Returns an integer value that represents the number of milliseconds between clicks for a double-click.

Remarks

A double-click is a series of two clicks of the mouse button, the second occurring within a specified time after the first. The double-click time is the maximum number of milliseconds that can occur between the first and second click of a double-click. For a double-click to be registered, it must also be within the same region. To determine this region, use the getDoubleClickSize method.


 SystemInformation.getDragSize

SystemInformation.getDragSize

Retrieves the width and height, in pixels, of a rectangle centered on a drag point to allow for limited movement of the mouse pointer before a drag operation begins.

Syntax

public static final Point getDragSize()

Return Value

Returns a Point object that represents the rectangle that a drag must extend outside of to be considered a drag.

Remarks

Use the getDragSize method to determine the rectangle that Windows uses as a boundary before starting a drag operation. This boundary lets the user click and release the mouse button easily without unintentionally starting a drag operation.


 SystemInformation.getFixedFrameBorderSize

SystemInformation.getFixedFrameBorderSize

Retrieves the thickness, in pixels, of the frame around the perimeter of a window that is not sizable.

Syntax

public static final Point getFixedFrameBorderSize()

Return Value

Returns a Point object that represents the size of a fixed window border.

See Also getFrameBorderSize


 SystemInformation.getFrameBorderSize

SystemInformation.getFrameBorderSize

Retrieves the thickness, in pixels, of the sizing border around the perimeter of a window that can be resized.

Syntax

public static final Point getFrameBorderSize()

Return Value

Returns a Point object that represents the width and height of a sizing border for a sizeable window.

See Also getFixedFrameBorderSize


 SystemInformation.getHorizScrollBarArrowWidth

SystemInformation.getHorizScrollBarArrowWidth

Retrieves the width, in pixels, of the arrow on a horizontal scroll bar.

Syntax

public static final int getHorizScrollBarArrowWidth()

Return Value

Returns an integer value that represents the width of a horizontal scroll bar arrow.

See Also getHorizScrollBarHeight, getHorizScrollBarThumbWidth, getVertScrollBarArrowHeight


 SystemInformation.getHorizScrollBarHeight

SystemInformation.getHorizScrollBarHeight

Retrieves the height, in pixels, of the horizontal scroll bar.

Syntax

public static final int getHorizScrollBarHeight()

Return Value

Returns an integer value that represents the height of a horizontal scroll bar.

See Also getHorizScrollBarThumbWidth, getHorizScrollBarArrowWidth, getVertScrollBarWidth


 SystemInformation.getHorizScrollBarThumbWidth

SystemInformation.getHorizScrollBarThumbWidth

Retrieves the width, in pixels, of the scroll box in a horizontal scroll bar.

Syntax

public static final int getHorizScrollBarThumbWidth()

Return Value

Returns an integer value that represents the width of a horizontal scroll box.

Remarks

Use the getHorizScrollBarThumbWidth method to determine the width of the scroll box used to indicate scroll bar position and to drag the scroll bar to a new position.

See Also getHorizScrollBarArrowWidth, getHorizScrollBarHeight, getVertScrollBarThumbHeight


 SystemInformation.getIconSize

SystemInformation.getIconSize

Retrieves the default width and height, in pixels, of an icon.

Syntax

public static final Point getIconSize()

Return Value

Returns a Point object that represents the default size of an icon.

Remarks

Use the getIconSize method to determine the Windows default icon size. This method determines whether the size of icons displayed in your applications are consistent with Windows. The icon size returned by this method is for large icons.

See Also getIconSpacingSize


 SystemInformation.getIconSpacingSize

SystemInformation.getIconSpacingSize

Retrieves the dimensions, in pixels, of a grid cell for items in a large icon view.

Syntax

public static final Point getIconSpacingSize()

Return Value

Returns a Point object that represents the dimensions of the grid used for arranging icons.

Remarks

Use the getIconSpacingSize method to determine the grid that each icon fits into when arranged. This value is always greater than or equal to the value returned by getIconSize.


 SystemInformation.getKanjiWindowHeight

SystemInformation.getKanjiWindowHeight

For double-byte character set (DBCS) versions of Windows, retrieves the height, in pixels, of the Kanji window at the bottom of the screen.

Syntax

public static final int getKanjiWindowHeight()

Return Value

Returns an integer value that represents the height of the Kanji window.

Remarks

Use the getKanjiWindowHeight method to determine the height of the Kanji window on systems that support the double-byte character set (DBCS). To determine whether the operating system supports DBCS, use the getDBCSEnabled method.


 SystemInformation.getMaxWindowTrackSize

SystemInformation.getMaxWindowTrackSize

Retrieves the default maximum dimensions, in pixels, of a window that has a caption and sizing borders.

Syntax

public static final Point getMaxWindowTrackSize()

Return Value

Returns a Point object that represents the maximum size a window can be sized to.

Remarks

The value returned by getMaxWindowTrackSize refers to dimensions of the entire desktop. The user cannot drag the window frame to a size larger than these dimensions. A form can override this value by overriding its getMaxTrackSize method.

See Also com.ms.wfc.ui.Form


 SystemInformation.getMenuButtonSize

SystemInformation.getMenuButtonSize

Retrieves the dimensions, in pixels, of menu bar buttons.

Syntax

public static final Point getMenuButtonSize()

Return Value

Returns a Point object that represents the size of menu bar buttons.

Remarks

Use the getMenuButtonSize method to determine the size of a menu button, such as the child window close buttons used in a multiple document interface application. The dimensions of a menu button should be similar to the dimensions returned for caption buttons using the getCaptionButtonSize method.

See Also getMenuCheckSize, getMenuHeight


 SystemInformation.getMenuCheckSize

SystemInformation.getMenuCheckSize

Retrieves the dimensions, in pixels, of the default menu check mark.

Syntax

public static final Point getMenuCheckSize()

Return Value

Returns a Point object that represents the default size of a menu check mark.

Remarks

Use the getMenuCheckSize method to determine the size of the image used by Windows to display a check mark next to a selected menu item.

See Also getMenuHeight, getMenuButtonSize


 SystemInformation.getMenuHeight

SystemInformation.getMenuHeight

Retrieves the height, in pixels, of a single-line menu bar.

Syntax

public static final int getMenuHeight()

Return Value

Returns an integer value that represents the height of one line of a menu.

Remarks

Use the getMenuHeight method to determine the height that is currently defined by Windows for a menu bar.

See Also getMenuButtonSize, getMenuCheckSize


 SystemInformation.getMidEastEnabled

SystemInformation.getMidEastEnabled

Determines if the operating system supports Hebrew and Arabic languages.

Syntax

public static final boolean getMidEastEnabled()

Return Value

Returns true if the system supports Hebrew or Arabic; otherwise, returns false.


 SystemInformation.getMinimizedWindowSize

SystemInformation.getMinimizedWindowSize

Retrieves the dimensions, in pixels, of a normal minimized window.

Syntax

public static final Point getMinimizedWindowSize()

Return Value

Returns a Point object that represents the size of a normal minimized window.

Remarks

Use the getMinimizedWindowSize method to determine the dimensions for a minimized window as specified by Windows.

See Also getMinimizedWindowSpacingSize


 SystemInformation.getMinimizedWindowSpacingSize

SystemInformation.getMinimizedWindowSpacingSize

Retrieves the dimensions, in pixels, of a grid cell for minimized windows.

Syntax

public static final Point getMinimizedWindowSpacingSize()

Return Value

Returns a Point object that represents the grid into which minimized windows will be placed.

Remarks

Use the getMinimizedWindowSpacingSize method to determine the rectangle that a minimized window is sized to when arranged. This value is always greater than or equal to the value returned from a call to getMinimizedWindowSize.


 SystemInformation.getMinimumWindowSize

SystemInformation.getMinimumWindowSize

Retrieves the minimum width and height, in pixels, of a window.

Syntax

public static final Point getMinimumWindowSize()

Return Value

Returns a Point object that represents the minimum allowable size of a window.

Remarks

Use the getMinimumWindowSize method to determine the dimensions specified by Windows as the minimum size for a window. You can use this method to limit the resizing of your application's windows to a size larger than the dimension returned by this method.


 SystemInformation.getMinWindowTrackSize

SystemInformation.getMinWindowTrackSize

Retrieves the minimum tracking width and height, in pixels, of a window.

Syntax

public static final Point getMinWindowTrackSize()

Return Value

Returns a Point object that represents the default minimum tracking size that Windows allows.

Remarks

Use the getMinWindowTrackSize method to determine the minimum window size while a user is dragging the window frame. A form can override this value by overriding its com.ms.wfc.ui.Form.getMinTrackSize method.

See Also com.ms.wfc.ui.Form


 SystemInformation.getMonitorCount

SystemInformation.getMonitorCount

Retrieves the number of monitors that are connected to the system.

Syntax

public static final int getMonitorCount()

Return Value

Returns an integer value that represents the number of monitors that are connected to the system.

Remarks

This method returns a value greater than one only if multiple monitors are presently connected to the system.

See Also getMonitorsSameDisplayFormat


 SystemInformation.getMonitorsSameDisplayFormat

SystemInformation.getMonitorsSameDisplayFormat

Determines if all monitors currently connected to the system have the same color format.

Syntax

public static final boolean getMonitorsSameDisplayFormat()

Return Value

Returns true if all monitors have the same color format; otherwise, returns false.

Remarks

Use the getMonitorsSameDisplayFormat method to determine whether all monitors currently connected to the system have the same color format. For example red, green, and blue pixels can be encoded with a different number of bits, or those bits can be located in different places in a pixel's color value.

Note Two displays can have the same bit depth but different color formats.

See Also getMonitorCount


 SystemInformation.getMouseButtons

SystemInformation.getMouseButtons

Retrieves the number of buttons on the mouse connected to the system.

Syntax

public static final int getMouseButtons()

Return Value

Returns an integer value representing the number of buttons on the mouse.

Remarks

If no mouse is installed, this method returns a zero value. You can use this method to determine the number of mouse buttons that your application can support and provide additional functionality if more than two buttons are available.

See Also getMouseButtonsSwapped, getMousePresent


 SystemInformation.getMouseButtonsSwapped

SystemInformation.getMouseButtonsSwapped

Determines whether the usage of the left and right mouse buttons has been swapped.

Syntax

public static final boolean getMouseButtonsSwapped()

Return Value

Returns true if the usage of the left and right mouse buttons is swapped; otherwise, returns false.

Remarks

Use the getMouseButtonsSwapped method to determine whether the left and right mouse buttons have opposite usage.This method determines how the system responds to mouse button clicks and other mouse button events.

See Also getMouseButtons, getMousePresent


 SystemInformation.getMousePresent

SystemInformation.getMousePresent

Determines whether the system has a mouse installed.

Syntax

public static final boolean getMousePresent()

Return Value

Returns true if a mouse is installed; otherwise, returns false.

See Also getMouseButtons, getMouseButtonsSwapped


 SystemInformation.getMouseWheelPresent

SystemInformation.getMouseWheelPresent

Determines whether the mouse that is currently installed on the system has a mouse wheel.

Syntax

public static final boolean getMouseWheelPresent()

Return Value

Returns true if the currently installed mouse has a mouse wheel; otherwise, returns false.

Remarks

Use this method when determining whether to process code that requires a mouse wheel.

See Also getMouseWheelScrollLines, getNativeMouseWheelSupport


 SystemInformation.getMouseWheelScrollLines

SystemInformation.getMouseWheelScrollLines

Retrieves the number of lines to scroll when the mouse wheel is rotated.

Syntax

public static final int getMouseWheelScrollLines()

Return Value

Returns an integer that represents the number of lines to scroll.

Remarks

Use this method to determine how many lines to increase or decrease in a control that has a scroll bar.

See Also getNativeMouseWheelSupport, getMouseWheelPresent


 SystemInformation.getNativeMouseWheelSupport

SystemInformation.getNativeMouseWheelSupport

Determines whether the operating system natively supports a mouse wheel.

Syntax

public static final boolean getNativeMouseWheelSupport()

Return Value

Returns true if the system natively supports the mouse wheel; otherwise, returns false.

Remarks

Mouse wheel operations that occur through a com.ms.wfc.ui.Control object work even if the system does not natively provide support for a mouse wheel.

See Also getMouseWheelPresent, getMouseWheelScrollLines


 SystemInformation.getNetwork

SystemInformation.getNetwork

Determines whether this computer is on a network.

Syntax

public static final boolean getNetwork()

Return Value

Returns true if a network is present; otherwise, returns false.

Remarks

Use the getNetwork method to determine whether a network is available before performing network-oriented operations.


 SystemInformation.getPenWindows

SystemInformation.getPenWindows

Determines whether the Microsoft Windows for Pen Computing extensions are installed.

Syntax

public static final boolean getPenWindows()

Return Value

Returns true if the extensions are installed; otherwise, returns false.


 SystemInformation.getPrimaryMonitorMaximizedWindowSize

SystemInformation.getPrimaryMonitorMaximizedWindowSize

Retrieves the default dimensions, in pixels, of a maximized top-left window on the primary monitor.

Syntax

public static final Point getPrimaryMonitorMaximizedWindowSize()

Return Value

Returns a Point object that represents the dimensions of a maximized window on the primary monitor.

See Also getPrimaryMonitorSize, com.ms.wfc.ui.Screen


 SystemInformation.getPrimaryMonitorSize

SystemInformation.getPrimaryMonitorSize

Retrieves the width and height, in pixels, of the screen of the primary display monitor when multiple monitors are installed.

Syntax

public static final Point getPrimaryMonitorSize()

Return Value

Returns a Point object that represents the size, in pixels of the primary monitor.

See Also getPrimaryMonitorMaximizedWindowSize


 SystemInformation.getRightAlignedMenus

SystemInformation.getRightAlignedMenus

Determines whether drop-down menus are right-aligned.

Syntax

public static final boolean getRightAlignedMenus()

Return Value

Returns true if drop-down menus are right-aligned, or returns false if the menus are left-aligned.


 SystemInformation.getSecure

SystemInformation.getSecure

Determines whether security is present on this operating system.

Syntax

public static final boolean getSecure()

Return Value

Returns true if security is present; otherwise, returns false.

Remarks

The getSecure method allows you to determine whether a Security Manager is available on the operating system. Windows NT provides a Security Manager to determine access to the registry and file system access. Windows 95 does not provide a Security Manager.


 SystemInformation.getShowSounds

SystemInformation.getShowSounds

Determines whether the user requires an application to present information visually in situations where it would otherwise present the information audibly.

Syntax

public static final boolean getShowSounds()

Return Value

Returns true if the application should visually show audible output, or returns false if the application can freely use audio.

Remarks

Use the getShowSounds method to determine whether the application can play sounds and other audio outputs or whether the audio needs to be visually shown. This method can help to provide accessibility to your application.


 SystemInformation.getSmallIconSize

SystemInformation.getSmallIconSize

Retrieves the recommended dimensions, in pixels, of a small icon.

Syntax

public static final Point getSmallIconSize()

Return Value

Returns a Point object that represents the size of a small icon.

Remarks

Use the getSmallIcons method to determine the size of small icons in Windows. Small icons typically appear in window captions and in the Small Icon view in Windows Explorer.


 SystemInformation.getSpecialFolderPath

SystemInformation.getSpecialFolderPath

Retrieves the path to a specific special folder.

Syntax

public static final String getSpecialFolderPath( int folder )

Parameters

folder

An integer value that represents the special folder path to retrieve.

Return Value

Returns a path to the special folder.

Remarks

Special folders are common locations, defined by Windows, that store various types of data. When calling this method, use the constants in the SpecialFolder class to determine the folder to retrieve. You can also obtain the proper storage directory for items such as documents and sound files.


 SystemInformation.getToolWindowCaptionButtonSize

SystemInformation.getToolWindowCaptionButtonSize

Retrieves the dimensions, in pixels, of small caption buttons.

Syntax

public static final Point getToolWindowCaptionButtonSize()

Return Value

Returns a Point object that represents the size of small caption buttons.

Remarks

Use the getToolWindowCaptionButtonSize method to obtain the dimensions of the buttons placed in the caption of a tool window. You can use this method to assist in adding your own custom buttons to the caption in a tool window.

See Also getToolWindowCaptionHeight


 SystemInformation.getToolWindowCaptionHeight

SystemInformation.getToolWindowCaptionHeight

Retrieves the height, in pixels, of a small caption.

Syntax

public static final int getToolWindowCaptionHeight()

Return Value

Returns an integer value that represents the height of a small caption.

Remarks

Use the getToolWindowCaptionHeight method to determine the height of a tool window caption in Windows. This method can assist in manipulating the caption area of a tool window.

See Also getToolWindowCaptionButtonSize


 SystemInformation.getUserName

SystemInformation.getUserName

Retrieves the user name for the current thread.

Syntax

public static final String getUserName()

Return Value

Returns a String object that represents the current user name.

Remarks

Use the getUserName method to obtain the name of the user currently logged on to the system.


 SystemInformation.getVertScrollBarArrowHeight

SystemInformation.getVertScrollBarArrowHeight

Retrieves the height, in pixels, of the arrow image on the vertical scroll bar.

Syntax

public static final int getVertScrollBarArrowHeight()

Return Value

Returns an integer value that represents the height of a vertical scroll bar arrow.

Remarks

Use the getVertScrollBarArrowHeight method to determine the height of the arrow on a vertical scroll bar.

See Also getHorizScrollBarArrowWidth


 SystemInformation.getVertScrollBarThumbHeight

SystemInformation.getVertScrollBarThumbHeight

Retrieves the height, in pixels, of the scroll box on a vertical scroll bar.

Syntax

public static final int getVertScrollBarThumbHeight()

Return Value

Returns an integer value that represents the height of a vertical scroll box.

Remarks

Use the getVertScrollBarThumbHeight method to determine the height of the box used to indicate scroll bar position and to drag the scroll bar to a new position.

See Also getHorizScrollBarThumbWidth


 SystemInformation.getVertScrollBarWidth

SystemInformation.getVertScrollBarWidth

Retrieves the width, in pixels, of the vertical scroll bar.

Syntax

public static final int getVertScrollBarWidth()

Return Value

Returns an integer value that represents the width of a vertical scroll bar.

See Also getHorizScrollBarHeight


 SystemInformation.getVirtualScreen

SystemInformation.getVirtualScreen

Retrieves the bounds of the virtual screen.

Syntax

public static final Rectangle getVirtualScreen()

Return Value

Returns a Rectangle object that represents the bounding rectangle of the entire virtual screen.

Remarks

Use the getVirtualScreen method to determine the bounds of the entire desktop on a multimonitor system. You can then determine the maximum visual space available on a system that has multiple monitors installed.

Note The left and top coordinates of the rectangle can be nonzero or negative.

See Also getWorkingArea, com.ms.wfc.ui.Screen


 SystemInformation.getWorkingArea

SystemInformation.getWorkingArea

Retrieves the size of the working area.

Syntax

public static final Rectangle getWorkingArea()

Return Value

Returns a Rectangle object that represents the bounds of the working area of the screen, in pixels.

Remarks

Use the getWorkingArea method to determine the bounds of the screen that can be used by applications. The working area is the portion of the screen not obscured by the system tray and other top-level windows that are docked to the Windows desktop.

See Also getVirtualScreen, com.ms.wfc.ui.Screen


SystemInformation.ArrangeDirection Class

Defines constants used to denote the direction the operating system uses to arrange minimized windows.

package com.ms.wfc.app

public static class SystemInformation.ArrangeDirection

Remarks

Use the constants defined in this class with the constants in the SystemInformation.ArrangeStartingPosition class to determine the results of a call to the SystemInformation.getArrange method.


 SystemInformation.ArrangeDirection Fields

SystemInformation.ArrangeDirection Fields

Fields | Description
DOWN | Arranges minimized windows vertically from top to bottom.
LEFT | Arranges minimized windows horizontally from left to right.
RIGHT | Arranges minimized windows horizontally from right to left.
UP | Arranges minimized windows vertically from bottom to top.


 SystemInformation.ArrangeDirection.DOWN

SystemInformation.ArrangeDirection.DOWN

Arranges minimized windows vertically from top to bottom.

Syntax

public static final int DOWN;


 SystemInformation.ArrangeDirection.LEFT

SystemInformation.ArrangeDirection.LEFT

Arranges minimized windows horizontally from left to right.

Syntax

public static final int LEFT;


 SystemInformation.ArrangeDirection.RIGHT

SystemInformation.ArrangeDirection.RIGHT

Arranges minimized windows horizontally from right to left.

Syntax

public static final int RIGHT;


 SystemInformation.ArrangeDirection.UP

SystemInformation.ArrangeDirection.UP

Arranges minimized windows vertically from bottom to top.

Syntax

public static final int UP;


SystemInformation.ArrangeStartingPosition Class

Defines constants used to denote the starting position the system uses to arrange minimized windows.

package com.ms.wfc.app

public static class SystemInformation.ArrangeStartingPosition

Remarks

Use the constants defined in this class with the constants in the SystemInformation.ArrangeDirection class to determine the results of a call to the SystemInformation.getArrange method.


 SystemInformation.ArrangeStartingPosition Fields

SystemInformation.ArrangeStartingPosition Fields

Fields | Description
BOTTOMLEFT | Starts arranging minimized windows at the lower-left corner of the screen (default position).
BOTTOMRIGHT | Starts arranging minimized windows at the lower-right corner of the screen.
HIDE | Hides minimized windows by moving them off the visible area of the screen.
TOPLEFT | Starts arranging minimized windows at the upper-left corner of the screen.
TOPRIGHT | Starts arranging minimized windows at the upper-right corner of the screen.


 SystemInformation.ArrangeStartingPosition.BOTTOMLEFT

SystemInformation.ArrangeStartingPosition.BOTTOMLEFT

Starts arranging minimized windows at the lower-left corner of the screen (default position).

Syntax

public static final int BOTTOMLEFT;


 SystemInformation.ArrangeStartingPosition.BOTTOMRIGHT

SystemInformation.ArrangeStartingPosition.BOTTOMRIGHT

Starts arranging minimized windows at the lower-right corner of the screen.

Syntax

public static final int BOTTOMRIGHT;


 SystemInformation.ArrangeStartingPosition.HIDE

SystemInformation.ArrangeStartingPosition.HIDE

Hides minimized windows by moving them off the visible area of the screen.

Syntax

public static final int HIDE;


 SystemInformation.ArrangeStartingPosition.TOPLEFT

SystemInformation.ArrangeStartingPosition.TOPLEFT

Starts arranging minimized windows at the upper-left corner of the screen.

Syntax

public static final int TOPLEFT;


 SystemInformation.ArrangeStartingPosition.TOPRIGHT

SystemInformation.ArrangeStartingPosition.TOPRIGHT

Starts arranging minimized windows at the upper-right corner of the screen.

Syntax

public static final int TOPRIGHT;


ThreadExceptionDialog Class

Implements a dialog box that is displayed when an unhandled exception occurs in a thread.

Form
  |
  +--ThreadExceptionDialog

package com.ms.wfc.app

public class ThreadExceptionDialog
extends Form

Remarks

The ThreadExceptionDialog class provides a dialog box that is displayed when an unhandled exception occurs in a thread. To display the form once it has been created, use the showDialog method in the Form class. The dialog box provides a description of the thread that caused the error as well as a Details button so you can display the call stack where the exception occurred. Use the ThreadExceptionDialog class to assist in debugging applications.

Note The ThreadExceptionDialog is automatically shown in response to an unhandled exception if a handler for a thread exception is not provided.

See Also com.ms.wfc.ui.Form.showDialog, com.ms.wfc.ui.Form, ThreadExceptionEventHandler


 ThreadExceptionDialog Methods

ThreadExceptionDialog Methods

Constructors | Description
ThreadExceptionDialog | Creates a new ThreadExceptionDialog object.


 ThreadExceptionDialog.ThreadExceptionDialog

ThreadExceptionDialog.ThreadExceptionDialog

Creates a new ThreadExceptionDialog object.

Syntax

public ThreadExceptionDialog( Throwable t )

Parameters

t

The exception that occurred.

Remarks

When the dialog box has been constructed, use the showDialog method of the Form class to display it. You can determine which button was clicked in a ThreadExceptionDialog by using the return value of the showDialog method and comparing the value to the fields in the com.ms.wfc.ui.DialogResult class. You can also determine the button that was clicked by calling the com.ms.wfc.ui.Form.getDialogResult method and comparing the value to the fields in the DialogResult class.


ThreadExceptionEvent Class

Implements a ThreadExceptionEvent object.

Event
  |
  +--ThreadExceptionEvent

package com.ms.wfc.app

public class ThreadExceptionEvent
extends Event

Remarks

The ThreadExceptionEvent object is created by a thread when it has encountered an unhandled exception. Use the ThreadExceptionEvent object in your thread exception event handler to determine the type of exception that was thrown.

See Also ThreadExceptionEventHandler


 ThreadExceptionEvent Methods

ThreadExceptionEvent Methods

Constructors | Description
ThreadExceptionEvent | Creates a new ThreadExceptionEvent object.


 ThreadExceptionEvent.ThreadExceptionEvent

ThreadExceptionEvent.ThreadExceptionEvent

Creates a new ThreadExceptionEvent object.

Syntax

public ThreadExceptionEvent( Throwable t )

Parameters

t

The exception that has occurred.


 ThreadExceptionEvent Fields

ThreadExceptionEvent Fields

Fields | Description
exception | Describes the exception that has occurred.


 ThreadExceptionEvent.exception

ThreadExceptionEvent.exception

Describes the exception that has occurred.

Syntax

public Throwable exception;

Remarks

Use this field to determine the type of thread exception that has occurred and handle it appropriately in your code.


ThreadExceptionEventHandler Delegate

Invokes the handler method for the event that has occurred.

package com.ms.wfc.app

public multicast delegate
void ThreadExceptionEventHandler( Object sender, ThreadExceptionEvent e );

Remarks

The syntax of the ThreadExceptionEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a ThreadExceptionEvent object that provides information about the event.

See Also addOnThreadException, ThreadExceptionEvent


Time Class

Represents an element of time.

package com.ms.wfc.app

public class Time
implements IConstructable, IPersistable

Remarks

A Time object represents the number of 100 nanosecond units that have elapsed since midnight on January 1, 100 AD. You can use Time class to store and compare time-based and date-based information. It provides several methods for creating a Time object based on the system clock's date and time, adding new values to time and date fields, formatting the date and time stored in the Time object, and comparing the Time object to other dates or times. Time objects can be changed only by using the class's addXXX methods to create a new Time object that represents the changes.

See Also com.ms.wfc.util.Value


 Time Methods

Time Methods

Constructors | Description
Time | Creates a Time object.

Methods | Description
add | Creates a new Time object that represents the number of time units (100 nanoseconds) after the time that this Time object represents.
addDays | Creates a new Time object that represents the number of days after the time that this Time object represents.
addHours | Creates a new Time object that represents the number of hours after the time that this Time object represents.
addMillis | Creates a new Time object that represents the number of milliseconds after the time that this Time object represents.
addMinutes | Creates a new Time object that represents the number of minutes after the time that this Time object represents.
addMonths | Creates a new Time object that represents the number of months after the time that this Time object represents.
addSeconds | Creates a new Time object that represents the number of seconds after the time that this Time object represents.
addYears | Creates a new Time object that represents the number of years after the time that this Time object represents.
compare | Compares two Time objects.
compareTo | Compares this Time object to another Time object.
equals | Tests for equality.
formatLongDate | Retrieves the Time object as a String using the long date format.
formatLongTime | Retrieves the Time object as a String using the long time format.
formatShortDate | Retrieves the Time object as a String using the short date format.
formatShortTime | Retrieves the Time object as a String using the short time format.
fromFileTime | Creates a Time object based on the specified value.
getDate | Creates a Time object that represents the same date as this Time object but without a time of day specified.
getDay | Retrieves the day of the month that this Time object represents.
getDayOfWeek | Retrieves the day of the week that this Time object represents.
getDayOfYear | Retrieves the day of the year that this Time object represents.
getHour | Retrieves the hour of the day that this Time object represents.
getMillis | Retrieves the milliseconds of the second that this Time object represents.
getMinute | Retrieves the minutes of the hour that this Time object represents.
getMonth | Retrieves the month of the year that this Time object represents.
getSecond | Retrieves the seconds of the minute that this Time object represents.
getTimeOfDay | Creates a Time object that represents the same time of day as this Time object, but without a date specified.
getYear | Retrieves the year that this Time object represents.
save | Stores the Time object in persisted storage.
setDate | Creates a new Time object that contains the date from another Time object and the time of day from this Time object.
setTimeOfDay | Creates a new Time object that contains the date from this Time object and the time of day from another Time object.
toDouble | Retrieves the Time object as an OLE-formatted double value.
toFileTime | Retrieves the Time object as a Win32 FILETIME value.
toLocalTime | Creates a Time object that represents this Time object in the user's local time zone.
toLong | Retrieves the number of time units (100 nanoseconds) units that are stored in this Time object.
toString | Retrieves this Time object as a String object.
toSystemTime | Retrieves this Time object as a Win32 SYSTEMTIME structure.
toUniversalTime | Creates a new Time object that represents this Time object in the coordinated universal time (UTC) time zone.
toVariant | Retrieves this Time object as a com.ms.com.Variant object.


 Time.add

Time.add

Creates a new Time object that represents the number of time units (100 nanoseconds) after the time that this Time object represents.

Syntax

public Time add( long interval )

Parameters

interval

An integer value that represents the number of time units (100 nanoseconds) to add to the current time.

Return Value

Returns a Time object that represents the new time.

Remarks

Time objects cannot be altered. Use the add method to create a new Time object whose date and time is based on the current Time object but incremented by the number of time units specified in interval.

The following example illustrates how to use the add method to create a new Time object that is two hours later in time than a Time object that is initialized to the current time:

public void AddTwoHours()
{
    //Create object that is set to current time
    Time now = new Time();
    //Output the current time
    System.out.println("The current time is: " + now.toString());

    //Increment the current time by two hours
    Time twoHoursLater = now.add(Time.UNITS_PER_HOUR * 2);
    //Output the time
    System.out.println("The time two hours from now is: " + twoHoursLater.toString());
}

See Also Time.UNITS_PER_HOUR


 Time.addDays

Time.addDays

Creates a new Time object that represents the number of days after the time that this Time object represents.

Syntax

public Time addDays( double interval )

public Time addDays( int interval )

Parameters

interval

An integer or double value that represent the number of days to add to the current time.

Return Value

Returns a Time object that represents the new time.

Remarks

Time objects cannot be altered. Use the addDays method to create a new Time object whose date is based on the current Time object but incremented by the number of days specified in interval.

The following example illustrates how to use the addDays method to create a new Time object that is two days later in time than a Time object that is initialized to the current date:

public void AddTwoDays()
{
    //Create object that is set to current date
    Time now = new Time();
    //Output the current date
    System.out.println("The current date is: " + now.formatShortDate());

    //Increment the current time by two days
    Time twoDaysLater = now.addDays(2);
    //Output the date
    System.out.println("The date two days from now is: " + twoDaysLater.formatShortDate());
}

See Also formatShortDate, addMonths, addYears


 Time.addHours

Time.addHours

Creates a new Time object that represents the number of hours after the time that this Time object represents.

Syntax

public Time addHours( long interval )

Parameters

interval

A long value that represents the number of hours to add to the current time.

Return Value

Returns a Time object representing the new time.

Remarks

Time objects cannot be altered. Use the addHours method to create a new Time object whose time is based on the current Time object but incremented by the number of hours specified in interval.

Example

The following example illustrates how to use the addHours method to create a new Time object that is two hours later in time than a Time object that is initialized to the current time:

public void AddTwoHours()
{
    //Create object that is set to current time
    Time now = new Time();
    //Output the current time
    System.out.println("The current time is: " + now.toString());

    //Increment the current time by two hours
    Time twoHoursLater = now.addHours(2);
    //Output the time
    System.out.println("The time two hours from now is: " + twoHoursLater.formatShortTime());
}

See Also addMillis, addMinutes, addSeconds, formatShortTime


 Time.addMillis

Time.addMillis

Creates a new Time object that represents the number of milliseconds after the time that this Time object represents.

Syntax

public Time addMillis( long interval )

Parameters

interval

A long value that represents the number of milliseconds to add to the current time.

Return Value

Returns a Time object representing the new time.

Remarks

Time objects cannot be altered. Use the addMillis method to create a new Time object whose time is based on the current Time object but incremented by the number of milliseconds specified in interval.

See Also addHours, addMinutes, addSeconds


 Time.addMinutes

Time.addMinutes

Creates a new Time object that represents the number of minutes after the time that this Time object represents.

Syntax

public Time addMinutes( long interval )

Parameters

interval

A long value that represents the number of minutes to add to the current time.

Return Value

Returns a Time object representing the new time.

Remarks

Time objects cannot be altered. Use the addMinutes method to create a new Time object whose time is based on the current Time object but incremented by the number of minutes specified in interval.

Example

The following example illustrates how to use the addHours method to create a new Time object that is two hours later in time than a Time object that is initialized to the current time:

public void AddThirtyMinutes()
{
    //Create object that is set to current time
    Time now = new Time();
    //Output the current time
    System.out.println("The current time is: " + now.toString());

    //Increment the current time by 30 minutes
    Time thirtyMinutes = now.addMinutes(30);
    //Output the time
    System.out.println("The time 30 minutes from now is: " + thirtyMinutes.formatShortTime());
}

See Also addMillis, addHours, addSeconds, formatShortTime


 Time.addMonths

Time.addMonths

Creates a new Time object that represents the number of months after the time that this Time object represents.

Syntax

public Time addMonths( int interval )

Parameters

interval

An integer value that represents the number of months to add to the current time.

Return Value

Returns a Time object representing the new time.

Remarks

Time objects cannot be altered. Use the addMonths method to create a new Time object whose date is based on the current Time object but incremented by the number of months specified in interval.

Example

The following example illustrates how to use the addMonths method to create a new Time object that is three months later in time than a Time object that is initialized to New Year's Day 1999:

public String ReturnFirstQuarter()
{
    //Create object that is set to the beginning of 1999
    Time newYears = new Time(1999,01,01);

    //Increment newyears by 3 months
    Time firstQuarter = newYears.addMonths(3);
    //Output the date
    return firstQuarter.formatLongDate();
}

See Also formatLongDate, addDays, addYears


 Time.addSeconds

Time.addSeconds

Creates a new Time object that represents the number of seconds after the time that this Time object represents.

Syntax

public Time addSeconds( long interval )

Parameters

interval

A long value that represents the number of seconds to add to the current time.

Return Value

Returns a Time object representing the new time.

Remarks

Time objects cannot be altered. Use the addSeconds method to create a new Time object whose time is based on the current Time object but incremented by the number of seconds specified in interval.

Example

The following example illustrates how to use the addSeconds method to create a new Time object that is 30 seconds later in time than a Time object that is initialized to the current time:

public void AddThirtySeconds()
{
    //Create object that is set to current time
    Time now = new Time();
    //Output the current time
    System.out.println("The current time is: " + now.toString());

    //Increment the current time by 30 seconds
    Time thirtySeconds = now.addSeconds(30);
    //Output the time
    System.out.println("The time 30 seconds from now is: " + thirtySeconds.formatLongTime());
}

See Also addMillis, addHours, addMinutes, formatLongTime


 Time.addYears

Time.addYears

Creates a new Time object that represents the number of years after the time that this Time object represents.

Syntax

public Time addYears( int interval )

Parameters

interval

An integer value that represents the number of years to add to the current time.

Return Value

Returns a Time object representing the new time.

Remarks

Time objects cannot be altered. Use the addYears method to create a new Time object whose date is based on the current Time object but incremented by the number of years specified in interval.

Example

The following example illustrates how to use the addYears method to create a new Time object that is six years later in time than a Time object that is initialized to the current time:

public int ReturnMastersYear()
{
    //Create object that is set to current date
    Time startCollege = new Time();

    //Increment startCollege by 6 years
    Time endMasters = startCollege.addYears(6);
    //Output the date
    return endMasters.getYear();
}

See Also getYear, addDays, addMonths


 Time.compare

Time.compare

Compares two Time objects.

Syntax

public static int compare( Time t1, Time t2 )

Parameters

t1

The first Time object to compare.

t2

The second Time object to compare.

Return Value

Returns 1 if t1 is greater than t2; returns 0 if the two Time objects are equal; returns -1 if t2 is greater that t1.

See Also compareTo, equals


 Time.compareTo

Time.compareTo

Compares this Time object to another Time object.

Syntax

public int compareTo( Time t )

Parameters

t

The Time object to compare the current Time object to.

Return Value

Returns 1 if t is greater than the current Time object; returns 0 if the two Time objects are equal; returns -1 if the current Time object is greater that t.

See Also compare, equals


 Time.equals

Time.equals

Tests for equality.

Syntax

public boolean equals( Object object )

Parameters

object

The object to compare to.

Return Value

Returns true if object is a Time object that represents the same time as this Time object.

Remarks

Use this method if you are unsure whether an object is a valid Time object. To compare two known Time objects, use the compare or compareTo methods.


 Time.formatLongDate

Time.formatLongDate

Retrieves the Time object as a String using the long date format.

Syntax

public String formatLongDate()

Return Value

Returns a String object that represents the long date format of the Time object.

Remarks

Use the formatLongDate method to extract only the date fields in a Time object. For an example of how to use this method, see the addMonths method.

See Also formatShortDate, formatLongTime


 Time.formatLongTime

Time.formatLongTime

Retrieves the Time object as a String using the long time format.

Syntax

public String formatLongTime()

Return Value

Returns a String object that represents the long time format of the Time object.

Remarks

Use the formatLongTime method to extract only the time fields in a Time object. For an example of how to use this method, see the addSeconds method.

See Also formatShortTime, formatLongDate


 Time.formatShortDate

Time.formatShortDate

Retrieves the Time object as a String using the short date format.

Syntax

public String formatShortDate()

Return Value

Returns a String object that represents the short date format of the Time object.

Remarks

Use the formatShortDate method to extract only the date fields in a Time object. For an example of how to use this method, see the addDays method.

See Also formatLongDate, formatShortTime


 Time.formatShortTime

Time.formatShortTime

Retrieves the Time object as a String using the short time format.

Syntax

public String formatShortTime()

Return Value

Returns a String object that represents the short time format of the Time object.

Remarks

Use the formatShortTime method to extract only the time fields in a Time object. For an example of how to use this method, see the addHours method.

See Also formatLongTime, formatShortDate


 Time.fromFileTime

Time.fromFileTime

Creates a Time object based on the specified value.

Syntax

public static Time fromFileTime( long fileTime )

Parameters

fileTime

A long value that represents a Win32 FILETIME value to create a new Time object for.

Return Value

Returns a new Time object that represents the equivalent of the time stored in the fileTime parameter.

Remarks

The value stored in the fileTime parameter must be formatted as a Win32 FILETIME value, which means that the fileTime parameter must contain the number of 100 nanosecond units elapsed since January 1, 1601, in coordinated universal time (UTC). This method adjusts the base time and converts the time to local time.


 Time.getDate

Time.getDate

Creates a Time object that represents the same date as this Time object but without a time of day specified.

Syntax

public Time getDate()

Return Value

Returns a new Time object with the date of this Time object.

See Also getTimeOfDay


 Time.getDay

Time.getDay

Retrieves the day of the month that this Time object represents.

Syntax

public int getDay()

Return Value

Returns an integer value that represents the day of the month that this Time object represents.

Remarks

The number returned by the getDay method is always between 1 and 31.

See Also getDayOfWeek, getDayOfYear, getDate


 Time.getDayOfWeek

Time.getDayOfWeek

Retrieves the day of the week that this Time object represents.

Syntax

public int getDayOfWeek()

Return Value

Returns an integer value that represents the day of the week that this Time object represents.

Remarks

The number returned by the getDayOfWeek method is always between 1 and 7 where a value of 1 represents Monday.

See Also getDayOfYear, getDay


 Time.getDayOfYear

Time.getDayOfYear

Retrieves the day of the year that this Time object represents.

Syntax

public int getDayOfYear()

Return Value

Returns an integer value that represents the day of the year that this Time object represents.

Remarks

The number returned by the getDayOfYear method is always between 1 and 366.

See Also getDayOfWeek, getDay


 Time.getHour

Time.getHour

Retrieves the hour of the day that this Time object represents.

Syntax

public int getHour()

Return Value

Returns an integer value that represents the hour of the day that this Time object represents.

Remarks

The number returned by the getHour method is always between 0 and 23.

See Also getMinute, getSecond, getMillis, getTimeOfDay


 Time.getMillis

Time.getMillis

Retrieves the milliseconds of the second that this Time object represents.

Syntax

public int getMillis()

Return Value

Returns an integer value that represents the millisecond of the second that this Time object represents.

Remarks

The number returned by the getMillis method is always between 0 and 999.

See Also getSecond, getMinute, getHour, getTimeOfDay


 Time.getMinute

Time.getMinute

Retrieves the minutes of the hour that this Time object represents.

Syntax

public int getMinute()

Return Value

Returns an integer value that represents the minutes of the hour that this Time object represents.

Remarks

The number returned by the getMinute method is always between 0 and 59.

See Also getSecond, getMillis, getHour, getTimeOfDay


 Time.getMonth

Time.getMonth

Retrieves the month of the year that this Time object represents.

Syntax

public int getMonth()

Return Value

Returns an integer value that represents the month of the year that this Time object represents.

Remarks

The number returned by the getMonth method is always between 1 and 12.

See Also getDay, getYear, getDate


 Time.getSecond

Time.getSecond

Retrieves the seconds of the minute that this Time object represents.

Syntax

public int getSecond()

Return Value

Returns an integer value that represents the seconds of the minute that this Time object represents.

Remarks

The number returned by the getSecond method is always between 0 and 59.

See Also getHour, getMinute, getMillis, getTimeOfDay


 Time.getTimeOfDay

Time.getTimeOfDay

Creates a Time object that represents the same time of day as this Time object, but without a date specified.

Syntax

public Time getTimeOfDay()

Return Value

Returns a new Time object with the time of day of this Time object.

See Also getDate


 Time.getYear

Time.getYear

Retrieves the year that this Time object represents.

Syntax

public int getYear()

Return Value

Returns an integer value that represents the year that this Time object represents.

Remarks

The number returned by the getYear method will always be between 100 and 10,000.

See Also getDay, getMonth, getDate


 Time.save

Time.save

Stores the Time object in persisted storage.

Syntax

public void save( IDataStream stream )

Parameters

stream

An object that implements the IDataStream interface that is used to store the Time object to persisted storage.

Remarks

Use the save method to store a Time object in persisted storage so the state of the Time object can be persisted and restored at a later time. You can restore the persisted version of a Time object using the constructors in this class.

See Also Time


 Time.setDate

Time.setDate

Creates a new Time object that contains the date from another Time object and the time of day from this Time object.

Syntax

public Time setDate( Time date )

Parameters

date

A Time object that contains the date that you want to combine with the current Time object's time value.

Return Value

Returns a new Time object that combines the date from the date parameter and the time from the current Time object.

Remarks

Use this method to create a new Time object that is a combination of two different Time objects.

See Also setTimeOfDay


 Time.setTimeOfDay

Time.setTimeOfDay

Creates a new Time object that contains the date from this Time object and the time of day from another Time object.

Syntax

public Time setTimeOfDay( Time timeOfDay )

Parameters

timeOfDay

A Time object that contains the time that you want to combine with the current Time object's date values.

Return Value

Returns a new Time object that is a combination of the time from the timeOfDay parameter and the date from the current Time object.

Remarks

Use this method to create a new Time object that is a combination of two different Time objects.

See Also setDate


 Time.Time

Time.Time

Creates a Time object.

Syntax

public Time()

public Time( IDataStream stream )

public Time( double d )

public Time( long units )

public Time( Time t )

public Time( SYSTEMTIME st )

public Time( String s )

public Time( int year, int month, int day )

public Time( int year, int month, int day, int hour, int min, int sec )

public Time( Variant v )

Parameters

stream

An object that implements the IDataStream interface used to retrieve a date and time from persisted storage.

d

A double value that contains an OLE-formatted time value.

units

A long value that contains the time value to store in the new Time object.

t

A Time object to clone.

st

A Win32 SYSTEMTIME structure used to set the Time object.

s

A String object used to parse into the Time object.

year

An integer value that represents the year to set the Time object.

month

An integer value that represents the month to set the Time object.

day

An integer value that represents the day to set the Time object.

hour

An integer value that represents the hour to set the Time object. The hour must be specified in 24-hour format.

in

An integer value that represents the minute to set the Time object.

sec

An integer value that represents the second to set the Time object.

v

A com.ms.com.Variant object used to set the Time object.

Remarks

The Time class provides several constructors for creating a Time object. If you call the first version, the Time object that is created contains the current local time. If you have a time value that has been acquired from an OLE source, you can use the third version that accepts a double value to store the time and date properly. The eighth version defines a Time object based strictly on the date. The time fields in a Time object created with this version are initalized to midnight. The last version creates a Time object from a Variant object. Use this version to interact with time values from COM objects and ActiveX controls.


 Time.toDouble

Time.toDouble

Retrieves the Time object as an OLE-formatted double value.

Syntax

public double toDouble()

Return Value

Returns a double value that contains the OLE-formatted time value for this Time object.


 Time.toFileTime

Time.toFileTime

Retrieves the Time object as a Win32 FILETIME value.

Syntax

public long toFileTime()

Return Value

Returns a long value that contains the Win32 FILETIME value for this Time object.

Remarks

Dates that are earlier than January 1, 1601, cannot be converted to a FILETIME value.


 Time.toLocalTime

Time.toLocalTime

Creates a Time object that represents this Time object in the user's local time zone.

Syntax

public Time toLocalTime()

Return Value

Returns a new Time object that represents this Time object in the user's local time zone.


 Time.toLong

Time.toLong

Retrieves the number of time units (100 nanoseconds) units that are stored in this Time object.

Syntax

public long toLong()

Return Value

Returns a long value that represents the number of time units (100 nanoseconds) that have passed in this Time object since January 1, 100 AD.


 Time.toString

Time.toString

Retrieves this Time object as a String object.

Syntax

public String toString()

Return Value

Returns a String object that represents the string version of the time and date stored in this Time object.

Remarks

To retrieve the string representation of a Time object with either long or short formatting, use the formatLongDate, formatShortDate, formatLongTime, and formatShortTime methods.


 Time.toSystemTime

Time.toSystemTime

Retrieves this Time object as a Win32 SYSTEMTIME structure.

Syntax

public SYSTEMTIME toSystemTime()

Return Value

Returns a Win32 SYSTEMTIME structure that represents the time stored in this Time object.

Remarks

Use the toSystemTime method when you need to work with time values in the Win32 API. Dates that are earlier than January 1, 1601, cannot be converted to a SYSTEMTIME value.


 Time.toUniversalTime

Time.toUniversalTime

Creates a new Time object that represents this Time object in the coordinated universal time (UTC) time zone.

Syntax

public Time toUniversalTime()

Return Value

Returns a new Time object that represents this Time object in the UTC time zone.


 Time.toVariant

Time.toVariant

Retrieves this Time object as a com.ms.com.Variant object.

Syntax

public Variant toVariant()

Return Value

Returns a com.ms.com.Variant that represents the time and date stored in this Time object.

Remarks

Use this method to convert this Time object to a value that can be used with COM objects and ActiveX controls.


 Time Fields

Time Fields

Fields | Description
MAX_UNITS | Specifies the maximum number of time units (100 nanoseconds) that can be stored in a Time object.
MIN_SYSTEM_UNITS | Specifies the number of time units (100 nanoseconds) that can be stored in a SYSTEMTIME or FILETIME structure.
MIN_UNITS | Specifies the minimum number of time units (100 nanoseconds) that can be stored in a Time object.
UNITS_PER_DAY | Specifies the number of time units (100 nanoseconds) per day.
UNITS_PER_HOUR | Specifies the number of time units (100 nanoseconds) per hour.
UNITS_PER_MILLISECOND | Specifies the number of time units (100 nanoseconds) per millisecond.
UNITS_PER_MINUTE | Specifies the number of time units (100 nanoseconds) units per minute.
UNITS_PER_SECOND | Specifies the number of time units (100 nanoseconds) units per second.


 Time.MAX_UNITS

Time.MAX_UNITS

Specifies the maximum number of time units (100 nanoseconds) that can be stored in a Time object.

Syntax

public static final long MAX_UNITS;


 Time.MIN_SYSTEM_UNITS

Time.MIN_SYSTEM_UNITS

Specifies the number of time units (100 nanoseconds) that can be stored in a SYSTEMTIME or FILETIME structure.

Syntax

public static final long MIN_SYSTEM_UNITS;


 Time.MIN_UNITS

Time.MIN_UNITS

Specifies the minimum number of time units (100 nanoseconds) that can be stored in a Time object.

Syntax

public static final long MIN_UNITS;


 Time.UNITS_PER_DAY

Time.UNITS_PER_DAY

Specifies the number of time units (100 nanoseconds) per day.

Syntax

public static final long UNITS_PER_DAY;


 Time.UNITS_PER_HOUR

Time.UNITS_PER_HOUR

Specifies the number of time units (100 nanoseconds) per hour.

Syntax

public static final long UNITS_PER_HOUR;


 Time.UNITS_PER_MILLISECOND

Time.UNITS_PER_MILLISECOND

Specifies the number of time units (100 nanoseconds) per millisecond.

Syntax

public static final long UNITS_PER_MILLISECOND;


 Time.UNITS_PER_MINUTE

Time.UNITS_PER_MINUTE

Specifies the number of time units (100 nanoseconds) units per minute.

Syntax

public static final long UNITS_PER_MINUTE;


 Time.UNITS_PER_SECOND

Time.UNITS_PER_SECOND

Specifies the number of time units (100 nanoseconds) units per second.

Syntax

public static final long UNITS_PER_SECOND;


Timer Class

Implements the Timer control.

Component
  |
  +--Timer

package com.ms.wfc.app

public class Timer
extends Component

Remarks

The Timer control is used to trigger an event at user-defined intervals. Use the control's Timer event to perform a polling operation or to display a splash screen for a specified amount of time. Whenever the Timer control's enabled property is set to true and the interval property is greater than 0, the timer event is triggered at intervals based on the interval property setting.


 Timer Methods

Timer Methods

Constructors | Description
Timer | Creates a Timer control.

Methods | Description
addOnTimer | Adds a timer event handler to the Timer control.
dispose | Disposes of the Timer control.
getEnabled | Retrieves a boolean value indicating whether the control is enabled.
getInterval | Retrieves the interval, in milliseconds, of the Timer control's interval.
onTimer | Provides repeated calls based on the Timer control's interval property setting.
removeOnTimer | Removes a timer event handler from the Timer control.
setEnabled | Determines whether the Timer control's timer event is being triggered.
setInterval | Sets the time between timer events.
start | Starts the Timer control.
stop | Stops the Timer control.


 Timer.addOnTimer

Timer.addOnTimer

Adds a timer event handler to the Timer control.

Syntax

public final void addOnTimer( EventHandler value )

Parameters

value

The EventHandler to add.

Remarks

The timer event is where you can place code that you want to run at regular intervals. Whenever the Timer control's enabled property is set to true and the interval property is greater than 0, the timer event is triggered at intervals based on the interval property setting.

See Also removeOnTimer


 Timer.dispose

Timer.dispose

Disposes of the Timer control.

Syntax

public void dispose()

Remarks

The Timer control's dispose method overrides the com.ms.wfc.core.Component.dispose method. The Timer control's implementation sets the enabled property to false before disposing of the control. This allows the control to be disposed of properly and released through garbage collection. If you are overriding the Timer control, use this method to perform other operations prior to disposing of the control.


 Timer.getEnabled

Timer.getEnabled

Retrieves a boolean value indicating whether the control is enabled.

Syntax

public final boolean getEnabled()

Return Value

Returns true if the timer is currently enabled, or returns false if it is disabled.

Remarks

The getEnabled method allows you to determine whether the Timer control is enabled and triggering its timer event at regular intervals.

See Also setEnabled, start, stop


 Timer.getInterval

Timer.getInterval

Retrieves the interval, in milliseconds, of the Timer control's interval.

Syntax

public final int getInterval()

Return Value

Returns the number of milliseconds between each Timer control interval.

Remarks

Use the getInterval method to determine the number of milliseconds the Timer control will wait before triggering its timer event.

See Also setInterval


 Timer.onTimer

Timer.onTimer

Provides repeated calls based on the Timer control's interval property setting.

Syntax

protected void onTimer( Event e )

Parameters

e

The timer event object, which is always defined as Event.EMPTY.

Remarks

The Timer control's implementation of this method calls any EventHandler objects that were added through addOnTimer. If you are extending the Timer control, you can override this method to provide your own objects to the timer event.

See Also com.ms.wfc.core.Event


 Timer.removeOnTimer

Timer.removeOnTimer

Removes a timer event handler from the Timer control.

Syntax

public final void removeOnTimer( EventHandler value )

Parameters

value

The EventHandler object to remove.

Remarks

The timer event is where you can place code that you want to run at regular intervals. Whenever the Timer control's enabled property is set to true and the interval property is greater than 0, the timer event is triggered at intervals based on the interval property setting.

See Also addOnTimer


 Timer.setEnabled

Timer.setEnabled

Determines whether the Timer control's timer event is being triggered.

Syntax

public final synchronized void setEnabled( boolean value )

Parameters

value

Set to true to enable the Timer control to trigger its timer event; otherwise, set to false.

Remarks

Use the setEnabled method to enable or disable the triggering of the timer event. You can use this method to turn the Timer control's abilities on and off. To allow the Timer control to be properly released for garbage collection, you must ensure that the enabled property is set to false before the control is disposed of.

See Also getEnabled, start, stop


 Timer.setInterval

Timer.setInterval

Sets the time between timer events.

Syntax

public final synchronized void setInterval( int value )

Parameters

value

The number of milliseconds between timer events. If this value is less than 1 millisecond, the interval will be set to one millisecond.

Remarks

The Timer control is not a threaded control. Therefore, the timer event may not be triggered exactly at the time specified in the interval property. Delays in the timer event can be caused by long system processes or the loading of other applications.

See Also getInterval


 Timer.start

Timer.start

Starts the Timer control.

Syntax

public final void start()

Remarks

The start method is used to start the Timer control and causes the timer event to be triggered routinely based on the control's interval property. The start method is identical to calling the setEnabled method and passing a true value.

See Also stop, getEnabled


 Timer.stop

Timer.stop

Stops the Timer control.

Syntax

public final void start()

Remarks

The stop method is used to stop the Timer control. The timer event is not triggered. The stop method is identical to calling the setEnabled method and passing a false value.

See Also start, getEnabled


 Timer.Timer

Timer.Timer

Creates a Timer control.

Syntax

public Timer()

public Timer( IContainer container )

Parameters

container

The Container object that holds the Timer.

Remarks

Creates an instance of the Timer control. In the second version of this constructor, specifying a container for the Timer control causes the control to be disposed of when the control's container is disposed of.

Note If the Timer control's enabled property is set to true, the Timer control will not be released during garbage collection. Always pass a container object into the Timer control so that the container can dispose of the Timer control properly.


Version Class

Retrieves version information about the underlying operating system.

package com.ms.wfc.app

public class Version

Remarks

Use the Version class to determine information about the operating system that your application is running on and how to operate best on a specified system. The Version class cannot be instantiated.

Note The Version class should not be used to determine the features, such as DirectX and MouseWheel support, that are available to your application. To determine feature information, query the operating system directly because updates and service packs can add features to the operating system.


 Version Methods

Version Methods

Methods | Description
getVersion | Retrieves the version information for the operating system.


 Version.getVersion

Version.getVersion

Retrieves the version information for the operating system.

Syntax

public static Version getVersion()

Return Value

Returns a Version object representing the version information for the operating system.

Remarks

Use the getVersion method to retrieve a Version object that contains information about the type of operating system and its major, minor, and build version numbers.


 Version Fields

Version Fields

Fields | Description
buildNumber | Specifies the build number of the operating system.
major | Specifies the major version number of the operating system.
minor | Specifies the minor version number of the operating system.
platformId | Specifies the platform identifier of the operating system.
text | Specifies the operating system-defined version information.
WIN32_NT | Determines whether the operating system is Windows NT.
WIN32_WINDOWS | Determines whether the operating system is Windows 95 or later.
WIN32S | Determines whether the operating system is Win32s running on a 16-bit version of Windows.


 Version.buildNumber

Version.buildNumber

Specifies the build number of the operating system.

Syntax

public final int buildNumber;

Remarks

Version numbers are typically represented in the following format: major.minor.buildNumber.


 Version.major

Version.major

Specifies the major version number of the operating system.

Syntax

public final int major;

Remarks

Version numbers are typically represented in the following format: major.minor.buildNumber.


 Version.minor

Version.minor

Specifies the minor version number of the operating system.

Syntax

public final int minor;

Remarks

Version numbers are typically represented in the following format: major.minor.buildNumber.


 Version.platformId

Version.platformId

Specifies the platform identifier of the operating system.

Syntax

public final int platformId;

Remarks

Use the platformId field to determine the general operating system that your application is running on. The value of the field is equal to the WIN32S, WIN32_WINDOWS, or WIN32_NT field of the Version class.


 Version.text

Version.text

Specifies the operating system-defined version information.

Syntax

public final String text;

Remarks

The text field provides the version information string that is defined within the operating system.


 Version.WIN32_NT

Version.WIN32_NT

Determines whether the operating system is Windows NT.

Syntax

public static final int WIN32_NT;

Remarks

To determine which operating system your application is running on, compare this field with the value of the platformId field.

See Also platformId


 Version.WIN32_WINDOWS

Version.WIN32_WINDOWS

Determines whether the operating system is Windows 95 or later.

Syntax

public static final int WIN32_WINDOWS;

Remarks

To determine which operating system your application is running on, compare this field with the value of the platformId field.

See Also platformId


 Version.WIN32S

Version.WIN32S

Determines whether the operating system is Win32s running on a 16-bit version of Windows.

Syntax

public static final int WIN32S;

Remarks

To determine which operating system your application is running on compare this field with the value of the platformId field. The Win32s platform is a layer used on 16-bit versions of Windows to provide access to 32-bit applications.

See Also platformId


Window Class

Provides a low-level encapsulation of a window handle and a window procedure.

Callback
  |
  +--Window

package com.ms.wfc.app

public class Window
extends Callback

Remarks

The Window class supports the creation, subclassing, and superclassing of windows. It automatically manages Window class creation and registration. Following the creation of a Window object, a window handle can be created using the createHandle method. Alternatively, the assignHandle method can be used to subclass an existing window handle. The window handle can be destroyed by using the destroyHandle method. Alternatively, the releaseHandle method can be used to un-subclass the handle. The Window class automatically calls the releaseHandle method if it receives a WM_NCDESTROY window message, indicating that Windows has destroyed the handle.

Note A Window object is not eligible for garbage collection when it is associated with a window handle. To ensure proper garbage collection, window handles must be destroyed manually by calling either the destroyHandle method or the DestroyWindow Windows API function. It can be released using the releaseHandle method. Once a Window object is no longer associated with a Win32 window handle, the Window object will be elligible for garbage collection.


 Window Methods

Window Methods

Methods | Description
assignHandle | Assigns a handle to a Window object.
createHandle | Creates a window handle for this Window object.
defWndProc | Invokes the default window procedure associated with this Window object.
destroyHandle | Destroys the handle associated with a Window object.
fromHandle | Retrieves the Window object associated with the specified handle.
getHandle | Retrieves the handle of the Window object.
onHandleChange | Specifies a notification method that is called whenever the handle for a window is changed.
releaseHandle | Releases the handle associated with the Window object.
wndProc | Specifies the window procedure for the Window object.


 Window.assignHandle

Window.assignHandle

Assigns a handle to a Window object.

Syntax

public void assignHandle( int handle )

Parameters

handle

The handle to assign to this object.

Exceptions

WFCException exception thrown if the Window object already has a handle.

Remarks

A handle passed as a parameter to assignHandle is subclassed so that any window messages sent to the handle are intercepted by the wndProc method. The handle can be un-subclassed later using the releaseHandle method, in effect restoring the handle's window procedure to its former value. The assignHandle method calls the onHandleChange method to indicate that the value of the handle has changed.

See Also wndProc, releaseHandle, onHandleChange


 Window.createHandle

Window.createHandle

Creates a window handle for this Window object.

Syntax

public void createHandle( CreateParams cp )

Parameters

cp

A com.ms.wfc.ui.CreateParams object that represents the creation parameters for this window.

Remarks

The CreateParam object assigned to the createHandle method specifies the parameter values that are passed to the CreateWindowEx Windows API function to create a window and its handle. A non-null value in the className field of the CreateParams object indicates that the newly created window handle should subclass the specified window class. For example, if className is set to "BUTTON", the newly created window handle will be a subclass of the BUTTON window class defined by Windows. The param field of the CreateParams object must be either null or refer to an instance of a class that was declared using the @dll.struct directive.

See Also com.ms.wfc.ui.CreateParams, assignHandle, releaseHandle


 Window.defWndProc

Window.defWndProc

Invokes the default window procedure associated with this Window object.

Syntax

protected void defWndProc( Message m )

Parameters

m

The message that is currently being processed.

Remarks

The defWndProc is the default window procedure for your application. If you are subclassing the Window class, you can override this method to provide your own default window procedure.

Note It is an error to call defWndProc when the handle for the Window object is zero.


 Window.destroyHandle

Window.destroyHandle

Destroys the handle associated with a Window object.

Syntax

public void destroyHandle()

Remarks

The destroyHandle method is used to destroy the handle for a window. Calling this method sets the handle to zero and calls the onHandleChange method in response to the change in the window handle.

See Also onHandleChange


 Window.fromHandle

Window.fromHandle

Retrieves the Window object associated with the specified handle.

Syntax

public static Window fromHandle( int handle )

Parameters

handle

A handle to a window.

Return Value

Returns the Window object associated with the specified handle. The return value is null if the handle does not have an associated Window object.

Remarks

The fromHandle method allows you to get the Window object that is associated with a window handle. If you have received a handle from another method, use this method to retrieve the Window object for the handle.

See Also getHandle


 Window.getHandle

Window.getHandle

Retrieves the handle of the Window object.

Syntax

public final int getHandle()

Return Value

Returns the window handle, or returns zero if no handle is associated with this Window object.

Remarks

Use this method when calling Windows Foundation Classes for Java (WFC) or Windows API methods that require a handle to a window or control.

See Also fromHandle


 Window.onHandleChange

Window.onHandleChange

Specifies a notification method that is called whenever the handle for a window is changed.

Syntax

protected void onHandleChange()

Remarks

If you are subclassing the Window class, you can override this method to track changes that are made to the window handle.


 Window.releaseHandle

Window.releaseHandle

Releases the handle associated with the Window object.

Syntax

public void releaseHandle()

Remarks

Use the releaseHandle method to release the method associated with a Window object. This method does not destroy the handle. Instead, it sets the handle's window procedure to the default window procedure, in effect un-subclassing the window handle. Calling this method sets the handle to zero and calls the onHandleChange method in response to the change in the window handle.

See Also onHandleChange, destroyHandle


 Window.wndProc

Window.wndProc

Specifies the window procedure for the Window object.

Syntax

protected void wndProc( Message m )

Parameters

m

The Message object associated with the current Windows message.

Remarks

This method is invoked when a window message is sent to the window handle. If you are subclassing the Window class, you can override this method to implement specific message processing. The Message object contains the window handle (hWnd), the window message (msg), and the two message parameters (wParam and lParam). The window procedure result is set by modifying the result field in the Message object. The default result is zero. When overriding wndProc, always call super.wndProc for any unhandled messages.

See Also Message


Package com.ms.wfc.core

Provides core component model classes.

Classes

CancelEvent

Represents an event that can be canceled.

ClassInfo

Provides metadata for a component.

Component

Represents the base class for all components.

ComponentInfo

Contains information about a component, including its properties, events, extenders, and attributes.

ComponentManager

Provides design-time information about components.

ConstructorArg

Represents a constructor argument for a class.

Container

Represents a container for components.

Customizer

Implements the customizer of a component.

CustomizerVerb

Represents a verb that can be run by a component's customizer.

Enum

Represents the base enumerator class.

Event

Represents the base class for all events.

EventInfo

Defines an event of a component.

ExtenderInfo

Defines an extender property of a component.

MemberInfo

Represents the base class for property, event, and extender definitions.

PropertyInfo

Defines a property of a component.

ResourceManager

Manages resource data.

ResourceReader

Reads a binary resource file.

ResourceSet

Represents a set of named resource-based properties.

ResourceWriter

Stores resource data to a file.

SubProperty

Represents a subproperty of a property value.

ValueEditor

Represents the base class for value editors.

VerbExecuteEvent

Provides data for the verbExecute event.

WFCException

Represents the WFC base exception class.

WFCInvalidArgumentException

Represents an exception for invalid arguments.

WFCInvalidEnumException

Represents an exception for invalid arguments that are enumerators.

WFCInvalidPropertyValue

Represents an exception for invalid property values.

WFCInvalidStateException

Represents an exception for when the state of an object becomes invalid.

WFCSystemException

Represents an exception for errors in system calls.

WFCWarning

Represents a warning rather than an error.

WFCWin32Exception

Represents an exception for a Win32 error code.

Interfaces

IAttributes

Defines a callback interface for enumerating the attributes of a component.

IClassInfo

Defines the interface for exposing component metadata.

IComponent

Defines the component interface.

IComponentSite

Defines the interface for a component site.

IConstructable

Allows a class to indicate what constructor arguments are needed to create an object of its type.

IContainer

Defines the container interface.

ICustomizer

Defines the interface for a customizer of a component.

IEditorHost

Defines a callback interface that assists a value editor in presenting a user interface.

IEditorSite

Defines a callback interface through which a value editor accesses the owner of the values that are being edited.

IEvents

Defines a callback interface for enumerating the events of a component.

IExtenderProvider

Defines the interface for extending properties to other components in a container.

IExtenders

Defines a callback interface for enumerating the extender properties of a component.

IPersistable

Allows an object to be written to a stream and read from a stream.

IProperties

Defines a callback interface for enumerating the properties of a component.

IRequireBegin

Defines an interface that specifies when a component is usable.

IResourceLoader

Defines an interface for retrieving a resource from a component's namespace.

IResourceManager

Defines an interface for managing resource data.

IResourceReader

Defines an interface for reading a binary resource file.

IResourceSet

Defines an interface for accessing named resource-based properties.

IResourceWriter

Defines an interface for storing resource data to a file.

IValueAccess

Defines a callback interface for retrieving and setting a property value.

IValueEditor

Defines the interface for a value editor.

Delegates

CancelEventHandler

Identifies an event handler method.

EventHandler

Identifies an event handler method.

VerbExecuteEventHandler

Identifies the method that will handle the verbExecute event.

Attributes

The com.ms.wfc.core package provides the following attribute classes:

  • BindableAttribute
  • BrowsableAttribute
  • CategoryAttribute
  • DefaultValueAttribute
  • DescriptionAttribute
  • DispidAttribute
  • HelpAttribute
  • LocalizableAttribute
  • MemberAttribute
  • PersistableAttribute
  • ShowInToolboxAttribute
  • ValueEditorAttribute

For more information about these attributes, see Attribute Classes.

Value Editors

The com.ms.wfc.core package provides the following value editor classes:

  • ArrayEditor
  • BooleanEditor
  • ByteEditor
  • CharacterEditor
  • DoubleEditor
  • FieldsEditor
  • FloatEditor
  • ImmediateStringEditor
  • IntegerEditor
  • LongEditor
  • NonEditableReferenceEditor
  • ReferenceEditor
  • ShortEditor
  • StringEditor
  • StringListEditor

For more information about these editors, see Value Editor Classes.


Attribute Classes (com.ms.wfc.core)

These classes provide attributes that describe a component's properties, events, and extenders.

MemberAttribute
  |
  +--BindableAttribute
  |
  +--BrowsableAttribute
  |
  +--CategoryAttribute
  |
  +--DefaultValueAttribute
  |
  +--DescriptionAttribute
  |
  +--DispidAttribute
  |
  +--HelpAttribute
  |
  +--LocalizableAttribute
  |
  +--PersistableAttribute
  |
  +--ShowInToolboxAttribute
  |
  +--ValueEditorAttribute

package com.ms.wfc.core

MemberAttribute

The abstract base class from which all other attribute classes derive. Attributes are used to create PropertyInfo, EventInfo, ExtenderInfo, and ClassInfo objects, which define a component's members.

BindableAttribute

Specifies whether a property is appropriate to bind data to. A data binder typically makes available only the properties that are marked with BindableAttribute.YES. If the property has no bindable attribute or is marked with BindableAttribute.NO, then it is not appropriate for binding. For information about how WFC supports data binding, see Data Binding in WFC.

BrowsableAttribute

Specifies whether a property, event, or extender can be modified at design time. A visual designer typically displays in a property browser those members that either have no browsable attribute or are marked with BrowsableAttribute.YES. Members that are marked with BrowsableAttribute.NO are not appropriate for design-time editing.

CategoryAttribute

Specifies that a property, event, or extender belongs to certain category. A visual designer can use categories to organize members into groups of similar behavior. The CategoryAttribute class defines the following common categories:

  • CategoryAttribute.Action
  • CategoryAttribute.Appearance
  • CategoryAttribute.Behavior
  • CategoryAttribute.Data
  • CategoryAttribute.DragDrop
  • CategoryAttribute.Focus
  • CategoryAttribute.Key
  • CategoryAttribute.Mouse
  • CategoryAttribute.Position

DefaultValueAttribute

Specifies the default value for a property or extender. A member's default value is typically its initial value. A visual designer can use the default value to reset the member's value. Default values can also be used by a code generator to determine whether code should be generated for the member. A DefaultValueAttribute object can be created for any value, although the following common default values are already defined:

Property Type | Default Value
Boolean-valued properties | DefaultValueAttribute.TRUE DefaultValueAttribute.FALSE
Integer-valued properties | DefaultValueAttribute.ZERO DefaultValueAttribute.ONE DefaultValueAttribute.NEGATIVE_ONE
String-valued properties | DefaultValueAttribute.EMPTY_STRING
Properties that take an array | DefaultValueAttribute.EMPTY_ARRAY
Properties that can take the null value | DefaultValueAttribute.NULL
Properties that take a Color class constant | DefaultValueAttribute.COLOR_WINDOW DefaultValueAttribute.COLOR_CONTROL

DescriptionAttribute

Specifies a description for a property, event, or extender. A visual designer can display the specified description when referencing the component member, such as in a property browser.

DispidAttribute

Specifies a DISPID for a property. A DISPID is a dispatch identifier that is used by OLE when a WFC control is exposed as an ActiveX control. Typically, you do not need to specify this attribute because the values for most DISPIDs are arbitrary. Although ActiveX controls do define a small list of specific DISPIDs for common properties, WFC handles most of these for you.

HelpAttribute

Specifies a help file and help topic for a property, extender, or event. A visual designer can use the specified information to provide help about the member.

LocalizableAttribute

Specifies whether a property or extender should be localized. When code is generated for a component, members that are marked with LocalizableAttribute.YES should be localized for the different language versions of the component. Members that have no localizable attribute or are marked with LocalizableAttribute.NO are not localized.

PersistableAttribute

Specifies whether a property or extender should be examined when generating code. If the member is marked with PersistableAttribute.NO, the component's code generator will not generate code for this member. If the member has no persistable attribute or is marked with PersistableAttribute.YES, the code generator will examine the member to determine whether code should be generated.

ShowInToolboxAttribute

Specifies a component's visibility in a toolbox. If a component is marked with ShowInToolboxAttribute.YES in its ClassInfo, a visual designer can show the component in a toolbox and display it on a form, either natively or through a wrapper. Components that have no visibility attribute or are marked with ShowInToolboxAttribute.NO are not displayed in a toolbox.

Note Any component whose ClassInfo extends com.ms.wfc.core.Component.ClassInfo automatically inherits the ShowInToolboxAttribute.YES attribute.

ValueEditorAttribute

Specifies a value editor for a property or extender. When editing the property or extender, a visual designer should instantiate the specified value editor and not use the default editor for the member's type.


Value Editor Classes (com.ms.wfc.core)

These classes provide editors for property values of a given type. Value editors are used within a property browser to modify property values at design time.

ValueEditor
  |
  +--ArrayEditor
  |
  +--BooleanEditor
  |
  +--ByteEditor
  |
  +--CharacterEditor
  |
  +--DoubleEditor
  |
  +--FieldsEditor
  |
  +--FloatEditor
  |
  +--ImmediateStringEditor
  |
  +--LongEditor
  |
  +--ReferenceEditor
  |    |
  |    +--NonEditableReferenceEditor
  |
  +--ShortEditor
  |
  +--StringEditor
  |
  +--StringListEditor

package com.ms.wfc.core

ArrayEditor

Supports property values that are arrays, providing a dialog box to visually add, remove, and sort arrays. This class allows editing of values but does not convert text into values.

BooleanEditor

Supports property values of type boolean. This class can translate to and from textual representations.

ByteEditor

Supports property values of type byte. This class can translate to and from textual representations.

CharacterEditor

Supports property values of type char. This class can translate to and from textual representations.

DoubleEditor

Supports property values of type double. This class can translate to and from textual representations.

FieldsEditor

Supports property values that are the fields of a class. This class enumerates possible values by finding the public static final fields in a class that match the property type. The value editor for the Enum class extends FieldsEditor.

FloatEditor

Supports property values of type float. This class can translate to and from textual representations.

ImmediateStringEditor

Supports string property values that can be updated with each keystroke.

IntegerEditor

Supports property values of type int. This class can translate to and from textual representations.

LongEditor

Supports property values of type long. This class can translate to and from textual representations.

NonEditableReferenceEditor

Supports property values that reference the names of components, and prevents these names from being changed. This class extends ReferenceEditor.

ReferenceEditor

Supports property values that reference other components. This class enumerates possible values by querying the container of the hosting component for all components that implement the property type.

ShortEditor

Supports property values of type short. This class can translate to and from textual representations.

StringEditor

Supports property values that are strings.

StringListEditor

Supports property values that are arrays of strings, providing a dialog box to visually edit the array.


CancelEvent Class

Represents an event that can be canceled.

Event
  |
  +--CancelEvent

package com.ms.wfc.core

public class CancelEvent
extends Event

Remarks

To cancel the event, set the cancel field to true. For information about the WFC event model, see Handling Events in WFC.


 CancelEvent Methods

CancelEvent Methods

Constructors | Description
CancelEvent | Creates a CancelEvent object.


 CancelEvent.CancelEvent

CancelEvent.CancelEvent

Creates a CancelEvent object.

Syntax

public CancelEvent()

public CancelEvent( boolean cancel )

Parameters

cancel

The default value of the cancel flag. Set to true to cancel the event; otherwise, set to false. (If no value is specified, this flag is set to false.)


 CancelEvent Fields

CancelEvent Fields

Fields | Description
cancel | Indicates whether the event will be canceled.


 CancelEvent.cancel

CancelEvent.cancel

Indicates whether the event will be canceled.

Syntax

public boolean cancel;

Remarks

Set this field to true to cancel the event.


CancelEventHandler Delegate

Identifies an event handler method.

package com.ms.wfc.core

public multicast delegate
void CancelEventHandler( Object sender, CancelEvent e );

Remarks

The syntax of the CancelEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a CancelEvent object that provides the event data.

When you create a CancelEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC.


ClassInfo Class

Provides metadata for a component.

package com.ms.wfc.core

public class ClassInfo
implements IClassInfo

Remarks

ClassInfo provides design-time information about a component class, including the component's properties, events, and attributes. This information is then available to be browsed at run time, such as in the Properties window of the Forms Designer.

To use ClassInfo, a component class provides a public static inner class named ClassInfo, which typically extends the ClassInfo of the component class's superclass. This allows the component to inherit the metadata of the superclass.

Note Although a ClassInfo is not required to extend the superclass's ClassInfo, it must implement the IClassInfo interface.

The following example shows a portion of the ClassInfo of the Edit control:

public class Edit extends Control
{
   ...  // Members of class Edit.

   public static class ClassInfo extends Control.ClassInfo
   {
      // Define the properties.
      public static final PropertyInfo autoSize = new PropertyInfo(
         Edit.class, "autoSize", Boolean.TYPE,
         CategoryAttribute.Behavior,
         DefaultValueAttribute.TRUE,
         new DescriptionAttribute("Enables automatic resizing."));

      public static final PropertyInfo backColor = new PropertyInfo(
         com.ms.wfc.ui.Control.ClassInfo.backColor,
         DefaultValueAttribute.COLOR_WINDOW);

      // Define the events.
      public static final EventInfo textChanged = new EventInfo(
         Edit.class,"textChanged", EventHandler.class,
         CategoryAttribute.Behavior,
         new DescriptionAttribute("Occurs when the text property of this control changes."));

      // Specify the default event.
      public String getDefaultEventName() {
         return "textChanged";

      }

      // Add the properties.
      public void getProperties(IProperties props) {
         super.getProperties(props);
         props.add(autoSize);
         props.add(backColor);
      }

      // Add the events.
      public void getEvents(IEvents events) {
         super.getEvents(events);
         events.add(textChanged);
      }
   }
}

See Also ComponentInfo


 ClassInfo Methods

ClassInfo Methods

Methods | Description
getAttributes | Specifies the attributes of the component class.
getCustomizer | Retrieves the customizer of the specified component.
getDefaultEventName | Retrieves the name of the default event of the component class.
getDefaultPropertyName | Retrieves the name of the default property of the component class.
getEvents | Specifies the events of the component class.
getExtenders | Specifies the extender properties of the component class.
getProperties | Specifies the properties of the component class.
getToolboxBitmap | Retrieves the image that is used to represent the component in toolboxes, list views, and so on.


 ClassInfo.getAttributes

ClassInfo.getAttributes

Specifies the attributes of the component class.

Syntax

public void getAttributes( IAttributes attributes )

Parameters

attributes

An object implementing the IAtttibutes interface that is used to enumerate the attributes.

Remarks

For each attribute, getAttributes calls the add method of the attributes parameter. The following example shows a portion of the ClassInfo of the Control class:

public static class ClassInfo extends Component.ClassInfo {

   public void getAttributes(IAttributes attribs) {
      super.getAttributes(attribs);

      // Specify that the control should be displayed in the toolbox.
      attribs.add(ShowInToolboxAttribute.YES);
   }
}


 ClassInfo.getCustomizer

ClassInfo.getCustomizer

Retrieves the customizer of the specified component.

Syntax

public ICustomizer getCustomizer( Object component )

Parameters

component

The object to retrieve the customizer for. This parameter must be an instance of either the component class or one of its subclasses.

Return Value

Returns an object implementing the ICustomizer interface. If the component does not support a customizer, null is returned.

Remarks

A customizer provides the ability to create a set of design pages for a component, to edit the component, and to execute its design-time verbs.


 ClassInfo.getDefaultEventName

ClassInfo.getDefaultEventName

Retrieves the name of the default event of the component class.

Syntax

public String getDefaultEventName()

Return Value

Returns the default event name. If the component class has no default event, null is returned. For more information, see IClassInfo.getDefaultEventName.


 ClassInfo.getDefaultPropertyName

ClassInfo.getDefaultPropertyName

Retrieves the name of the default property of the component class.

Syntax

public String getDefaultPropertyName()

Return Value

Returns the default property name. If the component class has no property event, null is returned. For more information, see IClassInfo.getDefaultPropertyName.


 ClassInfo.getEvents

ClassInfo.getEvents

Specifies the events of the component class.

Syntax

public void getEvents( IEvents events )

Parameters

events

An object implementing the IEvents interface that is used to enumerate the events.

Remarks

For each event, getEvents calls the add method of the events parameter. For a sample implementation, see the ClassInfo overview.


 ClassInfo.getExtenders

ClassInfo.getExtenders

Specifies the extender properties of the component class.

Syntax

public void getExtenders( IExtenders extenders )

Parameters

extenders

An object implementing the IExtenders interface that is used to enumerate the extenders.

Remarks

For each extender property, getExtenders calls the add method of the extenders parameter. The following example shows a portion of the ClassInfo of the HelpProvider class:

public static class ClassInfo extends Component.ClassInfo {

   public static final ExtenderInfo helpTopic = new ExtenderInfo(HelpProvider.class,
      "helpTopic", Control.class, String.class,
      DefaultValueAttribute.NULL,
      LocalizableAttribute.YES,
      new DescriptionAttribute("The help topic."));

   public static final ExtenderInfo helpString = new ExtenderInfo(HelpProvider.class,
      "helpString", Control.class, String.class,
      DefaultValueAttribute.NULL,
      LocalizableAttribute.YES,
      new DescriptionAttribute("The help string."));

   public void getExtenders(IExtenders iexts) {
      super.getExtenders(iexts);
      iexts.add(helpTopic);
      iexts.add(helpString);
   }
 }


 ClassInfo.getProperties

ClassInfo.getProperties

Specifies the properties of the component class.

Syntax

public void getProperties( IProperties props )

Parameters

props

An object implementing the IProperties interface that is used to enumerate the properties.

Remarks

For each property, getProperties calls the add method of the props parameter. For a sample implementation, see the ClassInfo overview.


 ClassInfo.getToolboxBitmap

ClassInfo.getToolboxBitmap

Retrieves the image that is used to represent the component in toolboxes, list views, and so on.

Syntax

public Bitmap getToolboxBitmap()

Return Value

Returns a Bitmap object that represents the image. If no bitmap is found, null is returned.

Remarks

This method searches for the bitmap in the same directory as the component class. The name of the bitmap must be the same as the name of the component class.


Component Class

Represents the base class for all components.

package com.ms.wfc.core

public class Component
implements IComponent , IResourceLoader

Remarks

A component can be hosted in a container. For each component in a container, the container creates a site that it uses to manage the component.

For components that are also controls, WFC defines the com.ms.wfc.ui.Control class, which extends Component. Each WFC control extends Control.

See Also IContainer, IComponentSite


 Component Methods

Component Methods

Constructors | Description
Component | Creates a Component object.

Methods | Description
addOnDispose | Assigns a delegate to the dispose event.
componentChanged | Specifies that the component has changed.
dispose | Disposes of the component.
getChildOf | Determines whether this component is a child of the specified component.
getComponentSite | Retrieves the site of the component.
getContainer | Returns the component's container.
getDesignMode | Determines whether the component is currently in design mode.
getDisposing | Determines whether the component is currently being disposed of.
getName | Retrieves the name of the component that is maintained by the site.
getResource | Retrieves a named resource.
getService | Retrieves a service provided by the site.
onDispose | Triggers the dispose event.
removeOnDispose | Removes the delegate that is assigned to the dispose event.
setComponentSite | Sets the site of the component.
setName | Sets the name of the component that is maintained by the site.


 Component.addOnDispose

Component.addOnDispose

Assigns a delegate to the dispose event.

Syntax

public void addOnDispose( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

The dispose event occurs when the component is disposed of through the dispose method. Components that maintain references to other components must register dispose event handlers for the referenced components so that the references can be cleared when the components are disposed of.

See Also removeOnDispose


 Component.Component

Component.Component

Creates a Component object.

Syntax

public Component()


 Component.componentChanged

Component.componentChanged

Specifies that the component has changed.

Syntax

public synchronized void componentChanged()

Remarks

A component's customizer should call this method when it changes a property of the component; this ensures a property browser will display the updated property.


 Component.dispose

Component.dispose

Disposes of the component.

Syntax

public synchronized void dispose()

Remarks

Call dispose when the component is no longer needed. This method removes the component from its container (if the component has a site) and triggers the dispose event.

See Also IComponent.dispose


 Component.getChildOf

Component.getChildOf

Determines whether this component is a child of the specified component.

Syntax

public boolean getChildOf( IComponent component )

Parameters

component

The parent component.

Return Value

Returns true if this component is a child of component; otherwise, returns false.

See Also IComponent.getChildOf


 Component.getComponentSite

Component.getComponentSite

Retrieves the site of the component.

Syntax

public IComponentSite getComponentSite()

Return Value

Returns an object implementing the IComponentSite interface that represents the component's site.

See Also setComponentSite


 Component.getContainer

Component.getContainer

Returns the component's container.

Syntax

public synchronized IContainer getContainer()

Return Value

Returns an object implementing the IContainer interface that represents the component's container. If the component does not have a site, null is returned.


 Component.getDesignMode

Component.getDesignMode

Determines whether the component is currently in design mode.

Syntax

public synchronized boolean getDesignMode()

Return Value

Returns true if the component is in design mode; otherwise, returns false. (If the component does not have a site, this method always returns false.)


 Component.getDisposing

Component.getDisposing

Determines whether the component is currently being disposed of.

Syntax

public synchronized boolean getDisposing()

Return Value

Returns true if the component is being disposed of; otherwise, returns false.

See Also dispose


 Component.getName

Component.getName

Retrieves the name of the component that is maintained by the site.

Syntax

public synchronized String getName()

Return Value

Returns the component name held by the component's site. If the component does not have a site, null is returned.

See Also setName


 Component.getResource

Component.getResource

Retrieves a named resource.

Syntax

public IDataStream getResource( String name )

Parameters

name

The name of the resource to be retrieved.

Return Value

Returns an object implementing the IDataStream interface that contains the resource. If no resource with the specified name is found, null is returned.


 Component.getService

Component.getService

Retrieves a service provided by the site.

Syntax

public synchronized Object getService( Class service )

Parameters

service

An interface that represents the service.

Return Value

Returns an object that implements the specified interface. If the site does not support this service, or if the component does not have a site, null is returned.


 Component.onDispose

Component.onDispose

Triggers the dispose event.

Syntax

protected void onDispose( Event e )

Parameters

e

An Event object.

Remarks

The dispose event occurs when the component is disposed of through the dispose method.

When overriding onDispose, be sure to call super.onDispose.

See Also addOnDispose, removeOnDispose


 Component.removeOnDispose

Component.removeOnDispose

Removes the delegate that is assigned to the dispose event.

Syntax

public void removeOnDispose( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnDispose


 Component.setComponentSite

Component.setComponentSite

Sets the site of the component.

Syntax

public void setComponentSite( IComponentSite value )

Parameters

value

An object implementing the IComponentSite interface that represents the component's site. A non-null value indicates that the component has been added to a container; a null value indicates that the component is being removed from a container.

See Also getComponentSite


 Component.setName

Component.setName

Sets the name of the component that is maintained by the site.

Syntax

public synchronized void setName( String value )

Parameters

value

The component name held by the component's site.

Exceptions

WFCException thrown if the component does not have a site.

See Also getName


ComponentInfo Class

Contains information about a component, including its properties, events, extenders, and attributes.

package com.ms.wfc.core

public final class ComponentInfo

Remarks

An instance of ComponentInfo can be obtained through the ComponentManager class.


 ComponentInfo Methods

ComponentInfo Methods

Methods | Description
getAttributes | Retrieves the attributes that were specified in the component's ClassInfo.
getClassInfo | Retrieves the ClassInfo of the component.
getComponentClass | Retrieves the class type of the component.
getDefaultEventInfo | Retrieves the default event of the component.
getDefaultEventName | Retrieves the name of the default event of the component.
getDefaultPropertyInfo | Retrieves the default property of the component.
getDefaultPropertyName | Retrieves the name of the default property of the component.
getEvents | Retrieves the events that were specified in the component's ClassInfo.
getExtenders | Retrieves the extenders that were specified in the component's ClassInfo.
getProperties | Retrieves the properties that were specified in the component's ClassInfo.


 ComponentInfo.getAttributes

ComponentInfo.getAttributes

Retrieves the attributes that were specified in the component's ClassInfo.

Syntax

public MemberAttribute[] getAttributes()

public MemberAttribute[] getAttributes( MemberAttribute[] attributes )

Parameters

attributes

An array of MemberAttribute objects that specify which attributes should be retrieved.

Return Value

Returns an array of MemberAttribute objects. If no parameter was passed to getAttributes, all attributes specified in the component's ClassInfo are returned; otherwise, getAttributes returns only those attributes that satisfy the items in the attributes array. (An item in the attributes array is satisfied if it specifies an attribute in the component's ClassInfo or represents the default attribute for that type if the attribute is not specified in the ClassInfo.)

See Also IClassInfo


 ComponentInfo.getClassInfo

ComponentInfo.getClassInfo

Retrieves the ClassInfo of the component.

Syntax

public IClassInfo getClassInfo()

Return Value

Returns an object implementing the IClassInfo interface that represents the component's ClassInfo inner class.


 ComponentInfo.getComponentClass

ComponentInfo.getComponentClass

Retrieves the class type of the component.

Syntax

public Class getComponentClass()

Return Value

Returns the component's type.


 ComponentInfo.getDefaultEventInfo

ComponentInfo.getDefaultEventInfo

Retrieves the default event of the component.

Syntax

public EventInfo getDefaultEventInfo()

Return Value

Returns an EventInfo object that represents the default event. If no default event is defined, null is returned.

Remarks

The name of the default event is specified in the component's ClassInfo. For more information, see IClassInfo.getDefaultEventName.

See Also getDefaultEventName


 ComponentInfo.getDefaultEventName

ComponentInfo.getDefaultEventName

Retrieves the name of the default event of the component.

Syntax

public String getDefaultEventName()

Return Value

Returns the default event name. If no default event is defined, null is returned.

Remarks

The name of the default event is specified in the component's ClassInfo. For more information, see IClassInfo.getDefaultEventName.

See Also getDefaultEventInfo


 ComponentInfo.getDefaultPropertyInfo

ComponentInfo.getDefaultPropertyInfo

Retrieves the default property of the component.

Syntax

public String getDefaultPropertyInfo()

Return Value

Returns a PropertyInfo object that represents the default property. If no default property is defined, null is returned.

Remarks

The name of the default property is specified in the component's ClassInfo. For more information, see IClassInfo.getDefaultPropertyName.

See Also getDefaultPropertyName


 ComponentInfo.getDefaultPropertyName

ComponentInfo.getDefaultPropertyName

Retrieves the name of the default property of the component.

Syntax

public String getDefaultPropertyName()

Return Value

Returns the default property name. If no default event is defined, null is returned.

Remarks

The name of the default property is specified in the component's ClassInfo. For more information, see IClassInfo.getDefaultPropertyName.

See Also getDefaultPropertyInfo


 ComponentInfo.getEvents

ComponentInfo.getEvents

Retrieves the events that were specified in the component's ClassInfo.

Syntax

public EventInfo[] getEvents()

public EventInfo[] getEvents( MemberAttribute[] attributes )

Parameters

attributes

An array of MemberAttribute objects that specify which events should be retrieved.

Return Value

Returns an array of EventInfo objects. If no parameter was passed to getEvents, all events specified in the component's ClassInfo are returned; otherwise, getEvents returns only those events whose attributes satisfy the items in the attributes array. (An item in the attributes array is satisfied if it specifies an attribute in an event's EventInfo or represents the default attribute for that type if the attribute is not specified in the EventInfo.)

See Also IClassInfo


 ComponentInfo.getExtenders

ComponentInfo.getExtenders

Retrieves the extenders that were specified in the component's ClassInfo.

Syntax

public ExtenderInfo[] getExtenders()

public ExtenderInfo[] getExtenders( MemberAttribute[] attributes )

Parameters

attributes

An array of MemberAttribute objects that specify which extenders should be retrieved.

Return Value

Returns an array of ExtenderInfo objects. If no parameter was passed to getExtenders, all extenders specified in the component's ClassInfo are returned; otherwise, getExtenders returns only those extenders whose attributes satisfy the items in the attributes array. (An item in the attributes array is satisfied if it specifies an attribute in an extender's ExtenderInfo or represents the default attribute for that type if the attribute is not specified in the ExtenderInfo.)

See Also IClassInfo


 ComponentInfo.getProperties

ComponentInfo.getProperties

Retrieves the properties that were specified in the component's ClassInfo.

Syntax

public PropertyInfo[] getProperties()

public PropertyInfo[] getProperties( MemberAttribute[] attributes )

Parameters

attributes

An array of MemberAttribute objects that specify which properties should be retrieved.

Return Value

Returns an array of PropertyInfo objects. If no parameter was passed to getProperties, all properties specified in the component's ClassInfo are returned; otherwise, getProperties returns only those properties whose attributes satisfy the items in the attributes array. (An item in the attributes array is satisfied if it specifies an attribute in a property's PropertyInfo or represents the default attribute for that type if the attribute is not specified in the PropertyInfo.)

See Also IClassInfo


ComponentManager Class

Provides design-time information about components.

package com.ms.wfc.core

public final class ComponentManager

Remarks

A visual designer can use the ComponentManager class to determine the properties and events that a component supports. For example, the getComponentInfo method uses the component's ClassInfo class to create a ComponentInfo object. This instance of ComponentInfo can then be used to retrieve all properties, events, extenders, and attributes of the component.

The ComponentManager class is also used to get value editors for the component. A value editor allows property values to be edited in a property browser.

See Also IValueEditor


 ComponentManager Methods

ComponentManager Methods

Methods | Description
classForName | Loads the specified class.
createClassInfo | Creates an instance of a ClassInfo class.
getComponentInfo | Retrieves an instance of ComponentInfo for the specified class.
getValueEditor | Retrieves a value editor for the specified data type.
registerClassInfo | Registers a ClassInfo class for the specified component.
registerValueEditorClass | Registers a value editor for the specified data type.


 ComponentManager.classForName

ComponentManager.classForName

Loads the specified class.

Syntax

public static Class classForName( Class cls, String name )

Parameters

cls

A class that was loaded with the same namespace as the class you want to load.

name

The name of the class to be loaded.

Return Value

Returns a java.lang.Class object for the specified class name.

Exceptions

java.lang.ClassNotFoundException thrown if the class could not be loaded.

Remarks

This method loads the class using the class loader of cls. Use this method instead of java.lang.Class.forName to ensure that the correct class loader is used.


 ComponentManager.createClassInfo

ComponentManager.createClassInfo

Creates an instance of a ClassInfo class.

Syntax

public static IClassInfo createClassInfo( Class classInfoClass )

Parameters

classInfoClass

The ClassInfo class to be instantiated. (This class must implement the IClassInfo interface.)

Exceptions

java.lang.InstantiationException thrown if the ClassInfo class could not be created.

java.lang.IllegalAccessException thrown if you do not have permission to create the ClassInfo class.

Return Value

Returns an instance of classInfoClass.


 ComponentManager.getComponentInfo

ComponentManager.getComponentInfo

Retrieves an instance of ComponentInfo for the specified class.

Syntax

public static synchronized ComponentInfo getComponentInfo( Class componentClass )

public static synchronized ComponentInfo getComponentInfo( Class componentClass, boolean throwExceptions )

Parameters

componentClass

The class of the component to retrieve the component information for.

throwExceptions

Set to true to throw an exception if an instance of ComponentInfo could not be created. Set to false to catch the exception and return null. The default value is false.

Exceptions

WFCException thrown if the ComponentInfo object could not be created and throwExceptions is true.

Return Value

Returns an instance of the ComponentInfo class for the component.

Remarks

This method uses the component's ClassInfo class to create the ComponentInfo object. This instance of ComponentInfo can be used to retrieve all properties, events, extenders, and attributes of the component.


 ComponentManager.getValueEditor

ComponentManager.getValueEditor

Retrieves a value editor for the specified data type.

Syntax

public static synchronized IValueEditor getValueEditor( Class type )

public static synchronized IValueEditor getValueEditor( Class type, IEditorSite site )

public static synchronized IValueEditor getValueEditor( Class type, IEditorSite site, boolean throwExceptions )

Parameters

type

The class of the data type to retrieve the value editor for.

site

An object implementing the IEditorSite interface that represents the value editor's site. If no site is needed, pass null for this parameter.

throwExceptions

Set to true to throw an exception if a value editor exists but could not be created. Set to false to catch the exception and return null. The default value is false.

Return Value

Returns an object implementing the IValueEditor interface that represents the value editor. If no value editor exists for the specified type, null is returned.

Exceptions

WFCException thrown if the value editor could not be created and throwExceptions is true.


 ComponentManager.registerClassInfo

ComponentManager.registerClassInfo

Registers a ClassInfo class for the specified component.

Syntax

public static void registerClassInfo( Class componentClass, Class classInfo )

Parameters

componentClass

The class of the component to register the ClassInfo for.

classInfo

The ClassInfo class to be associated with componentClass.

Remarks

To find a ClassInfo for a given component, WFC typically looks for an inner class named ClassInfo. However, if a component class cannot define an inner class, the registerClassInfo method can be used to create a custom mapping between the component and a ClassInfo class.

See Also IClassInfo


 ComponentManager.registerValueEditorClass

ComponentManager.registerValueEditorClass

Registers a value editor for the specified data type.

Syntax

public static void registerValueEditorClass( Class type, Class valueEditorClass )

Parameters

type

The class of the data type to register the value editor for.

valueEditorClass

The class of the value editor to be associated with type.

Remarks

To find a value editor for a given class type, WFC typically looks for an inner class named Editor. However, if a class cannot define an inner class, the registerValueEditorClass method can be used to create a custom mapping between the class type and a value editor class. For example, WFC uses this method to register editors for the primitive types.

See Also IValueEditor


ConstructorArg Class

Represents a constructor argument for a class.

package com.ms.wfc.core

public class ConstructorArg

Remarks

This class is primarily used to persist an object at design time. The IConstructable.getContructorArgs method returns an array of ConstructorArg objects that represent the constructor arguments needed to create the object. By implementing IConstructable, a class can participate in code generation.

The following example shows a Point class that implements IConstructable:

public class Point implements IConstructable
{
   public int x;  // The horizontal position of the point.
   public int y;  // The vertical position of the point.

   public Point(int x, int y)
   {
      this.x = x;
      this.y = y;
   }

   public ConstructorArg[] getConstructorArgs()
   {
      return new ConstructorArg[] {
         new ConstructorArg(new Integer(x), Integer.TYPE),
         new ConstructorArg(new Integer(y), Integer.TYPE)
      };
   }

   ...  // Remaining class implementation.
}


 ConstructorArg Methods

ConstructorArg Methods

Constructors | Description
ConstructorArg | Creates a ConstructorArg object.

Methods | Description
getType | Retrieves the type of the ConstrutorArg object.
getValue | Retrieves the value of the ConstrutorArg object.


 ConstructorArg.ConstructorArg

ConstructorArg.ConstructorArg

Creates a ConstructorArg object.

Syntax

public ConstructorArg( Object value, Class type )

Parameters

value

The value of the argument expressed as a class object.

type

The class type of the argument.

Remarks

For a simple example that shows how the ConstructorArg class is used, see the ConstructorArg overview.


 ConstructorArg.getType

ConstructorArg.getType

Retrieves the type of the ConstrutorArg object.

Syntax

public Class getType()

Return Value

Returns the class type of this object.

Remarks

For a simple example that shows how the ConstructorArg class is used, see the ConstructorArg overview.


 ConstructorArg.getValue

ConstructorArg.getValue

Retrieves the value of the ConstrutorArg object.

Syntax

public Object getValue()

Return Value

Returns the value of this object.

Remarks

For a simple example that shows how the ConstructorArg class is used, see the ConstructorArg overview.


Container Class

Represents a container for components.

package com.ms.wfc.core

public class Container
implements IContainer

Remarks

A container represents a logical containment of components, rather than a physical containment. For each component that is added to a container, the container creates a site that it uses to manage the component. The container is responsible for the lifetime of its components.

See Also Component, IComponentSite


 Container Methods

Container Methods

Constructors | Description
Container | Creates a Container object.

Methods | Description
add | Adds a component to the container.
dispose | Removes and disposes of all components in the container.
getComponent | Retrieves a component in the container.
getComponents | Retrieves all components in the container.
remove | Removes a component from the container.


 Container.add

Container.add

Adds a component to the container.

Syntax

public void add( IComponent component )

public void add( IComponent component, String name )

Parameters

component

The component to be added.

name

The name to be associated with the component.

Remarks

This method creates the site that associates the component with the container.

See Also remove


 Container.Container

Container.Container

Creates a Container object.

Syntax

public Container()


 Container.dispose

Container.dispose

Removes and disposes of all components in the container.

Syntax

public synchronized void dispose()

See Also remove


 Container.getComponent

Container.getComponent

Retrieves a component in the container.

Syntax

public synchronized IComponent getComponent( String name )

Parameters

name

The name associated with the component to be retrieved.

Return Value

Returns an object implementing the IComponent interface that represents the specified component. If no component has the specified name, null is returned.

See Also getComponents


 Container.getComponents

Container.getComponents

Retrieves all components in the container.

Syntax

public synchronized IComponent[] getComponents()

Return Value

Returns an array of objects implementing the IComponent interface that represent all components in the container.

See Also getComponent


 Container.remove

Container.remove

Removes a component from the container.

Syntax

public synchronized void remove( IComponent component )

Parameters

component

The component to be removed.

Remarks

This method sets the component's site to null.

See Also add, IComponent.setComponentSite


Customizer Class

Implements the customizer of a component.

package com.ms.wfc.core

public class Customizer
implements ICustomizer

Remarks

This class provides a base implementation of the ICustomizer interface. A customizer creates a set of design pages for a component, determines its design-time verbs, and executes those verbs.

Note A design page is the WFC equivalent of an OLE property page. When possible, you should use a value editor instead of a design page to provide a more seamless user interface through the property browser.

See Also IValueEditor


 Customizer Methods

Customizer Methods

Methods | Description
getDesignPages | Retrieves an array of classes for each design page used by the component.
getHitTest | Determines whether the specified point is active.
getVerbs | Returns the design-time verbs supported by the associated component.


 Customizer.getDesignPages

Customizer.getDesignPages

Retrieves an array of classes for each design page used by the component.

Syntax

public Class [] getDesignPages()

Return Value

Returns null by default.

Remarks

Override this method to return the component's design pages. A design page is the WFC equivalent of an OLE property page.


 Customizer.getHitTest

Customizer.getHitTest

Determines whether the specified point is active.

Syntax

public boolean getHitTest( Point point )

Parameters

point

A Point object that represents a point relative to the upper-left corner of the component.

Return Value

Returns false by default.

Remarks

Override this method to allow the component to support a design-time user interface. When getHitTest returns true, mouse messages at the specified point can be passed to the component.


 Customizer.getVerbs

Customizer.getVerbs

Returns the design-time verbs supported by the associated component.

Syntax

public CustomizerVerb[] getVerbs()

Return Value

Returns null by default.

Remarks

Override this method to return the component's verbs. For more information, see ICustomizer.getVerbs.


CustomizerVerb Class

Represents a verb that can be run by a component's customizer.

package com.ms.wfc.core

public class CustomizerVerb

Remarks

A verb is command that a customizer can execute on a given component. Typically, verbs are implemented in the designer through a shortcut menu that appears when the user right-clicks the component. When the user selects the verb on the shortcut menu, the verbExecute event occurs. This event allows the customizer to add functionality to the designer.

See Also ICustomizer


 CustomizerVerb Methods

CustomizerVerb Methods

Constructors | Description
CustomizerVerb | Creates a CustomizerVerb object.

Methods | Description
addOnVerbExecute | Assigns a delegate to the verbExecute event.
getBitmap | Retrieves the picture associated with the verb.
getChecked | Retrieves the checked state of the verb on the shortcut menu.
getData | Retrieves the data associated with the verb.
getEnabled | Retrieves the enabled state of the verb on the shortcut menu.
getText | Retrieves the menu item text associated with the verb.
onVerbExecute | Triggers the verbExecute event.
performVerbExecute | Generates a verbExecute event.
removeOnVerbExecute | Removes the delegate assigned to the verbExecute event.
setBitmap | Sets the picture associated with the verb.
setChecked | Sets the checked state of the verb on the shortcut menu.
setData | Sets the enabled state of the verb on the shortcut menu.
setEnabled | Sets the enabled state of the verb on the shortcut menu.


 CustomizerVerb.addOnVerbExecute

CustomizerVerb.addOnVerbExecute

Assigns a delegate to the verbExecute event.

Syntax

public final void addOnVerbExecute( VerbExecuteEventHandler handler )

Parameters

handler

The VerbExecuteEventHandler delegate to be notified when the event occurs.

Remarks

The verbExecute event occurs when the user selects the verb on the component's shortcut menu.

See Also removeOnVerbExecute


 CustomizerVerb.CustomizerVerb

CustomizerVerb.CustomizerVerb

Creates a CustomizerVerb object.

Syntax

public CustomizerVerb( Object data, VerbExecuteEventHandler handler )

public CustomizerVerb( Object data, VerbExecuteEventHandler handler, Bitmap bitmap, boolean enabled, boolean checked )

Parameters

data

The user-defined data to be associated with the verb.

handler

The VerbExecuteEventHandler delegate to be notified when the verbExecute event occurs.

bitmap

A Bitmap object that represents the picture to be associated with the verb.

enabled

Set to true if the verb should appear enabled on the shortcut menu; otherwise, set to false.

checked

Set to true if the verb should appear checked on the shortcut menu; otherwise, set to false.

Remarks

Verbs are typically implemented in the designer through a shortcut menu that appears when the user right-clicks the component. The text of the menu item for the verb is determined by calling the toString method of data. When the user selects a verb on the shortcut menu, the verbExecute event is triggered and the event handler associated with handler is invoked.


 CustomizerVerb.getBitmap

CustomizerVerb.getBitmap

Retrieves the picture associated with the verb.

Syntax

public final Bitmap getBitmap()

Return Value

Returns a Bitmap object that represents the verb's picture. A visual designer may or may not use this picture.

See Also setBitmap


 CustomizerVerb.getChecked

CustomizerVerb.getChecked

Retrieves the checked state of the verb on the shortcut menu.

Syntax

public final boolean getChecked()

Return Value

Returns true if the verb appears checked; otherwise, returns false.

See Also setChecked


 CustomizerVerb.getData

CustomizerVerb.getData

Retrieves the data associated with the verb.

Syntax

public final Object getData()

Return Value

Returns an object that specifies the verb's data. This data is used to determine the menu item text for the verb.

See Also setData, getText


 CustomizerVerb.getEnabled

CustomizerVerb.getEnabled

Retrieves the enabled state of the verb on the shortcut menu.

Syntax

public final boolean getEnabled()

Return Value

Returns true if the verb is enabled; otherwise, returns false.

See Also setEnabled


 CustomizerVerb.getText

CustomizerVerb.getText

Retrieves the menu item text associated with the verb.

Syntax

public String getText()

Return Value

Returns the menu item text, which is determined by calling toString on the verb's data. If the verb has no associated data, this method returns null.

See Also getData


 CustomizerVerb.onVerbExecute

CustomizerVerb.onVerbExecute

Triggers the verbExecute event.

Syntax

protected void onVerbExecute( VerbExecuteEvent event )

Parameters

event

A VerbExecuteEvent object that provides the event data.

Remarks

The verbExecute event occurs when the user selects the verb on the component's shortcut menu.

When overriding onVerbExecute, be sure to call super.onVerbExecute.

See Also performVerbExecute, addOnVerbExecute, removeOnVerbExecute


 CustomizerVerb.performVerbExecute

CustomizerVerb.performVerbExecute

Generates a verbExecute event.

Syntax

public final void performVerbExecute()

Remarks

The verbExecute event occurs when the user selects the verb on the component's shortcut menu. The performVerbExecute method can be called to force the event to occur.

See Also addOnVerbExecute


 CustomizerVerb.removeOnVerbExecute

CustomizerVerb.removeOnVerbExecute

Removes the delegate assigned to the verbExecute event.

Syntax

public final void removeOnVerbExecute( VerbExecuteEventHandler handler )

Parameters

handler

The VerbExecuteEventHandler delegate to be removed.

See Also addOnVerbExecute


 CustomizerVerb.setBitmap

CustomizerVerb.setBitmap

Sets the picture associated with the verb.

Syntax

public final void setBitmap( Bitmap bitmap )

Parameters

bitmap

A Bitmap object that represents the verb's picture.

See Also getBitmap


 CustomizerVerb.setChecked

CustomizerVerb.setChecked

Sets the checked state of the verb on the shortcut menu.

Syntax

public final void setChecked( boolean value )

Parameters

value

Set to true for the verb to appear checked; otherwise, set to false.

See Also getChecked


 CustomizerVerb.setData

CustomizerVerb.setData

Sets the enabled state of the verb on the shortcut menu.

Syntax

public final void setData( Object data )

Parameters

data

An object that specifies the verb's data. This data is used to determine the menu item text for the verb.

See Also getData, getText


 CustomizerVerb.setEnabled

CustomizerVerb.setEnabled

Sets the enabled state of the verb on the shortcut menu.

Syntax

public final void setEnabled( boolean value )

Parameters

value

Set to true for the verb to appear enabled; otherwise, set to false.

See Also getEnabled


Enum Class

Represents the base enumerator class.

package com.ms.wfc.core

public class Enum

Remarks

Extend this class for the Properties window to recognize your constants. To create your own enumerator class, declare the public static final integers and override the valid method. To associate a property with your enumerator, specify that the property has the enumerator type in the ClassInfo inner class. (Because the enumerator types are integers, the actual type of the property in the method declarations should be an int.) The Properties window will display a drop-down list with the enumerator values.

The following code shows a simple example:

// Define an enumerator class.
class Alignment extends Enum {

   public static final int NONE = 0;
   public static final int LEFT = 1;
   public static final int CENTER = 2;
   public static final int RIGHT = 3;

   public static boolean valid(int value) {
      if (value < 0 || value > 3) return false;
        return true;
   }
}

// Set the alignment property of an object.
myObject.setAlignment(Alignment.LEFT);


 Enum Methods

Enum Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 Enum.valid

Enum.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid for this class; otherwise, returns false.

Remarks

The default implementation returns false. Be sure to override this method in your own enumerator class.


Event Class

Represents the base class for all events.

package com.ms.wfc.core

public class Event

Remarks

The Event class is typically used for events that have no associated information. The EMPTY field is used to represent such "empty" events. (The Event class also defines the extendedInfo field, which holds specialized information only for com.ms.wfc.html events. This field is not used outside the context of the com.ms.wfc.html package.)

WFC extends the Event class for events that provide specific information. For example, the ScrollEvent subclass defines fields that specify the type of scroll event that occurred and the new value for the scroll bar.

For information about the WFC event model, see Handling Events in WFC.

See Also CancelEvent


 Event Methods

Event Methods

Constructors | Description
Event | Creates an Event object.


 Event.Event

Event.Event

Creates an Event object.

Syntax

public Event()

public Event( Object extendedInfo )

Parameters

extendedInfo

Additional information supplied by com.ms.wfc.html events. You should not pass a value for this parameter outside the context of the com.ms.wfc.html package. For more information, see Event.extendedInfo and DhEventInfo.


 Event Fields

Event Fields

Fields | Description
EMPTY | Specifies an Event object with no associated information.
extendedInfo | Specifies additional information for com.ms.wfc.html events.


 Event.EMPTY

Event.EMPTY

Specifies an Event object with no associated information.

Syntax

public static final Event EMPTY;

Remarks

For events that are registered by an EventHandler delegate, Event.EMPTY is passed to the on<EventName> method when the event is triggered. This allows an Event object to be created once and reused each time the event is triggered.


 Event.extendedInfo

Event.extendedInfo

Specifies additional information for com.ms.wfc.html events.

Syntax

public final Object extendedInfo;

Remarks

The com.ms.wfc.html package provides events with specialized information, which can be accessed by casting this field to a DhEventInfo object. This field should not be used outside the context of the com.ms.wfc.html package.


EventHandler Delegate

Identifies an event handler method.

package com.ms.wfc.core

public multicast delegate
void EventHandler( Object sender, Event e );

Remarks

The syntax of the EventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is an Event object.

When you create an EventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC.


EventInfo Class

Defines an event of a component.

MemberInfo
  |
  +--EventInfo

package com.ms.wfc.core

public final class EventInfo
extends MemberInfo

Remarks

Events allow you to get run-time notifications from a component. The EventInfo class is used within the component's ClassInfo inner class. When you create an EventInfo object, you specify the component class, the name of the event, the associated delegate, and the various attributes of the event. (Attributes can be specified using the classes that extend MemberAttribute.)

The following example shows a portion of the ClassInfo of the Control class:

public static class ClassInfo extends Component.ClassInfo {
   public static final EventInfo click = new EventInfo(
      Control.class, "click", EventHandler.class,
      CategoryAttribute.Action,
      new DescriptionAttribute("Occurs when the control is clicked."));

   public static final EventInfo keyDown = new EventInfo(
      Control.class, "keyDown", KeyEventHandler.class,
      CategoryAttribute.Key,
      new DescriptionAttribute("Occurs when a key is first pressed."));

   public void getEvents(IEvents events) {
      super.getEvents(events);
      events.add(click);
      events.add(keyDown);
   }
}

Every event has a structure through which it passes its information. The base structure is the Event class, from which all other event structures derive. To handle the event, you define a method that takes a source object (the object that triggered the event) and a structure particular to that event. This handler is assigned to the event through a delegate. The following code shows a simple example:

class MyClass {
   Button button1 = new Button();

   // Define the handler for the click event.
   void button1_click(Object sender, Event e) {
      ... // Handle the event.
   }

   public MyClass() {
      // Assign the handler to the event through a delegate.
      button1.addOnClick(new EventHandler(this.button1_click));
   }
}

For each event defined through EventInfo, the component class must implement the following methods, which add and remove delegates and trigger the event, respectively:

public void addOn<EventName>( <EventStructure>Handler handler )

public void removeOn<EventName>( <EventStructure>Handler handler )

protected void on<EventName>( <EventStructure> e )

The <EventStructure>Handler parameter is a delegate, which is typically declared as follows:

public multicast delegate void <EventStructure>Handler( Object sender, <EventStructure> e );

The syntax of the delegate specifies the syntax of the handler method. Note that if the delegate is declared as multicast, multiple handlers can be added. For more information about delegates and the WFC event model, see Handling Events in WFC.

Note An event name typically begins with a lowercase letter, while the case of the associated methods is mixed. For example, an event named doubleClick is associated with addOnDoubleClick, removeOnDoubleClick, and onDoubleClick methods.

An EventInfo object can be obtained programmatically through the ComponentManager class.

See Also PropertyInfo, ExtenderInfo


 EventInfo Methods

EventInfo Methods

Constructors | Description
EventInfo | Creates an EventInfo object.

Methods | Description
addEventHandler | Adds a delegate to a component.
getAddMethod | Retrieves the addOn<EventName> method of the component class.
getMulticast | Determines whether the delegate type for the event is declared as multicast.
getRemoveMethod | Retrieves the removeOn<EventName> method of the component class.
getType | Retrieves the type of the delegate for the event.
removeEventHandler | Removes a delegate from a component.


 EventInfo.addEventHandler

EventInfo.addEventHandler

Adds a delegate to a component.

Syntax

public void addEventHandler( Object component, Delegate value )

Parameters

component

The component on which the delegate will receive events.

value

A com.ms.lang.Delegate object that encapsulates the handling method and object.

Remarks

This method invokes the component's addOn<EventName> method to add the specified delegate.

See Also removeEventHandler


 EventInfo.EventInfo

EventInfo.EventInfo

Creates an EventInfo object.

Syntax

public EventInfo( Class componentClass, String name, Class type, MemberAttribute[] attributes )

public EventInfo( Class componentClass, String name, Class type )

public EventInfo( Class componentClass, String name, Class type, MemberAttribute a1 )

public EventInfo( Class componentClass, String name, Class type, MemberAttribute a1, MemberAttribute a2 )

public EventInfo( Class componentClass, String name, Class type, MemberAttribute a1, MemberAttribute a2, MemberAttribute a3 )

public EventInfo( Class componentClass, String name, Class type, MemberAttribute a1, MemberAttribute a2, MemberAttribute a3, MemberAttribute a4 )

public EventInfo( EventInfo oldEventInfo, MemberAttribute[] attributes )

public EventInfo( EventInfo oldEventInfo, MemberAttribute a1 )

public EventInfo( EventInfo oldEventInfo, MemberAttribute a1, MemberAttribute a2 )

public EventInfo( EventInfo oldEventInfo, MemberAttribute a1, MemberAttribute a2, MemberAttribute a3 )

public EventInfo( EventInfo oldEventInfo, MemberAttribute a1, MemberAttribute a2, MemberAttribute a3, MemberAttribute a4 )

Parameters

componentClass

The type of the component that defines the event.

name

The name of the event.

type

The type of the event handling delegate.

attributes

An array of MemberAttribute objects that specify the attributes of the event.

a1, a2, a3, a4

A MemberAttribute object that specifies an attribute of the event.

oldEventInfo

An existing EventInfo object on which to base the new event.

Remarks

When you create a new event using an existing EventInfo object, the attributes of the existing event and those specified for the new event are combined. However, if an attribute of the existing event is of the same class as an attribute specified for the new event, the attribute for the new event takes precedence. For example, if you pass an EventInfo object that specifies CategoryAttribute.Key, but you also pass CategoryAttribute.Mouse, the new event is given the CategoryAttribute.Mouse attribute.

For an example that shows how to create an EventInfo object, see the EventInfo overview.


 EventInfo.getAddMethod

EventInfo.getAddMethod

Retrieves the addOn<EventName> method of the component class.

Syntax

public Method getAddMethod()

Return Value

Returns the addOn<EventName> method.


 EventInfo.getMulticast

EventInfo.getMulticast

Determines whether the delegate type for the event is declared as multicast.

Syntax

public boolean getMulticast()

Return Value

Returns true if the delegate is declared as multicast; otherwise, returns false.

Remarks

If a delegate is declared as multicast, multiple handlers can be assigned to an event.


 EventInfo.getRemoveMethod

EventInfo.getRemoveMethod

Retrieves the removeOn<EventName> method of the component class.

Syntax

public Method getRemoveMethod()

Return Value

Returns the removeOn<EventName> method.


 EventInfo.getType

EventInfo.getType

Retrieves the type of the delegate for the event.

Syntax

public Class getType()

Return Value

Returns the delegate type.


 EventInfo.removeEventHandler

EventInfo.removeEventHandler

Removes a delegate from a component.

Syntax

public void removeEventHandler( Object component, Delegate value )

Parameters

component

The component on which the delegate was receiving events.

value

A com.ms.lang.Delegate object that represents the delegate to be removed.

Remarks

This method invokes the component's removeOn<EventName> method to remove the specified delegate.

See Also addEventHandler


ExtenderInfo Class

Defines an extender property of a component.

MemberInfo
  |
  +--ExtenderInfo

package com.ms.wfc.core

public class ExtenderInfo
extends MemberInfo

Remarks

An extender property allows a component to provide properties to other components. An example is the toolTip property of the ToolTip component. When this component is present, all other controls on the form appear to have an extra toolTip property.

Note In order to provide extender properties, a component must implement the IExtenderProvider interface.

The ExtenderInfo class is used within a component's ClassInfo inner class. When you create an ExtenderInfo object, you specify the component class that is providing the extender, the name of the extender, the component class that is receiving the extender, the type of the extender, and the various attributes of the extender. (Attributes can be specified using the classes that extend MemberAttribute.)

The following example shows a portion of the ClassInfo of the ToolTip class:

public static class ClassInfo extends Component.ClassInfo {
   public static final ExtenderInfo toolTip = new ExtenderInfo(
      ToolTip.class, "toolTip", Control.class, String.class,
      LocalizableAttribute.YES,
      new DefaultValueAttribute.NULL,
      new DescriptionAttribute(
    "Determines the tool tip shown when the mouse hovers over the control."));

   public void getExtenders(IExtenders iexts) {
      super.getExtenders(iexts);
      iexts.add(toolTip);
   }
}

For a read-only extender property defined through ExtenderInfo, the component class providing the extender must implement the following method:

public <extenderType> get<ExtenderName>( Object extendee )

For a read/write extender property, the component class must implement get<ExtenderName> as well as the following method:

public void set<ExtenderName>( Object extendee, <extenderType> value )

In the syntax for these methods, the extendee parameter is the object that receives the extender. These methods return and set the value of the extender for the extendee object.

Note An extender name typically begins with a lowercase letter, while the case of the associated methods is mixed. For example, a read/write extender property named toolTip is associated with getToolTip and setToolTip methods.

The following example shows how to set an extender property:

Button button1 = new Button();
Button button2 = new Button();
ToolTip toolTip1 = new ToolTip();

toolTip1.setToolTip(button1, "button1's tooltip");
toolTip1.setToolTip(button2, "button2's tooltip");

In addition to the get<ExtenderName> and set<ExtenderName> methods, the component class providing the extender can optionally implement the following two methods:

public boolean shouldPersist<ExtenderName>( Object extendee )

public void reset<ExtenderName>( Object extendee )

These methods involve the extender's default value, which is specified using DefaultValueAttribute. The shouldPersist<ExtenderName> method returns true if the current value of the extender is different than its default value, indicating that the value should be persisted. The reset<ExtenderName> method resets the extender to its default value.

If the ExtenderInfo definition specifies a value editor (using ValueEditorAttribute), this value editor is used to edit the extender. Otherwise, a system-provided value editor is used.

An ExtenderInfo object can be obtained programmatically through the ComponentManager class.

See Also PropertyInfo, EventInfo, Attribute Classes


 ExtenderInfo Methods

ExtenderInfo Methods

Constructors | Description
ExtenderInfo | Creates an ExtenderInfo object.

Methods | Description
canResetValue | Determines whether the value of the extender property can be reset.
getExtendeeType | Retrieves the type of the object receiving the extender property.
getGetMethod | Retrieves the get<ExtenderName> method of the extender component.
getIsReadOnly | Determines whether the extender property is read-only.
getResetMethod | Retrieves the reset<ExtenderName> method of the extender component.
getSetMethod | Retrieves the set<ExtenderName> method of the extender component.
getShouldPersistMethod | Retrieves the shouldPersist<ExtenderName> method of the extender component.
getType | Retrieves the type of the extender property.
getValue | Retrieves the current value of the extender property for the specified extender-extendee pair.
getValueEditor | Retrieves the value editor of the extender property.
resetValue | Resets the value of the extender property for the specified extender-extendee pair.
setValue | Sets the value of the extender property for the specified extender-extendee pair.
shouldPersistValue | Determines whether the value of the extender property should be persisted.


 ExtenderInfo.canResetValue

ExtenderInfo.canResetValue

Determines whether the value of the extender property can be reset.

Syntax

public boolean canResetValue ( Object extender, Object extendee )

Parameters

extender

The object providing the extender property.

extendee

The object receiving the extender property.

Return Value

Returns true if the extender's value can be reset; otherwise, returns false.

Remarks

If a default value is specified in this ExtenderInfo object and the value returned by getValue is different than the default value, canResetValue returns true. If there is no default value, canResetValue invokes and returns the value of the component's shouldPersist<ExtenderName> method, if this method and the reset<ExtenderName> method exist. (If only the reset<ExtenderName> method exists, true is returned.) If none of these cases apply, false is returned.


 ExtenderInfo.ExtenderInfo

ExtenderInfo.ExtenderInfo

Creates an ExtenderInfo object.

Syntax

public ExtenderInfo( Class extenderClass, String propertyName, Class extendeeType, Class propertyType, MemberAttribute[] attributes )

public ExtenderInfo( Class extenderClass, String propertyName, Class extendeeType, Class propertyType )

public ExtenderInfo( Class extenderClass, String propertyName, Class extendeeType, Class propertyType, MemberAttribute a1 )

public ExtenderInfo( Class extenderClass, String propertyName, Class extendeeType, Class propertyType, MemberAttribute a1, MemberAttribute a2 )

public ExtenderInfo( Class extenderClass, String propertyName, Class extendeeType, Class propertyType, MemberAttribute a1, MemberAttribute a2, MemberAttribute a3 )

public ExtenderInfo( Class extenderClass, String propertyName, Class extendeeType, Class propertyType, MemberAttribute a1, MemberAttribute a2, MemberAttribute a3, MemberAttribute a4 )

public ExtenderInfo( ExtenderInfo oldExtenderInfo, MemberAttribute[] attributes )

public ExtenderInfo( ExtenderInfo oldExtenderInfo, MemberAttribute a1 )

public ExtenderInfo( ExtenderInfo oldExtenderInfo, MemberAttribute a1, MemberAttribute a2 )

public ExtenderInfo( ExtenderInfo oldExtenderInfo, MemberAttribute a1, MemberAttribute a2, MemberAttribute a3 )

public ExtenderInfo( ExtenderInfo oldExtenderInfo, MemberAttribute a1, MemberAttribute a2, MemberAttribute a3, MemberAttribute a4 )

Parameters

extenderClass

The type of the component that defines the extender. (This component should implement the IExtenderProvider interface.)

propertyName

The name of the extender.

extendeeType

The type of the component to receive the extender property.

propertyType

The type of the extender.

attributes

An array of MemberAttribute objects that specify the attributes of the property.

a1, a2, a3, a4

A MemberAttribute object that specifies an attribute of the property.

oldExtenderInfo

An existing ExtenderInfo object on which to base the new extender.

Remarks

When you create a new extender using an existing ExtenderInfo object, the attributes of the existing extender and those specified for the new extender are combined. However, if an attribute of the existing extender is of the same class as an attribute specified for the new extender, the attribute for the new extender takes precedence. For example, if you pass an ExtenderInfo object that specifies DefaultValueAttribute.ZERO, but you also pass DefaultValueAttribute.ONE, the new extender is given the DefaultValueAttribute.ONE attribute.

For an example that shows how to create an ExtenderInfo object, see the ExtenderInfo overview.


 ExtenderInfo.getExtendeeType

ExtenderInfo.getExtendeeType

Retrieves the type of the object receiving the extender property.

Syntax

public Class getExtendeeType()

Return Value

Returns the extendee object's type.


 ExtenderInfo.getGetMethod

ExtenderInfo.getGetMethod

Retrieves the get<ExtenderName> method of the extender component.

Syntax

public Method getGetMethod()

Return Value

Returns the get<ExtenderName> method.


 ExtenderInfo.getIsReadOnly

ExtenderInfo.getIsReadOnly

Determines whether the extender property is read-only.

Syntax

public boolean getIsReadOnly()

Return Value

Returns true if the extender component has no set<ExtenderName> method; otherwise, returns false.


 ExtenderInfo.getResetMethod

ExtenderInfo.getResetMethod

Retrieves the reset<ExtenderName> method of the extender component.

Syntax

public Method getResetMethod()

Return Value

Returns the reset<ExtenderName> method, if it exists; otherwise, returns null.


 ExtenderInfo.getSetMethod

ExtenderInfo.getSetMethod

Retrieves the set<ExtenderName> method of the extender component.

Syntax

public Method getSetMethod()

Return Value

Returns the set<ExtenderName> method, if it exists; otherwise, returns null.


 ExtenderInfo.getShouldPersistMethod

ExtenderInfo.getShouldPersistMethod

Retrieves the shouldPersist<ExtenderName> method of the extender component.

Syntax

public Method getShouldPersistMethod()

Return Value

Returns the shouldPersist<ExtenderName> method, if it exists; otherwise, returns null.


 ExtenderInfo.getType

ExtenderInfo.getType

Retrieves the type of the extender property.

Syntax

public Class getType()

Return Value

Returns the extender type.


 ExtenderInfo.getValue

ExtenderInfo.getValue

Retrieves the current value of the extender property for the specified extender-extendee pair.

Syntax

public Object getValue( Object extender, Object extendee )

Parameters

extender

The object providing the extender property.

extendee

The object receiving the extender property.

Return Value

Returns the value of the extender property for the extendee object.

Remarks

This method invokes the extender object's get<ExtenderName> method to retrieve the value of the extender. The extender object manages the value of the extender property for each extendee object.

See Also setValue


 ExtenderInfo.getValueEditor

ExtenderInfo.getValueEditor

Retrieves the value editor of the extender property.

Syntax

public IValueEditor getValueEditor()

public IValueEditor getValueEditor( IEditorSite site )

Parameters

site

An object implementing the IEditorSite interface that represents the value editor site.

Return Value

Returns an object implementing the IValueEditor interface that represents the value editor for the extender property.

Remarks

If a value editor is specified in this ExtenderInfo object, that editor is instantiated; otherwise, a system value editor is looked for. If there is no system value editor, null is returned.

Note Custom system value editors can be added through the ComponentManager.registerValueEditorClass method.


 ExtenderInfo.resetValue

ExtenderInfo.resetValue

Resets the value of the extender property for the specified extender-extendee pair.

Syntax

public void resetValue( Object extender, Object extendee )

Parameters

extender

The object providing the extender property.

extendee

The object receiving the extender property.

Remarks

If a default value is specified in this ExtenderInfo object, the value of the extender property is set to the default value. If the extender has no default value, this method invokes the extender object's reset<ExtenderName> method, if it exists. (If both these routes fail, the extender value remains unchanged.)


 ExtenderInfo.setValue

ExtenderInfo.setValue

Sets the value of the extender property for the specified extender-extendee pair.

Syntax

public void setValue( Object extender, Object extendee, Object value )

Parameters

extender

The object providing the extender property.

extendee

The object receiving the extender property.

value

The new value of the extender property.

Remarks

This method invokes the extender object's set<ExtenderName> method, if it exists. The extender object manages the value of the extender property for each extendee object.

See Also getValue


 ExtenderInfo.shouldPersistValue

ExtenderInfo.shouldPersistValue

Determines whether the value of the extender property should be persisted.

Syntax

public boolean shouldPersistValue( Object extender, Object extendee )

Parameters

extender

The object providing the extender property.

extendee

The object receiving the extender property.

Return Value

Returns true if the extender property should be persisted; otherwise, returns false.

Remarks

This method determines whether the state of the extender property is different from when the extendee object was first instantiated. If a default value is specified in this ExtenderInfo object, it is compared against the current value. If there is no default value, this method invokes and returns the value of the extender object's shouldPersist<ExtenderName> method, if it exists. If both these routes fail, true is returned.


IAttributes Interface

Defines a callback interface for enumerating the attributes of a component.

package com.ms.wfc.core

public interface IAttributes

Remarks

This interface is used in implementations of the getAttributes method of IClassInfo. This method is passed an instance of IAttributes and is responsible for calling IAttributes.add to enumerate the attributes of the associated component class.


 IAttributes Methods

IAttributes Methods

Methods | Description
add | Adds an attribute to the associated component class.


 IAttributes.add

IAttributes.add

Adds an attribute to the associated component class.

Syntax

public void add( MemberAttribute a )

Parameters

a

A MemberAttribute object that represents the attribute.

Remarks

For an example that shows how to use this method, see ClassInfo.getAttributes.


IClassInfo Interface

Defines the interface for exposing component metadata.

package com.ms.wfc.core

public interface IClassInfo

Remarks

The IClassInfo interface is used to provide component metadata that cannot be determined from the component itself. Examples of such metadata include the component's properties, events, icon, and so on.

A component never implements the IClassInfo interface directly. Rather, the component defines a public static inner class named ClassInfo, which in turn implements the IClassInfo interface. This type of implementation allows the metadata to be separated from the class itself in situations where the metadata is not required (such as when the component is deployed).

The following example shows a base class named Window and its associated ClassInfo implementation:

public class Window
{
   ... // Members of class Window.

   public static class ClassInfo implements IClassInfo
   {
      ... // Implementations of IClassInfo methods.
   }
}

If a component class extends another component class, the ClassInfo of the subclass typically extends the ClassInfo of the superclass. For example:

public class Button extends Window
{
   ... // Members of class Button.

   public static class ClassInfo extends Window.ClassInfo
   {
      ... // Overrides of IClassInfo methods.
   }
}

Compiling a component class that has an inner ClassInfo class produces two .class files. These files are named component.class and component$ClassInfo.class, where component is the name of the component class. The ComponentManager class uses this naming pattern to identify classes that support metadata.

See Also ComponentInfo


 IClassInfo Methods

IClassInfo Methods

Methods | Description
getAttributes | Specifies the attributes of the component class.
getCustomizer | Retrieves the customizer of the specified component.
getDefaultEventName | Retrieves the name of the default event of the component class.
getDefaultPropertyName | Retrieves the name of the default property of the component class.
getEvents | Specifies the events of the component class.
getExtenders | Specifies the extender properties of the component class.
getProperties | Specifies the properties of the component class.
getToolboxBitmap | Retrieves the image that is used to represent the component in toolboxes, list views, and so on.


 IClassInfo.getAttributes

IClassInfo.getAttributes

Specifies the attributes of the component class.

Syntax

public void getAttributes( IAttributes attributes )

Parameters

attributes

An object implementing the IAtttibutes interface that is used to enumerate the attributes.

Remarks

The getAttributes method should call the add method of the attributes parameter to enumerate each attribute. For a sample implementation, see ClassInfo.getAttributes.


 IClassInfo.getCustomizer

IClassInfo.getCustomizer

Retrieves the customizer of the specified component.

Syntax

public ICustomizer getCustomizer( Object component )

Parameters

component

The object to retrieve the customizer for. This parameter must be an instance of either the component class or one of its subclasses.

Return Value

Returns an object implementing the ICustomizer interface. If the component does not support a customizer, null is returned.

Remarks

A customizer provides the ability to create a set of design pages for a component, to edit the component, and to execute its design-time verbs.


 IClassInfo.getDefaultEventName

IClassInfo.getDefaultEventName

Retrieves the name of the default event of the component class.

Syntax

public String getDefaultEventName()

Return Value

Returns the default event name. If the component class has no default event, null is returned.

Remarks

The exact implications of a default event are defined by the tool that is editing the component. For example, in the Forms Designer, double-clicking a WFC component on a form in design mode opens the Text editor to an event handler. This handler is defined to handle the default event.


 IClassInfo.getDefaultPropertyName

IClassInfo.getDefaultPropertyName

Retrieves the name of the default property of the component class.

Syntax

public String getDefaultPropertyName()

Return Value

Returns the default property name. If the component class has no property event, null is returned.

Remarks

The exact implications of a default property are defined by the tool that is editing the component. For example, when a component's properties are displayed in the Properties window, the default property is initially selected.


 IClassInfo.getEvents

IClassInfo.getEvents

Specifies the events of the component class.

Syntax

public void getEvents( IEvents events )

Parameters

events

An object implementing the IEvents interface that is used to enumerate the events.

Remarks

The getEvents method should call the add method of the events parameter to enumerate each event. For a sample implementation, see the ClassInfo overview.


 IClassInfo.getExtenders

IClassInfo.getExtenders

Specifies the extender properties of the component class.

Syntax

public void getExtenders( IExtenders extenders )

Parameters

extenders

An object implementing the IExtenders interface that is used to enumerate the extenders.

Remarks

The getExtenders method should call the add method of the extenders parameter to enumerate each extender property. For a sample implementation, see ClassInfo.getExtenders.


 IClassInfo.getProperties

IClassInfo.getProperties

Specifies the properties of the component class.

Syntax

public void getProperties( IProperties props )

Parameters

props

An object implementing the IProperties interface that is used to enumerate the properties.

Remarks

The getProperties method should call the add method of the props parameter to enumerate each property. Each call to add specifies a new property or masks an already defined property of the same name with new attributes.

For a sample implementation of getProperties, see the ClassInfo overview.


 IClassInfo.getToolboxBitmap

IClassInfo.getToolboxBitmap

Retrieves the image that is used to represent the component in toolboxes, list views, and so on.

Syntax

public Bitmap getToolboxBitmap()

Return Value

Returns a Bitmap object that represents the image. If no bitmap is found, null is returned.


IComponent Interface

Defines the component interface.

package com.ms.wfc.core

public interface IComponent

Remarks

To be a component, a class must implement IComponent. Components can be hosted in containers. For each component in a container, the container creates a site that it uses to manage the component.

The Component class provides a base implementation of IComponent.

See Also IContainer, IComponentSite


 IComponent Methods

IComponent Methods

Methods | Description
addOnDispose | Assigns a delegate to the dispose event.
dispose | Disposes of the component.
getChildOf | Determines whether this component is a child of the specified component.
getComponentSite | Retrieves the site of the component.
removeOnDispose | Removes the delegate that is assigned to the dispose event.
setComponentSite | Sets the site of the component.


 IComponent.addOnDispose

IComponent.addOnDispose

Assigns a delegate to the dispose event.

Syntax

public void addOnDispose( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

The dispose event occurs when the component is disposed of through the dispose method. Components that maintain references to other components can register dispose event handlers for the referenced components so that the references can be cleared when the components are disposed of.

See Also removeOnDispose


 IComponent.dispose

IComponent.dispose

Disposes of the component.

Syntax

public void dispose()

Remarks

A call to dispose indicates that the component is no longer needed. An implementation of dispose must do the following:

  • Remove any references that the component is holding to other components. This is typically accomplished by assigning null to any fields that contain references to other components.
  • Release any system resources that are associated with the component, such as file handles, window handles, or database connections.
  • Dispose of any child components, such as child windows or submenu items, by calling the dispose method of these components. (A component is a child component if its getChildOf method returns true when passed this component.)
  • Remove the component from its container. If the component has a site, it must execute the following:
    site.getContainer().removeComponent(this);
    where site is the current (non-null) site.
  • Trigger a dispose event for any event handlers that have been registered through the addOnDispose method.

Ideally, a call to dispose will return a component to the state it was in immediately after it was created (this is not a requirement). Following a call to dispose, a component may raise exceptions for operations that cannot meaningfully be performed.


 IComponent.getChildOf

IComponent.getChildOf

Determines whether this component is a child of the specified component.

Syntax

public boolean getChildOf( IComponent component )

Parameters

component

The parent component.

Return Value

Returns true if this component is a child of component; otherwise, returns false.

Remarks

A component is considered a child of a specified parent component if the parent component's implementation of the dispose method also disposes the child component. Examples of child components are child windows and submenus.


 IComponent.getComponentSite

IComponent.getComponentSite

Retrieves the site of the component.

Syntax

public IComponentSite getComponentSite()

Return Value

Returns an object implementing the IComponentSite interface that represents the component's site. This site must be either the value that was passed to the most recent call to setComponentSite, or null if no calls have been made to setComponentSite.


 IComponent.removeOnDispose

IComponent.removeOnDispose

Removes the delegate that is assigned to the dispose event.

Syntax

public void removeOnDispose( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnDispose


 IComponent.setComponentSite

IComponent.setComponentSite

Sets the site of the component.

Syntax

public void setComponentSite( IComponentSite value )

Parameters

value

An object implementing the IComponentSite interface that represents the component's site. A non-null value indicates that the component has been added to a container; a null value indicates that the component is being removed from a container.

Remarks

The site passed to setComponentSite must be returned by subsequent calls to getComponentSite.


IComponentSite Interface

Defines the interface for a component site.

package com.ms.wfc.core

public interface IComponentSite

Remarks

A site represents the link between a component and its container. When a component is added to a container, a site is created that acts as a binding link between the component and the container.

See Also IComponent, IContainer


 IComponentSite Methods

IComponentSite Methods

Methods | Description
componentChanged | Specifies that the associated component has changed.
getComponent | Retrieves the component associated with the site.
getContainer | Retrieves the container associated with the site.
getDesignMode | Determines whether the associated component is currently in design mode.
getDisposing | Determines whether the associated component is currently being disposed of.
getName | Retrieves the name of the associated component that is maintained by the site.
getService | Retrieves a service provided by the site.
setName | Sets the name of the associated component that is maintained by the site.


 IComponentSite.componentChanged

IComponentSite.componentChanged

Specifies that the associated component has changed.

Syntax

public synchronized void componentChanged()

Remarks

A component's customizer should call this method when it changes a property of the component; this ensures a property browser will display the updated property.


 IComponentSite.getComponent

IComponentSite.getComponent

Retrieves the component associated with the site.

Syntax

public IComponent getComponent()

Return Value

Returns an object implementing the IComponent interface that represents the associated component.


 IComponentSite.getContainer

IComponentSite.getContainer

Retrieves the container associated with the site.

Syntax

public IContainer getContainer()

Remarks

Returns an object implementing the IContainer interface that represents the associated container.


 IComponentSite.getDesignMode

IComponentSite.getDesignMode

Determines whether the associated component is currently in design mode.

Syntax

public synchronized boolean getDesignMode()

Return Value

Returns true if the component is in design mode; otherwise, returns false.


 IComponentSite.getDisposing

IComponentSite.getDisposing

Determines whether the associated component is currently being disposed of.

Syntax

public synchronized boolean getDisposing()

Return Value

Returns true if the component is being disposed of; otherwise, returns false.

See Also dispose


 IComponentSite.getName

IComponentSite.getName

Retrieves the name of the associated component that is maintained by the site.

Syntax

public synchronized String getName()

Return Value

Returns the component name held by the site.

See Also setName


 IComponentSite.getService

IComponentSite.getService

Retrieves a service provided by the site.

Syntax

public synchronized Object getService( Class service )

Parameters

service

An interface that represents the service. Currently, the only service available is ISelectionService, which can be obtained by passing ISelectionService.class for this parameter.

Return Value

Returns an object that implements the specified interface. If the site does not support this service, null is returned.


 IComponentSite.setName

IComponentSite.setName

Sets the name of the associated component that is maintained by the site.

Syntax

public synchronized void setName( String value )

Parameters

value

The component name held by the site.

See Also getName


IConstructable Interface

Allows a class to indicate what constructor arguments are needed to create an object of its type.

package com.ms.wfc.core

public interface IConstructable

Remarks

This interface defines the getConstructorArgs method, which specifies the constructor arguments for creating a class object.

Note In order for the object to be persisted properly, the class must define a constructor that takes these arguments.

The IConstructable interface enables a class to be used as a property value for a component or control. In order for a visual designer to support a class as a data type, the class must implement either IComponent, IConstructable, or IPersistable. If the class implements IComponent, then it is a component like any other object in the designer. However, a lightweight class should instead implement IConstructable or IPersistable (or both). These two interfaces allow the class to participate in code generation. The IConstructable interface allows the class to inform the designer what parameters can be passed to the object's constructor; the IPersistable interface allows the object to be saved to a binary resource file.


 IConstructable Methods

IConstructable Methods

Methods | Description
getConstructorArgs | Retrieves the constructor arguments that are needed to instantiate the class.


 IConstructable.getConstructorArgs

IConstructable.getConstructorArgs

Retrieves the constructor arguments that are needed to instantiate the class.

Syntax

public ConstructorArg[] getConstructorArgs()

Return Value

Returns an array of ConstructorArg objects that represent the constructor arguments.


IContainer Interface

Defines the container interface.

package com.ms.wfc.core

public interface IContainer

Remarks

A container represents a logical containment of components. To be a container, a class must implement IContainer. For each component in a container, the container creates a site that it uses to manage the component.

The Container class provides a base implementation of IContainer.

See Also IComponent, IComponentSite


 IContainer Methods

IContainer Methods

Methods | Description
add | Adds a component to the container.
dispose | Removes and disposes of all components in the container.
getComponent | Retrieves a component in the container.
getComponents | Retrieves all components in the container.
remove | Removes a component from the container.


 IContainer.add

IContainer.add

Adds a component to the container.

Syntax

public void add( IComponent component )

public void add( IComponent component, String name )

Parameters

component

The component to be added.

name

The name to be associated with the component.

Remarks

This method creates the site that associates the component with the container.

See Also remove


 IContainer.dispose

IContainer.dispose

Removes and disposes of all components in the container.

Syntax

public synchronized void dispose()

See Also remove


 IContainer.getComponent

IContainer.getComponent

Retrieves a component in the container.

Syntax

public synchronized IComponent getComponent( String name )

Parameters

name

The name associated with the component to be retrieved.

Return Value

Returns an object implementing the IComponent interface that represents the specified component. If no component has the specified name, null is returned.

See Also getComponents


 IContainer.getComponents

IContainer.getComponents

Retrieves all components in the container.

Syntax

public synchronized IComponent[] getComponents()

Return Value

Returns an array of objects implementing the IComponent interface that represent all components in the container.

See Also getComponent


 IContainer.remove

IContainer.remove

Removes a component from the container.

Syntax

public synchronized void remove( IComponent component )

Parameters

component

The component to be removed.

Remarks

This method sets the component's site to null.

See Also add, IComponent.setComponentSite


ICustomizer Interface

Defines the interface for a customizer of a component.

package com.ms.wfc.core

public interface ICustomizer

Remarks

A customizer creates a set of design pages for a component, determines its design-time verbs, and executes those verbs. Instances of objects that implement the ICustomizer interface are created by the IClassInfo.getCustomizer method.

Note A design page is the WFC equivalent of an OLE property page. When possible, you should use a value editor instead of a design page to provide a more seamless user interface through the property browser.

The Customizer class provides a base implementation of ICustomizer.

See Also IValueEditor


 ICustomizer Methods

ICustomizer Methods

Methods | Description
getDesignPages | Retrieves an array of classes for each design page used by the component.
getHitTest | Determines whether the specified point is active.
getVerbs | Returns the design-time verbs supported by the associated component.


 ICustomizer.getDesignPages

ICustomizer.getDesignPages

Retrieves an array of classes for each design page used by the component.

Syntax

public Class[] getDesignPages()

Return Value

Returns an array of classes for each design page. Each class in the array must implement the IDesignPage interface.


 ICustomizer.getHitTest

ICustomizer.getHitTest

Determines whether the specified point is active.

Syntax

public boolean getHitTest( Point point )

Parameters

point

A Point object that represents a point relative to the upper-left corner of the component.

Return Value

Returns true if the point should be considered active, meaning the user can interact with it; otherwise, returns false.

Remarks

This method allows a component to support a design-time user interface. When getHitTest returns true, mouse messages at the specified point can be passed to the component.


 ICustomizer.getVerbs

ICustomizer.getVerbs

Returns the design-time verbs supported by the associated component.

Syntax

public CustomizerVerb[] getVerbs()

Return Value

Returns an array of CustomizerVerb objects that represent the component's verbs. If the component does not support any verbs, null is returned.

Remarks

A designer should display the verbs returned by this method on the component's shortcut menu. When the user selects one of the verbs, the performVerbExecute method is invoked on the corresponding CustomizerVerb object.

Note A designer typically provides a "Properties" item on the shortcut menu. This menu item should not be included in the list of verbs returned by getVerbs.


IEditorHost Interface

Defines a callback interface that assists a value editor in presenting a user interface.

package com.ms.wfc.core

public interface IEditorHost

Remarks

This interface represents a host service that is provided through IValueAccess.getService. Using IEditorHost, a value editor can launch a dialog box through the runDialog method. The host can also display a control in a drop-down window (if the value editor specifies the STYLE_DROPDOWNARROW style).

See Also IValueEditor


 IEditorHost Methods

IEditorHost Methods

Methods | Description
dropDownControl | Launches a drop-down window that contains a control.
dropDownDone | Indicates that the control inside a drop-down window has finished editing the value.
getHostHandle | Retrieves a handle to a window, which allows Windows dialog boxes to be parented.
runDialog | Launches a modal dialog box.


 IEditorHost.dropDownControl

IEditorHost.dropDownControl

Launches a drop-down window that contains a control.

Syntax

public void dropDownControl( Control ctl )

Parameters

ctl

A Control object to be displayed inside a drop-down window.

Remarks

Because this method attempts to give the control its current size, the control should set its desired size before each invocation of this method. The dropDownDone method should then be called when the control has finished editing the value. Note that the drop-down window may be exited prematurely through user action, in which case the control is made invisible.

When implementing the dropDownControl method, the associated value editor should specify the STYLE_DROPDOWNARROW style.


 IEditorHost.dropDownDone

IEditorHost.dropDownDone

Indicates that the control inside a drop-down window has finished editing the value.

Syntax

public void dropDownDone()

See Also dropDownControl


 IEditorHost.getHostHandle

IEditorHost.getHostHandle

Retrieves a handle to a window, which allows Windows dialog boxes to be parented.

Syntax

public int getHostHandle()

Return Value

Returns a window handle.


 IEditorHost.runDialog

IEditorHost.runDialog

Launches a modal dialog box.

Syntax

public int runDialog( Form dialog )

Parameters

dialog

The dialog box to be displayed.

Return Value

Returns the dialog result.

Remarks

This method also handles positioning the dialog box on the screen.


IEditorSite Interface

Defines a callback interface through which a value editor accesses the owner of the values that are being edited.

package com.ms.wfc.core

public interface IEditorSite

Remarks

This interface represents the link between a value editor and the owner of the values being edited. If the value editor requires knowledge about the owner, it should define a constructor that takes an IEditorSite object. This constructor causes the value editor to be instantiated for each use, rather than to be cached. For more information, see the IValueEditor overview.

See Also Value Editor Classes


 IEditorSite Methods

IEditorSite Methods

Methods | Description
getComponent | Retrieves the primary component that depends on the value being edited.
getComponents | Retrieves all components that depend on the value being edited.
getType | Retrieves the type of the value being edited.
getValueOwner | Retrieves the object that directly depends on the value being edited.
getValueOwners | Retrieves all objects that directly depend on the value being edited.


 IEditorSite.getComponent

IEditorSite.getComponent

Retrieves the primary component that depends on the value being edited.

Syntax

public IComponent getComponent()

Return Value

Returns the primary component that depends on the value.

Remarks

This method allows the value editor to access the design-time site information. For example, the ReferenceEditor class uses this information to determine the other components in the container.

See Also getComponents, getValueOwner


 IEditorSite.getComponents

IEditorSite.getComponents

Retrieves all components that depend on the value being edited.

Syntax

public IComponent[] getComponents()

Return Value

Returns an array of the components that depend on the value. (This array contains more than one item if multiple components are selected for editing.)

See Also getComponent, getValueOwners


 IEditorSite.getType

IEditorSite.getType

Retrieves the type of the value being edited.

Syntax

public Class getType()

Return Value

Returns the value type.


 IEditorSite.getValueOwner

IEditorSite.getValueOwner

Retrieves the object that directly depends on the value being edited.

Syntax

public Object getValueOwner()

Return Value

Returns the object that directly depends on the value.

Remarks

This method differs from getComponent in that the editing may occur on the property value of a non-component object. (If the object returned is a component, it is the same object that getComponent would return.)

See Also getValueOwners


 IEditorSite.getValueOwners

IEditorSite.getValueOwners

Retrieves all objects that directly depend on the value being edited.

Syntax

public Object[] getValueOwners()

Return Value

Returns an array of the objects that directly depend on the value. (This array contains more than one item if multiple components are selected for editing.)

Remarks

This method differs from getComponents in that the editing may occur on the property values of non-component objects. (If the objects returned are components, they are the same objects that getComponents would return.)

See Also getValueOwner


IEvents Interface

Defines a callback interface for enumerating the events of a component.

package com.ms.wfc.core

public interface IEvents

Remarks

This interface is used in implementations of the getEvents method of IClassInfo. This method is passed an instance of IEvents and is responsible for calling IEvents.add to enumerate the events of the associated component class.


 IEvents Methods

IEvents Methods

Methods | Description
add | Adds an event to the associated component class.


 IEvents.add

IEvents.add

Adds an event to the associated component class.

Syntax

public void add( EventInfo e )

Parameters

e

An EventInfo object that defines the event.

Remarks

For an example that shows how to use this method, see the ClassInfo overview.


IExtenderProvider Interface

Defines the interface for extending properties to other components in a container.

package com.ms.wfc.core

public interface IExtenderProvider

Remarks

Any component that provides extender properties must implement IExtenderProvider. A visual designer can then call IExtenderProvider.canExtend to determine which objects in the container should receive the extender properties.

For more information about extender properties, see ExtenderInfo.


 IExtenderProvider Methods

IExtenderProvider Methods

Methods | Description
canExtend | Determines whether an object can receive the extender properties.


 IExtenderProvider.canExtend

IExtenderProvider.canExtend

Determines whether an object can receive the extender properties.

Syntax

public boolean canExtend( Object target )

Parameters

target

The object to receive the extender properties.

Return Value

Returns true if the extender properties should be shown for the target object; otherwise, returns false.

Remarks

For more information about extender properties, see ExtenderInfo.


IExtenders Interface

Defines a callback interface for enumerating the extender properties of a component.

package com.ms.wfc.core

public interface IExtenders

Remarks

This interface is used in implementations of the getExtenders method of IClassInfo. This method is passed an instance of IExtenders and is responsible for calling IExtenders.add to enumerate the extender properties of the associated component class.


 IExtenders Methods

IExtenders Methods

Methods | Description
add | Adds an extender property to the associated component class.


 IExtenders.add

IExtenders.add

Adds an extender property to the associated component class.

Syntax

public void add( ExtenderInfo e )

Parameters

e

An ExtenderInfo object that defines the event.

Remarks

For an example that shows how to use this method, see ClassInfo.getExtenders.


IPersistable Interface

Allows an object to be written to a stream and read from a stream.

package com.ms.wfc.core

public interface IPersistable

Remarks

This interface defines the save method, which persists the class object to a stream.

Note In order to read the object from the stream, the class must implement a constructor that takes an IDataStream object, which contains data for instantiating the class.

The following example shows a Point class that implements IPersistable:

public class Point implements IPersistable
{
   public int x;  // The horizontal position of the point.
   public int y;  // The vertical position of the point.

   // Constructor that takes an IDataStream object.
   public Point(IDataStream stream) {
       x = stream.readInt();
       y = stream.readInt();
   }

   // Implementation of IPersistable.save.
   public void save(IDataStream stream) {
       stream.writeInt(x);
       stream.writeInt(y);
   }

   // Implementation of IPersistable.getExtension.
   public String getExtension() {
       return null;
   }

   ...  // Remaining class implementation.
}

The IPersistable interface enables a class to be used as a property value for a component or control. For more information, see the IConstructable overview.


 IPersistable Methods

IPersistable Methods

Methods | Description
getExtension | Retrieves the extension for the file name of the stream.
save | Persists the object to a stream.


 IPersistable.getExtension

IPersistable.getExtension

Retrieves the extension for the file name of the stream.

Syntax

public String getExtension()

Return Value

Returns the file name extension.


 IPersistable.save

IPersistable.save

Persists the object to a stream.

Syntax

public void save( IDataStream stream )

Parameters

stream

An IDataStream object to save the object to.


IProperties Interface

Defines a callback interface for enumerating the properties of a component.

package com.ms.wfc.core

public interface IProperties

Remarks

This interface is used in implementations of the getProperties method of IClassInfo. This method is passed an instance of IProperties and is responsible for calling IProperties.add to enumerate the properties of the associated component class.


 IProperties Methods

IProperties Methods

Methods | Description
add | Adds a property to the associated component class.


 IProperties.add

IProperties.add

Adds a property to the associated component class.

Syntax

public void add( PropertyInfo p )

Parameters

p

A PropertyInfo object that defines the property.

Remarks

For an example that shows how to use this method, see the ClassInfo overview.


IRequireBegin Interface

Defines an interface that specifies when a component is usable.

package com.ms.wfc.core

public interface IRequireBegin

Remarks

Any component that implements this interface requires the begin method to be called before it can be used. Once the begin method has been called, the component becomes active and can assume that all peers are loaded and all property sets are complete. (WFC code generation adds a call to the begin method for all IRequireBegin components at the end of initForm.)


 IRequireBegin Methods

IRequireBegin Methods

Methods | Description
begin | Signals the component that all peer components are loaded and the property sets are complete.


 IRequireBegin.begin

IRequireBegin.begin

Signals the component that all peer components are loaded and the property sets are complete.

Syntax

public void begin()

Remarks

This method must be called on the component before the component can be used.


IResourceLoader Interface

Defines an interface for retrieving a resource from a component's namespace.

package com.ms.wfc.core

public interface IResourceLoader


 IResourceLoader Methods

IResourceLoader Methods

Methods | Description
getResource | Retrieves a data stream for the specified resource.


 IResourceLoader.getResource

IResourceLoader.getResource

Retrieves a data stream for the specified resource.

Syntax

public IDataStream getResource( String resource )

Parameters

resource

The name of the resource to be retrieved.

Return Value

Returns an IDataStream object that represents the data stream containing the resource.


IResourceManager Interface

Defines an interface for managing resource data.

package com.ms.wfc.core

public interface IResourceManager

Remarks

This interface is used to manage the resource sets for multiple locales. Each property in the resource set should cascade, such that if a resource set does not contain a given property, the value of that property in the parent resource set is used.

The ResourceManager class provides an implementation of IResourceManager.


 IResourceManager Methods

IResourceManager Methods

Methods | Description
containsProperty | Determines whether the specified property is stored for a given locale.
getBoolean | Retrieves a boolean value for the specified property.
getByte | Retrieves a byte value for the specified property.
getChar | Retrieves a character for the specified property.
getDouble | Retrieves a double value for the specified property.
getFloat | Retrieves a float value for the specified property.
getInt | Retrieves an integer for the specified property.
getLong | Retrieves a long value for the specified property.
getNames | Retrieves the names of all properties for a given locale.
getObject | Retrieves the value of the specified property.
getProperties | Retrieves the values of all properties for a given locale.
getResourceSet | Retrieves the resource set that is storing the properties for the specified locale.
getShort | Retrieves a short value for the specified property.
getString | Retrieves a string for the specified property.
saveAllProperties | Saves all properties for all locales to disk.
setProperty | Sets the value of the specified property.
setResourceSet | Sets the resource set that will store the properties for the specified locale.


 IResourceManager.containsProperty

IResourceManager.containsProperty

Determines whether the specified property is stored for a given locale.

Syntax

public boolean containsProperty( String name )

public boolean containsProperty( Locale locale, String name )

Parameters

name

The name of the property.

locale

A Locale object that represents the locale to check. If no value is specified for this parameter, the current locale is used.

Return Value

Returns true if the property is contained by the resource manager; otherwise, returns false.


 IResourceManager.getBoolean

IResourceManager.getBoolean

Retrieves a boolean value for the specified property.

Syntax

public boolean getBoolean( String name )

public boolean getBoolean( Locale locale, String name )

Parameters

name

The name of the property.

locale

A Locale object that represents the locale to check. If no value is specified for this parameter, the current locale is used.

Return Value

Returns the property value expressed as a boolean value.

Remarks

If the resource set for the given locale does not contain the specified property, the parent chain is searched. If the property is contained within a parent resource set, then its value is returned; otherwise, false is returned.


 IResourceManager.getByte

IResourceManager.getByte

Retrieves a byte value for the specified property.

Syntax

public byte getByte( String name )

public byte getByte( Locale locale, String name )

Parameters

name

The name of the property.

locale

A Locale object that represents the locale to check. If no value is specified for this parameter, the current locale is used.

Return Value

Returns the property value expressed as a byte value.

Remarks

If the resource set for the given locale does not contain the specified property, the parent chain is searched. If the property is contained within a parent resource set, then its value is returned; otherwise, 0 is returned.


 IResourceManager.getChar

IResourceManager.getChar

Retrieves a character for the specified property.

Syntax

public char getChar( String name )

public char getChar( Locale locale, String name )

Parameters

name

The name of the property.

locale

A Locale object that represents the locale to check. If no value is specified for this parameter, the current locale is used.

Return Value

Returns the property value expressed as a char value.

Remarks

If the resource set for the given locale does not contain the specified property, the parent chain is searched. If the property is contained within a parent resource set, then its value is returned; otherwise, 0 is returned.


 IResourceManager.getDouble

IResourceManager.getDouble

Retrieves a double value for the specified property.

Syntax

public double getDouble( String name )

public double getDouble( Locale locale, String name )

Parameters

name

The name of the property.

locale

A Locale object that represents the locale to check. If no value is specified for this parameter, the current locale is used.

Return Value

Returns the property value expressed as a double value.

Remarks

If the resource set for the given locale does not contain the specified property, the parent chain is searched. If the property is contained within a parent resource set, then its value is returned; otherwise, 0.0 is returned.


 IResourceManager.getFloat

IResourceManager.getFloat

Retrieves a float value for the specified property.

Syntax

public float getFloat( String name )

public float getFloat( Locale locale, String name )

Parameters

name

The name of the property.

locale

A Locale object that represents the locale to check. If no value is specified for this parameter, the current locale is used.

Return Value

Returns the property value expressed as a float value.

Remarks

If the resource set for the given locale does not contain the specified property, the parent chain is searched. If the property is contained within a parent resource set, then its value is returned; otherwise, 0.0 is returned.


 IResourceManager.getInt

IResourceManager.getInt

Retrieves an integer for the specified property.

Syntax

public int getInt( String name )

public int getInt( Locale locale, String name )

Parameters

name

The name of the property.

locale

A Locale object that represents the locale to check. If no value is specified for this parameter, the current locale is used.

Return Value

Returns the property value expressed as an int value.

Remarks

If the resource set for the given locale does not contain the specified property, the parent chain is searched. If the property is contained within a parent resource set, then its value is returned; otherwise, 0 is returned.


 IResourceManager.getLong

IResourceManager.getLong

Retrieves a long value for the specified property.

Syntax

public long getLong( String name )

public long getLong( Locale locale, String name )

Parameters

name

The name of the property.

locale

A Locale object that represents the locale to check. If no value is specified for this parameter, the current locale is used.

Return Value

Returns the property value expressed as a long value.

Remarks

If the resource set for the given locale does not contain the specified property, the parent chain is searched. If the property is contained within a parent resource set, then its value is returned; otherwise, 0 is returned.


 IResourceManager.getNames

IResourceManager.getNames

Retrieves the names of all properties for a given locale.

Syntax

public String[] getNames()

public String[] getNames( Locale locale )

Parameters

locale

A Locale object that represents the locale to check. If no value is specified for this parameter, the current locale is used.

Return Value

Returns an array containing all names stored for the specified locale.

See Also getProperties


 IResourceManager.getObject

IResourceManager.getObject

Retrieves the value of the specified property.

Syntax

public Object getObject( String name )

public Object getObject( Locale locale, String name )

Parameters

name

The name of the property.

locale

A Locale object that represents the locale to check. If no value is specified for this parameter, the current locale is used.

Return Value

Returns an Object that represents the property value.

Remarks

If the resource set for the given locale does not contain the specified property, the parent chain is searched. If the property is contained within a parent resource set, then its value is returned; otherwise, null is returned.


 IResourceManager.getProperties

IResourceManager.getProperties

Retrieves the values of all properties for a given locale.

Syntax

public Object[] getProperties()

public Object[] getProperties( Locale locale )

Parameters

locale

A Locale object that represents the locale to check. If no value is specified for this parameter, the current locale is used.

Return Value

Returns an Object array containing all values stored for the specified locale.

See Also getNames


 IResourceManager.getResourceSet

IResourceManager.getResourceSet

Retrieves the resource set that is storing the properties for the specified locale.

Syntax

public IResourceSet getResourceSet( Locale locale )

Parameters

locale

A Locale object that represents the locale to check.

Return Value

Returns the IResourceSet object that is storing the properties.

See Also setResourceSet


 IResourceManager.getShort

IResourceManager.getShort

Retrieves a short value for the specified property.

Syntax

public short getShort( String name )

public short getShort( Locale locale, String name )

Parameters

name

The name of the property.

locale

A Locale object that represents the locale to check. If no value is specified for this parameter, the current locale is used.

Return Value

Returns the property value expressed as a short value.

Remarks

If the resource set for the given locale does not contain the specified property, the parent chain is searched. If the property is contained within a parent resource set, then its value is returned; otherwise, 0 is returned.


 IResourceManager.getString

IResourceManager.getString

Retrieves a string for the specified property.

Syntax

public String getString( String name )

public String getString( Locale locale, String name )

Parameters

name

The name of the property.

locale

A Locale object that represents the locale to check. If no value is specified for this parameter, the current locale is used.

Return Value

Returns the property value expressed as a string.

Remarks

If the resource set for the given locale does not contain the specified property, the parent chain is searched. If the property is contained within a parent resource set, then its value is returned; otherwise, null is returned.


 IResourceManager.saveAllProperties

IResourceManager.saveAllProperties

Saves all properties for all locales to disk.

Syntax

public void saveAllProperties( String directory, String baseName )

Parameters

directory

The directory to save the resource files to.

baseName

The base name for all the resource files. This name should not include any file extension.

Remarks

The resource set for each locale is saved with a unique file name, using baseName and the default country name of the locale.


 IResourceManager.setProperty

IResourceManager.setProperty

Sets the value of the specified property.

Syntax

public void setProperty( String name, boolean value )

public void setProperty( Locale locale, String name, boolean value )

public void setProperty( String name, byte value )

public void setProperty( Locale locale, String name, byte value )

public void setProperty( String name, char value )

public void setProperty( Locale locale, String name, char value )

public void setProperty( String name, double value )

public void setProperty( Locale locale, String name, double value )

public void setProperty( String name, float value )

public void setProperty( Locale locale, String name, float value )

public void setProperty( String name, int value )

public void setProperty( Locale locale, String name, int value )

public void setProperty( String name, long value )

public void setProperty( Locale locale, String name, long value )

public void setProperty( String name, Object value )

public void setProperty( Locale locale, String name, Object value )

public void setProperty( String name, short value )

public void setProperty( Locale locale, String name, short value )

public void setProperty( String name, String value )

public void setProperty( Locale locale, String name, String value )

Parameters

name

The name of the property to set.

locale

A Locale object that represents the locale to use. If no value is specified for this parameter, the current locale is used.

value

The value to set the property to.


 IResourceManager.setResourceSet

IResourceManager.setResourceSet

Sets the resource set that will store the properties for the specified locale.

Syntax

public void setResourceSet( Locale locale, IResourceSet set )

Parameters

locale

A Locale object that represents the locale to use.

set

An IResourceSet object that will store the properties.

See Also getResourceSet


IResourceReader Interface

Defines an interface for reading a binary resource file.

package com.ms.wfc.core

public interface IResourceReader

Remarks

This interface defines the depersistProperties method, which reads the data from a resource file. Use the IResourceWriter.persistProperties method to write the resource data to a file.

Important Because the format of resource files may change, always use an implementation of IResourceReader to read the file and a compatible implementation of IResourceWriter to write the file. For example, you can use the ResourceReader and ResourceWriter classes.

See Also IResourceSet


 IResourceReader Methods

IResourceReader Methods

Methods | Description
depersistProperties | Reads all resource data from the specified stream.


 IResourceReader.depersistProperties

IResourceReader.depersistProperties

Reads all resource data from the specified stream.

Syntax

public IResourceSet depersistProperties( IDataStream stream )

Parameters

stream

An IDataStream object that contains the resource data.

Return Value

Returns an IResourceSet object that represents the resources that were read.

Remarks

To write the resource data to a file, use the IResourceWriter.persistProperties method.


IResourceSet Interface

Defines an interface for accessing named resource-based properties.

package com.ms.wfc.core

public interface IResourceSet

Remarks

A resouce set is associated with a specific resource writer that persists the resource data to a file. In turn, the resource writer is associated with a resource reader that reads the resource set from the file.

See Also IResourceReader, IResourceWriter, IResourceManager


 IResourceSet Methods

IResourceSet Methods

Methods | Description
contains | Determines whether the specified property is stored in the resource set.
getNames | Retrieves the names of all properties that are stored in the resource set.
getProperties | Retrieves the values of all properties that are stored in the resource set.
getProperty | Retrieves the value of the specified property.
getWriter | Retrieves the class of the resource writer that is used to write the properties to a file.
setProperty | Sets the value of the specified property.


 IResourceSet.contains

IResourceSet.contains

Determines whether the specified property is stored in the resource set.

Syntax

public boolean contains( String name )

Parameters

name

The name of the property.

Return Value

Returns true if the property is contained in the resource set; otherwise, returns false.


 IResourceSet.getNames

IResourceSet.getNames

Retrieves the names of all properties that are stored in the resource set.

Syntax

public String[] getNames()

Return Value

Returns an array containing the names of the properties in the resource set.

See Also getProperties


 IResourceSet.getProperties

IResourceSet.getProperties

Retrieves the values of all properties that are stored in the resource set.

Syntax

public Object[] getProperties()

Return Value

Returns an array containing the values of the properties in the resource set.

See Also getNames, getProperty


 IResourceSet.getProperty

IResourceSet.getProperty

Retrieves the value of the specified property.

Syntax

public Object getProperty( String name )

Parameters

name

The name of the property.

Return Value

Returns the property value. If the resource set does not contain a property with the specified name, null is returned.

See Also setProperty, getProperties


 IResourceSet.getWriter

IResourceSet.getWriter

Retrieves the class of the resource writer that is used to write the properties to a file.

Syntax

public Class getWriter()

Return Value

Returns the class of the associated resource writer. This class should implement the IResourceWriter interface.


 IResourceSet.setProperty

IResourceSet.setProperty

Sets the value of the specified property.

Syntax

public void setProperty( String name, Object value )

Parameters

name

The name of the property.

value

The new value for the property.

See Also getProperty


IResourceWriter Interface

Defines an interface for storing resource data to a file.

package com.ms.wfc.core

public interface IResourceWriter

Remarks

This interface defines the persistProperties method, which writes resource data to a binary file. Use the IResourceReader.depersistProperties method to read the resource file.

Important Because the format of resource files may change, always use an implementation of IResourceWriter to write the file and a compatible implementation of IResourceReader to read the file. For example, you can use the ResourceWriter and ResourceReader classes.

See Also IResourceSet


 IResourceWriter Methods

IResourceWriter Methods

Methods | Description
persistProperties | Writes the specified set of resources to a file.


 IResourceWriter.persistProperties

IResourceWriter.persistProperties

Writes the specified set of resources to a file.

Syntax

public void persistProperties( IDataStream data, IResourceSet properties )

Parameters

data

An IDataStream object that represents the data stream to write the resource data to.

properties

An IResourceSet object that represents the resources to be written to the data stream.

Remarks

To read the resource data from a file, use the IResourceReader.depersistProperties method.


IValueAccess Interface

Defines a callback interface for retrieving and setting a property value.

package com.ms.wfc.core

public interface IValueAccess

Remarks

This interface allows the editValue method of a value editor to retrieve and set a property value. The editValue method typically performs the following steps:

  • Calls IValueAccess.getValue to retrieve the value.
  • Presents a user interface to modify the value. (The IValueAccess.getService method can be used to access services to help display the user interface.)
  • Calls IValueAccess.setValue to set the new value.

See Also IValueEditor


 IValueAccess Methods

IValueAccess Methods

Methods | Description
getService | Retrieves a host service to assist the value editor in displaying a user interface.
getValue | Retrieves a value to be edited.
setValue | Sets a new value that is the result of the edit.


 IValueAccess.getService

IValueAccess.getService

Retrieves a host service to assist the value editor in displaying a user interface.

Syntax

public Object getService( Class serviceClass )

Parameters

serviceClass

An interface that represents the requested service. Currently, the only service available is IEditorHost, which can be obtained by passing IEditorHost.class for this parameter.

Return Value

Returns an object that implements the specified interface. If the service is not available, null is returned.

Remarks

This method is typically invoked by the value editor's editValue method to launch a modal dialog box or provide a drop-down list.


 IValueAccess.getValue

IValueAccess.getValue

Retrieves a value to be edited.

Syntax

public Object getValue()

Return Value

Returns an object that represents the value.

Remarks

This method is typically invoked by the value editor's editValue method.

See Also setValue


 IValueAccess.setValue

IValueAccess.setValue

Sets a new value that is the result of the edit.

Syntax

public void setValue( Object value )

Parameters

value

An object that represents the new value.

Remarks

This method is typically invoked by the value editor's editValue method.

See Also getValue


IValueEditor Interface

Defines the interface for a value editor.

package com.ms.wfc.core

public interface IValueEditor

Remarks

A value editor is used to edit property values in a property browser. A class typically defines a public static inner class named Editor, which in turn implements the IValueEditor interface. This type of implementation allows the value editor to be separated from the class itself in situations where the value editor is not required (such as when the class is deployed).

The following example shows a class named Color and its associated value editor:

public class Color
{
   ... // Members of class Color.

   public static class Editor implements IValueEditor
   {
      ... // Implementations of IValueEditor methods.
   }
}

When a class defines a value editor, the editor implementation is automatically inherited by subclasses that do not provide their own value editors.

A value editor is typically obtained through the ComponentManager class. The component manager looks for a constructor that takes a parameter of type java.lang.Class, which represents the type of value to be edited, or a constructor that takes no parameters. For either of these two constructors, the value editor is instantiated once and reused when needed.

Note If the value editor requires special knowledge about the component whose property is being edited, it can define a constructor that takes an IEditorSite object. This constructor takes precedence over the other two constructors, and the value editor is instantiated for each use.

The component manager also provides the ability to register value editors for a particular type; this is useful for value editors that are not implemented as inner classes.

The ValueEditor class provides a default implementation of the IValueEditor interface. Value editors can extend ValueEditor instead of implementing the entire IValueEditor interface. For a list of value editors defined by WFC, see Value Editor Classes.


 IValueEditor Methods

IValueEditor Methods

Methods | Description
editValue | Provides a user interface for editing the property value.
getConstantName | Retrieves the fully qualified name of a constant that represents the specified value.
getStyle | Retrieves the style flags for the value editor.
getSubProperties | Retrieves the subproperties of the specified value.
getTextFromValue | Converts the specified value to a text string.
getValueFromSubPropertyValues | Creates a value of this editor's type from the specified values.
getValueFromText | Converts the specified text string to a value.
getValues | Retrieves the common values for the editor's type.
paintValue | Paints a representation of the specified value.


 IValueEditor.editValue

IValueEditor.editValue

Provides a user interface for editing the property value.

Syntax

public void editValue( IValueAccess valueAccess )

Parameters

valueAccess

An object implementing the IValueAccess interface that is used to access and modify the property value.

Remarks

This method first calls valueAccess.getValue to retrieve the current property value. To then present a user interface for editing the value, valueAccess.getService is called to help launch a modal dialog box or provide a drop-down control. Finally, valueAccess.setValue is called to set the new property value.

See Also STYLE_EDITVALUE, STYLE_DROPDOWNARROW


 IValueEditor.getConstantName

IValueEditor.getConstantName

Retrieves the fully qualified name of a constant that represents the specified value.

Syntax

public String getConstantName( Object value )

Parameters

value

The value to retrieve the constant for.

Return Value

Returns the fully qualified class name, followed by a period, followed by the name of a public static final field in the class; for example, "com.ms.wfc.ui.Color.BLACK". If no constant represents the specified value, null is returned.

Remarks

This method is typically used by a design-time environment that generates source code to initialize a component's properties.


 IValueEditor.getStyle

IValueEditor.getStyle

Retrieves the style flags for the value editor.

Syntax

public int getStyle()

Return Value

Returns a bitwise combination of the STYLE_XXX fields defined in this interface.


 IValueEditor.getSubProperties

IValueEditor.getSubProperties

Retrieves the subproperties of the specified value.

Syntax

public SubProperty[] getSubProperties( Object value )

Parameters

value

The value to be decomposed.

Return Value

Returns an array of SubProperty objects that represent the subproperties.

Remarks

Subproperties represent values that together compose the specified value. Each of these subproperties can be edited by the user, and getValueFromSubPropertyValues will be called to determine whether a new set of subproperties can compose a new value of this editor's type.

The getSubProperties method is called only if the STYLE_PROPERTIES style is present.


 IValueEditor.getTextFromValue

IValueEditor.getTextFromValue

Converts the specified value to a text string.

Syntax

public String getTextFromValue( Object value )

Parameters

value

The value to be converted to text.

Return Value

Returns the string that represents the value. If the value cannot be converted to a text string, an empty string is returned.

See Also getValueFromText


 IValueEditor.getValueFromSubPropertyValues

IValueEditor.getValueFromSubPropertyValues

Creates a value of this editor's type from the specified values.

Syntax

public Object getValueFromSubPropertyValues( Object[] values )

Parameters

values

An array of values. This array is typically a modified version of the values contained in the subproperties returned by getSubProperties.

Return Value

Returns the object created from the array of values. If the object could not be created, null is returned.

Remarks

This method is called only if the STYLE_PROPERTIES style is present.


 IValueEditor.getValueFromText

IValueEditor.getValueFromText

Converts the specified text string to a value.

Syntax

public Object getValueFromText( String text )

Parameters

text

A string that represents the value.

Return Value

Returns the value represented by the string. If no value can be determined from the string, null is returned.

Remarks

If the value editor specifies the STYLE_NOEDITABLETEXT style, this method is called only with strings that were previously returned from getTextFromValue.


 IValueEditor.getValues

IValueEditor.getValues

Retrieves the common values for the editor's type.

Syntax

public Object[] getValues()

Return Value

Returns an array of values.

Remarks

To display these values in a drop-down list, a property browser typically calls getTextFromValue and paintValue for each of the values.


 IValueEditor.paintValue

IValueEditor.paintValue

Paints a representation of the specified value.

Syntax

public void paintValue( Object value, Graphics g, Rectangle rect )

Parameters

value

The value to be painted.

g

A Graphics object that represents the device context.

rect

A Rectangle object that represents the rectangle to paint in.

Remarks

This method is called only if the STYLE_PAINTVALUE style is present. Note that if you change any properties of the Graphics object (such as the font or color), you should reset them to their previous values before returning.


 IValueEditor Fields

IValueEditor Fields

Fields | Description
STYLE_DROPDOWNARROW | Specifies that the property browser should display a drop-down arrow for the property.
STYLE_EDITVALUE | Specifies that the property browser should display an ellipsis button for the property.
STYLE_IMMEDIATE | Specifies that changes made to the property should be displayed immediately.
STYLE_NOARRAYEXPANSION | Specifies that arrays should not be expanded in a property browser.
STYLE_NOARRAYMULTISELECT | Specifies that the property browser should not display an entry for the multiselection of array elements.
STYLE_NOEDITABLETEXT | Specifies that the value editor should not accept arbitrary text input.
STYLE_PAINTVALUE | Specifies that the property browser should paint a representation of the property.
STYLE_PROPERTIES | Specifies that a property can have subproperties that can be edited.
STYLE_SHOWFIELDS | Specifies that the property browser should show the public static final fields of the class being edited.
STYLE_VALUES | Specifies that a property browser should display a drop-down list for the property.


 IValueEditor.STYLE_DROPDOWNARROW

IValueEditor.STYLE_DROPDOWNARROW

Specifies that the property browser should display a drop-down arrow for the property.

Syntax

public static final int STYLE_DROPDOWNARROW;

Remarks

This style indicates that the value editor implements the editValue method. Typically, a property browser will display a drop-down arrow, which allows the value editor to use a drop-down control to edit the property.

See Also getStyle, STYLE_VALUES, STYLE_EDITVALUE


 IValueEditor.STYLE_EDITVALUE

IValueEditor.STYLE_EDITVALUE

Specifies that the property browser should display an ellipsis button for the property.

Syntax

public static final int STYLE_EDITVALUE;

Remarks

This style indicates that the value editor implements the editValue method. Typically, a property browser will display an ellipses button, which allows the value editor to launch a modal dialog box to edit the property.

See Also getStyle, STYLE_DROPDOWNARROW


 IValueEditor.STYLE_IMMEDIATE

IValueEditor.STYLE_IMMEDIATE

Specifies that changes made to the property should be displayed immediately.

Syntax

public static final int STYLE_IMMEDIATE;

Remarks

This style typically causes a property browser to update the property value after each change is made (such as when each character is typed in the property edit box).

See Also getStyle


 IValueEditor.STYLE_NOARRAYEXPANSION

IValueEditor.STYLE_NOARRAYEXPANSION

Specifies that arrays should not be expanded in a property browser.

Syntax

public static final int STYLE_NOARRAYEXPANSION;

See Also getStyle


 IValueEditor.STYLE_NOARRAYMULTISELECT

IValueEditor.STYLE_NOARRAYMULTISELECT

Specifies that the property browser should not display an entry for the multiselection of array elements.

Syntax

public static final int STYLE_NOARRAYMULTISELECT;

Remarks

This style prevents the property browser from displaying an "all" entry for arrays. Edits made on this entry affect all elements in the array.

See Also getStyle


 IValueEditor.STYLE_NOEDITABLETEXT

IValueEditor.STYLE_NOEDITABLETEXT

Specifies that the value editor should not accept arbitrary text input.

Syntax

public static final int STYLE_NOEDITABLETEXT;

Remarks

This style indicates that the value editor does not support arbitrary text passed to the getValueFromText method; it can only accept text returned from getTextFromValue. This style typically causes a property browser to disallow typing in the property's edit box.

See Also getStyle


 IValueEditor.STYLE_PAINTVALUE

IValueEditor.STYLE_PAINTVALUE

Specifies that the property browser should paint a representation of the property.

Syntax

public static final int STYLE_PAINTVALUE;

Remarks

This style indicates that the value editor implements the paintValue method.

See Also getStyle


 IValueEditor.STYLE_PROPERTIES

IValueEditor.STYLE_PROPERTIES

Specifies that a property can have subproperties that can be edited.

Syntax

public static final int STYLE_PROPERTIES;

See Also getStyle, getSubProperties


 IValueEditor.STYLE_SHOWFIELDS

IValueEditor.STYLE_SHOWFIELDS

Specifies that the property browser should show the public static final fields of the class being edited.

Syntax

public static final int STYLE_SHOWFIELDS;

See Also getStyle


 IValueEditor.STYLE_VALUES

IValueEditor.STYLE_VALUES

Specifies that a property browser should display a drop-down list for the property.

Syntax

public static final int STYLE_VALUES;

Remarks

This style indicates that the value editor implements the getValues method. This style typically causes a property browser to display a drop-down list of possible values.

See Also getStyle


MemberInfo Class

Represents the base class for property, event, and extender definitions.

package com.ms.wfc.core

public class MemberInfo

Remarks

The MemberInfo class is primarily used to store the attributes of PropertyInfo, EventInfo, and ExtenderInfo objects. All attributes must extend MemberAttribute.


 MemberInfo Methods

MemberInfo Methods

Constructors | Description
MemberInfo | Creates a MemberInfo object.

Methods | Description
getAttribute | Retrieves the first attribute in the attributes collection of the specified type.
getAttributes | Retrieves all attributes of the member.
getCategory | Retrieves the category of the member.
getDescription | Retrieves the description of the member.
getHelpTopic | Retrieves the help topic of the member.
getHelpURL | Retrieves the name of the help file of the member.
getName | Retrieves the name of the member.


 MemberInfo.getAttribute

MemberInfo.getAttribute

Retrieves the first attribute in the attributes collection of the specified type.

Syntax

public MemberAttribute getAttribute( Class attributeClass )

Parameters

attributeClass

The type of the attribute; for example, DefaultValueAttribute.class or LocalizableAttribute.class. (All attributes extend MemberAttribute.)

Return Value

Returns a MemberAttribute object that represents the attribute. If no attribute of the specified type is found, null is returned.

See Also getCategory, getDescription, getHelpURL, getHelpTopic


 MemberInfo.getAttributes

MemberInfo.getAttributes

Retrieves all attributes of the member.

Syntax

public MemberAttribute[] getAttributes()

Return Value

Returns an array of MemberAttribute objects that represent the attributes.

See Also getAttribute


 MemberInfo.getCategory

MemberInfo.getCategory

Retrieves the category of the member.

Syntax

public String getCategory()

Return Value

Returns the member's category. If the member does not have the category attribute, an empty string is returned.

Remarks

This method searches the member's attributes for an instance of CategoryAttribute. If one is found, the associated category name is returned.


 MemberInfo.getDescription

MemberInfo.getDescription

Retrieves the description of the member.

Syntax

public String getDescription()

Return Value

Returns the member's description. If the member does not have the description attribute, an empty string is returned.

Remarks

This method searches the member's attributes for an instance of DescriptionAttribute. If one is found, the associated description text is returned.


 MemberInfo.getHelpTopic

MemberInfo.getHelpTopic

Retrieves the help topic of the member.

Syntax

public String getHelpTopic()

Return Value

Returns the help topic for the member. If the member does not have the help attribute, an empty string is returned.

Remarks

This method searches the member's attributes for an instance of HelpAttribute. If one is found, the associated help topic is returned.

See Also getHelpURL


 MemberInfo.getHelpURL

MemberInfo.getHelpURL

Retrieves the name of the help file of the member.

Syntax

public String getHelpURL()

Return Value

Returns the help file name for the member. If the member does not have the help attribute, an empty string is returned.

Remarks

This method searches the member's attributes for an instance of HelpAttribute. If one is found, the associated help file name is returned.

See Also getHelpTopic


 MemberInfo.getName

MemberInfo.getName

Retrieves the name of the member.

Syntax

public String getName()

Return Value

Returns the member's name.


 MemberInfo.MemberInfo

MemberInfo.MemberInfo

Creates a MemberInfo object.

Syntax

public MemberInfo( String name, MemberAttribute[] attributes )

public MemberInfo( MemberInfo oldMemberInfo, MemberAttribute[] attributes )

Parameters

name

The name of the member.

attributes

An array of MemberAttribute objects that specify the attributes of the member.

oldMemberInfo

An existing MemberInfo object on which to base the new member.


PropertyInfo Class

Defines a property of a component.

MemberInfo
  |
  +--PropertyInfo

package com.ms.wfc.core

public class PropertyInfo
extends MemberInfo

Remarks

Properties allow you to set up the state of the component. The PropertyInfo class is used within the component's ClassInfo inner class. When you create a PropertyInfo object, you specify the component class, the name and type of the property, and the various attributes of the property. (Attributes can be specified using the classes that extend MemberAttribute.)

The following example shows a portion of the ClassInfo of the Control class:

public static class ClassInfo extends Component.ClassInfo {
   public static final PropertyInfo allowDrop = new PropertyInfo(
      Control.class, "allowDrop", boolean.class,
      CategoryAttribute.Behavior,
      DefaultValueAttribute.FALSE,
      new DescriptionAttribute(
    "Indicates whether the control receives drag drop notifications.")));

   public static final PropertyInfo anchor = new PropertyInfo(
      Control.class, "anchor", int.class,
      CategoryAttribute.Position,
      new ValueEditorAttribute(AnchorEditor.class),
      new DefaultValueAttribute(new Integer(ControlAnchor.TOP | ControlAnchor.LEFT)),
      new DescriptionAttribute("Specifies the anchor of the control."));

   public static final PropertyInfo backColor = new PropertyInfo(
      Control.class, "backColor", Color.class,
      CategoryAttribute.Appearance,
      new DescriptionAttribute("Specifies the background color."));

   public void getProperties(IProperties props) {
      super.getProperties(props);
      props.add(allowDrop);
      props.add(anchor);
      props.add(backColor);
   }
}

For a read-only property defined through PropertyInfo, the component class must implement the following method, which allows the property's value to be returned:

public <propertyType> get<PropertyName>()

For a read/write property, the component class must implement get<PropertyName> as well as the following method to set the property value:

public void set<PropertyName>( <propertyType> value )

Note A property name typically begins with a lowercase letter, while the case of the associated methods is mixed. For example, a read/write property named backColor is associated with getBackColor and setBackColor methods.

In addition to the get<PropertyName> and set<PropertyName> methods, the component class can optionally implement the following two methods:

public boolean shouldPersist<PropertyName>()

public void reset<PropertyName>()

These methods involve the property's default value, which is specified using DefaultValueAttribute. The shouldPersist<PropertyName> method returns true if the current value of the property is different than its default value, indicating that the value should be persisted. The reset<PropertyName> method resets the property to its default value.

If the PropertyInfo definition specifies a value editor (using ValueEditorAttribute), this value editor is used to edit the property. Otherwise, a system-provided value editor is used.

A PropertyInfo object can be obtained programmatically through the ComponentManager class.

See Also EventInfo, ExtenderInfo, Attribute Classes


 PropertyInfo Methods

PropertyInfo Methods

Constructors | Description
PropertyInfo | Creates a PropertyInfo object.

Methods | Description
canResetValue | Determines whether the value of the property can be reset.
getGetMethod | Retrieves the get<PropertyName> method of the component class.
getIsReadOnly | Determines whether the property is read-only.
getResetMethod | Retrieves the reset<PropertyName> method of the component class.
getSetMethod | Retrieves the set<PropertyName> method of the component class.
getShouldPersistMethod | Retrieves the shouldPersist<PropertyName> method of the component class.
getType | Retrieves the type of the property.
getValue | Retrieves the current value of the property.
getValueEditor | Retrieves the value editor of the property.
resetValue | Resets the value of the property.
setValue | Sets the value of the property.
shouldPersistValue | Determines whether the value of the property should be persisted.


 PropertyInfo.canResetValue

PropertyInfo.canResetValue

Determines whether the value of the property can be reset.

Syntax

public boolean canResetValue ( Object component )

Parameters

component

The component that defines the property.

Return Value

Returns true if the property value can be reset; otherwise, returns false.

Remarks

If a default value is specified in this PropertyInfo object and the value returned by getValue is different than the default value, canResetValue returns true. If there is no default value, canResetValue invokes and returns the value of the component's shouldPersist<PropertyName> method, if this method and the reset<PropertyName> method exist. (If only the reset<PropertyName> method exists, true is returned.) If none of these cases apply, false is returned.


 PropertyInfo.getGetMethod

PropertyInfo.getGetMethod

Retrieves the get<PropertyName> method of the component class.

Syntax

public Method getGetMethod()

Return Value

Returns the get<PropertyName> method.


 PropertyInfo.getIsReadOnly

PropertyInfo.getIsReadOnly

Determines whether the property is read-only.

Syntax

public boolean getIsReadOnly()

Return Value

Returns true if the component class has no set<ExtenderName> method; otherwise, returns false.


 PropertyInfo.getResetMethod

PropertyInfo.getResetMethod

Retrieves the reset<PropertyName> method of the component class.

Syntax

public Method getResetMethod()

Return Value

Returns the reset<PropertyName> method, if it exists; otherwise, returns null.


 PropertyInfo.getSetMethod

PropertyInfo.getSetMethod

Retrieves the set<PropertyName> method of the component class.

Syntax

public Method getSetMethod()

Return Value

Returns the set<PropertyName> method.


 PropertyInfo.getShouldPersistMethod

PropertyInfo.getShouldPersistMethod

Retrieves the shouldPersist<PropertyName> method of the component class.

Syntax

public Method getShouldPersistMethod()

Return Value

Returns the shouldPersist<PropertyName> method, if it exists; otherwise, returns null.


 PropertyInfo.getType

PropertyInfo.getType

Retrieves the type of the property.

Syntax

public Class getType()

Return Value

Returns the property type.


 PropertyInfo.getValue

PropertyInfo.getValue

Retrieves the current value of the property.

Syntax

public Object getValue( Object component )

Parameters

component

The component that defines the property.

Return Value

Returns the value of the property.

Remarks

This method invokes the component's get<PropertyName> method to retrieve the current property value.

See Also setValue


 PropertyInfo.getValueEditor

PropertyInfo.getValueEditor

Retrieves the value editor of the property.

Syntax

public IValueEditor getValueEditor()

public IValueEditor getValueEditor ( IEditorSite site )

Parameters

site

An object implementing the IEditorSite interface that represents the value editor site.

Return Value

Returns an object implementing the IValueEditor interface that represents the value editor for the property.

Remarks

If a value editor is specified in this PropertyInfo object, that editor is instantiated; otherwise, a system value editor is looked for. If there is no system value editor, null is returned.

Note Custom system value editors can be added through the ComponentManager.registerValueEditorClass method.


 PropertyInfo.PropertyInfo

PropertyInfo.PropertyInfo

Creates a PropertyInfo object.

Syntax

public PropertyInfo( Class componentClass, String name, Class type, MemberAttribute[] attributes )

public PropertyInfo( Class componentClass, String name, Class type )

public PropertyInfo( Class componentClass, String name, Class type, MemberAttribute a1 )

public PropertyInfo( Class componentClass, String name, Class type, MemberAttribute a1, MemberAttribute a2 )

public PropertyInfo( Class componentClass, String name, Class type, MemberAttribute a1, MemberAttribute a2, MemberAttribute a3 )

public PropertyInfo( Class componentClass, String name, Class type, MemberAttribute a1, MemberAttribute a2, MemberAttribute a3, MemberAttribute a4 )

public PropertyInfo( Class componentClass, String name, Class type, MemberAttribute a1, MemberAttribute a2, MemberAttribute a3, MemberAttribute a4, MemberAttribute a5 )

public PropertyInfo( Class componentClass, String name, Class type, MemberAttribute a1, MemberAttribute a2, MemberAttribute a3, MemberAttribute a4, MemberAttribute a5, MemberAttribute a6 )

public PropertyInfo( PropertyInfo oldPropertyInfo, MemberAttribute[] attributes )

public PropertyInfo( PropertyInfo oldPropertyInfo, MemberAttribute a1 )

public PropertyInfo( PropertyInfo oldPropertyInfo, MemberAttribute a1, MemberAttribute a2 )

public PropertyInfo( PropertyInfo oldPropertyInfo, MemberAttribute a1, MemberAttribute a2, MemberAttribute a3 )

public PropertyInfo( PropertyInfo oldPropertyInfo, MemberAttribute a1, MemberAttribute a2, MemberAttribute a3, MemberAttribute a4 )

Parameters

componentClass

The type of the component that defines the property.

name

The name of the property.

type

The type of the property.

attributes

An array of MemberAttribute objects that specify the attributes of the property.

a1, a2, a3, a4, a5, a6

A MemberAttribute object that specifies an attribute of the property.

oldPropertyInfo

An existing PropertyInfo object on which to base the new property.

Remarks

When you create a new property using an existing PropertyInfo object, the attributes of the existing property and those specified for the new property are combined. However, if an attribute of the existing property is of the same class as an attribute specified for the new property, the attribute for the new property takes precedence. For example, if you pass a PropertyInfo object that specifies DefaultValueAttribute.TRUE, but you also pass DefaultValueAttribute.FALSE, the new property is given the DefaultValueAttribute.FALSE attribute.

For an example that shows how to create a PropertyInfo object, see the PropertyInfo overview.


 PropertyInfo.resetValue

PropertyInfo.resetValue

Resets the value of the property.

Syntax

public void resetValue( Object component )

Parameters

component

The component that defines the property.

Remarks

If a default value is specified in this PropertyInfo object, the value of the property is set to the default value. If the property has no default value, this method invokes the component's reset<PropertyName> method, if it exists. (If both these routes fail, the property value remains unchanged.)


 PropertyInfo.setValue

PropertyInfo.setValue

Sets the value of the property.

Syntax

public void setValue( Object component, Object value )

Parameters

component

The component that defines the property.

value

The new value of the property.

Remarks

This method invokes the component's set<PropertyName> method, if it exists.

See Also getValue


 PropertyInfo.shouldPersistValue

PropertyInfo.shouldPersistValue

Determines whether the value of the property should be persisted.

Syntax

public boolean shouldPersistValue( Object component )

Parameters

component

The component that defines the property.

Return Value

Returns true if the property should be persisted; otherwise, returns false.

Remarks

This method determines whether the state of the property is different from when the component was first instantiated. If a default value is specified in this PropertyInfo object, it is compared against the property's current value. If there is no default value, this method invokes and returns the value of the component's shouldPersist<PropertyName> method, if it exists. If both these routes fail, true is returned.


ResourceManager Class

Manages resource data.

package com.ms.wfc.core

public class ResourceManager
implements IPersistable , IResourceManager

Remarks

This class is used to retrieve and store resource data in a locale-specific manner, allowing localizable applications to be created.


 ResourceManager Methods

ResourceManager Methods

Constructors | Description
ResourceManager | Creates a ResourceManager object.

Methods | Description
containsProperty | Determines whether the specified property is stored for a given locale.
flush | Releases any cached resource data.
getBaseName | Retrieves the base name of the resource files.
getBoolean | Retrieves a boolean value for the specified property.
getByte | Retrieves a byte value for the specified property.
getChar | Retrieves a character for the specified property.
getDouble | Retrieves a double value for the specified property.
getExtension | Retrieves the extension for resource file names.
getFloat | Retrieves a float value for the specified property.
getInt | Retrieves an integer for the specified property.
getLocaleFileNameFromBase | Determines the localized name of a resource file.
getLong | Retrieves a long value for the specified property.
getNames | Retrieves the names of all properties for a given locale.
getObject | Retrieves the value of the specified property.
getProperties | Retrieves the values of all properties for a given locale.
getProperty | Retrieves the value of the specified property for the current locale.
getResource | Loads a binary resource file for the specified class.
getResourceLoader | Retrieves the resource loader associated with this resource manager.
getResourceSet | Retrieves the resource set that is storing the properties for the specified locale.
getShort | Retrieves a short value for the specified property.
getString | Retrieves a string for the specified property.
getValidData | Determines whether the specified value can be stored as a resource property.
save | Saves this resource manager to a stream.
saveAllProperties | Saves all properties for all locales to disk.
setBaseName | Sets the base name of the resource files.
setProperty | Sets the value of the specified property.
setResourceLoader | Sets the resource loader to be associated with this resource manager.
setResourceSet | Sets the resource set that will store the properties for the specified locale.


 ResourceManager.containsProperty

ResourceManager.containsProperty

Determines whether the specified property is stored for a given locale.

Syntax

public boolean containsProperty( String name )

public boolean containsProperty( Locale locale, String name )

Parameters

name

The name of the property.

locale

A Locale object that represents the locale to check. If no value is specified for this parameter, the current locale is used.

Return Value

Returns true if the property is contained by the resource manager; otherwise, returns false.


 ResourceManager.flush

ResourceManager.flush

Releases any cached resource data.

Syntax

public void flush()


 ResourceManager.getBaseName

ResourceManager.getBaseName

Retrieves the base name of the resource files.

Syntax

public String getBaseName()

Return Value

Returns the base name of the resource files. If no base file name is associated with this resource manager, an empty string is returned.

See Also setBaseName


 ResourceManager.getBoolean

ResourceManager.getBoolean

Retrieves a boolean value for the specified property.

Syntax

public boolean getBoolean( String name )

public boolean getBoolean( Locale locale, String name )

Parameters

name

The name of the property.

locale

A Locale object that represents the locale to check. If no value is specified for this parameter, the current locale is used.

Return Value

Returns the property value expressed as a boolean value.

Remarks

If the resource set for the given locale does not contain the specified property, the parent chain is searched. If the property is contained within a parent resource set, then its value is returned; otherwise, false is returned.


 ResourceManager.getByte

ResourceManager.getByte

Retrieves a byte value for the specified property.

Syntax

public byte getByte( String name )

public byte getByte( Locale locale, String name )

Parameters

name

The name of the property.

locale

A Locale object that represents the locale to check. If no value is specified for this parameter, the current locale is used.

Return Value

Returns the property value expressed as a byte value.

Remarks

If the resource set for the given locale does not contain the specified property, the parent chain is searched. If the property is contained within a parent resource set, then its value is returned; otherwise, 0 is returned.


 ResourceManager.getChar

ResourceManager.getChar

Retrieves a character for the specified property.

Syntax

public char getChar( String name )

public char getChar( Locale locale, String name )

Parameters

name

The name of the property.

locale

A Locale object that represents the locale to check. If no value is specified for this parameter, the current locale is used.

Return Value

Returns the property value expressed as a char value.

Remarks

If the resource set for the given locale does not contain the specified property, the parent chain is searched. If the property is contained within a parent resource set, then its value is returned; otherwise, 0 is returned.


 ResourceManager.getDouble

ResourceManager.getDouble

Retrieves a double value for the specified property.

Syntax

public double getDouble( String name )

public double getDouble( Locale locale, String name )

Parameters

name

The name of the property.

locale

A Locale object that represents the locale to check. If no value is specified for this parameter, the current locale is used.

Return Value

Returns the property value expressed as a double value.

Remarks

If the resource set for the given locale does not contain the specified property, the parent chain is searched. If the property is contained within a parent resource set, then its value is returned; otherwise, 0.0 is returned.


 ResourceManager.getExtension

ResourceManager.getExtension

Retrieves the extension for resource file names.

Syntax

public String getExtension()

Return Value

Returns the value of the EXTENSION field.


 ResourceManager.getFloat

ResourceManager.getFloat

Retrieves a float value for the specified property.

Syntax

public float getFloat( String name )

public float getFloat( Locale locale, String name )

Parameters

name

The name of the property.

locale

A Locale object that represents the locale to check. If no value is specified for this parameter, the current locale is used.

Return Value

Returns the property value expressed as a float value.

Remarks

If the resource set for the given locale does not contain the specified property, the parent chain is searched. If the property is contained within a parent resource set, then its value is returned; otherwise, 0.0 is returned.


 ResourceManager.getInt

ResourceManager.getInt

Retrieves an integer for the specified property.

Syntax

public int getInt( String name )

public int getInt( Locale locale, String name )

Parameters

name

The name of the property.

locale

A Locale object that represents the locale to check. If no value is specified for this parameter, the current locale is used.

Return Value

Returns the property value expressed as an int value.

Remarks

If the resource set for the given locale does not contain the specified property, the parent chain is searched. If the property is contained within a parent resource set, then its value is returned; otherwise, 0 is returned.


 ResourceManager.getLocaleFileNameFromBase

ResourceManager.getLocaleFileNameFromBase

Determines the localized name of a resource file.

Syntax

public final static String getLocaleFileNameFromBase( Locale locale, String baseName )

Parameters

locale

A Locale object that represents the locale to use.

baseName

The base name of the resource file. For example, the base name of the files "MyResource_enu.resources" and "MyResource_jpn.resources" is "MyResource".

Return Value

Returns the localized file name, including the file extension. For example, "MyResource_enu.resources" and "MyResource_jpn.resources" represent localized file names given the base name "MyResource".


 ResourceManager.getLong

ResourceManager.getLong

Retrieves a long value for the specified property.

Syntax

public long getLong( String name )

public long getLong( Locale locale, String name )

Parameters

name

The name of the property.

locale

A Locale object that represents the locale to check. If no value is specified for this parameter, the current locale is used.

Return Value

Returns the property value expressed as a long value.

Remarks

If the resource set for the given locale does not contain the specified property, the parent chain is searched. If the property is contained within a parent resource set, then its value is returned; otherwise, 0 is returned.


 ResourceManager.getNames

ResourceManager.getNames

Retrieves the names of all properties for a given locale.

Syntax

public String[] getNames()

public String[] getNames( Locale locale )

Parameters

locale

A Locale object that represents the locale to check. If no value is specified for this parameter, the current locale is used.

Return Value

Returns an array containing all names stored for the specified locale.

See Also getProperties


 ResourceManager.getObject

ResourceManager.getObject

Retrieves the value of the specified property.

Syntax

public Object getObject( String name )

public Object getObject( Locale locale, String name )

Parameters

name

The name of the property.

locale

A Locale object that represents the locale to check. If no value is specified for this parameter, the current locale is used.

Return Value

Returns an Object that represents the property value.

Remarks

If the resource set for the given locale does not contain the specified property, the parent chain is searched. If the property is contained within a parent resource set, then its value is returned; otherwise, null is returned.


 ResourceManager.getProperties

ResourceManager.getProperties

Retrieves the values of all properties for a given locale.

Syntax

public Object[] getProperties()

public Object[] getProperties( Locale locale )

Parameters

locale

A Locale object that represents the locale to check. If no value is specified for this parameter, the current locale is used.

Return Value

Returns an Object array containing all values stored for the specified locale.

See Also getNames


 ResourceManager.getProperty

ResourceManager.getProperty

Retrieves the value of the specified property for the current locale.

Syntax

public Object getProperty( String name )

Parameters

name

The name of the property.

Return Value

Returns an Object that represents the property value.

Remarks

If the resource set for the current locale does not contain the specified property, the parent chain is searched. If the property is contained within a parent resource set, then its value is returned; otherwise, null is returned.

See Also getObject, setProperty


 ResourceManager.getResource

ResourceManager.getResource

Loads a binary resource file for the specified class.

Syntax

public static IDataStream getResource( Class src, String name )

Parameters

src

The class to load the resource for.

name

The name of the resource to be loaded.

Return Value

Returns an IDataStream object that contains the specified resource.

Remarks

This method does not load a resource property file, but rather a stand-alone binary file that is a resource for the specified class.


 ResourceManager.getResourceLoader

ResourceManager.getResourceLoader

Retrieves the resource loader associated with this resource manager.

Syntax

public IResourceLoader getResourceLoader()

Return Value

Returns an IResourceLoader object that represents the resource loader.

See Also setResourceLoader


 ResourceManager.getResourceSet

ResourceManager.getResourceSet

Retrieves the resource set that is storing the properties for the specified locale.

Syntax

public final IResourceSet getResourceSet( Locale locale )

Parameters

locale

A Locale object that represents the locale to check.

Return Value

Returns the IResourceSet object that is storing the properties.

See Also setResourceSet


 ResourceManager.getShort

ResourceManager.getShort

Retrieves a short value for the specified property.

Syntax

public short getShort( String name )

public short getShort( Locale locale, String name )

Parameters

name

The name of the property.

locale

A Locale object that represents the locale to check. If no value is specified for this parameter, the current locale is used.

Return Value

Returns the property value expressed as a short value.

Remarks

If the resource set for the given locale does not contain the specified property, the parent chain is searched. If the property is contained within a parent resource set, then its value is returned; otherwise, 0 is returned.


 ResourceManager.getString

ResourceManager.getString

Retrieves a string for the specified property.

Syntax

public String getString( String name )

public String getString( Locale locale, String name )

Parameters

name

The name of the property.

locale

A Locale object that represents the locale to check. If no value is specified for this parameter, the current locale is used.

Return Value

Returns the property value expressed as a string.

Remarks

If the resource set for the given locale does not contain the specified property, the parent chain is searched. If the property is contained within a parent resource set, then its value is returned; otherwise, null is returned.


 ResourceManager.getValidData

ResourceManager.getValidData

Determines whether the specified value can be stored as a resource property.

Syntax

public static boolean getValidData( Object value )

Parameters

value

The value to check.

Return Value

Returns true if the value can be stored in a resource file; otherwise, returns false.


 ResourceManager.ResourceManager

ResourceManager.ResourceManager

Creates a ResourceManager object.

Syntax

public ResourceManager()

public ResourceManager( IResourceLoader loader, String baseName )

Parameters

loader

An IResourceLoader object that will retrieve the resource data.

baseName

The base name of the resource files. For example, the base name of the files "MyResource_enu.resources" and "MyResource_jpn.resources" is "MyResource".


 ResourceManager.save

ResourceManager.save

Saves this resource manager to a stream.

Syntax

public void save( IDataStream stream )

Parameters

stream

An IDataStream object to save the resource manager to.


 ResourceManager.saveAllProperties

ResourceManager.saveAllProperties

Saves all properties for all locales to disk.

Syntax

public void saveAllProperties( String directory, String baseName )

Parameters

directory

The directory to save the resource files to.

baseName

The base name for all the resource files. This name should not include any file extension.

Remarks

The resource set for each locale is saved with a unique file name, using baseName and the default country name of the locale.


 ResourceManager.setBaseName

ResourceManager.setBaseName

Sets the base name of the resource files.

Syntax

public void setBaseName( String value )

Parameters

value

The base name of the resource files. For example, the base name of the files "MyResource_enu.resources" and "MyResource_jpn.resources" is "MyResource".

See Also getBaseName


 ResourceManager.setProperty

ResourceManager.setProperty

Sets the value of the specified property.

Syntax

public void setProperty( String name, boolean value )

public void setProperty( Locale locale, String name, boolean value )

public void setProperty( String name, byte value )

public void setProperty( Locale locale, String name, byte value )

public void setProperty( String name, char value )

public void setProperty( Locale locale, String name, char value )

public void setProperty( String name, double value )

public void setProperty( Locale locale, String name, double value )

public void setProperty( String name, float value )

public void setProperty( Locale locale, String name, float value )

public void setProperty( String name, int value )

public void setProperty( Locale locale, String name, int value )

public void setProperty( String name, long value )

public void setProperty( Locale locale, String name, long value )

public void setProperty( String name, Object value )

public void setProperty( Locale locale, String name, Object value )

public void setProperty( String name, short value )

public void setProperty( Locale locale, String name, short value )

public void setProperty( String name, String value )

public void setProperty( Locale locale, String name, String value )

Parameters

name

The name of the property to set.

locale

A Locale object that represents the locale to use. If no value is specified for this parameter, the current locale is used.

value

The value to set the property to.


 ResourceManager.setResourceLoader

ResourceManager.setResourceLoader

Sets the resource loader to be associated with this resource manager.

Syntax

public void setResourceLoader( IResourceLoader value )

Parameters

value

An IResourceLoader object that represents the resource loader to use.

See Also getResourceLoader


 ResourceManager.setResourceSet

ResourceManager.setResourceSet

Sets the resource set that will store the properties for the specified locale.

Syntax

public final synchronized void setResourceSet( Locale locale, IResourceSet newSet )

Parameters

locale

A Locale object that represents the locale to use.

newSet

An IResourceSet object that will store the properties.

See Also getResourceSet


 ResourceManager Fields

ResourceManager Fields

Fields | Description
EXTENSION | Specifies the extension of all resource files.


 ResourceManager.EXTENSION

ResourceManager.EXTENSION

Specifies the extension of all resource files.

Syntax

public static final String EXTENSION;

Remarks

By default, this constant is set to "resources".


ResourceReader Class

Reads a binary resource file.

package com.ms.wfc.core

public final class ResourceReader
implements IResourceReader

Remarks

Because the format of resource files may change, always use the ResourceWriter class in conjunction with ResourceReader. This ensures that the implementation to read the resource file is compatible with the implementation to write it.

See Also IResourceSet


 ResourceReader Methods

ResourceReader Methods

Methods | Description
depersistProperties | Reads all resource data from the specified stream.


 ResourceReader.depersistProperties

ResourceReader.depersistProperties

Reads all resource data from the specified stream.

Syntax

public synchronized IResourceSet depersistProperties( IDataStream stream )

Parameters

stream

An IDataStream object that contains the resource data.

Return Value

Returns an IResourceSet object that represents the resources that were read.

Remarks

To write the resource data to a file, use the ResourceWriter.persistProperties method.


ResourceSet Class

Represents a set of named resource-based properties.

package com.ms.wfc.core

public class ResourceSet
implements IResourceSet

Remarks

This class is used by ResourceReader and ResourceWriter to read and write a resource file.

See Also ResourceManager


 ResourceSet Methods

ResourceSet Methods

Constructors | Description
ResourceSet | Creates a ResourceSet object.

Methods | Description
contains | Determines whether the specified property is stored in the resource set.
getNames | Retrieves the names of all properties that are stored in the resource set.
getProperties | Retrieves the values of all properties that are stored in the resource set.
getProperty | Retrieves the value of the specified property.
getWriter | Retrieves the class of the resource writer that is used to write the properties to a file.
setProperty | Sets the value of the specified property.


 ResourceSet.contains

ResourceSet.contains

Determines whether the specified property is stored in the resource set.

Syntax

public boolean contains( String name )

Parameters

name

The name of the property.

Return Value

Returns true if the property is contained in the resource set; otherwise, returns false.


 ResourceSet.getNames

ResourceSet.getNames

Retrieves the names of all properties that are stored in the resource set.

Syntax

public synchronized String[] getNames()

Return Value

Returns an array containing the names of the properties in the resource set.

See Also getProperties


 ResourceSet.getProperties

ResourceSet.getProperties

Retrieves the values of all properties that are stored in the resource set.

Syntax

public synchronized Object[] getProperties()

Return Value

Returns an array containing the values of the properties in the resource set.

See Also getNames, getProperty


 ResourceSet.getProperty

ResourceSet.getProperty

Retrieves the value of the specified property.

Syntax

public Object getProperty( String name )

Parameters

name

The name of the property.

Return Value

Returns the property value. If the resource set does not contain a property with the specified name, null is returned.

See Also setProperty, getProperties


 ResourceSet.getWriter

ResourceSet.getWriter

Retrieves the class of the resource writer that is used to write the properties to a file.

Syntax

public Class getWriter()

Return Value

Returns the class of the associated resource writer. This class should implement the IResourceWriter interface.


 ResourceSet.ResourceSet

ResourceSet.ResourceSet

Creates a ResourceSet object.

Syntax

public ResourceSet()

public ResourceSet( HashTable ht )

public ResourceSet( HashTable ht, boolean ownHashTable )

Parameters

ht

A HashTable object that contains the resource data.

ownHashTable

Set to true to store and retrieve data from the ht parameter; set to false to simply copy data from ht. If no value is specified for the ownHashTable parameter, the data from ht is copied.


 ResourceSet.setProperty

ResourceSet.setProperty

Sets the value of the specified property.

Syntax

public void setProperty( String name, Object value )

Parameters

name

The name of the property.

value

The new value for the property.

See Also getProperty


ResourceWriter Class

Stores resource data to a file.

package com.ms.wfc.core

public final class ResourceWriter
implements IResourceWriter

Remarks

Because the format of resource files may change, always use the ResourceReader class in conjunction with ResourceWriter. This ensures that the implementation to write to the resource file is compatible with the implementation to read it.

See Also IResourceSet


 ResourceWriter Methods

ResourceWriter Methods

Methods | Description
persistProperties | Writes the specified set of resources to a file.


 ResourceWriter.persistProperties

ResourceWriter.persistProperties

Writes the specified set of resources to a file.

Syntax

public void persistProperties( IDataStream data, IResourceSet properties )

Parameters

data

An IDataStream object that represents the data stream to write the resource data to.

properties

An IResourceSet object that represents the resources to be written to the data stream.

Remarks

To read the resource data from a file, use the ResourceReader.depersistProperties method.


SubProperty Class

Represents a subproperty of a property value.

package com.ms.wfc.core

public class SubProperty

Remarks

Subproperties represent the decomposition of a property value by its value editor. Subproperties are typically used when the property value cannot be altered, but has various styles that are set through its constructor.


 SubProperty Methods

SubProperty Methods

Constructors | Description
SubProperty | Creates a SubProperty object.

Methods | Description
getName | Retrieves the name of the subproperty.
getType | Retrieves the class type of the subproperty.
getValue | Retrieves the value of the subproperty.
getValueEditorClass | Retrieves the value editor for the subproperty.


 SubProperty.getName

SubProperty.getName

Retrieves the name of the subproperty.

Syntax

public String getName()

Return Value

Returns the subproperty name.


 SubProperty.getType

SubProperty.getType

Retrieves the class type of the subproperty.

Syntax

public Class getType()

Return Value

Returns the property type.


 SubProperty.getValue

SubProperty.getValue

Retrieves the value of the subproperty.

Syntax

public Object getValue()

Return Value

Returns an object that represents the value.


 SubProperty.getValueEditorClass

SubProperty.getValueEditorClass

Retrieves the value editor for the subproperty.

Syntax

public Class getValueEditorClass()

Return Value

Returns the value editor assigned during construction, or null if the standard value editor is used.


 SubProperty.SubProperty

SubProperty.SubProperty

Creates a SubProperty object.

Syntax

public SubProperty( String name, Class type, Object value, Class valueEditorClass )

public SubProperty( String name, Class type, Object value )

Parameters

name

The name of the subproperty.

type

The type of the subproperty.

value

The value of the subproperty.

valueEditorClass

The value editor for the subproperty. If no value is specified for this parameter, the standard value editor is used. For more information about value editors, see IValueEditor.

Remarks

A visual designer can use subproperties to customize immutable values.


ValueEditor Class

Represents the base class for value editors.

package com.ms.wfc.core

public class ValueEditor
implements IValueEditor

Remarks

This class provides a default implementation of the IValueEditor interface. A value editor is used to edit property values in a property browser. A class typically defines a public static inner class named Editor, which either extends ValueEditor or directly implements IValueEditor. For more information, see the IValueEditor overview.

See Also Value Editor Classes


 ValueEditor Methods

ValueEditor Methods

Methods | Description
editValue | Provides a user interface for editing the property value.
getConstantName | Retrieves the fully qualified name of a constant that represents the specified value.
getStyle | Retrieves the style flags for the value editor.
getSubProperties | Retrieves the subproperties of the specified value.
getTextFromValue | Converts the specified value to a text string.
getValueFromSubPropertyValues | Creates a value of this editor's type from the specified values.
getValueFromText | Converts the specified text string to a value.
getValues | Retrieves the common values for the editor's type.
paintValue | Paints a representation of the specified value.


 ValueEditor.editValue

ValueEditor.editValue

Provides a user interface for editing the property value.

Syntax

public void editValue( IValueAccess valueAccess )

Parameters

valueAccess

An object implementing the IValueAccess interface that is used to access and modify the property value.

Remarks

Override this method to launch a modal dialog box or provide a drop-down control to edit the property. For more information, see IValueEditor.editValue.


 ValueEditor.getConstantName

ValueEditor.getConstantName

Retrieves the fully qualified name of a constant that represents the specified value.

Syntax

public String getConstantName( Object value )

Parameters

value

The value to retrieve the constant for.

Return Value

Returns null by default.

Remarks

Override this method to return the fully qualified constant name. For more information, see IValueEditor.getConstantName.


 ValueEditor.getStyle

ValueEditor.getStyle

Retrieves the style flags for the value editor.

Syntax

public int getStyle()

Return Value

Returns 0 by default.

Remarks

Override this method to return a bitwise combination of the STYLE_XXX fields defined in the IValueEditor interface.


 ValueEditor.getSubProperties

ValueEditor.getSubProperties

Retrieves the subproperties of the specified value.

Syntax

public SubProperty[] getSubProperties( Object value )

Parameters

value

The value to be decomposed.

Return Value

Returns null by default.

Remarks

Subproperties represent values that together compose the specified value. Override this method to return the value's subproperties. For more information, see IValueEditor.getSubProperties.


 ValueEditor.getTextFromValue

ValueEditor.getTextFromValue

Converts the specified value to a text string.

Syntax

public String getTextFromValue( Object value )

Parameters

value

The value to be converted to text.

Return Value

Returns the string that represents the value. If the value parameter is null, an empty string is returned.

See Also getValueFromText


 ValueEditor.getValueFromSubPropertyValues

ValueEditor.getValueFromSubPropertyValues

Creates a value of this editor's type from the specified values.

Syntax

public Object getValueFromSubPropertyValues( Object[] values )

Parameters

values

An array of values. This array is typically a modified version of the values contained in the subproperties returned by getSubProperties.

Return Value

Returns null by default.

Remarks

Override this method to create and return a value created from the subproperties. This method is called only if the STYLE_PROPERTIES style is present.

See Also IValueEditor.STYLE_PROPERTIES


 ValueEditor.getValueFromText

ValueEditor.getValueFromText

Converts the specified text string to a value.

Syntax

public Object getValueFromText( String text )

Parameters

text

A string that represents the value.

Return Value

Returns null by default.

Remarks

Override this method to convert the string to a value. If the value editor specifies the IValueEditor.STYLE_NOEDITABLETEXT style, this method is called only with strings that were previously returned from getTextFromValue.


 ValueEditor.getValues

ValueEditor.getValues

Retrieves the common values for the editor's type.

Syntax

public Object[] getValues()

Return Value

Returns null by default.

Remarks

Override this method to retrieve the possible values. To display these values in a drop-down list, a property browser typically calls getTextFromValue and paintValue for each of the values.


 ValueEditor.paintValue

ValueEditor.paintValue

Paints a representation of the specified value.

Syntax

public void paintValue( Object value, Graphics g, Rectangle rect )

Parameters

value

The value to be painted.

g

A Graphics object that represents the device context.

rect

A Rectangle object that represents the rectangle to paint in.

Remarks

Override this method to paint the value. This method is called only if the IValueEditor.STYLE_PAINTVALUE style is present.


VerbExecuteEvent Class

Provides data for the verbExecute event.

Event
  |
  +--VerbExecuteEvent

package com.ms.wfc.core

public final class VerbExecuteEvent
extends Event

Remarks

A verb is a command that appears on a shortcut menu when the user right-clicks a component. The verbExecute event then occurs when the user selects a verb on the shortcut menu.

For information about the WFC event model, see Handling Events in WFC.

See Also CustomizerVerb, ICustomizer


 VerbExecuteEvent Methods

VerbExecuteEvent Methods

Constructors | Description
VerbExecuteEvent | Creates a VerbExecuteEvent object.


 VerbExecuteEvent.VerbExecuteEvent

VerbExecuteEvent.VerbExecuteEvent

Creates a VerbExecuteEvent object.

Syntax

public VerbExecuteEvent( Object data )

Parameters

data

The user-defined data associated with the verb that was executed.


 VerbExecuteEvent Fields

VerbExecuteEvent Fields

Fields | Description
data | Specifies the user-defined data associated with the verb that was executed.


 VerbExecuteEvent.data

VerbExecuteEvent.data

Specifies the user-defined data associated with the verb that was executed.

Syntax

public final Object data;


VerbExecuteEventHandler Delegate

Identifies the method that will handle the verbExecute event.

package com.ms.wfc.core

public multicast delegate
void VerbExecuteEventHandler( Object sender, VerbExecuteEvent e );

Remarks

A verb is a command that appears on a shortcut menu when the user right-clicks a component. The verbExecute event then occurs when the user selects a verb on the shortcut menu.

The syntax of the VerbExecuteEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a VerbExecuteEvent object that provides information about the event.

When you create an VerbExecuteEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC.


WFCException Class

Represents the WFC base exception class.

java.lang.RuntimeException
  |
  +--WFCException

package com.ms.wfc.core

public class WFCException
extends RuntimeException

Remarks

All WFC exceptions extend WFCException. Each WFCException object is associated with an inner exception, which allows the creation of exception trees. Call getBaseException to return the lowest exception in the hierarchy.


 WFCException Methods

WFCException Methods

Constructors | Description
WFCException | Creates a WFCException object.

Methods | Description
getBaseException | Retrieves the lowest, inner-most exception for the specified exception.
getStackTrace | Retrieves the stack trace for the specified exception.
printStackTrace | Prints the stack trace of the WFCException object.
rethrowException | Rethrows an exception, wrapping it in a WFCException object.
toString | Retrieves the string representation of the WFCException object.


 WFCException.getBaseException

WFCException.getBaseException

Retrieves the lowest, inner-most exception for the specified exception.

Syntax

public static final Throwable getBaseException( Throwable e )

Parameters

e

The exception to find the base exception for.

Return Value

Returns the base exception.

Remarks

This method traverses the exception hierarchy tree, using the inner exceptions of WFCException objects. getBaseException also looks for java.lang.ExceptionInInitializerError and java.lang.reflect.InvocationTargetException objects that may also contain exceptions.


 WFCException.getStackTrace

WFCException.getStackTrace

Retrieves the stack trace for the specified exception.

Syntax

public static final String getStackTrace( Throwable e )

Parameters

e

The exception to retrieve the stack trace for.

Return Value

Returns a string specifying the call stack.


 WFCException.printStackTrace

WFCException.printStackTrace

Prints the stack trace of the WFCException object.

Syntax

public void printStackTrace()

public void printStackTrace( PrintStream stream )

public void printStackTrace( PrintWriter writer )

Parameters

stream

A java.io.PrintStream object to print the stack trace to.

writer

A java.io.PrintWriter object to print the stack trace to.


 WFCException.rethrowException

WFCException.rethrowException

Rethrows an exception, wrapping it in a WFCException object.

Syntax

public static final void rethrowException( Throwable e )

public static final void rethrowException( String message, Throwable e )

Parameters

e

The exception to be rethrown.

message

The message to be displayed when the exception is rethrown. If no message is specified, the message associated with the e parameter is displayed.

Remarks

The first version of this method uses the message associated with the exception being rethrown. The exception being rethrown is not wrapped in a WFCException object if it is already of type WFCException or is a subclass of java.lang.RuntimeException.


 WFCException.toString

WFCException.toString

Retrieves the string representation of the WFCException object.

Syntax

public String toString()

Return Value

Returns a description of this exception. This string indicates the full hierarchy of inner exceptions.


 WFCException.WFCException

WFCException.WFCException

Creates a WFCException object.

Syntax

public WFCException()

public WFCException( String message )

public WFCException( String message, Throwable innerException )

public WFCException( Throwable innerException )

Parameters

message

The message to be displayed when this exception is thrown.

innerException

The inner exception to be associated with this exception.

Remarks

The fourth version of the constructor uses the message of the inner exception.


 WFCException Fields

WFCException Fields

Fields | Description
innerException | The inner exception associated with the WFCException object.


 WFCException.innerException

WFCException.innerException

The inner exception associated with the WFCException object.

Syntax

public final Throwable innerException;

See Also java.lang.Throwable


WFCInvalidArgumentException Class

Represents an exception for invalid arguments.

WFCException
  |
  +--WFCInvalidArgumentException

package com.ms.wfc.core

public class WFCInvalidArgumentException
extends WFCException


 WFCInvalidArgumentException Methods

WFCInvalidArgumentException Methods

Constructors | Description
WFCInvalidArgumentException | Creates a WFCInvalidArgumentException object.


 WFCInvalidArgumentException.WFCInvalidArgumentException

WFCInvalidArgumentException.WFCInvalidArgumentException

Creates a WFCInvalidArgumentException object.

Syntax

public WFCInvalidArgumentException()

public WFCInvalidArgumentException( String message )

Parameters

message

The message to be displayed when the exception is thrown.


WFCInvalidEnumException Class

Represents an exception for invalid arguments that are enumerators.

WFCException
  |
  +--WFCInvalidArgumentException
       |
       +--WFCInvalidEnumException

package com.ms.wfc.core

public class WFCInvalidEnumException
extends WFCInvalidArgumentException

See Also Enum


 WFCInvalidEnumException Methods

WFCInvalidEnumException Methods

Constructors | Description
WFCInvalidEnumException | Creates a WFCInvalidEnumException object.


 WFCInvalidEnumException.WFCInvalidEnumException

WFCInvalidEnumException.WFCInvalidEnumException

Creates a WFCInvalidEnumException object.

Syntax

public WFCInvalidEnumException()

public WFCInvalidEnumException( String message )

public WFCInvalidEnumException( String argumentName, int invalidValue, Class enumClass )

Parameters

message

The message to be displayed when the exception is thrown.

argumentName

The name of the argument that caused the exception.

invalidValue

The value of the argument that caused the exception.

enumClass

The class that extends Enum and contains the valid values.

Remarks

The third version of the constructor will have a localized message that says argumentName is invalid because its value is invalidValue and the value should be from enumClass.


WFCInvalidPropertyValue Class

Represents an exception for invalid property values.

WFCException
  |
  +--WFCInvalidPropertyValue

package com.ms.wfc.core

public class WFCInvalidPropertyValue
extends WFCException


 WFCInvalidPropertyValue Methods

WFCInvalidPropertyValue Methods

Constructors | Description
WFCInvalidPropertyValue | Creates a WFCInvalidPropertyException object.


 WFCInvalidPropertyValue.WFCInvalidPropertyValue

WFCInvalidPropertyValue.WFCInvalidPropertyValue

Creates a WFCInvalidPropertyException object.

Syntax

public WFCInvalidPropertyValue()

public WFCInvalidPropertyValue( String message )

Parameters

message

The message to be displayed when the exception is thrown.


WFCInvalidStateException Class

Represents an exception for when the state of an object becomes invalid.

WFCException
  |
  +--WFCInvalidStateException

package com.ms.wfc.core

public class WFCInvalidStateException
extends WFCException


 WFCInvalidStateException Methods

WFCInvalidStateException Methods

Constructors | Description
WFCInvalidStateException | Creates a WFCInvalidStateException object.


 WFCInvalidStateException.WFCInvalidStateException

WFCInvalidStateException.WFCInvalidStateException

Creates a WFCInvalidStateException object.

Syntax

public WFCInvalidStateException()

public WFCInvalidStateException( String message )

public WFCInvalidStateException( String message, Throwable innerException )

Parameters

message

The message to be displayed when the exception is thrown.

innerException

The inner exception to be associated with this exception.


WFCSystemException Class

Represents an exception for errors in system calls.

WFCException
  |
  +--WFCSystemException

package com.ms.wfc.core

public class WFCSystemException
extends WFCException

Remarks

System exceptions are thrown as a result of a Win32 call failure.


 WFCSystemException Methods

WFCSystemException Methods

Constructors | Description
WFCSystemException | Creates a WFCSystemException object.


 WFCSystemException.WFCSystemException

WFCSystemException.WFCSystemException

Creates a WFCSystemException object.

Syntax

public WFCSystemException()

public WFCSystemException( String message )

Parameters

message

The message to be displayed when the exception is thrown.


WFCWarning Class

Represents a warning rather than an error.

WFCException
  |
  +--WFCWarning

package com.ms.wfc.core

public class WFCWarning
extends WFCException


 WFCWarning Methods

WFCWarning Methods

Constructors | Description
WFCWarning | Creates a WFCWarning object.


 WFCWarning.WFCWarning

WFCWarning.WFCWarning

Creates a WFCWarning object.

Syntax

public WFCWarning( String message )

public WFCWarning( String message, String helpURL )

public WFCWarning( String message, String helpURL, String helpTopic )

Parameters

message

The message to be displayed when the warning occurs.

helpURL

The help file to be opened if the user requests help.

helpTopic

The help topic to be displayed if the user requests help.


 WFCWarning Fields

WFCWarning Fields

Fields | Description
helpTopic | The help topic associated with the warning.
helpURL | The help file associated with the warning.


 WFCWarning.helpTopic

WFCWarning.helpTopic

The help topic associated with the warning.

Syntax

public final String helpTopic;


 WFCWarning.helpURL

WFCWarning.helpURL

The help file associated with the warning.

Syntax

public final String helpURL;


WFCWin32Exception Class

Represents an exception for a Win32 error code.

WFCSystemException
  |
  +--WFCWin32Exception

package com.ms.wfc.core

public class WFCWin32Exception
extends WFCSystemException


 WFCWin32Exception Methods

WFCWin32Exception Methods

Constructors | Description
WFCWin32Exception | Creates a WFCWin32Exception object.


 WFCWin32Exception.WFCWin32Exception

WFCWin32Exception.WFCWin32Exception

Creates a WFCWin32Exception object.

Syntax

public WFCWin32Exception()

public WFCWin32Exception( int error )

public WFCWin32Exception( int error, String message )

Parameters

error

The Win32 error code to be associated with this exception.

message

The message to be displayed when the exception is thrown.

Remarks

If no error code is specified, the exception contains the last Win32 error reported by J/Direct. If no message is specified, the exception uses the Win32 error message associated with the error code.


 WFCWin32Exception Fields

WFCWin32Exception Fields

Fields | Description
errorCode | The Win32 error code associated with this exception.


 WFCWin32Exception.errorCode

WFCWin32Exception.errorCode

The Win32 error code associated with this exception.

Syntax

public final int errorCode;


Package com.ms.wfc.data

Provides basic data access using the ActiveX Data Objects (ADO) object model. Also provides classes that support data formatting.

Classes

AdoEnums

Defines the ADO enumeration constants.

AdoException

Represents an ADO exception.

AdoProperties

Encapsulates the ADO Properties collection, which contains all Property objects for an instance of an ADO object.

AdoProperty

Encapsulates the ADO Property object, which represents a property for an ADO object.

BooleanDataFormat

Represents a data format object for formatting boolean data types.

Command

Encapsulates the ADO Command object, which represents an executable command against a data source.

Connection

Encapsulates the ADO Connection object, which represents a connection to a data source.

ConnectionEvent

Provides data for events that result from an operation performed with a Connection object.

DataFormat

Represents the abstract implementation of the IDataFormat interface.

DataSpace

Encapsulates the ADO DataSpace object, which creates client-side proxies to business objects located on the middle tier.

DateDataFormat

Represents a data format object for formatting date and time data types.

DateFormat

Defines constants that specify the formats used by a DateDataFormat object.

Error

Encapsulates the ADO Error object, which represents a provider error.

Errors

Encapsulates the ADO Errors collection, which contains all Error objects created in response to provider errors.

Field

Encapsulates the ADO Field object, which represents a column of data with a data type.

Fields

Encapsulates the ADO Fields collection, which contains all Field objects of a Recordset object.

NumberDataFormat

Represents a data format object for formatting numeric data types.

ObjectProxy

Represents a server.

Parameter

Encapsulates the ADO Parameter object, which represents a parameter associated with a parameterized query or stored procedure.

Parameters

Encapsulates the ADO Parameters collection, which contains all Parameter objects of a Command object.

Recordset

Encapsulates the ADO Recordset object, which represents the set of records from a base table or from the results of an executed command.

RecordsetEvent

Provides data for events that result from an operation performed with a Recordset object.

Timestamp

Represents a timestamp data type.

Interfaces

IDataFormat

Defines the data formatting interface.

Delegates

ConnectionEventHandler

Identifies a handler method for events performed with a Connection object.

RecordsetEventHandler

Identifies a handler method for events performed with a Recordset object.


AdoException Class

Represents an ADO exception.

ComFailException
  |
  +--AdoException

package com.ms.wfc.data

public class AdoException
extends com.ms.com.ComFailException

Remarks

Exceptions of this type are thrown only by methods internal to WFC.


 AdoException Methods

AdoException Methods

Constructors | Description
AdoException | Creates an AdoException object.

Methods | Description
getErrorNumber | Retrieves the error number associated with the exception.


 AdoException.AdoException

AdoException.AdoException

Creates an AdoException object.

Syntax

public AdoException( int id )

public AdoException( String s )

public AdoException( int hr, String s )

Parameters

id

An integer specifying an error number. Specify one of the constants defined in the AdoEnums.ErrorValue class.

s

The message associated with the exception.

hr

An integer specifying an HRESULT returned by COM. This value is converted to a compatible error number.


 AdoException.getErrorNumber

AdoException.getErrorNumber

Retrieves the error number associated with the exception.

Syntax

public int getErrorNumber()

Return Value

Returns one of the constants defined in the AdoEnums.ErrorValue class.


AdoProperties Class

Encapsulates the ADO Properties collection, which contains all Property objects for an instance of an ADO object.

package com.ms.wfc.data

public class AdoProperties

Remarks

ADO supports COM collection objects, which contain sets of other ADO objects. For example, the Connection, Command, Recordset, and Field objects each have their own Properties collection. This collection contains a set of Property objects, which describe the characteristics of the object. The AdoProperties class is the WFC representation of the ADO Properties collection.

There are two types of Property objects: built-in and dynamic. Built-in properties are part of a given ADO object, and each object has methods to assign or retrieve the value of the property. Dynamic properties are appended to the Properties collection of the given ADO object by the underlying OLE DB provider.

To obtain the dynamic properties of an object, first call its getProperties method. This method returns its Properties collection as an AdoProperties object. Then call the getItem method on the AdoProperties object to retrieve the property, either by index or by name. This property is returned as an AdoProperty object.

The AdoProperties class contains the following methods, which encapsulate the properties and methods of the ADO Properties collection:

public int getCount ()

public AdoProperty getItem ( int n )
public AdoProperty getItem( String s )

public void refresh ()

See Also AdoProperty, ADO Collections


AdoProperty Class

Encapsulates the ADO Property object, which represents a property for an ADO object.

package com.ms.wfc.data

public class AdoProperty

Remarks

ADO supports COM Property objects, each of which has a name and a value that represents a characteristic of the object. The AdoProperty class is the WFC representation of the ADO Property object.

There are two types of Property objects: built-in and dynamic. Built-in properties are part of a given ADO object, and each object has methods to assign or retrieve the value of the property. Dynamic properties are appended to the Properties collection of the given ADO object by the underlying OLE DB provider.

To obtain the dynamic properties of an object, first call its getProperties method. This method returns its Properties collection as an AdoProperties object. Then call the getItem method on the AdoProperties object to retrieve the property, either by index or by name. This property is returned as an AdoProperty object.

An AdoProperty object itself has properties. The primary AdoProperty property is value, which retrieves and assigns a value for the property, specified as a com.ms.com.Variant object. As a convenience, ADO/WFC also provides accessor methods that retrieve and assign values not specified as variants, but as standard Java data types.

The AdoProperty class defines the following methods, which encapsulate the properties of the ADO Property object:

public int getAttributes ()
public void setAttributes( int attr )

public String getName ()

public int getType ()

public Variant getValue ()
public void setValue( Variant v )

In addition to the getValue and setValue methods, this class defines the following accessor methods that use Java data types to retrieve and set the value of the AdoProperty object:

public boolean getBoolean()
public void setBoolean( boolean v )

public byte getByte()
public void setByte( byte v )

public byte[] getBytes()
public void setBytes ( byte[] v )

public short getShort()
public void setShort( short v )

public int getInt()
public void setInt( int v )

public long getLong()
public void setLong( long v )

public float getFloat()
public void setFloat( float v )

public double getDouble()
public void setDouble( double v )

public String getString()
public void setString( String v )

public void setObject( Object v )
public Object getObject()

public boolean isNull()
public void setNull()

Note The isNull method returns a boolean value indicating whether the property is null. There is no getNull method.

See Also AdoProperties


BooleanDataFormat Class

Represents a data format object for formatting boolean data types.

DataFormat
  |
  +--BooleanDataFormat

package com.ms.wfc.data

public class BooleanDataFormat
extends DataFormat
implements IConstructable

Remarks

The Column and DataBinding classes provide a dataFormat property, which allows you to format numerical, date, or boolean values. For example, if a column in a DataGrid control contains boolean values, you can set its dataFormat property to a BooleanDataFormat object:

import com.ms.wfc.data.*;
import com.ms.wfc.data.ui.*;

/* Retrieve a boolean-valued column in a DataGrid control.
   Assume this column has an index of 1 in the grid. */
Column column1 = dataGrid1.getColumn(1);

/* Format the column by setting its dataFormat
   property. Create a BooleanDataFormat object
   and specify the strings to be displayed for
   false values, true values, and null values. */
column1.setDataFormat(new BooleanDataFormat("F", "T", "--"));

The BooleanDataFormat class provides three properties to format boolean values:

Property | Description
falseValue | Specifies the string to be displayed for false values. The default string is "False".
trueValue | Specifies the string to be displayed for true values. The default string is "True".
nullValue | Specifies the string to be displayed for null values. The default string is "(null)".

The following example shows how to reset the strings to their default values:

/* Retrieve the column's current BooleanDataFormat object. */
BooleanDataFormat bFormat = (BooleanDataFormat) column1.getDataFormat();

/* Reset the format strings to the default values
   by setting the falseValue, trueValue, and
   nullValue properties to null. */
bFormat.setFalseValue(null);
bFormat.setTrueValue(null);
bFormat.setNullValue(null);

For information about formatting boolean values in the Forms Designer, see Formatting Data.

See Also DateDataFormat, NumberDataFormat


 BooleanDataFormat Methods

BooleanDataFormat Methods

Constructors | Description
BooleanDataFormat | Creates a BooleanDataFormat object.

Methods | Description
getFalseValue | Retrieves the string that is displayed for false values.
getNullValue | Retrieves the string that is displayed for null values.
getTrueValue | Retrieves the string that is displayed for true values.
setFalseValue | Sets the string to be displayed for false values.
setNullValue | Sets the string to be displayed for null values.
setTrueValue | Sets the string to be displayed for true values.


 BooleanDataFormat.BooleanDataFormat

BooleanDataFormat.BooleanDataFormat

Creates a BooleanDataFormat object.

Syntax

public BooleanDataFormat()

public BooleanDataFormat( String falseValue, String trueValue )

public BooleanDataFormat( String falseValue, String trueValue, String nullValue )

Parameters

falseValue

The string to use for false values. The default string is "False".

trueValue

The string to use for true values. The default string is "True".

nullValue

The string to use for null values. The default string is "(null)".

Remarks

If no value is passed for falseValue, trueValue, or nullValue, the corresponding default string is used. To explicity use a default string, pass null for the parameter.


 BooleanDataFormat.getFalseValue

BooleanDataFormat.getFalseValue

Retrieves the string that is displayed for false values.

Syntax

public String getFalseValue()

Return Value

Returns the string that is used for false values.

See Also setFalseValue


 BooleanDataFormat.getNullValue

BooleanDataFormat.getNullValue

Retrieves the string that is displayed for null values.

Syntax

public String getNullValue()

Return Value

Returns the string that is used for null values.

See Also setNullValue


 BooleanDataFormat.getTrueValue

BooleanDataFormat.getTrueValue

Retrieves the string that is displayed for true values.

Syntax

public String getTrueValue()

Return Value

Returns the string that is used for true values.

See Also setTrueValue


 BooleanDataFormat.setFalseValue

BooleanDataFormat.setFalseValue

Sets the string to be displayed for false values.

Syntax

public void setFalseValue( String value )

Parameters

value

The string to use for false values. The default string is "False".

Remarks

Call setFalseValue to customize the display of false values. To return to the default string, pass null for the value parameter.

See Also getFalseValue


 BooleanDataFormat.setNullValue

BooleanDataFormat.setNullValue

Sets the string to be displayed for null values.

Syntax

public void setNullValue( String value )

Parameters

value

The string to use for null values. The default string is "(null)".

Remarks

Call setNullValue to customize the display of null values. To return to the default string, pass null for the value parameter.

See Also getNullValue


 BooleanDataFormat.setTrueValue

BooleanDataFormat.setTrueValue

Sets the string to be displayed for true values.

Syntax

public void setTrueValue( String value )

Parameters

value

The string to use for true values. The default string is "True".

Remarks

Call setTrueValue to customize the display of true values. To return to the default string, pass null for the value parameter.

See Also getTrueValue


ConnectionEvent Class

Provides data for events that result from an operation performed with a Connection object.

AdoEvent
  |
  +--ConnectionEvent

package com.ms.wfc.data

public class ConnectionEvent
extends AdoEvent

Remarks

The ConnectionEvent class defines the following fields that specify the event data:

public int adStatus;
public com.ms.wfc.data.Command
  command;
public String ConnectionString;
public int CursorType;
public com.ms.wfc.data.Error
  error;
public int LockType;
public int Options;
public String Password;
public int RecordsAffected;
public com.ms.wfc.data.Recordset
  recordSet;
public String Source;
public int TransactionLevel;
public String UserID;

For more information about events, see Handling Events in WFC and ADO Events in ADO/WFC.


ConnectionEventHandler Delegate

Identifies a handler method for events performed with a Connection object.

package com.ms.wfc.data

public delegate
void ConnectionEventHandler( Object sender, ConnectionEvent e );

Remarks

The syntax of the ConnectionEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a ConnectionEvent object that provides the event data.

When you create a ConnectionEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC. For information about ADO events in WFC, see ADO Events in ADO/WFC.


DataFormat Class

Represents the abstract implementation of the IDataFormat interface. This class also converts between the OLE interface IOleDataFormat and the WFC IDataFormat interface.

package com.ms.wfc.data

public abstract class DataFormat
implements IOleDataFormat, IDataFormat

See Also BooleanDataFormat, DateDataFormat, NumberDataFormat


 DataFormat Methods

DataFormat Methods

Constructors | Description
DataFormat | Creates a DataFormat object.

Methods | Description
addOnFormatChanged | Assigns a delegate to the formatChanged event.
getUseVariant | Determines whether the data format object can receive com.ms.com.Variant objects.
onFormatChanged | Triggers the formatChanged event.
performFormatChanged | Generates a formatChanged event.
removeOnFormatChanged | Removes the delegate assigned to the formatChanged event.


 DataFormat.addOnFormatChanged

DataFormat.addOnFormatChanged

Assigns a delegate to the formatChanged event.

Syntax

public void addOnFormatChanged( EventHandler handler )

Parameters

handler

The EventHandler delegate to be notified when the event occurs.

Remarks

The formatChanged event occurs when changes that affect data formatting are made to a property of the object.

See Also removeOnFormatChanged


 DataFormat.DataFormat

DataFormat.DataFormat

Creates a DataFormat object.

Syntax

public DataFormat()

public DataFormat( IDataFormat format )

Parameters

format

An object implementing the IDataFormat interface to be wrapped by this object.


 DataFormat.getUseVariant

DataFormat.getUseVariant

Determines whether the data format object can receive com.ms.com.Variant objects.

Syntax

protected boolean getUseVariant()

Return Value

Returns true if the format method can be called with variants; otherwise, returns false.

Remarks

By default, this method always returns false, which means variants are first converted to Java objects (such as Integer or Double objects) before the format method is called.


 DataFormat.onFormatChanged

DataFormat.onFormatChanged

Triggers the formatChanged event.

Syntax

protected void onFormatChanged( Event event )

Parameters

event

An Event object.

Remarks

The formatChanged event occurs when changes that affect data formatting are made to a property of the object.

When overriding onFormatChanged, be sure to call super.onFormatChanged.

See Also performFormatChanged, addOnFormatChanged, removeOnFormatChanged


 DataFormat.performFormatChanged

DataFormat.performFormatChanged

Generates a formatChanged event.

Syntax

public void performFormatChanged()

Remarks

The formatChanged event occurs when changes that affect data formatting are made to a property of the object. Call performFormatChanged to force the event to occur.

See Also addOnFormatChanged


 DataFormat.removeOnFormatChanged

DataFormat.removeOnFormatChanged

Removes the delegate assigned to the formatChanged event.

Syntax

public void removeOnFormatChanged( EventHandler handler )

Parameters

handler

The EventHandler delegate to be removed.

See Also addOnFormatChanged


DateDataFormat Class

Represents a data format object for formatting date data types.

DataFormat
  |
  +--DateDataFormat

package com.ms.wfc.data

public class DateDataFormat
extends DataFormat
implements IConstructable

Remarks

The Column and DataBinding classes provide a dataFormat property, which allows you to format numerical, date, or boolean values. For example, if a column in a DataGrid control contains dates or times, you can set its dataFormat property to a DateDataFormat object:

import com.ms.wfc.data.*;
import com.ms.wfc.data.ui.*;

/* Retrieve a date-valued column in a DataGrid control.
   Assume this column has an index of 1 in the grid. */
Column column1 = dataGrid1.getColumn(1);

/* Format the column by setting its dataFormat
   property. Create a DateDataFormat object and
   use the default Short Date format. */
column1.setDataFormat(new DateDataFormat());

The DateDataFormat class provides two properties to format date and time values:

Property | Description
format | Specifies the type of format, using one of the constants from the DateFormat class. The default value of this property is DateFormat.SHORT, which specifies the Short Date format.
customFormat | Specifies a custom format string, which is used only when the format property is set to DateFormat.CUSTOM.

The following example shows how to use these properties to change the initial format of the column:

/* Retrieve the column's current DateDataFormat object. */
DateDataFormat dFormat = (DateDataFormat) column1.getDataFormat();

/* Set the DateDataFormat object's format property
   to DateFormat.CUSTOM and set the customFormat
   property to a custom string. */
dFormat.setFormat(DateFormat.CUSTOM);
dFormat.setCustomFormat("mm/dd/yyyy");

For information about formatting date or time values in the Forms Designer, see Formatting Data.

See Also BooleanDataFormat, NumberDataFormat


 DateDataFormat Methods

DateDataFormat Methods

Constructors | Description
DateDataFormat | Creates a DateDataFormat object.

Methods | Description
getCustomFormat | Retrieves the custom format string.
getFormat | Retrieves the format type.
setCustomFormat | Sets the custom format string.
setFormat | Sets the format type.


 DateDataFormat.DateDataFormat

DateDataFormat.DateDataFormat

Creates a DateDataFormat object.

Syntax

public DateDataFormat()

public DateDataFormat( int format )

public DateDataFormat( String customFormat )

public DateDataFormat( int format, String customFormat )

Parameters

format

The type of format. Specify one of the constants defined by the DateFormat class.

customFormat

The custom format string to be used when the format type is set to DateFormat.CUSTOM. For information about possible format strings, see setCustomFormat.

Remarks

If no value is passed for format, the format type is set to DateFormat.SHORT.


 DateDataFormat.getCustomFormat

DateDataFormat.getCustomFormat

Retrieves the custom format string.

Syntax

public String getCustomFormat()

Return Value

Returns the current custom format string. For information about possible format strings, see setCustomFormat.


 DateDataFormat.getFormat

DateDataFormat.getFormat

Retrieves the format type.

Syntax

public int getFormat()

Return Value

Returns one of the constants defined by the DateFormat class.

See Also setFormat


 DateDataFormat.setCustomFormat

DateDataFormat.setCustomFormat

Sets the custom format string.

Syntax

public void setCustomFormat( String value )

Parameters

value

The string to be used to format dates or times.

Remarks

The setting of the customFormat property is only applied when the format property is set to DateFormat.CUSTOM. If the format property is not set to DateFormat.CUSTOM, then the custom format string is ignored.

Use the following guidelines to specify the custom format string:

  • To display months, days, hours, minutes, or seconds as numbers with no leading zeros, use m, d, h, m, or s, respectively.
  • To display months, days, hours, minutes, or seconds as numbers with leading zeros before single digits, use mm, dd, hh, mm, or ss, respectively.
  • To display abbreviations for the month, day, or year, use mmm, ddd, or yy, respectively.
  • To display the full name of the month, day, or year, use mmmm, dddd, or yyyy, respectively.
  • To display time according to the 12-hour clock, use either AM/PM, am/pm, A/P, or a/p. (To display the default AM/PM symbol that is defined by your system settings, use AMPM.)
  • To display static text within the format string, enclose the text in single quotation marks ('). Date and time symbols, such as the slash (/) and colon (:), do not require quotation marks. For example:
    'The date is' m/d/yy

See Also getCustomFormat


 DateDataFormat.setFormat

DateDataFormat.setFormat

Sets the format type.

Syntax

public void setFormat( int value )

Parameters

value

One of the constants defined by the DateFormat class. The default value of the format property is DateFormat.SHORT.

Remarks

To use a custom format string, set the format property to DateFormat.CUSTOM and set the customFormat property to the format string. Note that if the format property is set to DateFormat.SHORT, DateFormat.LONG, or DateFormat.TIME, any custom format string is ignored.

See Also getFormat


DateFormat Class

Defines constants that specify the date and time formats used by a DateDataFormat object. Use these constants to set the value of the object's format property.

Enum
  |
  +--DateFormat

package com.ms.wfc.data

public final class DateFormat
extends Enum


 DateFormat Methods

DateFormat Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 DateFormat.valid

DateFormat.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 DateFormat Fields

DateFormat Fields

Fields | Description
CUSTOM | Specifies a custom date or time format.
LONG | Specifies the Long Date format, as defined in the Regional Settings section of the Windows Control Panel.
SHORT | Specifies the Short Date format, as defined in the Regional Settings section of the Windows Control Panel.
TIME | Specifies the hh:mm format, in 24-hour time.


 DateFormat.CUSTOM

DateFormat.CUSTOM

Specifies a custom date or time format.

Syntax

public static final int CUSTOM;

Remarks

When a DateDataFormat object's format property is set to CUSTOM, you can define the custom format string through the customFormat property.


 DateFormat.LONG

DateFormat.LONG

Specifies the Long Date format, as defined in the Regional Settings section of the Windows Control Panel.

Syntax

public static final int LONG;

See Also DateDataFormat.getFormat, DateDataFormat.setFormat


 DateFormat.SHORT

DateFormat.SHORT

Specifies the Short Date format, as defined in the Regional Settings section of the Windows Control Panel.

Syntax

public static final int SHORT;

See Also DateDataFormat.getFormat, DateDataFormat.setFormat


 DateFormat.TIME

DateFormat.TIME

Specifies the hh:mm format, in 24-hour time.

Syntax

public static final int TIME;

See Also DateDataFormat.getFormat, DateDataFormat.setFormat


IDataFormat Interface

Defines the data formatting interface.

package com.ms.wfc.data

public interface IDataFormat

Remarks

Classes that implement the IDataFormat interface can format data that is presented to the user. The DataFormat class is an abstract implementation of this interface.


 IDataFormat Methods

IDataFormat Methods

Methods | Description
addOnFormatChanged | Assigns a delegate to the formatChanged event.
format | Formats data from a database format into a user-editable format.
removeOnFormatChanged | Removes the delegate assigned to the formatChanged event.
unformat | Removes the formatting from the user-editable data and restores the original database format.


 IDataFormat.addOnFormatChanged

IDataFormat.addOnFormatChanged

Assigns a delegate to the formatChanged event.

Syntax

public void addOnFormatChanged( EventHandler handler )

Parameters

handler

The EventHandler delegate to be notified when the event occurs.

Remarks

The formatChanged event should be triggered when any property changes on the object that affects data formatting.

See Also removeOnFormatChanged


 IDataFormat.format

IDataFormat.format

Formats data from a database format into a user-editable format.

Syntax

public Object format( Locale locale, Object data )

Parameters

locale

The locale to use when formatting the data.

data

The data to format.

Return Value

Returns a user-editable format.

Remarks

If the locale parameter is null, the current thread locale should be used. The type of the returned format can vary with the implementation, but will typically be a string.

See Also unformat


 IDataFormat.removeOnFormatChanged

IDataFormat.removeOnFormatChanged

Removes the delegate assigned to the formatChanged event.

Syntax

public void removeOnFormatChanged( EventHandler handler )

Parameters

handler

The EventHandler delegate to be removed.

See Also addOnFormatChanged


 IDataFormat.unformat

IDataFormat.unformat

Removes the formatting from the user-editable data and restores the original database format.

Syntax

public Object unformat( Locale locale, Object data )

Parameters

locale

The locale to use when removing the data format.

data

The user-editable data.

Return Value

Returns a database format.

Remarks

If the locale parameter is null, the current thread locale should be used. The type of the data parameter must be the same as the type returned from format.


NumberDataFormat Class

Represents a data format object for formatting numeric data types.

DataFormat
  |
  +--NumberDataFormat

package com.ms.wfc.data

public class NumberDataFormat
extends DataFormat
implements IConstructable

Remarks

The Column and DataBinding classes provide a dataFormat property, which allows you to format numerical, date, or boolean values. For example, if a column in a DataGrid control has a numeric data type, you can set its dataFormat property to a NumberDataFormat object:

import com.ms.wfc.data.*;
import com.ms.wfc.data.ui.*;

/* Retrieve a numeric-valued column in a DataGrid control.
   Assume this column has an index of 1 in the grid. */
Column column1 = dataGrid1.getColumn(1);

/* Format the column by setting its dataFormat
   property. Create a NumberDataFormat object and
   specify an initial numerical format string. */
column1.setDataFormat(new NumberDataFormat("#,##0"));

The NumberDataFormat class provides a format property that specifies a format string for numerical values. The following example shows how to set this property to change the initial format of the column:

/* Retrieve the column's current DateDataFormat object. */
NumberDataFormat nFormat = (NumberDataFormat) column1.getDataFormat();

/* Set the NumberDataFormat object's format
   property to a different format string. */
nFormat.setFormat("#.000");

For information about formatting numerical values in the Forms Designer, see Formatting Data.

See Also BooleanDataFormat, DateDataFormat


 NumberDataFormat Methods

NumberDataFormat Methods

Constructors | Description
NumberDataFormat | Creates a NumberDataFormat object.

Methods | Description
getFormat | Retrieves the format string.
setFormat | Sets the format string.


 NumberDataFormat.getFormat

NumberDataFormat.getFormat

Retrieves the format string.

Syntax

public String getFormat()

Return Value

Returns the current format string. For information about possible format strings, see setFormat.


 NumberDataFormat.NumberDataFormat

NumberDataFormat.NumberDataFormat

Creates a NumberDataFormat object.

Syntax

public NumberDataFormat()

public NumberDataFormat( String format )

Parameters

format

The string to be used to format numbers.


 NumberDataFormat.setFormat

NumberDataFormat.setFormat

Sets the format string.

Syntax

public void setFormat( String value )

Parameters

value

The string to be used to format numbers. The default format string is "#".

Remarks

Use the following guidelines to specify the format string:

  • Use 0 to display either the digit in the corresponding position or 0 if no digit is in that position.
  • Use # to display either the digit in the corresponding position or nothing if no digit is in that position.
  • To display static text within the format string, enclose the text in single quotation marks ('). Numerical symbols, such as the thousand separator (,) and decimal placeholder (.), do not require quotation marks. For example:
    'Number:' #,##0.00

See Also getFormat


RecordsetEvent Class

Provides data for events that result from an operation performed with a Recordset object.

AdoEvent
  |
  +--RecordsetEvent

package com.ms.wfc.data

public class RecordsetEvent
extends AdoEvent

Remarks

The RecordsetEvent class defines the following fields that specify the event data:

public int adReason;
public int adStatus;
public int cFields;
public int cRecords;
public com.ms.wfc.data.Error error;
public com.ms.wfc.data.Field[] fields;
public boolean fMoreData;
public int maxProgress;
public int progress;

For more information about events, see Handling Events in WFC and ADO Events in ADO/WFC.


RecordsetEventHandler Delegate

Identifies a handler method for events performed with a Recordset object.

package com.ms.wfc.data

public delegate
void RecordsetEventHandler( Object sender, RecordsetEvent e );

Remarks

The syntax of the RecordsetEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a RecordsetEvent object that provides the event data.

When you create a RecordsetEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC. For information about ADO events in WFC, see ADO Events in ADO/WFC.


Timestamp Class

Represents a timestamp data type.

package com.ms.wfc.data.ui

public class Timestamp

Remarks

This class can be used with databases that support a timestamp data type, such as Microsoft SQL Server. The following fields are defined, which specify the parts of time:

public int year;
public int month;
public int day;
public int hour;
public int minute;
public int second;
public int nanos;


 Timestamp Methods

Timestamp Methods

Constructors | Description
Timestamp | Creates a Timestamp object.

Methods | Description
toString | Converts this Timestamp object to a string.
toTime | Converts this Timestamp object to a Time object.


 Timestamp.Timestamp

Timestamp.Timestamp

Creates a Timestamp object.

Syntax

public Timestamp()

public Timestamp( long lTime )

public Timestamp( Time tTime )

public Timestamp( long lTime, int nanos )

Parameters

lTime

A long value that represents the time.

tTime

A Time object that represents the time.

nanos

An integer that represents the number of nanoseconds in the time.


 Timestamp.toString

Timestamp.toString

Converts this Timestamp object to a string.

Syntax

public String toString()

Return Value

Returns the string representation of the object.


 Timestamp.toTime

Timestamp.toTime

Converts this Timestamp object to a Time object.

Syntax

public Time toTime()

Return Value

Returns the equivalent Time object.


Package com.ms.wfc.data.ui

Provides classes that implement and support data-bound controls.

Classes

Column

Represents a single column in a DataGrid control.

ColumnEditingEvent

Provides data for the columnEditing event of the DataGrid control.

ColumnEvent

Provides data for the columnEditied, columnUpdated, and headerClick events of the DataGrid control.

ColumnResizeEvent

Provides data for the columnResize event of the DataGrid control.

ColumnUpdatingEvent

Provides data for the columnUpdating event of the DataGrid control.

DataBinder

Manages the collection of bindings between a data source and a set of components.

DataBinding

Represents a single binding between a field from a data source and a property of a component.

DataGrid

Implements a data-bound grid that is filled with data from an ADO recordset.

DataNavigator

Allows the user to change the current record in an ADO recordset.

DataSource

Provides data to a component.

EnterAction

Defines the constants that specify the behavior of the ENTER key within a DataGrid control.

ErrorEvent

Provides data for the error event of the DataGrid control.

GridLineStyle

Defines the constants that specify the style of the gridlines in a DataGrid control.

PositionChangeEvent

Provides data for the positionChange event of the DataGrid control.

Scrollbars

Defines the constants that specify which scroll bars are displayed in a DataGrid control.

TabAction

Defines the constants that specify the behavior of the TAB key within a DataGrid control.

Delegates

ColumnEditingEventHandler

Identifies the method that will handle the columnEditing event of a DataGrid control.

ColumnEventHandler

Identifies the method that will handle the columnEdited, columnUpdated, or headerClick event of a DataGrid control.

ColumnResizeEventHandler

Identifies the method that will handle the columnResize event of a DataGrid control.

ColumnUpdatingEventHandler

Identifies the method that will handle the columnUpdating event of a DataGrid control.

ErrorEventHandler

Identifies the method that will handle the error event of a DataGrid control.

PositionChangeEventHandler

Identifies the method that will handle the positionChange event of a DataGrid control.


Column Class

Represents a single column in a DataGrid control.

Component
  |
  +--Column

package com.ms.wfc.data.ui

public final class Column
extends Component

Remarks

When a DataGrid control binds to a recordset, it creates a set of Column objects, each bound to a field in the recordset. Each Column object is displayed as a column in the grid. The boundFieldName property of each column identifies the field that the column is bound to. By default, a column's header is set to the name of the bound field; however, you can change the header text by setting the column's caption property.

Initially, each field in the recordset has an associated column in the grid, and the columns are positioned according to the order of the fields in the recordset. However, you can easily add, remove, and rearrange columns in the grid, either at design time or run time. To programmatically add or remove a column, call the DataGrid control's addColumn and removeColumn methods. To rearrange columns, set the index properties of the Column objects.

A Column object displays the string representations of the values in the underlying field. To determine the actual data type of the field, call getDataType. To format column values that have a numerical, date, or boolean data type, call setDataFormat.

Column object properties are set independently of the other columns in the grid. The parent DataGrid control provides properties that first allow you to define default attributes for all columns in the grid. Using the Column object properties, you can then customize individual columns as needed. For example, set the DataGrid control's font property to define the default font for all text in the grid; then, specify a different font for one of the columns by setting the Column object's font property. The column's property setting overrides the grid's setting, for that particular column.

For information about how to access the properties of a column in the Properties window, see Accessing Column Properties.


 Column Methods

Column Methods

Constructors | Description
Column | Creates a Column object.

Methods | Description
getAlignment | Retrieves a value indicating the alignment of the values in the column.
getAllowSizing | Retrieves a boolean value indicating whether the column can be resized at run time.
getBackColor | Retrieves the background color of the cells in the column.
getBoundFieldName | Retrieves the name of the field in the recordset that the column is bound to.
getCaption | Retrieves the text displayed in the column's header.
getDataFormat | Retrieves the format of the column's data.
getDataType | Retrieves the data type of the field in the recordset that the column is bound to.
getFont | Retrieves the font of the text in the column.
getForeColor | Retrieves the color of the text in the column.
getIndex | Retrieves the index of the column in the grid.
getLeft | Retrieves the x-coordinate of the column.
getReadOnly | Retrieves a boolean value indicating whether the data in the column is read-only.
getSelectedBackColor | Retrieves the background color for selected cells in the column.
getSelectedForeColor | Retrieves the color for selected text in the column.
getValue | Retrieves the value of the cell in the grid's current row.
getVisible | Retrieves a boolean value indicating whether the column is visible (meaning it can be scrolled into view).
getWidth | Retrieves the width of the column.
getWrapText | Retrieves a boolean value indicating whether the text values in the column can wrap within their cells.
getWriteAllowed | Retrieves a boolean value indicating whether the underlying field supports write operations.
setAlignment | Sets the alignment of the text in the column.
setAllowSizing | Sets a boolean value indicating whether the column can be resized at run time.
setBackColor | Sets the background color for the cells in the column.
setBoundFieldName | Sets the name of the field in the recordset that the column is bound to.
setCaption | Sets the text to be displayed in the column's header.
setDataFormat | Sets the format of the column's data.
setFont | Sets the font of the text in the column.
setForeColor | Sets the color of the text in the column.
setIndex | Sets the index of the column in the grid.
setReadOnly | Sets a boolean value indicating whether the data in the column is read-only.
setSelectedBackColor | Sets the background color for selected cells in the column.
setSelectedForeColor | Sets the color for selected text in the column.
setValue | Sets the value of the cell in the grid's current row.
setVisible | Sets a boolean value indicating whether the column is visible (meaning it can be scrolled into view).
setWidth | Sets the width of the column.
setWrapText | Sets a boolean value indicating whether the values in the column can wrap within their cells.
shouldPersistBackColor | Indicates whether the column's background color should be persisted.
shouldPersistFont | Indicates whether the column's font should be persisted.
shouldPersistForeColor | Indicates whether the column's foreground color should be persisted.
shouldPersistSelectedBackColor | Indicates whether the column's background color for selected cells should be persisted.
shouldPersistSelectedForeColor | Indicates whether the column's foreground color for selected cells should be persisted.
toString | Retrieves a description of the column.


 Column.Column

Column.Column

Creates a Column object.

Syntax

public Column()

Remarks

To bind the column to a field in a recordset, call setBoundFieldName. To add the column to a DataGrid control, call the grid's addColumn or setColumns method.


 Column.getAlignment

Column.getAlignment

Retrieves a value indicating the alignment of the values in the column.

Syntax

public int getAlignment()

Return Value

Returns one of the constants defined by the com.ms.wfc.ui.ContentAlignment class.

See Also setAlignment


 Column.getAllowSizing

Column.getAllowSizing

Retrieves a boolean value indicating whether the column can be resized at run time.

Syntax

public boolean getAllowSizing()

Return Value

Returns true if the column width can be changed; otherwise, returns false. For more information, see setAllowSizing.


 Column.getBackColor

Column.getBackColor

Retrieves the background color of the cells in the column.

Syntax

public Color getBackColor()

Return Value

Returns a Color object that represents the background color of the column.

Remarks

To retrieve the background color when cells are selected, call getSelectedBackColor.

See Also setBackColor, shouldPersistBackColor


 Column.getBoundFieldName

Column.getBoundFieldName

Retrieves the name of the field in the recordset that the column is bound to.

Syntax

public String getBoundFieldName()

Return Value

Returns a string that identifies the name of the field the column is currently bound to.

See Also setBoundFieldName


 Column.getCaption

Column.getCaption

Retrieves the text displayed in the column's header.

Syntax

public String getCaption()

Return Value

Returns the column's current caption text.

See Also setCaption


 Column.getDataFormat

Column.getDataFormat

Retrieves the format of the column's data.

Syntax

public IDataFormat getDataFormat()

Return Value

Returns an object implementing the IDataFormat interface that specifies the format of the data in the column. For more information, see setDataFormat.


 Column.getDataType

Column.getDataType

Retrieves the data type of the field in the recordset that the column is bound to.

Syntax

public int getDataType()

Return Value

Returns an integer that represents the data type of the bound field. This value is one of the constants defined by the com.ms.wfc.data.AdoEnums.DataType class.


 Column.getFont

Column.getFont

Retrieves the font of the text in the column.

Syntax

public Font getFont()

Return Value

Returns a Font object that represents the font of the column's text.

See Also setFont, shouldPersistFont


 Column.getForeColor

Column.getForeColor

Retrieves the color of the text in the column.

Syntax

public Color getForeColor()

Return Value

Returns a Color object that represents the color of the column's text.

Remarks

To retrieve the color of text when cells are selected, call getSelectedForeColor.

See Also setForeColor, shouldPersistForeColor


 Column.getIndex

Column.getIndex

Retrieves the index of the column in the grid.

Syntax

public int getIndex()

Return Value

Returns the zero-based index that indicates the current position of the column.

Remarks

Note that every column, visible or hidden, has an index. For example, if you set the visible property of the first column to false, it still has an index of 0. The column that the user actually sees as the first column is still the second column in the grid, with an index of 1.

See Also setIndex


 Column.getLeft

Column.getLeft

Retrieves the x-coordinate of the column.

Syntax

public int getLeft()

Return Value

Returns the x-coordinate of the column, relative to the coordinates of the parent DataGrid control.

Remarks

You can use the column's left and width properties, along with the parent DataGrid control's rowTop method and rowHeight property, to determine the exact location and dimension of any cell in the grid.


 Column.getReadOnly

Column.getReadOnly

Retrieves a boolean value indicating whether the data in the column is read-only.

Syntax

public boolean getReadOnly()

Return Value

Returns true if the column is marked as read-only; otherwise, returns false. Note that if the parent DataGrid control's allowUpdate property is set to false, getReadOnly can still return false even though the data in the column cannot be changed.

See Also setReadOnly


 Column.getSelectedBackColor

Column.getSelectedBackColor

Retrieves the background color for selected cells in the column.

Syntax

public Color getSelectedBackColor()

Return Value

Returns a Color object that represents the background color for selected cells.

Remarks

To determine the background color when cells are not selected, call getBackColor.

See Also setSelectedBackColor, shouldPersistSelectedForeColor


 Column.getSelectedForeColor

Column.getSelectedForeColor

Retrieves the color for selected text in the column.

Syntax

public Color getSelectedForeColor()

Return Value

Returns a Color object that represents the color for selected text.

Remarks

To determine the color of text when it is not selected, call getForeColor.

See Also setSelectedForeColor, shouldPersistSelectedForeColor


 Column.getValue

Column.getValue

Retrieves the value of the cell in the grid's current row.

Syntax

public String getValue()

Return Value

Returns a string that represents the data value of the cell in the grid's current row.

Remarks

The value property of a Column object and the currentCellValue property of the parent DataGrid control do not necessarily reference the same cell. The grid's currentCellValue property refers to the cell that is the intersection of the current row and the current column. A column's value property refers to the cell that is in the grid's current row; however, this column may not be the current column in the grid.

See Also setValue


 Column.getVisible

Column.getVisible

Retrieves a boolean value indicating whether the column is visible (meaning it can be scrolled into view).

Syntax

public boolean getVisible()

Return Value

Returns true if the column can be scrolled into view; otherwise, returns false.

See Also setVisible


 Column.getWidth

Column.getWidth

Retrieves the width of the column.

Syntax

public int getWidth()

Return Value

Returns the current width (in pixels) of the column.

See Also setWidth


 Column.getWrapText

Column.getWrapText

Retrieves a boolean value indicating whether the text values in the column can wrap within their cells.

Syntax

public boolean getWrapText()

Return Value

Returns true if the column's values can wrap within their cells; otherwise, returns false. For more information, see setWrapText.


 Column.getWriteAllowed

Column.getWriteAllowed

Retrieves a boolean value indicating whether the underlying field supports write operations.

Syntax

public boolean getWriteAllowed()

Return Value

Returns true if the underlying field can be written to; otherwise, returns false. If it cannot be determined whether the field can be written to, true is returned.

See Also getReadOnly


 Column.setAlignment

Column.setAlignment

Sets the alignment of the text in the column.

Syntax

public void setAlignment( int align )

Parameters

align

One of the constants defined by the com.ms.wfc.ui.ContentAlignment class. The default value of the alignment property is ContentAlignment.MIDDLELEFT.

Exceptions

WFCInvalidArgumentException thrown if align is not a valid alignment.

See Also getAlignment


 Column.setAllowSizing

Column.setAllowSizing

Sets a boolean value indicating whether the column can be resized at run time.

Syntax

public void setAllowSizing( boolean allow )

Parameters

allow

Set to true to allow the column width to be changed; otherwise, set to false. The default value of the allowSizing property is true.

Remarks

When the allowSizing property is set to true, the mouse pointer turns into a double-headed arrow when positioned over the divider between column headers, and the user can resize the column by dragging.

Note If the parent DataGrid control's columnHeaders property is set to false, the column headers are not displayed and the user cannot resize columns.

To programmatically resize a column, call setWidth. Note that if the allowSizing property is false, setting the width has no effect.

See Also getAllowSizing


 Column.setBackColor

Column.setBackColor

Sets the background color for the cells in the column.

Syntax

public void setBackColor( Color color )

Parameters

color

A Color object that represents the background color of the column.

Remarks

Call setBackColor to override the default background color set by the parent DataGrid control. To later return to this default, pass null to setBackColor.

To set the background color for cells that are selected, call setSelectedBackColor.

See Also getBackColor, shouldPersistBackColor


 Column.setBoundFieldName

Column.setBoundFieldName

Sets the name of the field in the recordset that the column is bound to.

Syntax

public void setBoundFieldName( String name )

Parameters

name

A string that identifies the name of the field to bind the column to.

Remarks

When you call setBoundFieldName, the parent DataGrid control automatically rebinds the column to the specified field. The column's caption is updated to reflect the newly bound field.

Note that multiple columns can be bound to the same field.

See Also getBoundFieldName


 Column.setCaption

Column.setCaption

Sets the text to be displayed in the column's header.

Syntax

public void setCaption( String caption )

Parameters

caption

The caption text to be displayed.

Remarks

By default, the caption property is set to the name of the field that the column is bound to. Setting the caption to null or to an empty string clears the header text but does not hide the header. To hide all column headers in the grid, set the columnHeaders property of the parent DataGrid control to false.

See Also getCaption


 Column.setDataFormat

Column.setDataFormat

Sets the format of the column's data.

Syntax

public void setDataFormat( IDataFormat value )

Parameters

value

An object implementing the IDataFormat interface that specifies the format of the data in the column.

Remarks

The dataFormat property affects how the data is displayed in the grid column; it does not affect how the data is stored in the underlying recordset. You can specify a format for the following types of data values:

Data type | IDataFormat object
boolean | BooleanDataFormat
date or time | DateDataFormat
numerical | NumberDataFormat

For information about setting the dataFormat property in the Properties window, see Formatting Data.

See Also getDataFormat


 Column.setFont

Column.setFont

Sets the font of the text in the column.

Syntax

public void setFont( Font font )

Parameters

font

A Font object that represents the current font of the text in the column.

Remarks

Call setFont to override the default font set by the parent DataGrid control. To later return to this default, pass null to setFont.

See Also getFont, shouldPersistFont


 Column.setForeColor

Column.setForeColor

Sets the color of the text in the column.

Syntax

public void setForeColor( Color color )

Parameters

color

A Color object that represents the color of the text in the column.

Remarks

Call setForeColor to override the default text color set by the parent DataGrid control. To later return to this default, pass null to setForeColor.

To set the color of text for cells that are selected, call setSelectedForeColor.

See Also getForeColor, shouldPersistForeColor


 Column.setIndex

Column.setIndex

Sets the index of the column in the grid.

Syntax

public void setIndex( int index )

Parameters

index

The zero-based index that determines the new position for the column.

Remarks

Call setIndex to rearrange the columns in the grid. When you set a column's index property, the column is positioned at the specified index. The column that was previously at that index, and all subsequent columns, are shifted to the right (meaning their indices are increased by 1).

Note that every column, visible or hidden, has an index. For example, if you set the visible property of the first column to false, it still has an index of 0. The column that the user actually sees as the first column is still the second column in the grid, with an index of 1.

If you specify an index that lies outside the bounds of the grid's collection of columns, the column is positioned as either the first or the last column. For example, setting a column's index to a negative value positions the column as the first column. Setting the index to the value of the parent DataGrid control's columnCount property, or to a higher number, positions the column as the last column.

See Also getIndex


 Column.setReadOnly

Column.setReadOnly

Sets a boolean value indicating whether the data in the column is read-only.

Syntax

public void setReadOnly( boolean readonly )

Parameters

readonly

Set to true to make the column read-only and prevent the data from being changed; otherwise, set to false. The default value of the readOnly property is false.

Remarks

When a column is read-only, the data in the column cannot be changed. Both Column.setValue and DataGrid.setCurrentCellValue will fail to update the recordset if the column's readOnly property is true.

When the parent DataGrid control's allowUpdate property is true, you can set a column's readOnly property to true to prevent the user from changing only the data in that column. When the allowUpdate property is false, the data in all columns is read-only, regardless of any column's readOnly property setting.

See Also getReadOnly


 Column.setSelectedBackColor

Column.setSelectedBackColor

Sets the background color for selected cells in the column.

Syntax

public void setSelectedBackColor( Color color )

Parameters

color

A Color object that represents the background color for selected cells.

Remarks

Call setSelectedBackColor to override the default selected background color set by the parent DataGrid control. To later return to this default, pass null to setSelectedBackColor.

To set the background color for cells that are not selected, call setBackColor.

See Also getSelectedBackColor, shouldPersistSelectedBackColor


 Column.setSelectedForeColor

Column.setSelectedForeColor

Sets the color for selected text in the column.

Syntax

public void setSelectedForeColor( Color color )

Parameters

color

A Color object that represents the color of the text in the column.

Remarks

Call setSelectedForeColor to override the default selected text color set by the parent DataGrid control. To later return to this default, pass null to setSelectedForeColor.

To set the color of text that it is not selected, call setForeColor.

See Also getSelectedForeColor, shouldPersistSelectedForeColor


 Column.setValue

Column.setValue

Sets the value of the cell in the grid's current row.

Syntax

public void setValue( String value )

Parameters

value

A string that represents the formatted data value for the cell in the grid's current row.

Remarks

The value property of a Column object and the currentCellValue property of the parent DataGrid control do not necessarily reference the same cell. The grid's currentCellValue property refers to the cell that is the intersection of the current row and the current column. A column's value property refers to the cell that is in the grid's current row; however, this column may not be the current column in the grid.

Important In order to set the value property, the grid's allowUpdate property must be true, the column's readOnly property must be false, and the underlying field must allow data to be modified.

The string passed to setValue is automatically converted to a value of the appropriate data type. The column's dataType property identifies the type of the underlying field.

See Also getValue


 Column.setVisible

Column.setVisible

Sets a boolean value indicating whether the column is visible (meaning it can be scrolled into view).

Syntax

public void setVisible( boolean visible )

Parameters

visible

Set to true to allow the column to be visible; set to false to hide the column. The default value of the visible property is true.

Remarks

Setting the visible property to false simply hides the column in the grid. The column still has an index, and is included in the value of the parent DataGrid control's columnCount property.

To actually remove a column from the grid, call the DataGrid control's removeColumn method.

See Also getVisible


 Column.setWidth

Column.setWidth

Sets the width of the column.

Syntax

public void setWidth( int width )

Parameters

width

The new width (in pixels) for the column.

Exceptions

WFCInvalidArgumentException thrown if width is less than DataGrid.MIN_COLUMN_WIDTH.

Remarks

If the allowSizing property is set to true, the column's width can be resized at run time, either programmatically or by the user. The width property is then automatically set to the new width. Note that if the allowSizing property is false, the width cannot be changed.

Use the parent DataGrid control's defaultColumnWidth property to set the default width for all columns in the grid.

See Also getWidth


 Column.setWrapText

Column.setWrapText

Sets a boolean value indicating whether the values in the column can wrap within their cells.

Syntax

public void setWrapText( boolean wrap )

Parameters

wrap

Set to true to allow the values to wrap within their cells. (In order to fit multiple lines of text in a cell, set the rowHeight property of the parent DataGrid control.) Set to false to clip the text at the cell's right edge. The default value of the wrapText property is false.

See Also getWrapText


 Column.shouldPersistBackColor

Column.shouldPersistBackColor

Indicates whether the column's background color should be persisted.

Syntax

public boolean shouldPersistBackColor()

Return Value

Returns true if the background color should be persisted; otherwise, returns false.

Remarks

This method is used internally by the Forms Designer.


 Column.shouldPersistFont

Column.shouldPersistFont

Indicates whether the column's font should be persisted.

Syntax

public boolean shouldPersistFont()

Return Value

Returns true if the font should be persisted; otherwise, returns false.

Remarks

This method is used internally by the Forms Designer.


 Column.shouldPersistForeColor

Column.shouldPersistForeColor

Indicates whether the column's foreground color should be persisted.

Syntax

public boolean shouldPersistForeColor()

Return Value

Returns true if the foreground color should be persisted; otherwise, returns false.

Remarks

This method is used internally by the Forms Designer.


 Column.shouldPersistSelectedBackColor

Column.shouldPersistSelectedBackColor

Indicates whether the column's background color for selected cells should be persisted.

Syntax

public boolean shouldPersistSelectedBackColor()

Return Value

Returns true if the selected background color should be persisted; otherwise, returns false.

Remarks

This method is used internally by the Forms Designer.


 Column.shouldPersistSelectedForeColor

Column.shouldPersistSelectedForeColor

Indicates whether the column's foreground color for selected cells should be persisted.

Syntax

public boolean shouldPersistSelectedForeColor()

Return Value

Returns true if the selected foreground color should be persisted; otherwise, returns false.

Remarks

This method is used internally by the Forms Designer.


 Column.toString

Column.toString

Retrieves a description of the column.

Syntax

public String toString()

Return Value

Returns the column's string description.

Remarks

The string returned by toString provides the following information about the column:

  • The class name.
  • The name of the bound field.
  • The index of the field in the recordset.
  • The index of the column.


ColumnEditingEvent Class

Provides data for the columnEditing event of the DataGrid control.

Event
  |
  +--ColumnEditingEvent

package com.ms.wfc.data.ui

public final class ColumnEditingEvent
extends Event

Remarks

The columnEditing event occurs when a cell enters edit mode. A ColumnEditingEvent object specifies the column that is being edited and the key that was pressed to trigger the event, and provides a flag to cancel the event.

For information about the WFC event model, see Handling Events in WFC.


 ColumnEditingEvent Methods

ColumnEditingEvent Methods

Constructors | Description
ColumnEditingEvent | Creates a ColumnEditingEvent object.


 ColumnEditingEvent.ColumnEditingEvent

ColumnEditingEvent.ColumnEditingEvent

Creates a ColumnEditingEvent object.

Syntax

public ColumnEditingEvent( int column, int keyAscii, boolean cancel )

Parameters

column

The zero-based index of the column that is being edited.

keyAscii

The ASCII value for the key that was pressed that caused the event to occur. This value is 0 if the user pressed F2 or used the mouse to enter edit mode.

cancel

The default value of the cancel flag. Set to true to cancel the event; otherwise, set to false.


 ColumnEditingEvent Fields

ColumnEditingEvent Fields

Fields | Description
cancel | Indicates whether the event will be canceled.
column | Specifies the zero-based index of the column that is being edited.
keyAscii | Specifies the ASCII value for the key that was pressed that caused the event to occur.


 ColumnEditingEvent.cancel

ColumnEditingEvent.cancel

Indicates whether the event will be canceled.

Syntax

public boolean cancel;

Remarks

Set this field to true to cancel the columnEditing event and exit the cell's edit mode.


 ColumnEditingEvent.column

ColumnEditingEvent.column

Specifies the zero-based index of the column that is being edited.

Syntax

public final int column;


 ColumnEditingEvent.keyAscii

ColumnEditingEvent.keyAscii

Specifies the ASCII value for the key that was pressed that caused the event to occur.

Syntax

public final int keyAscii;

Remarks

The value of this field is 0 if the user pressed F2 or used the mouse to enter edit mode.


ColumnEditingEventHandler Delegate

Identifies the method that will handle the columnEditing event of a DataGrid control.

package com.ms.wfc.data.ui

public multicast delegate
void ColumnEditingEventHandler( Object sender, ColumnEditingEvent e );

Remarks

The syntax of the ColumnEditingEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a ColumnEditingEvent object that provides the event data.

When you create a ColumnEditingEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC.


ColumnEvent Class

Provides data for the columnEditied, columnUpdated, and headerClick events of the DataGrid control.

Event
  |
  +--ColumnEvent

package com.ms.wfc.data.ui

public final class ColumnEvent
extends Event

Remarks

A ColumnEvent object specifies which column in the grid is the target of the event. For information about the WFC event model, see Handling Events in WFC.


 ColumnEvent Methods

ColumnEvent Methods

Constructors | Description
ColumnEvent | Creates a ColumnEvent object.


 ColumnEvent.ColumnEvent

ColumnEvent.ColumnEvent

Creates a ColumnEvent object.

Syntax

public ColumnEvent( int column )

Parameters

column

The zero-based index of the column that the event applies to.


 ColumnEvent Fields

ColumnEvent Fields

Fields | Description
column | Specifies the zero-based index of the column that the event applies to.


 ColumnEvent.column

ColumnEvent.column

Specifies the zero-based index of the column that the event applies to.

Syntax

public int column;


ColumnEventHandler Delegate

Identifies the method that will handle the columnEdited, columnUpdated, or headerClick event of a DataGrid control.

package com.ms.wfc.data.ui

public multicast delegate
void ColumnEventHandler( Object sender, ColumnEvent e );

Remarks

The syntax of the ColumnEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a ColumnEvent object that provides the event data.

When you create a ColumnEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC.


ColumnResizeEvent Class

Provides data for the columnResize event of the DataGrid control.

Event
  |
  +--ColumnResizeEvent

package com.ms.wfc.data.ui

public class ColumnResizeEvent
extends Event

Remarks

The columnResize event occurs when a column in the grid is resized, either programmatically or by the user. A ColumnResizeEvent object specifies the column that is being resized and the new width of the column, and provides a flag to cancel the event.

For information about the WFC event model, see Handling Events in WFC.


 ColumnResizeEvent Methods

ColumnResizeEvent Methods

Constructors | Description
ColumnResizeEvent | Creates a columnResizeEvent object.


 ColumnResizeEvent.ColumnResizeEvent

ColumnResizeEvent.ColumnResizeEvent

Creates a columnResizeEvent object.

Syntax

public ColumnResizeEvent( int column, int newWidth, boolean cancel )

Parameters

column

The zero-based index of the column that is being resized.

newWidth

The new width of the column.

cancel

The default value of the cancel flag. Set to true to cancel the event; otherwise, set to false.


 ColumnResizeEvent Fields

ColumnResizeEvent Fields

Fields | Description
cancel | Indicates whether the event will be canceled.
column | Specifies the zero-based index of the column that is being resized.
newWidth | Specifies the new width of the column.


 ColumnResizeEvent.cancel

ColumnResizeEvent.cancel

Indicates whether the event will be canceled.

Syntax

public boolean cancel;

Remarks

Set this field to true to cancel the columnResize event and restore the previous width of the column.


 ColumnResizeEvent.column

ColumnResizeEvent.column

Specifies the zero-based index of the column that is being resized.

Syntax

public int column;


 ColumnResizeEvent.newWidth

ColumnResizeEvent.newWidth

Specifies the new width of the column.

Syntax

public int newWidth;


ColumnResizeEventHandler Delegate

Identifies the method that will handle the columnResize event of a DataGrid control.

package com.ms.wfc.data.ui

public multicast delegate
void ColumnResizeEventHandler( Object sender, ColumnResizeEvent e );

Remarks

The syntax of the ColumnResizeEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a ColumnResizeEvent object that provides the event data.

When you create a ColumnResizeEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC.


ColumnUpdatingEvent Class

Provides data for the columnUpdating event of the DataGrid control.

Event
  |
  +--ColumnUpdatingEvent

package com.ms.wfc.data.ui

public final class ColumnUpdatingEvent
extends Event

Remarks

The columnUpdating event occurs after the user changes the value of a cell in the grid but before the new value has been written to the underlying recordset. A ColumnUpdatingEvent object specifies the column that is being updated and the previous value of the cell, and provides a flag to cancel the update.

For information about the WFC event model, see Handling Events in WFC.


 ColumnUpdatingEvent Methods

ColumnUpdatingEvent Methods

Constructors | Description
ColumnUpdatingEvent | Creates a ColumnUpdatingEvent object.


 ColumnUpdatingEvent.ColumnUpdatingEvent

ColumnUpdatingEvent.ColumnUpdatingEvent

Creates a ColumnUpdatingEvent object.

Syntax

public ColumnUpdatingEvent( int column, String oldValue, boolean cancel )

Parameters

column

The zero-based index of the column that is being updated.

oldValue

The previous value in the column (before the value was changed).

cancel

The default value of the cancel flag. Set to true to cancel the event; otherwise, set to false.


 ColumnUpdatingEvent Fields

ColumnUpdatingEvent Fields

Fields | Description
cancel | Indicates whether the event will be canceled.
column | Specifies the zero-based index of the column that is being updated.
oldValue | Specifies the previous value in the column (before the value was changed).


 ColumnUpdatingEvent.cancel

ColumnUpdatingEvent.cancel

Indicates whether the event will be canceled.

Syntax

public boolean cancel;

Remarks

Set this field to true to cancel the columnUpdating event and restore the cell's previous value.


 ColumnUpdatingEvent.column

ColumnUpdatingEvent.column

Specifies the zero-based index of the column that is being updated.

Syntax

public int column;


 ColumnUpdatingEvent.oldValue

ColumnUpdatingEvent.oldValue

Specifies the previous value in the column (before the value was changed).

Syntax

public String oldValue;


ColumnUpdatingEventHandler Delegate

Identifies the method that will handle the columnUpdating event of a DataGrid control.

package com.ms.wfc.data.ui

public multicast delegate
void ColumnUpdatingEventHandler( Object sender, ColumnUpdatingEvent e );

Remarks

The syntax of the ColumnUpdatingEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a ColumnUpdatingEvent object that provides the event data.

When you create a ColumnUpdatingEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC.


DataBinder Class

Manages the collection of bindings between a data source and a set of components.

Component
  |
  +--DataBinder

package com.ms.wfc.data.ui

public class DataBinder
extends Component
implements IDataSourceListener

Remarks

Typically, a component is a visual control and a data source is a recordset. A bound control can exchange data between a property and a field of the data source. A complex control, such as the DataGrid control, can bind directly to a data source. A simple control, such as an edit box or check box, requires a DataBinder control to facilitate the binding.

Each binding is represented by a DataBinding object.

See Also Data Binding in WFC


 DataBinder Methods

DataBinder Methods

Constructors | Description
DataBinder | Creates a DataBinder control.

Methods | Description
addBinding | Adds a new binding to the bindings collection.
clearBindings | Removes all current bindings.
commitChanges | Commits changes made in the control to the data source.
getBindings | Retrieves an array of all current bindings.
getDataMember | Retrieves the bound member of the DataBinder control's underlying data source.
getDataSource | Retrieves the data source underlying the DataBinder control.
removeBinding | Removes the specified binding.
setBindings | Sets the current bindings for the DataBinder control.
setDataMember | Sets the bound member of the DataBinder control's underlying data source.
setDataSource | Sets the data source underlying the DataBinder control.


 DataBinder.addBinding

DataBinder.addBinding

Adds a new binding to the bindings collection.

Syntax

public void addBinding( DataBinding newBinding )

public void addBinding( IComponent target, String propertyName, String fieldName )

Parameters

newBinding

The DataBinding object that represents the binding to add.

target

The component to bind.

propertyName

The name of the property on the target object to bind.

fieldName

The name of the field in the underlying recordset to bind.

Remarks

This binding will work in a read-only manner unless the target parameter supports property change notifications. For more information, see Simple Data Binding.

See Also removeBinding


 DataBinder.clearBindings

DataBinder.clearBindings

Removes all current bindings.

Syntax

public void clearBindings()

See Also addBinding, removeBinding


 DataBinder.commitChanges

DataBinder.commitChanges

Commits changes made in the control to the data source.

Syntax

public void commitChanges()

Remarks

If the underlying data source is updateable, changes made to the value of the bound component are propagated to the data source.


 DataBinder.DataBinder

DataBinder.DataBinder

Creates a DataBinder control.

Syntax

public DataBinder()

public DataBinder( Recordset dataSource )

public DataBinder( Recordset dataSource, DataBinding[] bindings )

Parameters

dataSource

The Recordset object to bind to the DataBinder control.

bindings

An array of DataBinding objects that bind component properties to the dataSource object.

Remarks

The first syntax creates an unbound DataBinder control. The second syntax binds the DataBinder control to the specified recordset with no default bindings. The third syntax binds the DataBinder control to the specified recordset with the specified array of bindings.


 DataBinder.getBindings

DataBinder.getBindings

Retrieves an array of all current bindings.

Syntax

public DataBinding[] getBindings()

Return Value

Returns an array of DataBinding objects.

See Also setBindings


 DataBinder.getDataMember

DataBinder.getDataMember

Retrieves the bound member of the DataBinder control's underlying data source.

Syntax

public String getDataMember()

Return Value

Returns a string containing the name of the bound data member. The default member is returned if no data member was explicitly set.

See Also setDataMember, setDataSource


 DataBinder.getDataSource

DataBinder.getDataSource

Retrieves the data source underlying the DataBinder control.

Syntax

public IDataSource getDataSource()

Return Value

Returns an object that supports the IDataSource interface.

See Also setDataSource


 DataBinder.removeBinding

DataBinder.removeBinding

Removes the specified binding.

Syntax

public void removeBinding( DataBinding removeBinding )

public void removeBinding( Object target, String propertyName )

Parameters

removeBinding

A DataBinding object that represents the binding to remove.

target

The object to remove the binding from.

propertyName

The name of the property to remove the binding from.

See Also addBinding, clearBindings


 DataBinder.setBindings

DataBinder.setBindings

Sets the current bindings for the DataBinder control.

Syntax

public void setBindings( DataBinding[] bindings )

Parameters

bindings

An array of DataBinding objects.

See Also getBindings


 DataBinder.setDataMember

DataBinder.setDataMember

Sets the bound member of the DataBinder control's underlying data source.

Syntax

public void setDataMember( String m_dataMember )

Parameters

m_dataMember

The name of the bound data member.

See Also getDataMember, getDataSource


 DataBinder.setDataSource

DataBinder.setDataSource

Sets the data source underlying the DataBinder control.

Syntax

public void setDataSource( IDataSource value )

Parameters

value

An object that supports the IDataSource interface.

See Also getDataSource


DataBinding Class

Represents a single binding between a field from a data source and a property of a component.

package com.ms.wfc.data.ui

public class DataBinding
implements IConstructable

Remarks

This class is used by the DataBinder control to represent each binding on the data source.

See Also Data Binding in WFC


 DataBinding Methods

DataBinding Methods

Constructors | Description
DataBinding | Creates a DataBinding object.

Methods | Description
bindTarget | Enables or disables notification of changes to the property of the bound component.
commitChanges | Commits changes made in the control to the data source.
getDataFormat | Retrieves the data format associated with this binding.
getDataSource | Retrieves the data source underlying the DataBinding control.
getFieldName | Retrieves the name of the data field associated with this binding.
getPropertyName | Retrieves the name of the property associated with this binding.
getPropertyValue | Retrieves the value of the property of the bound component.
getTarget | Retrieves the bound component associated with this binding.
refreshPropertyValue | Updates the property of the bound component with data from the data source.
setDataFormat | Sets the data format for this binding.
setDataSource | Sets the data source underlying the DataBinding control.
setFieldName | Sets the name of the data field associated with this binding.
setPropertyName | Sets the name of a property associated with this binding.
setPropertyValue | Sets the value of the property of the bound component.
setTarget | Sets the component associated with this binding.


 DataBinding.bindTarget

DataBinding.bindTarget

Enables or disables notification of changes to the property of the bound component.

Syntax

public void bindTarget( boolean bind )

Parameters

bind

Set to true for the DataBinding object to receive notification of changes to the bound property; otherwise, set to false.


 DataBinding.commitChanges

DataBinding.commitChanges

Commits changes made in the control to the data source.

Syntax

public void commitChanges()

Remarks

If the underlying data source is updateable, changes made to the value of the bound component are propagated to the data source.


 DataBinding.DataBinding

DataBinding.DataBinding

Creates a DataBinding object.

Syntax

public DataBinding()

public DataBinding( IComponent target, String propertyName, String fieldName )

public DataBinding( IComponent target, String propertyName, String fieldName, IDataFormat format )

Parameters

target

The component to bind.

propertyName

The name of the property on the target component to bind.

fieldName

The name of the field in the data source that will supply data to the propertyName property.

format

The IDataFormat object to use to format the display of the bound data.


 DataBinding.getDataFormat

DataBinding.getDataFormat

Retrieves the data format associated with this binding.

Syntax

public IDataFormat getDataFormat()

Return Value

Returns an object that supports the IDataFormat interface.

Remarks

The IDataFormat interface can be used to format data that is presented to the user.

See Also setDataFormat


 DataBinding.getDataSource

DataBinding.getDataSource

Retrieves the data source underlying the DataBinding control.

Syntax

public Recordset getDataSource()

Return Value

Returns the underlying Recordset object.

See Also setDataSource


 DataBinding.getFieldName

DataBinding.getFieldName

Retrieves the name of the data field associated with this binding.

Syntax

public String getFieldName()

Return Value

Returns the name of the bound data field.

See Also setFieldName


 DataBinding.getPropertyName

DataBinding.getPropertyName

Retrieves the name of the property associated with this binding.

Syntax

public String getPropertyName()

Return Value

Returns the name of the bound property.

See Also setPropertyName


 DataBinding.getPropertyValue

DataBinding.getPropertyValue

Retrieves the value of the property of the bound component.

Syntax

public Object getPropertyValue()

Return Value

Returns the current value of the bound property.

Remarks

The value is retrieved directly from the property; the bound field is not used.

See Also setPropertyValue


 DataBinding.getTarget

DataBinding.getTarget

Retrieves the bound component associated with this binding.

Syntax

public IComponent getTarget()

Return Value

Returns the bound component, which supports the IComponent interface.

See Also setTarget


 DataBinding.refreshPropertyValue

DataBinding.refreshPropertyValue

Updates the property of the bound component with data from the data source.

Syntax

public void refreshPropertyValue()

See Also setPropertyValue


 DataBinding.setDataFormat

DataBinding.setDataFormat

Sets the data format for this binding.

Syntax

public void setDataFormat( IDataFormat format )

Parameters

format

An object that supports the IDataFormat interface.

Remarks

The IDataFormat interface can be used to format data that is presented to the user.

See Also getDataFormat


 DataBinding.setDataSource

DataBinding.setDataSource

Sets the data source underlying the DataBinding control.

Syntax

public void setDataSource( Recordset value )

Parameters

value

The Recordset object to be associated with this binding.

See Also getDataSource


 DataBinding.setFieldName

DataBinding.setFieldName

Sets the name of the data field associated with this binding.

Syntax

public void setFieldName( String name )

Parameters

name

The name of the data field to bind.

See Also getFieldName


 DataBinding.setPropertyName

DataBinding.setPropertyName

Sets the name of a property associated with this binding.

Syntax

public void setPropertyName( String name )

Parameters

name

The name of the property to bind.

See Also getPropertyName


 DataBinding.setPropertyValue

DataBinding.setPropertyValue

Sets the value of the property of the bound component.

Syntax

public void setPropertyValue( Object value )

Parameters

value

An object whose contents are used to set the property value.

Remarks

The property is set directly from the value parameter; the bound field is not used.

See Also getPropertyValue


 DataBinding.setTarget

DataBinding.setTarget

Sets the component associated with this binding.

Syntax

public void setTarget( IComponent target )

Parameters

target

The component to bind that supports the IComponent interface.

See Also getTarget


DataGrid Class

Implements a data-bound grid that is filled with data from an ADO recordset. The rows and columns in the grid represent the records and fields in the recordset.

Component
  |
  +--Control
       |
       +--DataGrid

package com.ms.wfc.data.ui

public class DataGrid
extends Control

Remarks

To bind the DataGrid control to a recordset, set its dataSource property (and optionally, the dataMember property). When the DataGrid control is bound, it is automatically populated with data.

Important You cannot bind the DataGrid control to a recordset that has a forward-only cursor. The recordset must also support bookmarks.

If the recordset allows records to be edited, added, or deleted, you can set DataGrid control properties to determine whether the grid can be used to modify the recordset. For example, the allowUpdate and allowDelete properties indicate whether records can be edited or deleted via the grid. If both the allowAddNew and allowUpdate properties are set to true, the user can add a new row to the grid, which then adds a new record to the recordset. Changes made through the DataGrid control are automatically propagated to the recordset, and vice versa.

The cell in the grid that has focus is outlined with a heavy border, and is referred to as the current cell. To specify the current cell, the user can click it with the mouse or navigate to it using the keyboard. (The allowArrows, enterAction, and tabAction properties define which keys can move the current cell focus.) To programmatically specify the current cell, call setCurrentRow and setCurrentColumn. The intersection of the current row and the current column determines the current cell. (Note that changing the current row in the grid changes the current record in the underlying recordset, and vice versa.)

When a cell is current, its contents can be changed (provided the allowUpdate property is true and the recordset permits data changes). To put the current cell in edit mode, the user can press F2, click in the cell, or simply begin typing to replace the cell's contents. To exit edit mode, the user can press F2 again or click outside the cell.

When a cell enters edit mode, the columnEditing event is triggered. This event specifies the column that is being edited and the key that was pressed that triggered the edit. After the user finishes typing and exits edit mode, the following events are triggered, in the specified order:

  • updating Occurs before the underlying recordset is updated with the new value; no information about the update is provided.
  • columnUpdating Occurs before the recordset is updated with the new value. This event specifies the column that is being updated and the previous value of the cell.
  • updated Occurs after the recordset is updated with the new value; no information about the update is provided.
  • columnUpdated Occurs after the recordset is updated with the new value. This event specifies the column that was updated.
  • columnEdited Indicates that editing is complete. This event specifies the column that was edited.

If the actual data value in the cell remains unchanged, or if the user simply enters and exits edit mode without typing, only the columnEditing and columnEdited events are triggered.

Note None of these events occur if you programmatically change a cell's value through setCurrentCellValue.

The DataGrid control supports the selection of entire rows or columns, but not the selection of individual cells. The user can select a row or column by clicking the row or column header; by pressing and holding down the CTRL key, multiple rows or columns can be selected. To programmatically select rows and columns, call setSelectedRows and setSelectedColumns.

Each column in the DataGrid control is a Column object, bound to a field in the underlying recordset. Each column maintains its own properties that are set independently of other columns. The properties of the DataGrid control can be used to define default attributes for all columns in the grid. Using the Column object properties, you can then customize individual columns as needed. For example, set the DataGrid control's font property to define the default font for all text in the grid; then, specify a different font for one of the columns by setting the Column object's font property. The column's property setting overrides the grid's setting for that particular column.

The DataGrid control identifies each column in the grid by a zero-based index. This index specifies the position of the column in the grid. By setting the column's index property, you can rearrange the columns in the grid. Note that every column has an index, even if you hide a column. For example, if you set the column's visible property to false, the column still has an index of 0. The column that the user now sees as the first column is still the second column in the grid, with an index of 1.

While a column in the grid is identified by its index, a row is identified by the bookmark of the record in the underlying recordset. For example, to programmatically change the current row in the grid, you call the setCurrentRow method and specify the bookmark of the corresponding record to be made current.

For the rows that are visible in the grid's current scroll position, you can determine the order in which a row is displayed by calling getDisplayIndex. When you pass a bookmark to this method, the zero-based display index of the corresponding row is returned (provided the row is currently visible).

For information about using the DataGrid control in the Forms Designer, see Binding Data with the DataGrid Control.


 DataGrid Methods

DataGrid Methods

Constructors | Description
DataGrid | Creates a DataGrid control.

Methods | Description
addColumn | Adds a column to the DataGrid control.
addOnColumnEdited | Assigns a delegate to the columnEdited event.
addOnColumnEditing | Assigns a delegate to the columnEditing event.
addOnColumnResize | Assigns a delegate to the columnResize event.
addOnColumnUpdated | Assigns a delegate to the columnUpdated event.
addOnColumnUpdating | Assigns a delegate to the columnUpdating event.
addOnDeleted | Assigns a delegate to the deleted event.
addOnDeleting | Assigns a delegate to the deleting event.
addOnError | Assigns a delegate to the error event.
addOnHeaderClick | Assigns a delegate to the headerClick event.
addOnInserted | Assigns a delegate to the inserted event.
addOnInserting | Assigns a delegate to the inserting event.
addOnPositionChange | Assigns a delegate to the positionChange event.
addOnRowResize | Assigns a delegate to the rowResize event.
addOnScroll | Assigns a delegate to the scroll event.
addOnSelChange | Assigns a delegate to the selChange event.
addOnUpdated | Assigns a delegate to the updated event.
addOnUpdating | Assigns a delegate to the updating event.
clearColumns | Removes all columns from the grid.
clearSelection | Removes any selection in the grid.
getAllowAddNew | Retrieves a boolean value indicating whether the user can add rows to the grid (provided the underlying recordset allows new records to be added).
getAllowArrows | Retrieves a boolean value indicating whether the arrow keys can be used to navigate the grid.
getAllowDelete | Retrieves a boolean value indicating whether the user can delete rows from the grid (provided the underlying recordset allows records to be deleted).
getAllowRowSizing | Retrieves a boolean value indicating whether the rows in the grid can be resized at run time.
getAllowUpdate | Retrieves a boolean value indicating whether data can be modified in the grid (provided the underlying recordset allows records to be modified).
getApproxRowCount | Retrieves the approximate number of rows in the DataGrid control.
getBorderStyle | Retrieves the current style of the DataGrid control's border.
getCaption | Retrieves the text displayed in the caption bar at the top of the grid.
getColumn | Retrieves the column at the specified index.
getColumnCount | Retrieves the number of columns in the grid, visible or hidden.
getColumnHeaders | Retrieves a boolean value indicating whether the column headers are displayed.
getColumns | Retrieves the collection of all columns in the grid.
getCurrentCellValue | Retrieves the value of the current cell.
getCurrentCellVisible | Retrieves a boolean value indicating whether the current cell is completely visible.
getCurrentColumn | Retrieves the current column in the grid.
getCurrentRow | Retrieves the bookmark associated with the current row in the grid.
getCurrentRowModified | Retrieves a boolean value indicating whether the data in the current row has been changed.
getDataMember | Retrieves the bound member of the DataGrid control's underlying data source.
getDataSource | Retrieves the data source underlying the DataGrid control.
getDefaultColumnWidth | Retrieves the default width of all columns in the grid.
getDisplayIndex | Retrieves the display index of the row associated with the specified bookmark.
getDynamicColumns | Retrieves a boolean value indicating whether the columns in the grid are determined dynamically.
getEnterAction | Retrieves a value indicating the behavior of the ENTER key within the grid.
getFirstRow | Retrieves the bookmark associated with the topmost visible row in the grid.
getGridLineStyle | Retrieves the current style of the control's gridlines.
getHeaderFont | Retrieves the font of the grid's column headers.
getHeaderLineCount | Retrieves the number of lines of text that can be displayed in the grid's column headers.
getLeftColumn | Retrieves the index of the leftmost visible column in the grid.
getRowHeight | Retrieves the height of the rows in the grid.
getRowSelectors | Retrieves a boolean value indicating whether row selectors are displayed in the grid.
getScrollbars | Retrieves a value indicating which scroll bars are displayed in the grid.
getSelectedBackColor | Retrieves the background color for selected cells in the grid.
getSelectedColumns | Retrieves the selected columns in the grid.
getSelectedForeColor | Retrieves the color for selected text in the grid.
getSelectedRows | Retrieves the bookmarks associated with the selected rows in the grid.
getTabAction | Retrieves a value indicating the behavior of the TAB key within the grid.
getVisibleColumns | Retrieves the number of visible columns in the grid's current scroll position.
getVisibleRows | Retrieves the number of visible rows in the grid's current scroll position.
getWrapCellPointer | Retrieves a boolean value that indicates whether the TAB, ENTER, and arrow keys can be used to wrap the current cell focus around rows and columns.
makeCurrentCellVisible | Scrolls the grid to bring the current cell completely into view.
onColumnEdited | Triggers the columnEdited event.
onColumnEditing | Triggers the columnEditing event.
onColumnResize | Triggers the columnResize event.
onColumnUpdated | Triggers the columnUpdated event.
onColumnUpdating | Triggers the columnUpdating event.
onDeleted | Triggers the deleted event.
onDeleting | Triggers the deleting event.
onError | Triggers the error event.
onHeaderClick | Triggers the headerClick event.
onInserted | Triggers the inserted event.
onInserting | Triggers the inserting event.
onPositionChange | Triggers the positionChange event.
onRowResize | Triggers the rowResize event.
onScroll | Triggers the scroll event.
onSelChange | Triggers the selChange event.
onUpdated | Triggers the updated event.
onUpdating | Triggers the updating event.
rebind | Reinitializes the binding between the DataGrid control and the underlying recordset.
removeColumn | Removes a column from the grid.
removeOnColumnEdited | Removes the delegate that is assigned to the columnEdited event.
removeOnColumnEditing | Removes the delegate that is assigned to the columnEditing event.
removeOnColumnResize | Removes the delegate that is assigned to the columnResize event.
removeOnColumnUpdated | Removes the delegate that is assigned to the columnUpdated event.
removeOnColumnUpdating | Removes the delegate that is assigned to the columnUpdating event.
removeOnDeleted | Removes the delegate that is assigned to the deleted event.
removeOnDeleting | Removes the delegate that is assigned to the deleting event.
removeOnError | Removes the delegate that is assigned to the error event.
removeOnHeaderClick | Removes the delegate that is assigned to the headerClick event.
removeOnInserted | Removes the delegate that is assigned to the inserted event.
removeOnInserting | Removes the delegate that is assigned to the inserting event.
removeOnPositionChange | Removes the delegate that is assigned to the positionChange event.
removeOnRowResize | Removes the delegate that is assigned to the rowResize event.
removeOnScroll | Removes the delegate that is assigned to the scroll event.
removeOnSelChange | Removes the delegate that is assigned to the selChange event.
removeOnUpdated | Removes the delegate that is assigned to the updated event.
removeOnUpdating | Removes the delegate that is assigned to the updating event.
rowBookmark | Retrieves the bookmark associated with the row that offsets the topmost visible row by the specified number of rows.
rowTop | Retrieves the y-coordinate at the top of the specified row.
scroll | Scrolls the grid horizontally and vertically.
setAllowAddNew | Sets a boolean value indicating whether the user can add rows to the grid (provided the underlying recordset allows new records to be added).
setAllowArrows | Sets a boolean value indicating whether the arrow keys can be used to navigate the grid.
setAllowDelete | Sets a boolean value indicating whether the user can delete rows from the grid (provided the underlying recordset allows records to be deleted).
setAllowRowSizing | Sets a boolean value indicating whether the rows in the grid can be resized at run time.
setAllowUpdate | Sets a boolean value indicating whether data can be modified in the grid (provided the underlying recordset allows records to be modified).
setBorderStyle | Sets the style of the DataGrid control's border.
setCaption | Sets the text displayed in the caption bar at the top of the grid.
setColumnHeaders | Sets a boolean value indicating whether the column headers are displayed.
setColumns | Sets the collection of all columns in the grid.
setCurrentCellValue | Sets the value of the current cell.
setCurrentColumn | Sets the current column in the grid.
setCurrentRow | Moves the current position to the row associated with the specified bookmark.
setDataMember | Sets the bound member of the DataGrid control's underlying data source.
setDataSource | Sets the data source underlying the DataGrid control.
setDefaultColumnWidth | Sets the default width for all columns in the grid.
setDynamicColumns | Sets a boolean value indicating whether the columns in the grid are determined dynamically.
setEnterAction | Sets a value indicating the behavior of the ENTER key within the grid.
setFirstRow | Sets the topmost visible row in the grid.
setGridLineStyle | Sets the style of the control's gridlines.
setHeaderFont | Sets the font of the grid's column headers.
setHeaderLineCount | Sets the number of lines of text that can be displayed in the grid's column headers.
setLeftColumn | Sets the leftmost visible column in the grid.
setRowHeight | Sets the height of the rows in the grid.
setRowSelectors | Sets a boolean value indicating whether row selectors are displayed in the grid.
setScrollbars | Sets a value indicating which scroll bars are displayed.
setSelectedBackColor | Sets the background color for selected cells in the grid.
setSelectedColumns | Selects the specified columns.
setSelectedForeColor | Sets the color for selected text in the grid.
setSelectedRows | Selects the rows associated with the specified bookmarks.
setTabAction | Sets a value indicating the behavior of the TAB key within the grid.
setWrapCellPointer | Sets a boolean value that indicates whether the TAB, ENTER, and arrow keys can be used to wrap the current cell focus around rows and columns.


 DataGrid.addColumn

DataGrid.addColumn

Adds a column to the DataGrid control.

Syntax

public Column addColumn( String boundFieldName )

public Column addColumn( Column toAdd )

Parameters

boundFieldName

The name of the field in the underlying recordset to bind the new column to. Note that multiple columns can be bound to the same field.

toAdd

A Column object that represents the column to be added.

Return Value

Returns a Column object that represents the added column.

Remarks

The newly-added column is placed at the far right of the grid. To change the column's position, set its index property.

See Also removeColumn


 DataGrid.addOnColumnEdited

DataGrid.addOnColumnEdited

Assigns a delegate to the columnEdited event.

Syntax

public void addOnColumnEdited( ColumnEventHandler handler )

Parameters

handler

The ColumnEventHandler delegate to be notified when the event occurs.

Remarks

The columnEdited event occurs when a cell exits edit mode. For more information, see the DataGrid Control overview.

See Also removeOnColumnEdited


 DataGrid.addOnColumnEditing

DataGrid.addOnColumnEditing

Assigns a delegate to the columnEditing event.

Syntax

public void addOnColumnEditing( ColumnEditingEventHandler handler )

Parameters

handler

The ColumnEditingEventHandler delegate to be notified when the event occurs.

Remarks

The columnEditing event occurs when a cell enters edit mode. For more information, see the DataGrid Control overview.

Canceling the columnEditing event exits the cell's edit mode and prevents the updating, columnUpdating, updated, columnUpdated, and columnEdited events from occurring.

See Also removeOnColumnEditing


 DataGrid.addOnColumnResize

DataGrid.addOnColumnResize

Assigns a delegate to the columnResize event.

Syntax

public void addOnColumnResize( ColumnResizeEventHandler handler )

Parameters

handler

The ColumnResizeEventHandler delegate to be notified when the event occurs.

Remarks

The columnResize event occurs when a column is resized, either programmatically or by the user. To programmatically resize a column, call its setWidth method.

Note A column can be resized only if its allowSizing property is set to true.

Canceling the columnResize event restores the previous width of the column.

See Also removeOnColumnResize


 DataGrid.addOnColumnUpdated

DataGrid.addOnColumnUpdated

Assigns a delegate to the columnUpdated event.

Syntax

public void addOnColumnUpdated( ColumnEventHandler handler )

Parameters

handler

The ColumnEventHandler delegate to be notified when the event occurs.

Remarks

The columnUpdated event occurs when the user changes a cell's value and the underlying recordset is updated. For more information, see the DataGrid Control overview.

Note The user can change a cell's value only if the recordset allows modifications, the allowUpdate property of the DataGrid control is set to true, and the readOnly property of the cell's column is set to false.

See Also removeOnColumnUpdated


 DataGrid.addOnColumnUpdating

DataGrid.addOnColumnUpdating

Assigns a delegate to the columnUpdating event.

Syntax

public void addOnColumnUpdating( ColumnUpdatingEventHandler handler )

Parameters

handler

The ColumnUpdatingEventHandler delegate to be notified when the event occurs.

Remarks

The columnUpdating event occurs when the user changes a cell's value, but before the underlying recordset is updated. For more information, see the DataGrid Control overview.

Note The user can change a cell's value only if the recordset allows modifications, the allowUpdate property of the DataGrid control is set to true, and the readOnly property of the cell's column is set to false.

Canceling the columnUpdating event restores the cell's previous value and prevents the updated and columnUpdated events from occurring.

See Also removeOnColumnUpdating


 DataGrid.addOnDeleted

DataGrid.addOnDeleted

Assigns a delegate to the deleted event.

Syntax

public void addOnDeleted( EventHandler handler )

Parameters

handler

The EventHandler delegate to be notified when the event occurs.

Remarks

The deleting event occurs when the user selects the row(s) to be deleted and presses the DELETE key. The records are then deleted from the underlying recordset and the deleted event occurs.

See Also removeOnDeleted


 DataGrid.addOnDeleting

DataGrid.addOnDeleting

Assigns a delegate to the deleting event.

Syntax

public void addOnDeleting( CancelEventHandler handler )

Parameters

handler

The CancelEventHandler delegate to be notified when the event occurs.

Remarks

The deleting event occurs when the user selects the row(s) to be deleted and presses the DELETE key. The records are then deleted from the underlying recordset and the deleted event occurs.

To determine which rows have been selected for deletion, call getSelectedRows.

Note The user can delete a row from the grid only if the recordset allows deletions and the allowDelete property of the DataGrid control is set to true.

Canceling the deleting event restores the deleted rows and prevents the deleted event from occurring.

See Also removeOnDeleting


 DataGrid.addOnError

DataGrid.addOnError

Assigns a delegate to the error event.

Syntax

public void addOnError( ErrorEventHandler handler )

Parameters

handler

The ErrorEventHandler delegate to be notified when the event occurs.

Remarks

The error event occurs as a result of an ADO exception.

See Also removeOnError


 DataGrid.addOnHeaderClick

DataGrid.addOnHeaderClick

Assigns a delegate to the headerClick event.

Syntax

public void addOnHeaderClick( ColumnEventHandler handler )

Parameters

handler

The ColumnEventHandler delegate to be notified when the event occurs.

Remarks

The headerClick event occurs when the user clicks a column header. Column headers are displayed if the columnHeaders property is set to true.

Clicking a column header also selects the column. After the headerClick event occurs, the selChange event is triggered.

See Also removeOnHeaderClick


 DataGrid.addOnInserted

DataGrid.addOnInserted

Assigns a delegate to the inserted event.

Syntax

public void addOnInserted( EventHandler handler )

Parameters

handler

The EventHandler delegate to be notified when the event occurs.

Remarks

The inserting event occurs when the user first clicks in the blank row of the grid. An empty record is then added to the underlying recordset and the inserted event occurs.

The columnEditing event is triggered after the inserted event to handle the editing of cell data.

See Also removeOnInserted


 DataGrid.addOnInserting

DataGrid.addOnInserting

Assigns a delegate to the inserting event.

Syntax

public void addOnInserting( CancelEventHandler handler )

Parameters

handler

The CancelEventHandler delegate to be notified when the event occurs.

Remarks

The inserting event occurs when the user first clicks in the blank row of the grid. An empty record is then added to the underlying recordset and the inserted event occurs.

Note The user can add a row to the grid only if the recordset allows additions and both the allowAddNew and allowUpdate properties of the DataGrid control are set to true.

Canceling the inserting event prevents the row from being added and prevents the inserted event from occurring.

See Also removeOnInserting


 DataGrid.addOnPositionChange

DataGrid.addOnPositionChange

Assigns a delegate to the positionChange event.

Syntax

public void addOnPositionChange( PositionChangeEventHandler handler )

Parameters

handler

The PositionChangeEventHandler delegate to be notified when the event occurs.

Remarks

The positionChange event occurs when the current position is moved within the grid, either programmatically or by the user. To programmatically change the current position, call setCurrentColumn or setCurrentRow. The user can change the current position by selecting another cell with the mouse or by navigating to another cell with the keyboard. (The allowArrows, enterAction, and tabAction properties determine how the keyboard can be used within the grid.)

See Also removeOnPositionChange


 DataGrid.addOnRowResize

DataGrid.addOnRowResize

Assigns a delegate to the rowResize event.

Syntax

public void addOnRowResize( CancelEventHandler handler )

Parameters

handler

The CancelEventHandler delegate to be notified when the event occurs.

Remarks

The rowResize event occurs when a row is resized, either programmatically or by the user. To programmatically resize rows, call setRowHeight.

Note Rows can be resized only if the allowRowSizing property is set to true.

Canceling the rowResize event restores the previous height of the rows.

See Also removeOnRowResize


 DataGrid.addOnScroll

DataGrid.addOnScroll

Assigns a delegate to the scroll event.

Syntax

public void addOnScroll( CancelEventHandler handler )

Parameters

handler

The CancelEventHandler delegate to be notified when the event occurs.

Remarks

The scroll event occurs when the grid is scrolled, either programmatically or by the user. To programmatically scroll the grid, call scroll, makeCurrentCellVisible, setFirstRow, or setLeftColumn. The user can scroll the grid by using the scroll bars or the keyboard. (The allowArrows, enterAction, and tabAction properties determine how the keyboard can be used within the grid.) When the scroll box is dragged, the scroll event is triggered when the scroll box is released.

Canceling the scroll event restores the grid's previous scroll position.

See Also removeOnScroll


 DataGrid.addOnSelChange

DataGrid.addOnSelChange

Assigns a delegate to the selChange event.

Syntax

public void addOnSelChange( CancelEventHandler handler )

Parameters

handler

The CancelEventHandler delegate to be notified when the event occurs.

Remarks

The selChange event occurs when rows or columns are selected in the grid, either programmatically or by the user. To programmatically select rows or columns, call setSelectedRows or setSelectedColumns. The user can select rows or columns by clicking the row selectors or column headers, respectively. Row selectors and column headers are displayed if the rowSelectors and columnHeaders properties are set to true.

Note When the user clicks a column header, a headerClick event is generated before the selChange event.

Canceling the selChange event restores the grid's previous selection.

See Also removeOnSelChange


 DataGrid.addOnUpdated

DataGrid.addOnUpdated

Assigns a delegate to the updated event.

Syntax

public void addOnUpdated( EventHandler handler )

Parameters

handler

The EventHandler delegate to be notified when the event occurs.

Remarks

The updated event occurs when the user changes a cell's value and the underlying recordset is updated. For more information, see the DataGrid Control overview.

Note The user can change a cell's value only if the recordset allows modifications, the allowUpdate property of the DataGrid control is set to true, and the readOnly property of the cell's column is set to false.

See Also removeOnUpdated


 DataGrid.addOnUpdating

DataGrid.addOnUpdating

Assigns a delegate to the updating event.

Syntax

public void addOnUpdating( CancelEventHandler handler )

Parameters

handler

The CancelEventHandler delegate to be notified when the event occurs.

Remarks

The updating event occurs when the user changes a cell's value, but before the underlying recordset is updated. For more information, see the DataGrid Control overview.

Note The user can change a cell's value only if the recordset allows modifications, the allowUpdate property of the DataGrid control is set to true, and the readOnly property of the cell's column is set to false.

Canceling the updating event restores the cell's previous value and prevents the updated and columnUpdated events from occurring.

See Also removeOnUpdating


 DataGrid.clearColumns

DataGrid.clearColumns

Removes all columns from the grid.

Syntax

public void clearColumns()

Remarks

To repopulate the grid, you can:

  • Call rebind to add the default set of columns from the recordset.
  • Call addColumn to add a single column.
  • Call setColumns, if you have stored an array of Column objects that were previously constructed.

To remove only a single column from the grid, call removeColumn.


 DataGrid.clearSelection

DataGrid.clearSelection

Removes any selection in the grid.

Syntax

public void clearSelection()

See Also setSelectedColumns, setSelectedRows


 DataGrid.DataGrid

DataGrid.DataGrid

Creates a DataGrid control.

Syntax

public DataGrid()

Remarks

Once you have created a DataGrid control, call setDataSource (and optionally, setDataMember) to bind the grid to a recordset and fill it with data.


 DataGrid.getAllowAddNew

DataGrid.getAllowAddNew

Retrieves a boolean value indicating whether the user can add rows to the grid (provided the underlying recordset allows new records to be added).

Syntax

public boolean getAllowAddNew()

Return Value

Returns true if the user can add rows to the grid; otherwise, returns false. For more information, see setAllowAddNew.


 DataGrid.getAllowArrows

DataGrid.getAllowArrows

Retrieves a boolean value indicating whether the arrow keys can be used to navigate the grid.

Syntax

public boolean getAllowArrows()

Return Value

Returns true if the arrow keys can move focus between the cells in the grid; otherwise, returns false.

See Also setAllowArrows


 DataGrid.getAllowDelete

DataGrid.getAllowDelete

Retrieves a boolean value indicating whether the user can delete rows from the grid (provided the underlying recordset allows records to be deleted).

Syntax

public boolean getAllowDelete()

Return Value

Returns true if the user can delete rows from the grid; otherwise, returns false. For more information, see setAllowDelete.


 DataGrid.getAllowRowSizing

DataGrid.getAllowRowSizing

Retrieves a boolean value indicating whether the rows in the grid can be resized at run time.

Syntax

public boolean getAllowRowSizing()

Return Value

Returns true if the height of the rows can be changed in the grid; otherwise, returns false.

See Also setAllowRowSizing


 DataGrid.getAllowUpdate

DataGrid.getAllowUpdate

Retrieves a boolean value indicating whether data can be modified in the grid (provided the underlying recordset allows records to be modified).

Syntax

public boolean getAllowUpdate()

Return Value

Returns true if the data can be modified in the grid; otherwise, returns false. For more information, see setAllowUpdate.


 DataGrid.getApproxRowCount

DataGrid.getApproxRowCount

Retrieves the approximate number of rows in the DataGrid control.

Syntax

public int getApproxRowCount()

Return Value

Returns the approximate number of rows in the grid.

Exceptions

WFCInvalidArgumentException thrown if the DataGrid control is not bound.

Remarks

The value returned by getApproxRowCount is used to calibrate the vertical scroll bar.


 DataGrid.getBorderStyle

DataGrid.getBorderStyle

Retrieves the current style of the DataGrid control's border.

Syntax

public int getBorderStyle()

Return Value

Returns one of the constants defined by the com.ms.wfc.ui.BorderStyle class.

See Also setBorderStyle


 DataGrid.getCaption

DataGrid.getCaption

Retrieves the text displayed in the caption bar at the top of the grid.

Syntax

public String getCaption()

Return Value

Returns a string that represents the current caption text. If the grid has no caption, an empty string is returned.

See Also setCaption


 DataGrid.getColumn

DataGrid.getColumn

Retrieves the column at the specified index.

Syntax

public Column getColumn( int index )

Parameters

index

The zero-based index of the column to be retrieved. A column's index indicates its position in the grid. The index of the last column is the value returned by getColumnCount minus 1. For more information, see the index property for Column objects.

Return Value

Returns a Column object that represents the column at the specified index.

Exceptions

WFCInvalidArgumentException thrown if index is not a valid column index.

Remarks

To retrieve all columns in the grid, call getColumns.


 DataGrid.getColumnCount

DataGrid.getColumnCount

Retrieves the number of columns in the grid, visible or hidden.

Syntax

public int getColumnCount()

Return Value

Returns the total number of columns in the grid.

Remarks

The value returned by getColumnCount includes all columns in the grid, even if a column's visible property is set to false.

To retrieve the number of columns that are only visible in the grid's current scroll position, call getVisibleColumns.


 DataGrid.getColumnHeaders

DataGrid.getColumnHeaders

Retrieves a boolean value indicating whether the column headers are displayed.

Syntax

public boolean getColumnHeaders()

Return Value

Returns true if the column headers are displayed; otherwise, returns false.

See Also setColumnHeaders


 DataGrid.getColumns

DataGrid.getColumns

Retrieves the collection of all columns in the grid.

Syntax

public Column[] getColumns()

Return Value

Returns an array of Column objects that represent the columns in the grid. The order of the elements in the array matches the order of the columns displayed in the grid. If the grid contains no columns, an empty array is returned.

Remarks

The array of columns returned by getColumns includes all columns in the grid, even if a column's visible property is set to false. The number of columns in the array is the value returned by getColumnCount.

To retrieve a single column in the grid, call getColumn.

See Also setColumns


 DataGrid.getCurrentCellValue

DataGrid.getCurrentCellValue

Retrieves the value of the current cell.

Syntax

public String getCurrentCellValue()

Return Value

Returns a string that represents the formatted data value of the current cell.

Exceptions

WFCInvalidArgumentException thrown if the DataGrid control is not bound.

See Also setCurrentCellValue


 DataGrid.getCurrentCellVisible

DataGrid.getCurrentCellVisible

Retrieves a boolean value indicating whether the current cell is completely visible.

Syntax

public boolean getCurrentCellVisible()

Return Value

Returns true if the current cell is completely visible in the grid's current scroll position; otherwise, returns false.

Remarks

If getCurrentCellVisible returns false, you can call makeCurrentCellVisible to scroll the grid and bring the entire cell into view.


 DataGrid.getCurrentColumn

DataGrid.getCurrentColumn

Retrieves the current column in the grid.

Syntax

public Column getCurrentColumn()

Return Value

Returns a Column object that represents the current column in the grid. If no column is current, null is returned.

See Also setCurrentColumn


 DataGrid.getCurrentRow

DataGrid.getCurrentRow

Retrieves the bookmark associated with the current row in the grid.

Syntax

public Object getCurrentRow()

Return Value

Returns the bookmark of the current row.

Exceptions

WFCInvalidArgumentException thrown if the DataGrid control is not bound.

See Also setCurrentRow


 DataGrid.getCurrentRowModified

DataGrid.getCurrentRowModified

Retrieves a boolean value indicating whether the data in the current row has been changed.

Syntax

public boolean getCurrentRowModified()

Return Value

Returns true if the data in the current row has been modified but the underlying recordset has not been updated; otherwise, returns false.

Exceptions

WFCInvalidArgumentException thrown if the DataGrid is not bound.

Remarks

The currentRowModified property is automatically set to true if any of the values in the current row have been changed, either programmatically or by the user. When another row becomes the current row, this property is reset to false.

To programmatically change the value in the current cell, call setCurrentCellValue.

Important In order to change the value of the current cell, the allowUpdate property must be set to true, the readOnly property of this cell's column must be false, and the recordset must allow data to be modified.


 DataGrid.getDataMember

DataGrid.getDataMember

Retrieves the bound member of the DataGrid control's underlying data source.

Syntax

public String getDataMember()

Return Value

Returns a string that identifies the bound member of the underlying data source. This string is either the name of the bound recordset or is an empty string. For more information, see setDataMember.

Remarks

To retrieve the underlying data source object, call getDataSource.


 DataGrid.getDataSource

DataGrid.getDataSource

Retrieves the data source underlying the DataGrid control.

Syntax

public IDataSource getDataSource()

Return Value

Returns an object implementing the IDataSource interface that currently exposes the recordset that is bound to the DataGrid control. For more information, see setDataSource.

Remarks

To retrieve the bound member of the underlying data source, call getDataMember.


 DataGrid.getDefaultColumnWidth

DataGrid.getDefaultColumnWidth

Retrieves the default width of all columns in the grid.

Syntax

public int getDefaultColumnWidth()

Return Value

Returns the current default width (in pixels) of all columns.

See Also setDefaultColumnWidth


 DataGrid.getDisplayIndex

DataGrid.getDisplayIndex

Retrieves the display index of the row associated with the specified bookmark.

Syntax

public int getDisplayIndex( Object bookmark )

Parameters

bookmark

The bookmark associated with the row.

Return Value

Returns the zero-based display index of the row. If the specified row is not currently visible, then -1 is returned.

Exceptions

WFCInvalidArgumentException thrown if the DataGrid control is not bound.

Remarks

A row's display index indicates the order in which it is displayed in the grid's current scroll position. The topmost visible row has a display index of 0.


 DataGrid.getDynamicColumns

DataGrid.getDynamicColumns

Retrieves a boolean value indicating whether the columns in the grid are determined dynamically.

Syntax

public boolean getDynamicColumns()

Return Value

Returns true if the columns are determined dynamically; otherwise, returns false. For more information, see setDynamicColumns.


 DataGrid.getEnterAction

DataGrid.getEnterAction

Retrieves a value indicating the behavior of the ENTER key within the grid.

Syntax

public int getEnterAction()

Return Value

Returns one of the constants defined by the EnterAction class.

See Also setEnterAction


 DataGrid.getFirstRow

DataGrid.getFirstRow

Retrieves the bookmark associated with the topmost visible row in the grid.

Syntax

public Object getFirstRow()

Return Value

Returns the bookmark of the topmost visible row.

Exceptions

WFCInvalidArgumentException thrown if the DataGrid control is not bound.

Remarks

The value of the firstRow property is undefined while the user is scrolling the grid.

See Also setFirstRow, getLeftColumn


 DataGrid.getGridLineStyle

DataGrid.getGridLineStyle

Retrieves the current style of the control's gridlines.

Syntax

public int getGridLineStyle()

Return Value

Returns one of the constants defined by the GridLineStyle class.

See Also setGridLineStyle


 DataGrid.getHeaderFont

DataGrid.getHeaderFont

Retrieves the font of the grid's column headers.

Syntax

public Font getHeaderFont()

Return Value

Returns a Font object that represents the current font of the column headers. The default value of the headerFont property is null, which means the column headers use the font of the text in the grid's cells.

See Also setHeaderFont


 DataGrid.getHeaderLineCount

DataGrid.getHeaderLineCount

Retrieves the number of lines of text that can be displayed in the grid's column headers.

Syntax

public int getHeaderLineCount()

Return Value

Returns the number of lines of text that can be displayed in the column headers.

See Also setHeaderLineCount


 DataGrid.getLeftColumn

DataGrid.getLeftColumn

Retrieves the index of the leftmost visible column in the grid.

Syntax

public int getLeftColumn()

Return Value

Returns the zero-based index of the leftmost visible column.

Remarks

The value of the leftColumn property is undefined while the user is scrolling the grid.

See Also setLeftColumn, getFirstRow


 DataGrid.getRowHeight

DataGrid.getRowHeight

Retrieves the height of the rows in the grid.

Syntax

public int getRowHeight()

Return Value

Returns the current height (in pixels) of the rows.

See Also setRowHeight


 DataGrid.getRowSelectors

DataGrid.getRowSelectors

Retrieves a boolean value indicating whether row selectors are displayed in the grid.

Syntax

public boolean getRowSelectors()

Return Value

Returns true if the rows display row selectors; otherwise, returns false.

See Also setRowSelectors


 DataGrid.getScrollbars

DataGrid.getScrollbars

Retrieves a value indicating which scroll bars are displayed in the grid.

Syntax

public int getScrollbars()

Return Value

Returns one of the constants defined by the Scrollbars class.

See Also setScrollbars


 DataGrid.getSelectedBackColor

DataGrid.getSelectedBackColor

Retrieves the background color for selected cells in the grid.

Syntax

public Color getSelectedBackColor()

Return Value

Returns a Color object that represents the background color for selected cells.

Remarks

To determine the background color of nonselected cells in the grid, call getBackColor.

See Also setSelectedBackColor


 DataGrid.getSelectedColumns

DataGrid.getSelectedColumns

Retrieves the selected columns in the grid.

Syntax

public Column[] getSelectedColumns()

Return Value

Returns an array of Column objects that represent the currently selected columns. If no columns are selected, an empty array is returned.

Remarks

You can call getSelectedColumns to determine the columns that the user has selected. The user selects a column by clicking its column header. The CTRL key can be used to select multiple columns at a time.

Note If the DataGrid control's columnHeaders property is set to false, the column headers are not displayed and the user cannot select columns.

The DataGrid control does not allow both columns and rows to be selected at the same time. If rows are selected, call getSelectedRows to determine the selected rows.

See Also setSelectedColumns, clearSelection


 DataGrid.getSelectedForeColor

DataGrid.getSelectedForeColor

Retrieves the color for selected text in the grid.

Syntax

public Color getSelectedForeColor()

Return Value

Returns a Color object that represents the color for selected text in the grid.

Remarks

To determine the color of text when it is not selected, call getForeColor.

See Also setSelectedForeColor


 DataGrid.getSelectedRows

DataGrid.getSelectedRows

Retrieves the bookmarks associated with the selected rows in the grid.

Syntax

public Object[] getSelectedRows()

Return Value

Returns an array of the bookmarks associated with the currently selected rows. If no rows are selected, an empty array is returned.

Remarks

Call getSelectedRows to retrieve the rows selected by the user. The user selects a row by clicking its row selector. The CTRL key can be used to select multiple rows at a time.

Note If the DataGrid control's rowSelectors property is set to false, the rows selectors are not displayed and the user cannot select rows.

The DataGrid control does not allow both rows and columns to be selected at the same time. If columns are selected, call getSelectedColumns to determine the selected columns.

See Also setSelectedRows, clearColumns


 DataGrid.getTabAction

DataGrid.getTabAction

Retrieves a value indicating the behavior of the TAB key within the grid.

Syntax

public int getTabAction()

Return Value

Returns one of the constants defined by the TabAction class.

See Also setTabAction


 DataGrid.getVisibleColumns

DataGrid.getVisibleColumns

Retrieves the number of visible columns in the grid's current scroll position.

Syntax

public int getVisibleColumns()

Return Value

Returns the number of columns that are at least partially displayed in the grid's current scroll position.

Remarks

To retrieve the total number of columns in the grid, call getColumnCount.

See Also getVisibleRows


 DataGrid.getVisibleRows

DataGrid.getVisibleRows

Retrieves the number of visible rows in the grid's current scroll position.

Syntax

public int getVisibleRows()

Return Value

Returns the number of rows that are at least partially displayed in the grid's current scroll position.

Exceptions

WFCInvalidArgumentException thrown if the DataGrid control is not bound.

Remarks

To retrieve the approximate number of rows in the entire grid, call getApproxRowCount.

See Also getVisibleColumns


 DataGrid.getWrapCellPointer

DataGrid.getWrapCellPointer

Retrieves a boolean value that indicates whether the TAB, ENTER, and arrow keys can be used to wrap the current cell focus around rows and columns.

Syntax

public boolean getWrapCellPointer()

Return Value

Returns true if the current cell focus can wrap around rows or columns; otherwise, returns false. For more information, see setWrapCellPointer.


 DataGrid.makeCurrentCellVisible

DataGrid.makeCurrentCellVisible

Scrolls the grid to bring the current cell completely into view.

Syntax

public void makeCurrentCellVisible()

Remarks

To determine whether that current cell is already visible, call getCurrentCellVisible.


 DataGrid.onColumnEdited

DataGrid.onColumnEdited

Triggers the columnEdited event.

Syntax

protected void onColumnEdited( ColumnEvent event )

Parameters

event

A ColumnEvent object that provides the event data.

Remarks

The columnEdited event occurs when a cell exits edit mode. For more information, see the DataGrid Control overview.

When overriding onColumnEdited, be sure to call super.onColumnEdited.

See Also addOnColumnEdited, removeOnColumnEdited


 DataGrid.onColumnEditing

DataGrid.onColumnEditing

Triggers the columnEditing event.

Syntax

protected void onColumnEditing( ColumnEditingEvent event )

Parameters

event

A ColumnEditingEvent object that provides the event data.

Remarks

The columnEditing event occurs when a cell enters edit mode. For more information, see the DataGrid Control overview.

When overriding onColumnEditing, be sure to call super.onColumnEditing.

See Also addOnColumnEditing, removeOnColumnEditing


 DataGrid.onColumnResize

DataGrid.onColumnResize

Triggers the columnResize event.

Syntax

protected void onColumnResize( ColumnResizeEvent event )

Parameters

event

A ColumnResizeEvent object that provides the event data.

Remarks

The columnResize event occurs when a column is resized, either programmatically or by the user.

When overriding onColumnResize, be sure to call super.onColumnResize.

See Also addOnColumnResize, removeOnColumnResize


 DataGrid.onColumnUpdated

DataGrid.onColumnUpdated

Triggers the columnUpdated event.

Syntax

protected void onColumnUpdated( ColumnEvent event )

Parameters

event

A ColumnEvent object that provides the event data.

Remarks

The columnUpdated event occurs when the user changes a cell's value and the underlying recordset is updated. For more information, see the DataGrid Control overview.

When overriding onColumnUpdated, be sure to call super.onColumnUpdated.

See Also addOnColumnUpdated, removeOnColumnUpdated


 DataGrid.onColumnUpdating

DataGrid.onColumnUpdating

Triggers the columnUpdating event.

Syntax

protected void onColumnUpdating( ColumnUpdatingEvent event )

Parameters

event

A ColumnUpdatingEvent object that provides the event data.

Remarks

The columnUpdating event occurs when the user changes a cell's value, but before the underlying recordset is updated. For more information, see the DataGrid Control overview.

When overriding onColumnUpdating, be sure to call super.onColumnUpdating.

See Also addOnColumnUpdating, removeOnColumnUpdating


 DataGrid.onDeleted

DataGrid.onDeleted

Triggers the deleted event.

Syntax

protected void onDeleted( Event event )

Parameters

event

An Event object.

Remarks

When the user selects the row(s) to be deleted and presses the DELETE key, the deleting event is triggered. The records are then deleted from the underlying recordset and the deleted event occurs.

When overriding onDeleted, be sure to call super.onDeleted.

See Also addOnDeleted, removeOnDeleted


 DataGrid.onDeleting

DataGrid.onDeleting

Triggers the deleting event.

Syntax

protected void onDeleting( CancelEvent event )

Parameters

event

A CancelEvent object that provides the event data.

Remarks

The deleting event occurs when the user selects the rows to be deleted and presses the DELETE key. The records are then deleted from the underlying recordset and the deleted event occurs.

When overriding onDeleting, be sure to call super.onDeleting.

See Also addOnDeleting, removeOnDeleting


 DataGrid.onError

DataGrid.onError

Triggers the error event.

Syntax

protected void onError( ErrorEvent event )

Parameters

event

An ColumnErrorEvent object that provides the event data.

Remarks

The error event occurs as a result of an ADO exception.

When overriding onError, be sure to call super.onError.

See Also addOnError, removeOnError


 DataGrid.onHeaderClick

DataGrid.onHeaderClick

Triggers the headerClick event.

Syntax

protected void onHeaderClick( ColumnEvent event )

Parameters

event

A ColumnEvent object that provides the event data.

Remarks

The headerClick event occurs when the user clicks a column header. Column headers are displayed if the columnHeaders property is set to true.

When overriding onHeaderClick, be sure to call super.onHeaderClick.

See Also addOnHeaderClick, removeOnHeaderClick


 DataGrid.onInserted

DataGrid.onInserted

Triggers the inserted event.

Syntax

protected void onInserted( Event event )

Parameters

event

An Event object.

Remarks

When the user first clicks in the blank row of the grid, the inserting event occurs. A record is then added to the underlying recordset and the inserted event occurs.

When overriding onInserted, be sure to call super.onInserted.

See Also addOnInserted, removeOnInserted


 DataGrid.onInserting

DataGrid.onInserting

Triggers the inserting event.

Syntax

protected void onInserting( CancelEvent event )

Parameters

event

A CancelEvent object that provides the event data.

Remarks

The inserting event occurs when the user first clicks in the blank row of the grid. A record is then added to the underlying recordset and the inserted event occurs.

When overriding onInserting, be sure to call super.onInserting.

See Also addOnInserting, removeOnInserting


 DataGrid.onPositionChange

DataGrid.onPositionChange

Triggers the positionChange event.

Syntax

protected void onPositionChange( PositionChangeEvent event )

Parameters

event

A PositionChangeEvent object that provides the event data.

Remarks

The positionChange event occurs when the current position is moved within the grid, either programmatically or by the user.

When overriding onPositionChange, be sure to call super.onPositionChange.

See Also addOnPositionChange, removeOnPositionChange


 DataGrid.onRowResize

DataGrid.onRowResize

Triggers the rowResize event.

Syntax

protected void onRowResize( CancelEvent event )

Parameters

event

A CancelEvent object that provides the event data.

Remarks

The rowResize event occurs when a row is resized, either programmatically or by the user.

When overriding onRowResize, be sure to call super.onRowResize.

See Also addOnRowResize, removeOnRowResize


 DataGrid.onScroll

DataGrid.onScroll

Triggers the scroll event.

Syntax

protected void onScroll( CancelEvent event )

Parameters

event

A CancelEvent object that provides the event data.

Remarks

The scroll event occurs when the grid is scrolled, either programmatically or by the user.

When overriding onScroll, be sure to call super.onScroll.

See Also addOnScroll, removeOnScroll


 DataGrid.onSelChange

DataGrid.onSelChange

Triggers the selChange event.

Syntax

protected void onSelChange( CancelEvent event )

Parameters

event

A CancelEvent object that provides the event data.

Remarks

The selChange event occurs when rows or columns are selected in the grid, either programmatically or by the user.

When overriding onSelChange, be sure to call super.onSelChange.

See Also addOnSelChange, removeOnSelChange


 DataGrid.onUpdated

DataGrid.onUpdated

Triggers the updated event.

Syntax

protected void onUpdated( Event event )

Parameters

event

An Event object.

Remarks

The updated event occurs when the user changes a cell's value and the underlying recordset is updated. For more information, see the DataGrid Control overview.

When overriding onUpdated, be sure to call super.onUpdated.

See Also addOnUpdated, removeOnUpdated


 DataGrid.onUpdating

DataGrid.onUpdating

Triggers the updating event.

Syntax

protected void onUpdating( CancelEvent event )

Parameters

event

A CancelEvent object that provides the event data.

Remarks

The updating event occurs when the user changes a cell's value, but before the underlying recordset is updated. For more information, see the DataGrid Control overview.

When overriding onUpdating, be sure to call super.onUpdating.

See Also addOnUpdating, removeOnUpdating


 DataGrid.rebind

DataGrid.rebind

Reinitializes the binding between the DataGrid control and the underlying recordset.

Syntax

public void rebind()

Remarks

This method causes the DataGrid control to perform the same operations that occur when you first set the dataSource property (and optionally, the dataMember property). The DataGrid control resets the columns based on the recordset that it is currently bound to.

See Also setDynamicColumns


 DataGrid.removeColumn

DataGrid.removeColumn

Removes a column from the grid.

Syntax

public void removeColumn( int index )

Parameters

index

The zero-based index of the column to be removed. A column's index indicates its position in the grid. The index of the last column is the value returned by getColumnCount minus 1. For more information, see the index property for Column objects.

Exceptions

WFCInvalidArgumentException thrown if index is not a valid column index.

Remarks

To remove all columns from the grid, call clearColumns.

See Also addColumn


 DataGrid.removeOnColumnEdited

DataGrid.removeOnColumnEdited

Removes the delegate that is assigned to the columnEdited event.

Syntax

public void removeOnColumnEdited( ColumnEventHandler handler )

Parameters

handler

The ColumnEventHandler delegate to be removed.

See Also addOnColumnEdited


 DataGrid.removeOnColumnEditing

DataGrid.removeOnColumnEditing

Removes the delegate that is assigned to the columnEditing event.

Syntax

public void removeOnColumnEditing( ColumnEditingEventHandler handler )

Parameters

handler

The ColumnEditingEventHandler delegate to be removed.

See Also addOnColumnEditing


 DataGrid.removeOnColumnResize

DataGrid.removeOnColumnResize

Removes the delegate that is assigned to the columnResize event.

Syntax

public void removeOnColumnResize( ColumnResizeEventHandler handler )

Parameters

handler

The ColumnResizeEventHandler delegate to be removed.

See Also addOnColumnResize


 DataGrid.removeOnColumnUpdated

DataGrid.removeOnColumnUpdated

Removes the delegate that is assigned to the columnUpdated event.

Syntax

public void removeOnColumnUpdated( ColumnEventHandler handler )

Parameters

handler

The ColumnEventHandler delegate to be removed.

See Also addOnColumnUpdated


 DataGrid.removeOnColumnUpdating

DataGrid.removeOnColumnUpdating

Removes the delegate that is assigned to the columnUpdating event.

Syntax

public void removeOnColumnUpdating( ColumnUpdatingEventHandler handler )

Parameters

handler

The ColumnUpdatingEventHandler delegate to be removed.

See Also addOnColumnUpdating


 DataGrid.removeOnDeleted

DataGrid.removeOnDeleted

Removes the delegate that is assigned to the deleted event.

Syntax

public void removeOnDeleted( EventHandler handler )

Parameters

handler

The EventHandler delegate to be removed.

See Also addOnDeleted


 DataGrid.removeOnDeleting

DataGrid.removeOnDeleting

Removes the delegate that is assigned to the deleting event.

Syntax

public void removeOnDeleting( CancelEventHandler handler )

Parameters

handler

The CancelEventHandler delegate to be removed.

See Also addOnDeleting


 DataGrid.removeOnError

DataGrid.removeOnError

Removes the delegate that is assigned to the error event.

Syntax

public void removeOnError( ErrorEventHandler handler )

Parameters

handler

The ErrorEventHandler delegate to be removed.

See Also addOnError


 DataGrid.removeOnHeaderClick

DataGrid.removeOnHeaderClick

Removes the delegate that is assigned to the headerClick event.

Syntax

public void removeOnHeaderClick( ColumnEventHandler handler )

Parameters

handler

The ColumnEventHandler delegate to be removed.

See Also addOnHeaderClick


 DataGrid.removeOnInserted

DataGrid.removeOnInserted

Removes the delegate that is assigned to the inserted event.

Syntax

public void removeOnInserted( EventHandler handler )

Parameters

handler

The EventHandler delegate to be removed.

See Also addOnInserted


 DataGrid.removeOnInserting

DataGrid.removeOnInserting

Removes the delegate that is assigned to the inserting event.

Syntax

public void removeOnInserting( CancelEventHandler handler )

Parameters

handler

The CancelEventHandler delegate to be removed.

See Also addOnInserting


 DataGrid.removeOnPositionChange

DataGrid.removeOnPositionChange

Removes the delegate that is assigned to the positionChange event.

Syntax

public void removeOnPositionChange( PositionChangeEventHandler handler )

Parameters

handler

The PositionChangeEventHandler delegate to be removed.

See Also addOnPositionChange


 DataGrid.removeOnRowResize

DataGrid.removeOnRowResize

Removes the delegate that is assigned to the rowResize event.

Syntax

public void removeOnRowResize( CancelEventHandler handler )

Parameters

handler

The CancelEventHandler delegate to be removed.

See Also addOnRowResize


 DataGrid.removeOnScroll

DataGrid.removeOnScroll

Removes the delegate that is assigned to the scroll event.

Syntax

public void removeOnScroll( CancelEventHandler handler )

Parameters

handler

The CancelEventHandler delegate to be removed.

See Also addOnScroll


 DataGrid.removeOnSelChange

DataGrid.removeOnSelChange

Removes the delegate that is assigned to the selChange event.

Syntax

public void removeOnSelChange( CancelEventHandler handler )

Parameters

handler

The CancelEventHandler delegate to be removed.

See Also addOnSelChange


 DataGrid.removeOnUpdated

DataGrid.removeOnUpdated

Removes the delegate that is assigned to the updated event.

Syntax

public void removeOnUpdated( EventHandler handler )

Parameters

handler

The EventHandler delegate to be removed.

See Also addOnUpdated


 DataGrid.removeOnUpdating

DataGrid.removeOnUpdating

Removes the delegate that is assigned to the updating event.

Syntax

public void removeOnUpdating( CancelEventHandler handler )

Parameters

handler

The CancelEventHandler delegate to be removed.

See Also addOnUpdating


 DataGrid.rowBookmark

DataGrid.rowBookmark

Retrieves the bookmark associated with the row that offsets the topmost visible row by the specified number of rows.

Syntax

public Object rowBookmark( int displayRow )

Parameters

displayRow

The number of rows to offset the topmost visible row. A positive value identifies a subsequent row; a negative value identifies a previous row. The value 0 identifies the topmost visible row itself.

Exceptions

WFCInvalidArgumentException thrown if the DataGrid control is not bound or if displayRow does not reference a valid row.

Return Value

Returns the bookmark associated with the row at the specified offset.


 DataGrid.rowTop

DataGrid.rowTop

Retrieves the y-coordinate at the top of the specified row.

Syntax

public int rowTop( Object row )

Parameters

row

The bookmark associated with a row in the grid.

Return Value

Returns the y-coordinate at the top of the row, relative to the coordinates of the DataGrid control.

Exceptions

WFCInvalidArgumentException thrown if row does not reference a valid row.

Remarks

The rowTop method returns a coordinate for any row in the grid, regardless of whether the row is visible in the grid's current scroll position. If the row lies before the set of currently visible rows, the returned coordinate is negative.

You can use the rowTop method and rowHeight property, along with the left and width properties of a column, to determine the exact location and dimension of any cell in the grid.


 DataGrid.scroll

DataGrid.scroll

Scrolls the grid horizontally and vertically.

Syntax

public void scroll( int cols, int rows )

Parameters

cols

The number of columns to scroll in the horizontal direction. Positive values scroll right; negative values scroll left. Note that scrolling by 0 columns makes the current leftmost column completely visible.

rows

The number of rows to scroll in the vertical direction. Positive values scroll down; negative values scroll up.

Exceptions

WFCInvalidArgumentException thrown if the DataGrid control is not bound.

Remarks

If you specify a value for cols or rows that is out of range, the grid simply scrolls to the maximum position in that direction.

You can also scroll the grid by calling setFirstRow and setLeftColumn.


 DataGrid.setAllowAddNew

DataGrid.setAllowAddNew

Sets a boolean value indicating whether the user can add rows to the grid (provided the underlying recordset allows new records to be added).

Syntax

public void setAllowAddNew( boolean allowAddNew )

Parameters

allowAddNew

Set to true to allow rows to be added to the grid; otherwise, set to false. The default value of the allowAddNew property is true.

Remarks

If the underlying recordset allows new records to be added, setting both the allowAddNew and allowUpdate properties to true causes the DataGrid control to display a blank row after the last row in the grid. The user can then enter a new row of data, which, in turn, adds a new record to the recordset. If either the allowAddNew property or the allowUpdate property is false, no blank row is displayed and a new row cannot be added.

Important If the recordset does not allow new records to be added, the grid will not display a blank row, even if the allowAddNew and allowUpdate properties are true.

See Also getAllowAddNew


 DataGrid.setAllowArrows

DataGrid.setAllowArrows

Sets a boolean value indicating whether the arrow keys can be used to navigate the grid.

Syntax

public void setAllowArrows( boolean allowArrows )

Parameters

allowArrows

Set to true for the arrow keys to move the current cell focus within the grid; set to false for the arrow keys to move focus between the controls on the form. The default value of the allowArrows property is true.

Remarks

If both the allowArrows and wrapCellPointer properties are true, the current cell focus can wrap around rows and columns. For example, if the current cell is the last cell in a row, pressing the right arrow key will make the first cell in the next row the current cell.

You can further define keyboard navigation in the grid by calling setEnterAction and setTabAction.

See Also getAllowArrows


 DataGrid.setAllowDelete

DataGrid.setAllowDelete

Sets a boolean value indicating whether the user can delete rows from the grid (provided the underlying recordset allows records to be deleted).

Syntax

public void setAllowDelete( boolean allowDelete )

Parameters

allowDelete

Set to true to allow rows to be deleted from the grid; otherwise, set to false. The default value of the allowDelete property is true.

Remarks

If the underlying recordset allows records to be deleted, setting the allowDelete property to true enables the DELETE key to delete rows from the grid, which, in turn, deletes records the from the recordset. If this property is false, the DataGrid control will ignore any attempt to delete a row in the grid.

Important If the underlying recordset does not allow records to be deleted, the grid will not allow deletions, even if the allowDelete property is true.

See Also getAllowDelete


 DataGrid.setAllowRowSizing

DataGrid.setAllowRowSizing

Sets a boolean value indicating whether the rows in the grid can be resized at run time.

Syntax

public void setAllowRowSizing( boolean rowSizing )

Parameters

rowSizing

Set to true to allow the height of the rows to be changed; otherwise, set to false. The default value of the rowSizing property is true.

Remarks

When the allowRowSizing property is true, the mouse pointer turns into a double-headed arrow when positioned over the row divider between any two row selectors, and the user can resize the rows by dragging. All rows in the DataGrid control have the same height; resizing one row resizes them all.

Note If the rowSelectors property is false, the row selectors are not displayed and the user cannot resize rows.

To programmatically resize the rows, call setRowHeight. Note that if the allowRowSizing property is false, setting the row height has no effect.

See Also getAllowRowSizing


 DataGrid.setAllowUpdate

DataGrid.setAllowUpdate

Sets a boolean value indicating whether data can be modified in the grid (provided the underlying recordset allows records to be modified).

Syntax

public void setAllowUpdate( boolean allowUpdate )

Parameters

allowUpdate

Set to true to allow the data in the grid to be modified; otherwise, set to false. The default value of the allowUpdate property is true.

Remarks

The data in the current cell can be changed only if the underlying recordset allows records to be modified, the allowUpdate property is set to true, and the readOnly property of the cell's column is false.

The current cell's value can be changed programmatically or by the user. To programmatically change a cell's value, call setCurrentCellValue.

If the allowUpdate property is set to false, data cannot be changed in the grid, and calling setCurrentCellValue will fail. The user can still scroll through the grid and select data, but the grid will not allow data to be changed.

Important If the underlying recordset does not allow records to be modified, the grid will not allow data modifications, even if the allowUpdate property is true.

See Also getAllowUpdate


 DataGrid.setBorderStyle

DataGrid.setBorderStyle

Sets the style of the DataGrid control's border.

Syntax

public void setBorderStyle( int borderStyle )

Parameters

borderStyle

One of the constants defined by the com.ms.wfc.ui.BorderStyle class. The default value of the borderStyle property is BorderStyle.FIXED_3D.

Exceptions

WFCInvalidArgumentException thrown if borderStyle is not a valid style.

See Also getBorderStyle


 DataGrid.setCaption

DataGrid.setCaption

Sets the text displayed in the caption bar at the top of the grid.

Syntax

public void setCaption( String caption )

Parameters

caption

The caption text to be displayed. The default value of the caption property is an empty string.

Remarks

The caption is displayed above the column headers. If the caption property is set to an empty string, then the caption bar is not displayed.

See Also getCaption


 DataGrid.setColumnHeaders

DataGrid.setColumnHeaders

Sets a boolean value indicating whether the column headers are displayed.

Syntax

public void setColumnHeaders( boolean columnHeaders )

Parameters

columnHeaders

Set to true to display the column headers; otherwise, set to false. The default value of the columnHeaders property is true.

Remarks

By default, the text displayed in the column headers are based on the names of the fields in the underlying recordset. To change a column's header text, set the caption property of the Column object.

See Also getColumnHeaders


 DataGrid.setColumns

DataGrid.setColumns

Sets the collection of all columns in the grid.

Syntax

public void setColumns( Column[] columns )

Parameters

columns

An array of Column objects that identify the columns to appear in the grid.

Remarks

Setting the columns property removes all columns that are currently in the grid and replaces them with the new set of columns. To simply append a single column to the grid's collection of columns, call addColumn.

For information about setting the columns property in the Properties window, see Adding, Removing, and Rearranging Columns.

See Also getColumns


 DataGrid.setCurrentCellValue

DataGrid.setCurrentCellValue

Sets the value of the current cell.

Syntax

public void setCurrentCellValue( String val )

Parameters

val

A string that represents the value for the current cell.

Exceptions

WFCInvalidArgumentException thrown if the DataGrid control is not bound.

WFCException thrown if the allowUpdate property is set to false, the underlying recordset does not allow modifications, or the readOnly property of the cell's column is set to true.

Remarks

The string passed to setCurrentCellValue is automatically converted to a value of the appropriate type. The dataType property of the current column identifies the data type of the underlying field in the recordset.

See Also getCurrentCellValue


 DataGrid.setCurrentColumn

DataGrid.setCurrentColumn

Sets the current column in the grid.

Syntax

public void setCurrentColumn( Column column )

public void setCurrentColumn( int index )

Parameters

column

A Column object that represents the column to be made current.

index

The zero-based index of the column to be made current. A column's index indicates its position in the grid. The index of the last column is the value returned by getColumnCount minus 1. For more information, see the index property for Column objects.

Exceptions

WFCInvalidArgumentException thrown if column is null or if index is not a valid column index.

Remarks

When calling setCurrentColumn, the grid is automatically scrolled if the column to be made current is not visible. Note that setting the current column does not change the current row. To set the current row, call setCurrentRow.


 DataGrid.setCurrentRow

DataGrid.setCurrentRow

Moves the current position to the row associated with the specified bookmark.

Syntax

public void setCurrentRow( Object bookmark )

Parameters

row

The bookmark associated with the row to be made current.

Exceptions

WFCInvalidArgumentException thrown if the DataGrid control is not bound or if bookmark refers to an invalid row.

Remarks

Calling setCurrentRow will automatically scroll the grid if the row to be made current is not visible. Note that setting the current row does not change the current column. To set the current column, call setCurrentColumn.

See Also getCurrentRow


 DataGrid.setDataMember

DataGrid.setDataMember

Sets the bound member of the DataGrid control's underlying data source.

Syntax

public void setDataMember( String dataMember )

Parameters

dataMember

The name of the member of the underlying data source that is to be bound to the DataGrid control.

Remarks

To bind the DataGrid control to a recordset, first set the dataSource property to identify the data source associated with the control. A data source is an object that implements the IDataSource interface and exposes one or more recordsets. To specify which recordset is to be bound, set the dataMember property. For example:

/* Bind a DataGrid control to the recordset named
   "Products", which is exposed by the data source, ds.  */
dataGrid1.setDataSource(ds);
dataGrid1.setDataMember("Products");

If you do not call setDataMember, then the data source's default recordset will be bound. (You can explicitly specify the default recordset by setting the dataMember property to an empty string.)

/* Bind the control to the default recordset
   exposed by the data source, ds.  */
dataGrid1.setDataSource(ds);
dataGrid1.setDataMember("");  /* This line is optional.  */

Note that the ADO Recordset and DataSource components already implement the IDataSource interface. Therefore, you can set the dataSource property directly to one of these components. In this case, you do not have to set the dataMember property:

/* Pass the Recordset component, rs, directly to
   setDataSource without calling setDataMember.  */
dataGrid1.setDataSource(rs);

See Also getDataMember, getDataSource


 DataGrid.setDataSource

DataGrid.setDataSource

Sets the data source underlying the DataGrid control.

Syntax

public void setDataSource( IDataSource dataSource )

Parameters

dataSource

An object implementing the IDataSource interface that exposes the recordset to be bound to the DataGrid control.

Remarks

A data source is an object that implements the IDataSource interface and exposes one or more recordsets, one of which will be bound to the DataGrid control. To specify which recordset is bound, call setDataMember.

Note Because the ADO Recordset and DataSource components already implement the IDataSource interface, you can set the dataSource property directly to one of these components. In this case, you do not have to set the dataMember property.

See Also getDataSource, getDataMember


 DataGrid.setDefaultColumnWidth

DataGrid.setDefaultColumnWidth

Sets the default width for all columns in the grid.

Syntax

public void setDefaultColumnWidth( int width )

Parameters

width

The new default width (in pixels) for all columns in the grid. The default value of the defaultColumnWidth property is 75.

Remarks

To set the width of an individual column, use the width property of the Column object.

See Also getDefaultColumnWidth


 DataGrid.setDynamicColumns

DataGrid.setDynamicColumns

Sets a boolean value indicating whether the columns in the grid are determined dynamically.

Syntax

public void setDynamicColumns( boolean value )

Parameters

value

Set to true to determine the columns dynamically; otherwise, set to false. The default value of the dynamicColumns property is true.

Remarks

When the dynamicColumns property is set to true, the columns in the grid are always determined by the fields in the bound data source. However, if you change any column properties, the dynamicColumns property is automatically set to false, indicating the columns are static.

To reset the columns when the dynamicColumns property is set to true, call rebind. To reset the columns when this property is false, call setColumns.

See Also getDynamicColumns


 DataGrid.setEnterAction

DataGrid.setEnterAction

Sets a value indicating the behavior of the ENTER key within the grid.

Syntax

public void setEnterAction( int action )

Parameters

action

One of the constants defined by the EnterAction class. The default value of the enterAction property is EnterAction.NONE.

Exceptions

WFCInvalidEnumException thrown if action is not a valid action for the ENTER key.

Remarks

If the enterAction property is set to EnterAction.COLUMNNAVIGATION or EnterAction.ROWNAVIGATION, and the wrapCellPointer property is set to true, the current cell focus can wrap around rows or columns. For example, if the enterAction property is set to COLUMNNAVIGATION and the current cell focus is in the last column of the row, pressing the ENTER key will move the focus to the first column in the next row.

You can further define keyboard navigation in the grid by setting the allowArrows and tabAction properties.

See Also getEnterAction


 DataGrid.setFirstRow

DataGrid.setFirstRow

Sets the topmost visible row in the grid.

Syntax

public void setFirstRow( Object row )

Parameters

row

The bookmark associated with the row to be displayed as the topmost row.

Exceptions

WFCInvalidArgumentException thrown if the DataGrid control is not bound or if row does not refer to a valid row.

Remarks

Calling setFirstRow causes the grid to scroll so that the specified row becomes the topmost row. Note that the current row remains unchanged. To change the current row, call setCurrentRow.

See Also getFirstRow


 DataGrid.setGridLineStyle

DataGrid.setGridLineStyle

Sets the style of the control's gridlines.

Syntax

public void setGridLineStyle( int gridLineStyle )

Parameters

gridLineStyle

One of the constants defined by the GridLineStyle class. The default value of the gridLineStyle property is GridLineStyle.SINGLELINE.

Exceptions

WFCInvalidArgumentException thrown if gridLineStyle is not a valid style.

See Also getGridLineStyle


 DataGrid.setHeaderFont

DataGrid.setHeaderFont

Sets the font of the grid's column headers.

Syntax

public void setHeaderFont( Font headerFont )

Parameters

headerFont

A Font object that specifies the new font of the column headers.

Remarks

By default, the column headers use the font of the text in the cells, which is defined by the DataGrid control's font property. Call setHeaderFont to draw the column headers in a different font. If necessary, the height of the headers will be automatically resized to accommodate the new font.

To return to the default font setting, set the headerFont property to null.

See Also getHeaderFont


 DataGrid.setHeaderLineCount

DataGrid.setHeaderLineCount

Sets the number of lines of text that can be displayed in the grid's column headers.

Syntax

public void setHeaderLineCount( int lines )

Parameters

lines

The number of lines of text that can be displayed in the columns headers. The default value is 1.

Exceptions

WFCInvalidArgumentException thrown if lines is less than 1.

Remarks

The height of the column headers is determined by the values of the headerLineCount and headerFont properties.

To hide the column headers, set the columnHeaders property to false. To change the text that is displayed in the headers, set the caption properties of the individual Column objects.

See Also getHeaderLineCount


 DataGrid.setLeftColumn

DataGrid.setLeftColumn

Sets the leftmost visible column in the grid.

Syntax

public void setLeftColumn( int index )

Parameters

index

The zero-based index of the column to be displayed as the leftmost column. A column's index indicates its position in the grid. The index of the last column is the value returned by getColumnCount minus 1. For more information, see the index property for Column objects.

Exceptions

WFCInvalidArgumentException thrown if index is not a valid column index.

Remarks

Calling setLeftColumn causes the grid to scroll so that the specified column becomes the leftmost column. Note that the current column remains unchanged. To change the current column, call setCurrentColumn.


 DataGrid.setRowHeight

DataGrid.setRowHeight

Sets the height of the rows in the grid.

Syntax

public void setRowHeight( int rowHeight )

Parameters

rowHeight

The new height (in pixels) for the rows in the grid. The default value of the rowHeight property is 20.

Exceptions

WFCInvalidArgumentException thrown if rowHeight is less than MIN_ROW_HEIGHT.

Remarks

All rows in the grid have the same height. If the allowRowSizing property is set to true, the rows can be resized at run time, either programmatically or by the user. The rowHeight property is then automatically set to the new height. Note that if the allowRowSizing property is false, the row height cannot be changed.

See Also getRowHeight


 DataGrid.setRowSelectors

DataGrid.setRowSelectors

Sets a boolean value indicating whether row selectors are displayed in the grid.

Syntax

public void setRowSelectors( boolean selectors )

Parameters

selectors

Set to true to display a row selector for the rows in the grid; otherwise, set to false. The default value of the rowSelectors property is true.

Remarks

Row selectors appear to the left of the rows. The user can select a row by clicking its row selector.

See Also getRowSelectors


 DataGrid.setScrollbars

DataGrid.setScrollbars

Sets a value indicating which scroll bars are displayed.

Syntax

public void setScrollbars( int scroll )

Parameters

scroll

One of the constants defined by the Scrollbars class. The default value of the scrollbars property is Scrollbars.BOTH.

Exceptions

WFCInvalidArgumentException thrown if scroll is not a valid scroll bar setting.

Remarks

When the scrollbars property is set to either Scrollbars.VERTICAL, Scrollbars.HORIZONTAL, or Scrollbars.BOTH, the specified scroll bars are always displayed, even if all rows or columns are currently visible in the grid.

If the scrollbars property is set to Scrollbars.NONE, the keyboard can still be used to scroll the grid, provided the allowArrows, enterAction, and tabAction properties are set appropriately.

See Also getScrollbars


 DataGrid.setSelectedBackColor

DataGrid.setSelectedBackColor

Sets the background color for selected cells in the grid.

Syntax

public void setSelectedBackColor( Color color )

Parameters

color

A Color object that specifies the background color for selected cells in the grid.

Remarks

Use the DataGrid control's selectedBackColor property to set the default background color for all selected cells in the grid. To then customize this color for an individual column, set the Column object's selectedBackColor property. The selectedBackColor setting for a column overrides the grid's setting, for that particular column.

The default value of the grid's selectedBackColor property is Color.HIGHLIGHT. To return to this default, pass null to setSelectedBackColor.

To set the background color of nonselected cells in the grid, call setBackColor.

See Also getSelectedBackColor


 DataGrid.setSelectedColumns

DataGrid.setSelectedColumns

Selects the specified columns.

Syntax

public void setSelectedColumns( Column[] columns )

Parameters

columns

An array of Column objects that identify the columns to be selected.

Remarks

Calling setSelectedColumns clears any previous selection in the grid. Note that you cannot select both columns and rows at the same time. To programmatically select rows, call setSelectedRows.

The DataGrid control does not support the selection of single cells.

See Also getSelectedColumns, clearSelection


 DataGrid.setSelectedForeColor

DataGrid.setSelectedForeColor

Sets the color for selected text in the grid.

Syntax

public void setSelectedForeColor( Color color )

Parameters

color

A Color object that specifies the color for selected text in the grid.

Remarks

Use the DataGrid control's selectedForeColor property to set the default color for selected text in all columns in the grid. To then customize this color for an individual column, set the Column object's selectedForeColor property. The selectedForeColor setting for a column overrides the grid's setting, for that particular column.

The default value of the grid's selectedForeColor property is Color.HIGHLIGHTTEXT. To return to this default, pass null to setSelectedForeColor.

To set the color of text when it is not selected, call setForeColor.

See Also getSelectedForeColor


 DataGrid.setSelectedRows

DataGrid.setSelectedRows

Selects the rows associated with the specified bookmarks.

Syntax

public void setSelectedRows( Object[] bookmarks )

Parameters

bookmarks

An array of bookmarks associated with the rows to be selected.

Remarks

Calling setSelectedRows clears any previous selection in the grid. Note that you cannot select both rows and columns at the same time. To programmatically select columns, call setSelectedColumns.

The DataGrid control does not support the selection of single cells.

See Also getSelectedRows, clearSelection


 DataGrid.setTabAction

DataGrid.setTabAction

Sets a value indicating the behavior of the TAB key within the grid.

Syntax

public void setTabAction( int action )

Parameters

action

One of the constants defined by the TabAction class. The default value of the tabAction property is TabAction.CONTROLNAVIGATION.

Exceptions

WFCInvalidArgumentException thrown if action is not a valid action for the TAB key.

Remarks

If the tabAction property is set to TabAction.COLUMNNAVIGATION or TabAction.ROWNAVIGATION, and the wrapCellPointer property is set to true, the current cell focus can wrap around rows or columns. For example, if the tabAction property is set to COLUMNNAVIGATION and the current cell focus is in the last column of the row, pressing the TAB key will move the focus to the first column in the next row.

You can further define keyboard navigation in the grid by setting the allowArrows and enterAction properties.

See Also getTabAction


 DataGrid.setWrapCellPointer

DataGrid.setWrapCellPointer

Sets a boolean value that indicates whether the TAB, ENTER, and arrow keys can be used to wrap the current cell focus around rows and columns.

Syntax

public void setWrapCellPointer( boolean wrapCellPointer )

Parameters

wrapCellPointer

Set to true to enable the current cell focus to wrap around rows or columns; otherwise, set to false. The default value of the wrapCellPointer property is false.

Remarks

The tabAction, enterAction, and allowArrows properties determine whether the TAB, ENTER, and arrow keys can be used to navigate within a row or column of the grid. When the wrapCellPointer property is set to true, these keys can then be used to wrap the current cell focus around rows and columns. For example, if the user is navigating within a row, the current cell focus will wrap from the last column to the first column in the next row (or from the first column to the last column in the previous row).

See Also getWrapCellPointer


 DataGrid Fields

DataGrid Fields

Fields | Description
MIN_COLUMN_WIDTH | Specifies the minimum width (in pixels) of the columns in the grid.
MIN_ROW_HEIGHT | Specifies the minimum height (in pixels) of the rows in the grid.


 DataGrid.MIN_COLUMN_WIDTH

DataGrid.MIN_COLUMN_WIDTH

Specifies the minimum width (in pixels) of the columns in the grid.

Syntax

public static final int MIN_COLUMN_WIDTH;

Remarks

The columns in the grid cannot be resized to a value less than MIN_COLUMN_WIDTH. (By default, this constant is defined to be 10.)

See Also Column.setWidth


 DataGrid.MIN_ROW_HEIGHT

DataGrid.MIN_ROW_HEIGHT

Specifies the minimum height (in pixels) of the rows in the grid.

Syntax

public static final int MIN_ROW_HEIGHT;

Remarks

The rows in the grid cannot be resized to a value less than MIN_ROW_HEIGHT. (By default, this constant is defined to be 5.)

See Also setRowHeight


DataNavigator Class

Allows the user to change the current record in an ADO recordset.

Component
  |
  +--Control
       |
       +--DataNavigator

package com.ms.wfc.data.ui

public class DataNavigator
extends Control

Remarks

To bind the DataNavigator control to a recordset, set its dataSource property (and optionally, the dataMember property). Typically, you use the DataNavigator control in conjunction with the DataBinder control. The DataBinder control binds the property of another control to a field in the recordset. This property obtains data from the recordset's current record, which is initially the first record. In order for the user to move to another record, use a DataNavigator control that is bound to the same recordset.

The DataNavigator control provides four buttons that allow the user to navigate the recordset:

Button | Navigation Direction
<< | Move to the first record.
< | Move to the previous record.
> | Move to the next record.
>> | Move to the last record.

For information about using the DataNavigator control in the Forms Designer, see Navigating Records.


 DataNavigator Methods

DataNavigator Methods

Constructors | Description
DataNavigator | Creates a DataNavigator control.

Methods | Description
getDataMember | Retrieves the bound member of the DataNavigator control's underlying data source.
getDataSource | Retrieves the data source underlying the DataNavigator control.
moveFirst | Moves the underlying recordset to the first record.
moveLast | Moves the underlying recordset to the last record.
moveNext | Moves the underlying recordset to the next record.
movePrevious | Moves the underlying recordset to the previous record.
setDataMember | Sets the bound member of the DataNavigator control's underlying data source.
setDataSource | Sets the data source underlying the DataNavigator control.


 DataNavigator.DataNavigator

DataNavigator.DataNavigator

Creates a DataNavigator control.

Syntax

public DataNavigator()

Remarks

Once you have created a DataNavigator control, call setDataSource (and optionally, setDataMember) to bind the control to a recordset.


 DataNavigator.getDataMember

DataNavigator.getDataMember

Retrieves the bound member of the DataNavigator control's underlying data source.

Syntax

public final String getDataMember()

Return Value

Returns a string that identifies the bound member of the underlying data source. This string is either the name of the bound recordset or is an empty string. For more information, see setDataMember.

Remarks

To retrieve the data source object that underlies the DataNavigator control, call getDataSource.


 DataNavigator.getDataSource

DataNavigator.getDataSource

Retrieves the data source underlying the DataNavigator control.

Syntax

public final IDataSource getDataSource()

Return Value

Returns an object implementing the IDataSource interface that currently exposes the recordset that is bound to the DataNavigator control. For more information, see setDataSource.

Remarks

To retrieve the bound member of the underlying data source, call getDataMember.


 DataNavigator.moveFirst

DataNavigator.moveFirst

Moves the underlying recordset to the first record.

Syntax

protected void moveFirst( Recordset recordset )

Parameters

recordset

A Recordset object that represents the underlying recordset.

Remarks

This method is invoked when the user presses the button to move to the first record. You can override moveFirst to add your own error handling or additional behavior.

See Also moveLast, moveNext, movePrevious


 DataNavigator.moveLast

DataNavigator.moveLast

Moves the underlying recordset to the last record.

Syntax

protected void moveLast( Recordset recordset )

Parameters

recordset

A Recordset object that represents the underlying recordset.

Remarks

This method is invoked when the user presses the button to move to the last record. You can override moveLast to add your own error handling or additional behavior.

See Also moveFirst, moveNext, movePrevious


 DataNavigator.moveNext

DataNavigator.moveNext

Moves the underlying recordset to the next record.

Syntax

protected void moveNext( Recordset recordset )

Parameters

recordset

A Recordset object that represents the underlying recordset.

Remarks

This method is invoked when the user presses the button to move to the next record. Note that if the last record is current when moveNext is called, the position of the recordset will remain unchanged.

You can override moveNext to add your own error handling or additional behavior.

See Also moveFirst, moveLast, movePrevious


 DataNavigator.movePrevious

DataNavigator.movePrevious

Moves the underlying recordset to the previous record.

Syntax

protected void movePrevious( Recordset recordset )

Parameters

recordset

A Recordset object that represents the underlying recordset.

Remarks

This method is invoked when the user presses the button to move to the previous record. Note that if the first record is current when movePrevious is called, the position of the recordset will remain unchanged.

You can override movePrevious to add your own error handling or additional behavior.

See Also moveFirst, moveLast, moveNext


 DataNavigator.setDataMember

DataNavigator.setDataMember

Sets the bound member of the DataNavigator control's underlying data source.

Syntax

public void setDataMember( String dataMember )

Parameters

dataMember

The name of the member of the underlying data source that is to be bound to the DataNavigator control.

Remarks

To bind the DataNavigator control to a recordset, first set the dataSource property to identify the data source associated with the control. A data source is an object that implements the IDataSource interface and exposes one or more recordsets. To specify which recordset is to be bound, set the dataMember property. For example:

/* Bind a DataNavigator control to the recordset named
   "Products", which is exposed by the data source, ds. */
dataNavigator1.setDataSource(ds);
dataNavigator1.setDataMember("Products");

If you do not call setDataMember, then the data source's default recordset will be bound. (You can explicitly specify the default recordset by setting the dataMember property to an empty string.)

/* Bind the control to the default recordset
   exposed by the data source, ds. */
dataNavigator1.setDataSource(ds);
dataNavigator1.setDataMember("");  /* This line is optional. */

Note that the ADO Recordset and DataSource components already implement the IDataSource interface. Therefore, you can set the dataSource property directly to one of these components. In this case, you do not have to set the dataMember property:

/* Pass the Recordset component, rs, directly to
   setDataSource without calling setDataMember. */
dataNavigator1.setDataSource(rs);

See Also getDataMember, getDataSource


 DataNavigator.setDataSource

DataNavigator.setDataSource

Sets the data source underlying the DataNavigator control.

Syntax

public void setDataSource( IDataSource dataSource )

Parameters

dataSource

An object implementing the IDataSource interface that exposes the recordset to be bound to the DataNavigator control.

Remarks

A data source is an object that implements the IDataSource interface and exposes one or more recordsets, one of which will be bound to the DataNavigator control. To specify which recordset is bound, call setDataMember.

Note Because the ADO Recordset and DataSource components already implement the IDataSource interface, you can set the dataSource property directly to one of these components. In this case, you do not have to set the dataMember property.

See Also getDataSource, getDataMember


DataSource Class

Provides data to a component.

Component
  |
  +--DataSource

package com.ms.wfc.data.ui

public class DataSource
extends Component
implements IRequireBegin, IDataSource, IDataSourceListener

Remarks

The DataSource control combines the functionality of the ADO Connection, Command, and Recordset objects.


 DataSource Methods

DataSource Methods

Constructors | Description
DataSource | Creates a DataSource control.

Methods | Description
begin | Opens a connection to the data source.
close | Closes the connection to the data source.
dispose | Disposes of this component.
getAsyncConnect | Retrieves a boolean value indicating whether the connection to the data source will be made asynchronously.
getAsyncExecute | Retrieves a boolean value indicating whether commands to the data source will be executed asynchronously.
getAsyncFetch | Retrieves a boolean value indicating whether a recordset resulting from a query to the data source will be fetched asynchronously.
getCacheSize | Retrieves the number of records that can be cached locally in memory.
getCommand | Retrieves the Command object associated with the data source.
getCommandText | Retrieves the command string issued to the data source.
getCommandTimeout | Retrieves the amount of time to wait for a command to complete before terminating the attempt.
getCommandType | Retrieves the type of command issued to the data source.
getConnection | Retrieves the Connection object associated with the data source.
getConnectionString | Retrieves the string used to make a connection to the data source.
getConnectionTimeout | Retrieves the amount of time to wait for a connection to be established before terminating the attempt.
getCursorLocation | Retrieves the location of the cursor engine.
getCursorType | Retrieves the type of cursor used by the data source.
getDesignTimeData | Retrieves a boolean value indicating whether a connection should be made to the data source while working on a form in a visual designer.
getFilter | Retrieves the criteria for including or excluding records.
getIsolationLevel | Retrieves the degree to which this DataSource object is aware of transactions made by other users to the same data source.
getLockType | Retrieves the type of lock placed on a recordset during editing.
getMaxRecords | Retrieves the maximum number of records to return from a query.
getMode | Retrieves the available permissions for modifying data in the connection to the data source.
getParentDataSource | Retrieves the parent data source in a hierarchical recordset.
getParentFieldName | Retrieves the name of the field that associates the parent and child recordsets of a hierarchical recordset.
getPassword | Retrieves the password specified in the connection to the data source.
getPrepared | Retrieves a boolean value indicating whether the associated command is optimized for execution (prepared).
getRecordset | Retrieves the recordset associated with the data source.
getSort | Retrieves the sort order for the data source.
getStayInSync | Retrieves a boolean value indicating whether the row position in a child recordset will change to correspond to a change in the row position of the parent recordset.
getUserId | Retrieves the user identification specified in the connection to the data source.
isChildDataSource | Indicates whether this data source is the child recordset in a hierarchical recordset.
requery | Re-executes the command that created the recordset associated with the data source.
setAsyncConnect | Sets a boolean value indicating whether the connection to the data source will be made asynchronously.
setAsyncExecute | Sets a boolean value indicating whether the commands to the data source will be executed asynchronously.
setAsyncFetch | Sets a boolean value indicating whether a recordset resulting from a query to the data source will be fetched asynchronously.
setCacheSize | Sets the number of records that can be cached locally in memory.
setCommandText | Sets the command string that will be issued to the data source.
setCommandTimeout | Sets the amount of time to wait for a command to complete before terminating the attempt.
setCommandType | Sets the type of command issued to the data source.
setConnectionString | Sets the string used to make a connection to the data source.
setConnectionTimeout | Sets the amount of time to wait for a connection to be established before terminating the attempt.
setCursorLocation | Sets the location of the cursor engine.
setCursorType | Sets the type of cursor used by the data source.
setDesignTimeData | Sets a boolean value indicating whether a connection should be made to the data source while working on a form in a visual designer.
setFilter | Sets the criteria for including or excluding records.
setIsolationLevel | Sets the degree to which this DataSource object is aware of transactions made by other users to the same data source.
setLockType | Sets the type of lock placed on a recordset during editing.
setMaxRecords | Sets the maximum number of records to return from a query.
setMode | Sets the available permissions for modifying data in the connection to the data source.
setParentDataSource | Sets the parent data source in a hierarchical recordset.
setParentFieldName | Sets the name of the field that associates the parent and child recordsets of a hierarchical recordset.
setPassword | Sets the password for the connection to the data source.
setPrepared | Sets a boolean value indicating whether the associated command should be optimized for execution (prepared).
setSort | Sets the sort order for the data source.
setStayInSync | Sets a boolean value indicating whether the row position in a child recordset will change to correspond to a change in the row position of the parent recordset.
setUserId | Sets the user identification for the connection to the data source.


 DataSource.begin

DataSource.begin

Opens a connection to the data source.

Syntax

public void begin()

Remarks

If a command is associated with the DataSource object, the command is executed and the resulting recordset is opened.

See Also close


 DataSource.close

DataSource.close

Closes the connection to the data source.

Syntax

public void close()

See Also begin


 DataSource.DataSource

DataSource.DataSource

Creates a DataSource control.

Syntax

public DataSource()


 DataSource.dispose

DataSource.dispose

Disposes of this component.

Syntax

public void dispose()


 DataSource.getAsyncConnect

DataSource.getAsyncConnect

Retrieves a boolean value indicating whether the connection to the data source will be made asynchronously.

Syntax

public boolean getAsyncConnect()

Return Value

Returns true if the connection will be made asynchronously; otherwise, returns false.

See Also setAsyncConnect


 DataSource.getAsyncExecute

DataSource.getAsyncExecute

Retrieves a boolean value indicating whether commands to the data source will be executed asynchronously.

Syntax

public boolean getAsyncExecute()

Return Value

Returns true if commands will be executed asynchronously; otherwise, returns false.

See Also setAsyncExecute


 DataSource.getAsyncFetch

DataSource.getAsyncFetch

Retrieves a boolean value indicating whether a recordset resulting from a query to the data source will be fetched asynchronously.

Syntax

public boolean getAsyncFetch()

Return Value

Returns true if the recordset will be fetched asynchronously; otherwise, returns false.

See Also setAsyncFetch


 DataSource.getCacheSize

DataSource.getCacheSize

Retrieves the number of records that can be cached locally in memory.

Syntax

public int getCacheSize()

Return Value

Returns the number of records that can be cached locally.

See Also setCacheSize, ADO CacheSize property


 DataSource.getCommand

DataSource.getCommand

Retrieves the Command object associated with the data source.

Syntax

public Command getCommand()

Return Value

Returns the associated Command object.

See Also getRecordset, getConnection


 DataSource.getCommandText

DataSource.getCommandText

Retrieves the command string issued to the data source.

Syntax

public String getCommandText()

Return Value

Returns the command string.

Remarks

The command is typically a query that will return a recordset.

See Also setCommandText, getCommandType


 DataSource.getCommandTimeout

DataSource.getCommandTimeout

Retrieves the amount of time to wait for a command to complete before terminating the attempt.

Syntax

public int getCommandTimeout()

Return Value

Returns the time in seconds to wait.

See Also setCommandTimeout, ADO CommandTimeout property


 DataSource.getCommandType

DataSource.getCommandType

Retrieves the type of command issued to the data source.

Syntax

public int getCommandType()

Return Value

Returns one of the values defined in the AdoEnums.CommandType class.

Remarks

The appropriate setting for the commandType property enhances the evaluation of the command text.

See Also setCommandType, getCommandText


 DataSource.getConnection

DataSource.getConnection

Retrieves the Connection object associated with the data source.

Syntax

public Connection getConnection()

Return Value

Returns the associated Connection object.

See Also getRecordset, getCommand


 DataSource.getConnectionString

DataSource.getConnectionString

Retrieves the string used to make a connection to the data source.

Syntax

public String getConnectionString()

Return Value

Returns the connection string.

See Also setConnectionString


 DataSource.getConnectionTimeout

DataSource.getConnectionTimeout

Retrieves the amount of time to wait for a connection to be established before terminating the attempt.

Syntax

public int getConnectionTimeout()

Return Value

Returns the time in seconds to wait.

See Also setConnectionTimeout, ADO ConnectionTimeout property


 DataSource.getCursorLocation

DataSource.getCursorLocation

Retrieves the location of the cursor engine.

Syntax

public int getCursorLocation()

Return Value

Returns one of the values defined in the AdoEnums.CursorLocation class.

Remarks

The cursorLocation property provides either client-side or server-side cursor support.

See Also setCursorLocation


 DataSource.getCursorType

DataSource.getCursorType

Retrieves the type of cursor used by the data source.

Syntax

public int getCursorType()

Return Value

Returns one of the values defined in the AdoEnums.CursorType class.

See Also setCursorType


 DataSource.getDesignTimeData

DataSource.getDesignTimeData

Retrieves a boolean value indicating whether a connection should be made to the data source while working on a form in a visual designer.

Syntax

public boolean getDesignTimeData()

Return Value

Returns true if the connection will be made in design mode; otherwise, returns false.

See Also setDesignTimeData


 DataSource.getFilter

DataSource.getFilter

Retrieves the criteria for including or excluding records.

Syntax

public String getFilter()

Return Value

Returns a string that specifies the criteria for the filter. For more information, see setFilter.

See Also ADO Filter property


 DataSource.getIsolationLevel

DataSource.getIsolationLevel

Retrieves the degree to which this DataSource object is aware of transactions made by other users to the same data source.

Syntax

public int getIsolationLevel()

Return Value

Returns one of the values defined in the AdoEnums.IsolationLevel class.

See Also setIsolationLevel


 DataSource.getLockType

DataSource.getLockType

Retrieves the type of lock placed on a recordset during editing.

Syntax

public int getLockType()

Return Value

Returns one of the values defined in the AdoEnums.LockType class.

See Also setLockType


 DataSource.getMaxRecords

DataSource.getMaxRecords

Retrieves the maximum number of records to return from a query.

Syntax

public int getMaxRecords()

Return Value

Returns the number of records to be returned from a query in a recordset.

See Also setMaxRecords, ADO MaxRecords property


 DataSource.getMode

DataSource.getMode

Retrieves the available permissions for modifying data in the connection to the data source.

Syntax

public int getMode()

Return Value

Returns one of the values defined in the AdoEnums.ConnectMode class.

See Also setMode


 DataSource.getParentDataSource

DataSource.getParentDataSource

Retrieves the parent data source in a hierarchical recordset.

Syntax

public DataSource getParentDataSource()

Return Value

Returns the parent DataSource object.

See Also setParentDataSource


 DataSource.getParentFieldName

DataSource.getParentFieldName

Retrieves the name of the field that associates the parent and child recordsets of a hierarchical recordset.

Syntax

public String getParentFieldName()

Return Value

Returns the name of the parent field.

See Also setParentFieldName


 DataSource.getPassword

DataSource.getPassword

Retrieves the password specified in the connection to the data source.

Syntax

public String getPassword()

Return Value

Returns the password associated with the data source.

See Also setPassword


 DataSource.getPrepared

DataSource.getPrepared

Retrieves a boolean value indicating whether the associated command is optimized for execution (prepared).

Syntax

public boolean getPrepared()

Return Value

Returns true if the command has been prepared; otherwise, returns false.

Remarks

The performance of a command that is executed several times will be enhanced if the command is prepared.

See Also setPrepared


 DataSource.getRecordset

DataSource.getRecordset

Retrieves the recordset associated with the data source.

Syntax

public Recordset getRecordset()

Return Value

Returns the associated Recordset object.

Remarks

If the associated recordset is closed, this method opens it. If no recordset is set, a default one is created.

See Also getCommand, getConnection


 DataSource.getSort

DataSource.getSort

Retrieves the sort order for the data source.

Syntax

public String getSort()

Return Value

Returns a string specifying one or more field names the recordset is sorted on, and whether each field is sorted in ascending or descending order.

See Also setSort, ADO Sort property


 DataSource.getStayInSync

DataSource.getStayInSync

Retrieves a boolean value indicating whether the row position in a child recordset will change to correspond to a change in the row position of the parent recordset.

Syntax

public boolean getStayInSync()

Return Value

Returns true if the child and parent row positions will stay in synchronization; otherwise, returns false.

See Also setStayInSync


 DataSource.getUserId

DataSource.getUserId

Retrieves the user identification specified in the connection to the data source.

Syntax

public String getUserId()

Return Value

Returns the user identification associated with the data source.

See Also setUserID


 DataSource.isChildDataSource

DataSource.isChildDataSource

Indicates whether this data source is the child recordset in a hierarchical recordset.

Syntax

public boolean isChildDataSource()

Return Value

Returns true if the data source is a child recordset; otherwise, returns false.

See Also getParentDataSource, setParentDataSource


 DataSource.requery

DataSource.requery

Re-executes the command that created the recordset associated with the data source.

Syntax

public void requery()

Remarks

If the recordset is currently open, it is closed before the command is re-executed.


 DataSource.setAsyncConnect

DataSource.setAsyncConnect

Sets a boolean value indicating whether the connection to the data source will be made asynchronously.

Syntax

public void setAsyncConnect( boolean asyncConnect )

Parameters

asyncConnect

Set to true for the connection to be made asynchronously; otherwise, set to false.

See Also getAsyncConnect


 DataSource.setAsyncExecute

DataSource.setAsyncExecute

Sets a boolean value indicating whether the commands to the data source will be executed asynchronously.

Syntax

public void setAsyncExecute( boolean asyncExecute )

Parameters

asyncExecute

Set to true for commands to be executed asynchronously; otherwise, set to false.

See Also getAsyncExecute


 DataSource.setAsyncFetch

DataSource.setAsyncFetch

Sets a boolean value indicating whether a recordset resulting from a query to the data source will be fetched asynchronously.

Syntax

public void setAsyncFetch( boolean asyncFetch )

Parameters

asyncFetch

Set to true for the recordset to be fetched asynchronously; otherwise, set to false.

See Also getAsyncFetch


 DataSource.setCacheSize

DataSource.setCacheSize

Sets the number of records that can be cached locally in memory.

Syntax

public void setCacheSize( int cacheSize )

Parameters

cacheSize

The number of records that can be cached locally.

See Also getCacheSize, ADO CacheSize property


 DataSource.setCommandText

DataSource.setCommandText

Sets the command string that will be issued to the data source.

Syntax

public void setCommandText( String cmdText )

Parameters

cmdText

The command text.

Remarks

The command is typically a query that will return a recordset.

See Also getCommandText, setCommandType


 DataSource.setCommandTimeout

DataSource.setCommandTimeout

Sets the amount of time to wait for a command to complete before terminating the attempt.

Syntax

public void setCommandTimeout( int timeout )

Parameters

timeout

The time in seconds to wait.

See Also getCommandTimeout, ADO CommandTimeout property


 DataSource.setCommandType

DataSource.setCommandType

Sets the type of command issued to the data source.

Syntax

public void setCommandType( int commandType )

Parameters

commandType

One of the values defined in the AdoEnums.CommandType class.

Remarks

The appropriate setting for the commandType property enhances the evaluation of the command text.

See Also getCommandType, getCommandText


 DataSource.setConnectionString

DataSource.setConnectionString

Sets the string used to make a connection to the data source.

Syntax

public void setConnectionString( String connectionString )

Parameters

connectionString

The connection string.

See Also getConnectionString


 DataSource.setConnectionTimeout

DataSource.setConnectionTimeout

Sets the amount of time to wait for a connection to be established before terminating the attempt.

Syntax

public void setConnectionTimeout( int timeout )

Parameters

timeout

The time in seconds to wait.

See Also getConnectionTimeout, ADO ConnectionTimeout property


 DataSource.setCursorLocation

DataSource.setCursorLocation

Sets the location of the cursor engine.

Syntax

public void setCursorLocation( int cursorLocation )

Parameters

cursorLocation

One of the values defined in the AdoEnums.CursorLocation class.

Remarks

The cursorLocation property provides either client-side or server-side cursor support.

See Also getCursorLocation


 DataSource.setCursorType

DataSource.setCursorType

Sets the type of cursor used by the data source.

Syntax

public void setCursorType( int cursorType )

Parameters

cursorType

One of the values defined in the AdoEnums.CursorType class.

See Also getCursorType


 DataSource.setDesignTimeData

DataSource.setDesignTimeData

Sets a boolean value indicating whether a connection should be made to the data source while working on a form in a visual designer.

Syntax

public void setDesignTimeData( boolean fDesign )

Parameters

fDesign

Set to true if a connection should be made in design mode; otherwise, set to false.

See Also getDesignTimeData


 DataSource.setFilter

DataSource.setFilter

Sets the criteria for including or excluding records.

Syntax

public void setFilter( String filter )

Parameters

filter

A string that indicates the criteria for the filter.

Remarks

The criteria string is made up of clauses in the form FieldName-Operator-Value. You can join clauses with AND and OR.

  • FieldName is a name of a field in the recordset. You should enclose field names that contain spaces in square brackets.
  • Operator is one of the following: <, >, <=,>=, <>, =, LIKE. If Operator is LIKE, then Value can use wildcards. The asterisk (*) wildcard matches any number of characters, and the percent sign (%) wildcard matches one character. You can either use a wildcard at the beginning and end of a pattern, or only at the end.
  • Value is what you compare to the value of FieldName. Use single quotes with strings and pound signs (#) with dates. For numbers, you can use decimal points, dollar signs, and scientific notation.

See Also getFilter, ADO Filter property


 DataSource.setIsolationLevel

DataSource.setIsolationLevel

Sets the degree to which this DataSource object is aware of transactions made by other users to the same data source.

Syntax

public void setIsolationLevel( int level )

Parameters

level

One of the values defined in the AdoEnums.IsolationLevel class.

See Also getIsolationLevel


 DataSource.setLockType

DataSource.setLockType

Sets the type of lock placed on a recordset during editing.

Syntax

public void setLockType( int lockType )

Parameters

lockType

One of the values defined in the AdoEnums.LockType class.

See Also getLockType


 DataSource.setMaxRecords

DataSource.setMaxRecords

Sets the maximum number of records to return from a query.

Syntax

public void setMaxRecords( int maxRecords )

Parameters

maxRecords

The maximum number of records to return.

See Also getMaxRecords, ADO MaxRecords property


 DataSource.setMode

DataSource.setMode

Sets the available permissions for modifying data in the connection to the data source.

Syntax

public void setMode( int mode )

Parameters

mode

One of the values defined in the AdoEnums.ConnectMode class.

See Also getMode


 DataSource.setParentDataSource

DataSource.setParentDataSource

Sets the parent data source in a hierarchical recordset.

Syntax

public void setParentDataSource( DataSource source )

Parameters

source

The parent DataSource object.

See Also getParentDataSource


 DataSource.setParentFieldName

DataSource.setParentFieldName

Sets the name of the field that associates the parent and child recordsets of a hierarchical recordset.

Syntax

public void setParentFieldName( String name )

Parameters

name

The name of the parent field.

See Also getParentFieldName


 DataSource.setPassword

DataSource.setPassword

Sets the password for the connection to the data source.

Syntax

public void setPassword( String password )

Parameters

password

The password to associate with the data source.

See Also getPassword


 DataSource.setPrepared

DataSource.setPrepared

Sets a boolean value indicating whether the associated command should be optimized for execution (prepared).

Syntax

public void setPrepared( boolean prepared )

Parameters

prepared

Set to true to prepare the command; otherwise, set to false.

Remarks

The performance of a command that is executed several times will be enhanced if the command is prepared.

See Also getPrepared


 DataSource.setSort

DataSource.setSort

Sets the sort order for the data source.

Syntax

public void setSort( String sort )

Parameters

sort

A string that specifies one or more field names to sort the recordset on, and whether each field is sorted in ascending or descending order.

See Also getSort, ADO Sort property


 DataSource.setStayInSync

DataSource.setStayInSync

Sets a boolean value indicating whether the row position in a child recordset will change to correspond to a change in the row position of the parent recordset.

Syntax

public void setStayInSync( boolean stayInSync )

Parameters

stayInSync

Set to true for the child and parent row positions to stay in synchronization; otherwise, set to false.

See Also getStayInSync


 DataSource.setUserId

DataSource.setUserId

Sets the user identification for the connection to the data source.

Syntax

public void setUserId( String userId )

Parameters

userId

The user identification to associate with the data source.

See Also getUserID


EnterAction Class

Defines the constants that specify the behavior of the ENTER key within a DataGrid control.

Enum
  |
  +--EnterAction

package com.ms.wfc.data.ui

public class EnterAction
extends Enum

Remarks

Use the EnterAction constants to set the value of the DataGrid control's enterAction property.


 EnterAction Fields

EnterAction Fields

Fields | Description
COLUMNNAVIGATION | Specifies that the ENTER key will move focus to the cell in the next column, within the same row.
NONE | Specifies that the ENTER key cannot be used to move the current cell focus within the grid.
ROWNAVIGATION | Specifies that the ENTER key will move focus to the cell in the next row, within the same column.


 EnterAction.COLUMNNAVIGATION

EnterAction.COLUMNNAVIGATION

Specifies that the ENTER key will move focus to the cell in the next column, within the same row.

Syntax

public static final int COLUMNNAVIGATION;

See Also DataGrid.getEnterAction, DataGrid.setEnterAction


 EnterAction.NONE

EnterAction.NONE

Specifies that the ENTER key cannot be used to move the current cell focus within the grid.

Syntax

public static final int NONE;

See Also DataGrid.getEnterAction, DataGrid.setEnterAction


 EnterAction.ROWNAVIGATION

EnterAction.ROWNAVIGATION

Specifies that the ENTER key will move focus to the cell in the next row, within the same column.

Syntax

public static final int ROWNAVIGATION;

See Also DataGrid.getEnterAction, DataGrid.setEnterAction


ErrorEvent Class

Provides data for the error event of the DataGrid control.

Event
  |
  +--ErrorEvent

package com.ms.wfc.data.ui

public class ErrorEvent
extends Event

Remarks

The error event occurs as the result of an ADO exception. An ErrorEvent object specifies the ADO exception that was thrown, and provides a flag to indicate whether an unhandled exception dialog box should be displayed.

For information about the WFC event model, see Handling Events in WFC.


 ErrorEvent Methods

ErrorEvent Methods

Constructors | Description
ErrorEvent | Creates a ErrorEvent object.


 ErrorEvent.ErrorEvent

ErrorEvent.ErrorEvent

Creates a ErrorEvent object.

Syntax

public ErrorEvent( Throwable error, boolean displayDialog )

Parameters

error

The ADO exception that was generated.

displayDialog

Set to true to display an unhandled exception dialog box; otherwise, set to false.


 ErrorEvent Fields

ErrorEvent Fields

Fields | Description
displayDialog | Indicates whether an unhandled exception dialog box should be displayed.
error | Specifies the ADO exception that was generated.


 ErrorEvent.displayDialog

ErrorEvent.displayDialog

Indicates whether an unhandled exception dialog box should be displayed.

Syntax

public boolean displayDialog;


 ErrorEvent.error

ErrorEvent.error

Specifies the ADO exception that was generated.

Syntax

public final Throwable error;


ErrorEventHandler Delegate

Identifies the method that will handle the error event of a DataGrid control.

package com.ms.wfc.data.ui

public multicast delegate
void ErrorEventHandler( Object sender, ErrorEvent e );

Remarks

The syntax of the ErrorEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a ErrorEvent object that provides the event data.

When you create an ErrorEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC.


GridLineStyle Class

Defines the constants that specify the style of the gridlines in a DataGrid control.

Enum
  |
  +--GridLineStyle

package com.ms.wfc.data.ui

public class GridLineStyle
extends Enum

Remarks

Use the GridLineStyle constants to set the value of the DataGrid control's gridLineStyle property.


 GridLineStyle Fields

GridLineStyle Fields

Fields | Description
NONE | Specifies that the control has no gridlines between cells.
RAISED3D | Specifies that the control has raised, three-dimensional gridlines.
SINGLELINE | Specifies that the control's gridlines are single lines.
SUNKEN3D | Specifies that the control has sunken, three-dimensional gridlines.


 GridLineStyle.NONE

GridLineStyle.NONE

Specifies that the control has no gridlines between cells.

Syntax

public static final int NONE;

See Also DataGrid.getGridLineStyle, DataGrid.setGridLineStyle


 GridLineStyle.RAISED3D

GridLineStyle.RAISED3D

Specifies that the control has raised, three-dimensional gridlines.

Syntax

public static final int RAISED3D;

See Also DataGrid.getGridLineStyle, DataGrid.setGridLineStyle


 GridLineStyle.SINGLELINE

GridLineStyle.SINGLELINE

Specifies that the control's gridlines are single lines.

Syntax

public static final int SINGLELINE;

See Also DataGrid.getGridLineStyle, DataGrid.setGridLineStyle


 GridLineStyle.SUNKEN3D

GridLineStyle.SUNKEN3D

Specifies that the control has sunken, three-dimensional gridlines.

Syntax

public static final int SUNKEN3D;

See Also DataGrid.getGridLineStyle, DataGrid.setGridLineStyle


PositionChangeEvent Class

Provides data for the positionChange event of the DataGrid control.

Event
  |
  +--PositionChangeEvent

package com.ms.wfc.data.ui

public class PositionChangeEvent
extends Event

Remarks

The positionChange event occurs when the current position is moved within the grid. A PositionChangeEvent object specifies the row and column that were previously current, before the position was changed.

For information about the WFC event model, see Handling Events in WFC.


 PositionChangeEvent Methods

PositionChangeEvent Methods

Constructors | Description
PositionChangeEvent | Creates a PositionChangeEvent object.


 PositionChangeEvent.PositionChangeEvent

PositionChangeEvent.PositionChangeEvent

Creates a PositionChangeEvent object.

Syntax

public PositionChangeEvent( int lastColumn, Object lastRow )

Parameters

lastColumn

The zero-based index of the column that was current before the position changed.

lastRow

The bookmark associated with the row that was current before the position changed.


 PositionChangeEvent Fields

PositionChangeEvent Fields

Fields | Description
lastColumn | Specifies the zero-based index of the column that was current before the position changed.
lastRow | Specifies the bookmark associated with the row that was current before the position changed.


 PositionChangeEvent.lastColumn

PositionChangeEvent.lastColumn

Specifies the zero-based index of the column that was current before the position changed.

Syntax

public int lastColumn;


 PositionChangeEvent.lastRow

PositionChangeEvent.lastRow

Specifies the bookmark associated with the row that was current before the position changed.

Syntax

public Object lastRow;


PositionChangeEventHandler Delegate

Identifies the method that will handle the positionChange event of a DataGrid control.

package com.ms.wfc.data.ui

public multicast delegate
void PositionChangeEventHandler( Object sender, PositionChangeEvent e );

Remarks

The syntax of the PositionChangeEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a PositionChangeEvent object that provides the event data.

When you create a PositionChangeEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC.


Scrollbars Class

Defines the constants that specify which scroll bars are displayed in a DataGrid control.

Enum
  |
  +--Scrollbars

package com.ms.wfc.data.ui

public class Scrollbars
extends Enum

Remarks

Use the Scrollbars constants to set the value of the DataGrid control's scrollbars property.


 Scrollbars Fields

Scrollbars Fields

Fields | Description
BOTH | Specifies that both the vertical and horizontal scroll bars are displayed.
HORIZONTAL | Specifies that only the horizontal scroll bar is displayed.
NONE | Specifies that no scroll bars are displayed.
VERTICAL | Specifies that only the vertical scroll bar is displayed.


 Scrollbars.BOTH

Scrollbars.BOTH

Specifies that both the vertical and horizontal scroll bars are displayed.

Syntax

public static final int BOTH;

See Also DataGrid.getScrollbars, DataGrid.setScrollbars


 Scrollbars.HORIZONTAL

Scrollbars.HORIZONTAL

Specifies that only the horizontal scroll bar is displayed.

Syntax

public static final int HORIZONTAL;

See Also DataGrid.getScrollbars, DataGrid.setScrollbars


 Scrollbars.NONE

Scrollbars.NONE

Specifies that no scroll bars are displayed.

Syntax

public static final int NONE;

See Also DataGrid.getScrollbars, DataGrid.setScrollbars


 Scrollbars.VERTICAL

Scrollbars.VERTICAL

Specifies that only the vertical scroll bar is displayed.

Syntax

public static final int VERTICAL;

See Also DataGrid.getScrollbars, DataGrid.setScrollbars


TabAction Class

Defines the constants that specify the behavior of the TAB key within a DataGrid control.

Enum
  |
  +--TabAction

package com.ms.wfc.data.ui

public class TabAction
extends Enum

Remarks

Use the TabAction constants to set the value of the DataGrid control's tabAction property.


 TabAction Fields

TabAction Fields

Fields | Description
COLUMNNAVIGATION | Specifies that the TAB key will move focus to the cell in the next column, within the same row.
CONTROLNAVIGATION | Specifies that the TAB key will move focus between controls on the form. The TAB key cannot be used to move the current cell focus within the grid.
ROWNAVIGATION | Specifies that the TAB key will move the focus to the cell in the next row, within the same column.


 TabAction.COLUMNNAVIGATION

TabAction.COLUMNNAVIGATION

Specifies that the TAB key will move focus to the cell in the next column, within the same row.

Syntax

public static final int COLUMNNAVIGATION;

See Also DataGrid.getTabAction, DataGrid.setTabAction


 TabAction.CONTROLNAVIGATION

TabAction.CONTROLNAVIGATION

Specifies that the TAB key will move focus between controls on the form. The TAB key cannot be used to move the current cell focus within the grid.

Syntax

public static final int CONTROLNAVIGATION;

See Also DataGrid.getTabAction, DataGrid.setTabAction


 TabAction.ROWNAVIGATION

TabAction.ROWNAVIGATION

Specifies that the TAB key will move the focus to the cell in the next row, within the same column.

Syntax

public static final int ROWNAVIGATION;

See Also DataGrid.getTabAction, DataGrid.setTabAction


Package com.ms.wfc.html

Provides access to the Dynamic HTML object model from Java classes. This includes both client and server applications.

Classes

DhAlignment

Defines alignment constants.

DhBaseContainer

Represents the base class for all container elements.

DhBorderInfo

Provides structured information about an element's border styles.

DhBorders

Defines constants for border sides.

DhBorderStyle

Defines constants for border styles.

DhBreak

Implements an HTML line break element.

DhBrowser

Enables access to Internet Explorer browser functionality.

DhBulletedList

Implements ordered and unordered bulleted and numbered lists in HTML.

DhButton

Implements an HTML push button control.

DhCantAddElementException

Signals that a request for a named element failed because an element with that name does not exist.

DhCantModifyElementException

Signals that an attempt has been made to modify a read-only element, such as one that has been sent from a server to a client.

DhCell

Creates a table cell.

DhCheckBox

Implements an intrinsic HTML check box control with a text label.

DhComboBox

Implements an HTML drop-down combo box control.

DhComponentWrapper

Wraps a WFC control so that it is accessible from the HTML document.

DhCursor

Defines constants for controlling an element's cursor style.

DhDialogInfo

Represents an information class for dialog boxes.

DhDocument

Represents an HTML document.

DhEdit

Implements an HTML edit box control.

DhElement

Represents the superclass for all user interface elements in this package.

DhElementExistsInDocumentException

Signals that a specified element has already been added to the document.

DhElementNotFoundException

Signals that a request for a specified element failed because an element with that name does not exist.

DhEnumeration

Represents a collection of elements in the HTML document.

DhEventInfo

Carries event information from the event source to the event sink.

DhForm

Represents an element container that uses traditional HTML one-dimensional flow layout.

DhHorizontalRule

Represents an HTML horizontal rule element, which creates a horizontal divider bar on the page.

DhHotSpot

Implements an object that represents a hotspot in an image map.

DhHotSpotShapes

Provides constants for DhHotSpot shapes.

DhHTMLGenerator

Represents a base class for HTML generation.

DhHyperlink

Creates a jump in the document to a bookmark or element in the current document or to a different document.

DhImage

Implements an image object that displays a bitmap file in the document.

DhInlineFrame

Represents an inline frame element.

DhInsertOptions

Provides constants for inserting DhElement items into container items.

DhJumpPoint

Represents a bookmark within a document.

DhLinkTarget

Provides constants for setting the document's target window.

DhListBox

Implements an HTML list box control.

DhListType

Provides constants and support for list types in a DhBulletedList control.

DhMargins

Provides constant definitions for margin style manipulation.

DhMarginWidthInfo

Provides structured information about an element's margin settings.

DhModule

Provides siting services for the com.ms.wfc.html package.

DhObjectFactory

Creates an object from an existing ActiveX/COM or Java object and adds it to the document.

DhPaddings

Provides constant definitions for padding style manipulation.

DhPaddingWidthInfo

Provides information about an element's padding width settings.

DhPropertyBag

Retrieves attribute values in the module's PARAM tags.

DhRadioButton

Implements an intrinsic HTML radio button control with a text label.

DhRawHTML

Enables output of arbitrary raw HTML to the document.

DhResetButton

Implements a reset button control for HTTP form submission.

DhRow

Implements a row in a DhTable table.

DhScrollBars

Defines constants for scroll bars.

DhSelectBox

Represents the base class for the DhComboBox and DhListBox controls.

DhStyle

Represents a collection of properties that can be freely applied to any element.

DhStyleBase

Provides the superclass for classes that support styles, such as DhStyle and DhElement objects.

DhSubmitButton

Implements a submit button control for HTTP formsubmission.

DhTable

Creates a table element that can be populated with rows and columns.

DhText

Represents static text in an HTML document.

DhTextMode

Defines mode constants for the DhText class.

DhUnits

Provides constants for various unit types in DHTML.

DhWindow

Encapsulates an HTML window.

DhWindowInfo

Provides constants for setting features for a new browser or modal dialog window.


DhAlignment Class

Defines alignment constants.

Enum
  |
  +--DhAlignment

package com.ms.wfc.html

public class DhAlignment
extends Enum

Remarks

Align constants are used by the DhStyleBase, DhElement, DhListBox, and DhRadioButton classes.


 DhAlignment Methods

DhAlignment Methods

Methods | Description
valid | Determines whether a specified value is valid for this enumeration type.


 DhAlignment.valid

DhAlignment.valid

Determines whether a specified value is valid for this enumeration type.

Syntax

public static boolean valid( int n )

Parameters

n

The value to check.

Return Value

Returns true if the value is valid for this class; otherwise, returns false.

Remarks

You should override this method in your own enumeration classes.


 DhAlignment Fields

DhAlignment Fields

Fields | Description
ABSBOTTOM | Specifies vertical bottom alignment.
ABSMIDDLE | Specifies vertical middle alignment.
BASELINE | Specifies alignment at the baseline of the current line's text.
BOTTOM | Specifies bottom alignment.
CENTER | Specifies center alignment.
JUSTIFY | Specifies justified alignment.
LEFT | Specifies text on the left, button on the right for DhRadioButton, DhCheckBox.
RIGHT | Text on the right, button on the left for DhRadioButton, DhCheckBox.
SUBSCRIPT | Specifies a subscript attribute.
SUPERSCRIPT | Specifies a superscript attribute.
TEXTTOP | Specifies alignment with the top of the current line's text.
TOP | Specifies top alignment.


 DhAlignment.ABSBOTTOM

DhAlignment.ABSBOTTOM

Specifies vertical bottom alignment.

Syntax

public static final int ABSBOTTOM;


 DhAlignment.ABSMIDDLE

DhAlignment.ABSMIDDLE

Specifies vertical middle alignment.

Syntax

public static final int ABSMIDDLE;


 DhAlignment.BASELINE

DhAlignment.BASELINE

Specifies alignment at the baseline of the current line's text.

Syntax

public static final int BASELINE;


 DhAlignment.BOTTOM

DhAlignment.BOTTOM

Specifies bottom alignment.

Syntax

public static final int BOTTOM;


 DhAlignment.CENTER

DhAlignment.CENTER

Specifies center alignment.

Syntax

public static final int CENTER;


 DhAlignment.JUSTIFY

DhAlignment.JUSTIFY

Specifies justified alignment.

Syntax

public static final int JUSTIFY;


 DhAlignment.LEFT

DhAlignment.LEFT

Specifies text on the left, button on the right for DhRadioButton, DhCheckBox.

Syntax

public static final int LEFT;

Remarks

The following is a left-aligned label:


 DhAlignment.RIGHT

DhAlignment.RIGHT

Text on the right, button on the left for DhRadioButton, DhCheckBox.

Syntax

public static final int RIGHT;

Remarks

The following is a right-aligned label:


 DhAlignment.SUBSCRIPT

DhAlignment.SUBSCRIPT

Specifies a subscript attribute.

Syntax

public static final int SUBSCRIPT;


 DhAlignment.SUPERSCRIPT

DhAlignment.SUPERSCRIPT

Specifies a superscript attribute.

Syntax

public static final int SUPERSCRIPT;


 DhAlignment.TEXTTOP

DhAlignment.TEXTTOP

Specifies alignment with the top of the current line's text.

Syntax

public static final int TEXTTOP;


 DhAlignment.TOP

DhAlignment.TOP

Specifies top alignment.

Syntax

public static final int TOP;


DhBaseContainer Class

Represents the base class for all container elements.

Component
  |
  +--DhStyleBase
     |
     +--DhElement
        |
       +--DhBaseContainer

package com.ms.wfc.html

public abstract class DhBaseContainer
extends DhElement
implements ITopLevelWindow

Remarks

This class should be derived from but never instantiated itself.


 DhBaseContainer Methods

DhBaseContainer Methods

Methods | Description
add | Adds a Windows Foundation Classes for Java (WFC) control to the container.
dispose | Frees all resources associated with this element.
findElement | Locates the child element with the specified peer, ID, index, or DhElement object.
getAllElements | Recursively retrieves all child elements and their children.
getElementCount | Retrieves the number of child elements in this container.
getElements | Retrieves the direct child elements of this container.
onChildAdded | Called by the framework after a child element is added to this container.
onChildRemoved | Called after a child element is removed from this container.
onChildrenFound | Called when all the direct children of this container are available.
remove | Removes an element from this container.
removeAll | Removes all child elements from this container.
replace | Replaces a child element with another.
setDocument | Sets the document that is associated with this container.
setNewComponents | Adds the components to the container.
setNewElements | Adds the HTML elements to the container.


 DhBaseContainer.add

DhBaseContainer.add

Adds a Windows Foundation Classes for Java (WFC) control to the container.

Syntax

public void add( Control c )

protected void add( DhElement e )

protected void add( DhElement e, int insertFlag )

protected void add( DhElement e, DhElement relativeTo, int insertFlag )

Parameters

c

The WFC control to be added.

e

The element to add.

insertFlag

The insert position from DhInsertOptions.

relativeTo

The element relative to which the element is added.

See Also remove


 DhBaseContainer.dispose

DhBaseContainer.dispose

Frees all resources associated with this element.

Syntax

public void dispose( )

Remarks

This method might not be called at run time. Any resources used by the element should be set up to be released when the element is released for garbage collection. Inheriting classes should always call the superclass dispose method.


 DhBaseContainer.findElement

DhBaseContainer.findElement

Locates the child element with the specified peer, ID, index, or DhElement object.

Syntax

public DhElement findElement( IUnknown peer )

public DhElement findElement( String ID )

public DhElement findElement( int index )

public int findElement( DhElement e )

Parameters

peer

A reference to the peer object.

ID

The ID value of the element to find.

index

The ordinal position of the child element to return.

e

The DhElement child element to retrieve the index of.

Exceptions

DhElementNotFoundException thrown if a suitable child element is not found.

Return Value

Returns a child element, or returns null if one is not located.


 DhBaseContainer.getAllElements

DhBaseContainer.getAllElements

Recursively retrieves all child elements and their children.

Syntax

public DhElement[] getAllElements()

Return Value

Returns an array of all child elements.


 DhBaseContainer.getElementCount

DhBaseContainer.getElementCount

Retrieves the number of child elements in this container.

Syntax

public int getElementCount()

Return Value

Returns the number of child elements.


 DhBaseContainer.getElements

DhBaseContainer.getElements

Retrieves the direct child elements of this container.

Syntax

public DhElement[] getElements()

Return Value

Returns an array of direct child elements.


 DhBaseContainer.onChildAdded

DhBaseContainer.onChildAdded

Called by the framework after a child element is added to this container.

Syntax

protected void onChildAdded( DhElement eChild )

Parameters

eChild

A reference to the child element.

Remarks

Override this method in your derived class to be notified when a child element is added to the container. Note that this is valid only if the class can have children. This method will be called when the user calls DhBaseContainer.add on this container or binds to children of this container that are already on the HTML page using DhBaseContainer.findElement, for example.

Do not add functions that will add elements to this class, such as addText or newLine, or the method will infinitely recurse. You can, however, add elements to other containers from your override of this method.


 DhBaseContainer.onChildRemoved

DhBaseContainer.onChildRemoved

Called after a child element is removed from this container.

Syntax

protected void onChildRemoved( DhElement removedChild )

Parameters

removedChild

A reference to the child element that has been removed.

Remarks

Override this method in your derived class to be notified when a child element is removed from the container. Note that this is valid only if the class can have children.


 DhBaseContainer.onChildrenFound

DhBaseContainer.onChildrenFound

Called when all the direct children of this container are available.

Syntax

protected void onChildrenFound()

Remarks

Override this method in your derived class to be notified when all child elements are available. This method is called when child elements are inspected. This occurs when you call DhDocument.findElement specifying an element in an existing web page and when any other operation that requires the children to be inspected is performed. For performance reasons, the com.ms.wfc.html package delays this operation until the data is required.


 DhBaseContainer.remove

DhBaseContainer.remove

Removes an element from this container.

Syntax

public int remove( DhElement element )

Parameters

element

The element to remove.

Exceptions

WFCInvalidArgumentException thrown if element is not a child of this container.

Return Value

Returns the original ordinal position of the removed element.

See Also add


 DhBaseContainer.removeAll

DhBaseContainer.removeAll

Removes all child elements from this container.

Syntax

public void removeAll()

Remarks

These elements will no longer be visible if they were added prior to this call.


 DhBaseContainer.replace

DhBaseContainer.replace

Replaces a child element with another.

Syntax

protected void replace( DhElement eCur, DhElement eNew )

Parameters

eCur

The element to replace.

eNew

The new element.

Exceptions

DhElementNotFoundException thrown if eCur is not a child of this container.


 DhBaseContainer.setDocument

DhBaseContainer.setDocument

Sets the document that is associated with this container.

Syntax

public void setDocument( DhDocument document )

Parameters

document

The document to be set.


 DhBaseContainer.setNewComponents

DhBaseContainer.setNewComponents

Adds the components to the container.

Syntax

public final void setNewComponents( Component[] comps )

Parameters

comps

An array representing the components to be added to the control.

Remarks

Components can be derived only from com.ms.wfc.ui.Control or DhElement.


 DhBaseContainer.setNewElements

DhBaseContainer.setNewElements

Adds the HTML elements to the container.

Syntax

public final void setNewElements( DhElement[] elems )

Parameters

elems

An array representing the HTML elements to be added to the container.

Remarks

Components can be derived only from DhElement.


DhBorderInfo Class

Provides structured information about an element's border styles.

package com.ms.wfc.html

public class DhBorderInfo

Remarks

These constants are used by the DhStyleBase.getBorderInfo and DhStyleBase.setBorderInfo methods.

See Also DhUnits


 DhBorderInfo Methods

DhBorderInfo Methods

Constructors | Description
DhBorderInfo | Creates a DhBorderInfo object.

Methods | Description
cloneThis | Retrieves an identical copy of this DhBorderInfo object.
copy | Copies another DhBorderInfo object's internal data to this one.


 DhBorderInfo.clone

DhBorderInfo.clone

Retrieves an identical copy of this DhBorderInfo object.

Syntax

public DhBorderInfo clone()

Return Value

Returns a new DhBorderInfo object.


 DhBorderInfo.copy

DhBorderInfo.copy

Copies another DhBorderInfo object's internal data to this one.

Syntax

public void copy( DhBorderInfo biOther )

Parameters

biOther

The DhBorderInfo class to copy.


 DhBorderInfo.DhBorderInfo

DhBorderInfo.DhBorderInfo

Creates a DhBorderInfo object.

Syntax

public DhBorderInfo()

public DhBorderInfo( DhBorderInfo biInit )

Parameters

biInit

An existing DhBorderInfo object used to initialize this DhBorderInfo.


 DhBorderInfo Fields

DhBorderInfo Fields

Fields | Description
bottomColor | Specifies the bottom border color.
bottomStyle | Specifies the current bottom border style as one of the DhBorderStyle constants.
bottomWidth | Specifies the current bottom border width as an integer in the unit specified by bottomWidthUnit.
bottomWidthUnit | Specifies the unit label of the width of the bottom border as one of the DhUnits constants.
leftColor | Specifies the left border color.
leftStyle | Specifies the current left border style as one of the DhBorderStyle constants.
leftWidth | Specifies the current left border width as an integer in the unit specified by leftWidthUnit.
leftWidthUnit | Specifies the unit label of the width of the left border as one of the DhUnits constants.
rightColor | Specifies the right border color.
rightStyle | Specifies the current right border style as one of the DhBorderStyle constants.
rightWidth | Specifies the current right border width.
rightWidthUnit | Specifies the unit label of the width of the right border as one of the DhUnits constants.
topColor | Specifies the top border color.
topStyle | Specifies the current top border style as one of the DhBorderStyle constants.
topWidth | Specifies the current top border width in the unit specified by topWidthUnit.
topWidthUnit | Specifies the unit label of the width of the top border as one of the DhUnits constants.


 DhBorderInfo.bottomColor

DhBorderInfo.bottomColor

Specifies the bottom border color.

Syntax

public Color bottomColor;


 DhBorderInfo.bottomStyle

DhBorderInfo.bottomStyle

Specifies the current bottom border style as one of the DhBorderStyle constants.

Syntax

public int bottomStyle;


 DhBorderInfo.bottomWidth

DhBorderInfo.bottomWidth

Specifies the current bottom border width as an integer in the unit specified by bottomWidthUnit.

Syntax

public int bottomWidth;

Remarks

This label is valid only if width is in value/unit form (such as 20px), and bottomWidthUnit does not equal NULL.


 DhBorderInfo.bottomWidthUnit

DhBorderInfo.bottomWidthUnit

Specifies the unit label of the width of the bottom border as one of the DhUnits constants.

Syntax

public int bottomWidthUnit;

Remarks

This label is valid only if width is in value/unit form (such as 20px), and value is not NULL. For more information on unit label constants, see DhUnits.


 DhBorderInfo.leftColor

DhBorderInfo.leftColor

Specifies the left border color.

Syntax

public Color leftColor;


 DhBorderInfo.leftStyle

DhBorderInfo.leftStyle

Specifies the current left border style as one of the DhBorderStyle constants.

Syntax

public String leftStyle;


 DhBorderInfo.leftWidth

DhBorderInfo.leftWidth

Specifies the current left border width as an integer in the unit specified by leftWidthUnit.

Syntax

public int leftWidth;


 DhBorderInfo.leftWidthUnit

DhBorderInfo.leftWidthUnit

Specifies the unit label of the width of the left border as one of the DhUnits constants.

Syntax

public int leftWidthUnit;

Remarks

This label is valid only if width is in value/unit form (such as 20px), and value is not NULL. For more information on unit label constants, see DhUnits.


 DhBorderInfo.rightColor

DhBorderInfo.rightColor

Specifies the right border color.

Syntax

public Color rightColor;


 DhBorderInfo.rightStyle

DhBorderInfo.rightStyle

Specifies the current right border style as one of the DhBorderStyle constants.

Syntax

public String rightStyle;


 DhBorderInfo.rightWidth

DhBorderInfo.rightWidth

Specifies the current right border width.

Syntax

public int rightWidth;


 DhBorderInfo.rightWidthUnit

DhBorderInfo.rightWidthUnit

Specifies the unit label of the width of the right border as one of the DhUnits constants.

Syntax

public int rightWidthUnit;

Remarks

This label is valid only if width is in value/unit form (such as 20px), and value is not NULL. For more information on unit label constants, see DhUnits.


 DhBorderInfo.topColor

DhBorderInfo.topColor

Specifies the top border color.

Syntax

public Color topColor;


 DhBorderInfo.topStyle

DhBorderInfo.topStyle

Specifies the current top border style as one of the DhBorderStyle constants.

Syntax

public String topStyle;


 DhBorderInfo.topWidth

DhBorderInfo.topWidth

Specifies the current top border width in the unit specified by topWidthUnit.

Syntax

public int topWidth;


 DhBorderInfo.topWidthUnit

DhBorderInfo.topWidthUnit

Specifies the unit label of the width of the top border as one of the DhUnits constants.

Syntax

public int topWidthUnit;

Remarks

This label is valid only if width is in value/unit form (such as 20px), and value is not NULL. For more information on unit label constants, see DhUnits.


DhBorders Class

Defines constants for border sides.

Enum
  |
  +--DhBorders

package com.ms.wfc.html

public class DhBorders
extends Enum

Remarks

This class is used by the DhStyleBase.setBorderStyle and DhStyleBase.setBorderWidth methods to specify which borders to set. Values can be combined using the bitwise OR.


 DhBorders Methods

DhBorders Methods

Methods | Description
valid | Determines whether a specified value is valid for this enumeration type.


 DhBorders.valid

DhBorders.valid

Determines whether a specified value is valid for this enumeration type.

Syntax

public static boolean valid( int n )

Parameters

n

The value to check.

Return Value

Returns true if the value is valid for this class; otherwise, returns false.

Remarks

You should override this method in your own enumeration classes.


 DhBorders Fields

DhBorders Fields

Fields | Description
ALL | Specifies the combination of all border side items. This is equivalent to (TOP | RIGHT | BOTTOM | LEFT)
BOTTOM | Specifies the bottom border.
LEFT | Specifies the left border.
RIGHT | Specifies the right border.
TOP | Specifies the top border.


 DhBorders.ALL

DhBorders.ALL

Specifies the combination of all border side items. This is equivalent to (TOP | RIGHT | BOTTOM | LEFT)

Syntax

public static final int ALL;


 DhBorders.BOTTOM

DhBorders.BOTTOM

Specifies the bottom border.

Syntax

public static final int BOTTOM;


 DhBorders.LEFT

DhBorders.LEFT

Specifies the left border.

Syntax

public static final int LEFT;


 DhBorders.RIGHT

DhBorders.RIGHT

Specifies the right border.

Syntax

public static final int RIGHT;


 DhBorders.TOP

DhBorders.TOP

Specifies the top border.

Syntax

public static final int TOP;


DhBorderStyle Class

Defines constants for border styles.

Enum
  |
  +--DhBorderStyle

package com.ms.wfc.html

public class DhBorderStyle
extends Enum

Remarks

This class is used by the constants in DhBorderInfo, which is used by DhStyleBase.getBorderInfo and DhStyleBase.setBorderInfo methods.


 DhBorderStyle Methods

DhBorderStyle Methods

Methods | Description
valid | Determines whether a specified value is valid for this enumeration type.


 DhBorderStyle.valid

DhBorderStyle.valid

Determines whether a specified value is valid for this enumeration type.

Syntax

public static boolean valid( int n )

Parameters

n

The value to check.

Return Value

Returns true if the value is valid for this class; otherwise, returns false.

Remarks

You should override this method in your own enumeration classes.


 DhBorderStyle Fields

DhBorderStyle Fields

Fields | Description
DOUBLE | Specifies that a border is a double line drawn on top of the background of the element.
GROOVE | Specifies that a three-dimensional groove is drawn in colors based on the value.
INSET | Specifies that a three-dimensional inset is drawn in colors based on the value.
NONE | Specifies that no border is drawn (regardless of any border width).
OUTSET | Specifies that a three-dimensional outset is drawn in colors based on the value.
RIDGE | Specifies that a three-dimensional ridge is drawn in colors based on the value.
SOLID | Specifies that the border is a solid line.


 DhBorderStyle.DOUBLE

DhBorderStyle.DOUBLE

Specifies that a border is a double line drawn on top of the background of the element.

Syntax

public static final int DOUBLE;

Remarks

The sum of the two single lines and the space between equals the border-width value. The border width must be at least three pixels wide to draw a double border.


 DhBorderStyle.GROOVE

DhBorderStyle.GROOVE

Specifies that a three-dimensional groove is drawn in colors based on the value.

Syntax

public static final int GROOVE;


 DhBorderStyle.INSET

DhBorderStyle.INSET

Specifies that a three-dimensional inset is drawn in colors based on the value.

Syntax

public static final int INSET;


 DhBorderStyle.NONE

DhBorderStyle.NONE

Specifies that no border is drawn (regardless of any border width).

Syntax

public static final int NONE;


 DhBorderStyle.OUTSET

DhBorderStyle.OUTSET

Specifies that a three-dimensional outset is drawn in colors based on the value.

Syntax

public static final int OUTSET;


 DhBorderStyle.RIDGE

DhBorderStyle.RIDGE

Specifies that a three-dimensional ridge is drawn in colors based on the value.

Syntax

public static final int RIDGE;


 DhBorderStyle.SOLID

DhBorderStyle.SOLID

Specifies that the border is a solid line.

Syntax

public static final int SOLID;


DhBreak Class

Implements an HTML line break (<BR>) element.

Component
  |
  +--DhStyleBase
    |
    +--DhElement
      |
      +--DhBreak

package com.ms.wfc.html

public class DhBreak
extends DhElement


 DhBreak Methods

DhBreak Methods

Constructors | Description
DhBreak | Creates a DhBreak object.

Methods | Description
getClearFlag | Retrieves the current clear flag.
setClearFlag | Sets the current clear flag.


 DhBreak.DhBreak

DhBreak.DhBreak

Creates a DhBreak object.

Syntax

public DhBreak()

public DhBreak( int clearFlag )

Parameters

clearFlag

The clear type flag.

Remarks

The default constructor creates a DhBreak object with a standard line break (CLEAR_NONE).

See Also CLEAR_LEFT, CLEAR_RIGHT, CLEAR_ALL


 DhBreak.getClearFlag

DhBreak.getClearFlag

Retrieves the current clear flag.

Syntax

public int getClearFlag()

Return Value

Returns the current flag type.

See Also setClearFlag, CLEAR_NONE, CLEAR_LEFT, CLEAR_RIGHT, CLEAR_ALL


 DhBreak.setClearFlag

DhBreak.setClearFlag

Sets the current clear flag.

Syntax

public void setClearFlag( int clearFlag )

Parameters

clearFlag

The new flag type.

See Also

getClearFlag, CLEAR_NONE, CLEAR_LEFT, CLEAR_RIGHT, CLEAR_ALL


 DhBreak Fields

DhBreak Fields

Fields | Description
CLEAR_ALL | Inserts vertical space so that the next text displayed is past all floating images.
CLEAR_LEFT | Inserts vertical space so that the next text displayed is past left-aligned floating images.
CLEAR_NONE | Inserts a standard line break (the default).
CLEAR_RIGHT | Inserts vertical space so that the next text displayed is past right-aligned floating images.


 DhBreak.CLEAR_ALL

DhBreak.CLEAR_ALL

Inserts vertical space so that the next text displayed is past all floating images.

Syntax

public static final int CLEAR_ALL;


 DhBreak.CLEAR_LEFT

DhBreak.CLEAR_LEFT

Inserts vertical space so that the next text displayed is past left-aligned floating images.

Syntax

public static final int CLEAR_LEFT;


 DhBreak.CLEAR_NONE

DhBreak.CLEAR_NONE

Inserts a standard line break (the default).

Syntax

public static final int CLEAR_NONE;


 DhBreak.CLEAR_RIGHT

DhBreak.CLEAR_RIGHT

Inserts vertical space so that the next text displayed is past right-aligned floating images.

Syntax

public static final int CLEAR_RIGHT;


DhBrowser Class

Enables access to Internet Explorer browser functionality.

package com.ms.wfc.html

public class DhBrowser

Remarks

To use this class, call DhWindow.getBrowser, which returns an instance of a DhBrowser object. The following example shows retrieving and displaying all the browser string properties:

public class Class1 extends DhDocument
{

  protected void initForm()
  {
     DhWindow thisWindow = this.getWindow();
     DhBrowser browser = thisWindow.getBrowser();
     DhText t1, t2, t3, t4, t5, t6, t7, t8, t9, t10;
     this.add(t1 = new DhText("AppCodeName = " + browser.getAppCodeName()));
     this.newLine();
     this.add(t2 = new DhText("MinorVersion = " + browser.getAppMinorVersion()));
     this.newLine();
     this.add(t3 = new DhText("AppName = " + browser.getAppName()));
     this.newLine();
     this.add(t4 = new DhText("AppVersion = " + browser.getAppVersion()));
     this.newLine();
     this.add(t5 = new DhText("BrowserLanguage = " + browser.getBrowserLanguage()));
     this.newLine();
     this.add(t6 = new DhText("CpuClass = " + browser.getCpuClass()));
     this.newLine();
     this.add(t7 = new DhText("Platform = " + browser.getPlatform()));
     this.newLine();
     this.add(t8 = new DhText("SystemLanguage = " + browser.getSystemLanguage()));
     this.newLine();
     this.add(t9 = new DhText("UserAgent = " + browser.getUserAgent()));
     this.newLine();
     this.add(t10 = new DhText("UserLanguage = " + browser.getUserLanguage()));
  }


 DhBrowser Methods

DhBrowser Methods

Methods | Description
getAppCodeName | Retrieves the browser's code name.
getAppMinorVersion | Retrieves the application's minor version string.
getAppName | Retrieves the name of the browser.
getAppVersion | Retrieves the version of the browser.
getBrowserLanguage | Retrieves the browser language setting.
getCookieEnabled | Determines whether client-side cookies are enabled in the browser.
getCpuClass | Retrieves the CPU class string.
getOnLine | Determines whether the browser is connected online.
getPeer | Retrieves the underlying peer object for this class.
getPlatform | Retrieves the platform setting.
getSystemLanguage | Retrieves the system language setting.
getUserAgent | Retrieves the Hypertext Transfer Protocol (HTTP) user-agent header string.
getUserLanguage | Retrieves the user language setting.


 DhBrowser.getAppCodeName

DhBrowser.getAppCodeName

Retrieves the browser's code name.

Syntax

public String getAppCodeName()

Return Value

Returns the code name of the browser (for example, "Mozilla").


 DhBrowser.getAppMinorVersion

DhBrowser.getAppMinorVersion

Retrieves the application's minor version string.

Syntax

public String getAppMinorVersion()

Return Value

Returns the minor version of the browser (for example, ";SP1;").


 DhBrowser.getAppName

DhBrowser.getAppName

Retrieves the name of the browser.

Syntax

public String getAppName()

Return Value

Returns the name of the browser (for example, "Microsoft Internet Explorer").


 DhBrowser.getAppVersion

DhBrowser.getAppVersion

Retrieves the version of the browser.

Syntax

public String getAppVersion()

Return Value

Returns the version of the browser (for example, "4.0 (compatible; MSIE 4.01; Windows 95)").


 DhBrowser.getBrowserLanguage

DhBrowser.getBrowserLanguage

Retrieves the browser language setting.

Syntax

public String getBrowserLanguage()

Return Value

Returns a string containing the browser language.


 DhBrowser.getCookieEnabled

DhBrowser.getCookieEnabled

Determines whether client-side cookies are enabled in the browser.

Syntax

public boolean getCookieEnabled()

Return Value

Returns true if enabled; otherwise, returns false.


 DhBrowser.getCpuClass

DhBrowser.getCpuClass

Retrieves the CPU class string.

Syntax

public String getCpuClass()

Return Value

Returns the CPU type, such as "x86", "Alpha", or "Other".


 DhBrowser.getOnLine

DhBrowser.getOnLine

Determines whether the browser is connected online.

Syntax

public boolean getOnLine()

Return Value

Returns true if browser is online; otherwise, returns false.


 DhBrowser.getPeer

DhBrowser.getPeer

Retrieves the underlying peer object for this class.

Syntax

public IUnknown getPeer()

Return Value

Returns the peer object which underlies the DhBrowser object.

Remarks

This object implements the IOmNavigator interface.

Calling this method represents a very advanced usage scenario. Typically, you would never use this method.


 DhBrowser.getPlatform

DhBrowser.getPlatform

Retrieves the platform setting.

Syntax

public String getPlatform()

Return Value

Returns the platform string (for example, "Win32").


 DhBrowser.getSystemLanguage

DhBrowser.getSystemLanguage

Retrieves the system language setting.

Syntax

public String getSystemLanguage()

Return Value

Returns a string containing the system language (for example, "en-us").


 DhBrowser.getUserAgent

DhBrowser.getUserAgent

Retrieves the Hypertext Transfer Protocol (HTTP) user-agent header string.

Syntax

public String getUserAgent()

Return Value

Returns a the user-agent header string (for example, "Mozilla/4.0 (compatible; MSIE 4.01; Windows 95").


 DhBrowser.getUserLanguage

DhBrowser.getUserLanguage

Retrieves the user language setting.

Syntax

public String getUserLanguage()

Return Value

Returns a string containing the user language (for example, "en-us").


DhBulletedList Class

Implements ordered and unordered bulleted and numbered lists in HTML.

Component
  |
  +--DhStyleBase
     |
     +--DhElement
        |
        +--DhBaseContainer
           |
           +--DhBulletedList

package com.ms.wfc.html

public class DhBulletedList
extends DhBaseContainer
implements DhStringIDs

Remarks

This is a simple container class into which items can be added, each receiving its own bullet or number, as appropriate.


 DhBulletedList Methods

DhBulletedList Methods

Constructors | Description
DhBulletedList | Creates a DhBulletedList object.

Methods | Description
addItem | Adds the specified element to the end of the list.
getAllElements | Recursively retrieves all child elements and their children.
getElementIndex | Retrieves the index of the selected element if it is a direct child of this list.
getItem | Retrieves the element at the specified index.
getItems | Retrieves an array of elements in the list.
getListType | Retrieves the current list type.
insertItem | Inserts an element into the list at the specified index.
remove | Removes the specified element from the list.
removeAll | Removes all the elements from the list.
removeItem | Removes an element at the specified index from the list.
setItem | Sets or replaces the item at the specified index.
setItems | Sets all the items in the list.
setListType | Sets the current list type.


 DhBulletedList.addItem

DhBulletedList.addItem

Adds the specified element to the end of the list.

Syntax

public void addItem( DhElement e )

Parameters

e

The element to add.


 DhBulletedList.DhBulletedList

DhBulletedList.DhBulletedList

Creates a DhBulletedList object.

Syntax

public DhBulletedList()

public DhBulletedList( int listType )

Parameters

listType

The type of list, which can be one of the constants provided in DhListType.

Exceptions

WFCInvalidEnumException thrown if listType is not one of class constants.

Remarks

The default constructor creates a bulleted list (DhListType.BULLETED).


 DhBulletedList.getAllElements

DhBulletedList.getAllElements

Recursively retrieves all child elements and their children.

Syntax

public DhElement[ ] getAllElements( )

Returns

Returns an array of all child elements.


 DhBulletedList.getElementIndex

DhBulletedList.getElementIndex

Retrieves the index of the selected element if it is a direct child of this list.

Syntax

public int getElementIndex( DhElement e )

Parameters

e

The element for which the index is retrieved.

Returns

The zero-based index of the element, or -1 if the element is not in the list.


 DhBulletedList.getItem

DhBulletedList.getItem

Retrieves the element at the specified index.

Syntax

public DhElement getItem( int index )

Parameters

index

The index of the element to retrieve.

Exceptions

WFCInvalidArgumentException thrown if index is not in the list.


 DhBulletedList.getItems

DhBulletedList.getItems

Retrieves an array of elements in the list.

Syntax

public DhElement[ ] getItems( )

Returns

Returns an array of elements in the list.


 DhBulletedList.getListType

DhBulletedList.getListType

Retrieves the current list type.

Syntax

public int getListType()

Return Value

Returns one of the constants provided in DhListType.

See Also setListType


 DhBulletedList.insertItem

DhBulletedList.insertItem

Inserts an element into the list at the specified index.

Syntax

public void insertItem( DhElement newElement, int index )

Parameters

newElement

The new element to insert.

index

The zero-based index where the element is to be placed.

Remarks

If the index is less than 0 or greater than the number of elements in the list, the element is added to the end of the list.

See Also remove


 DhBulletedList.remove

DhBulletedList.remove

Removes the specified element from the list.

Syntax

public int remove( DhElement e )

Parameters

e

The element to remove.

Return Value

Returns the index of the element that was removed, or returns -1 if the element was not found.

See Also removeAll


 DhBulletedList.removeAll

DhBulletedList.removeAll

Removes all the elements from the list.

Syntax

public void removeAll()


 DhBulletedList.removeItem

DhBulletedList.removeItem

Removes an element at the specified index from the list.

Syntax

public void removeItem( int index )

Parameters

index

The index of the element to remove.

Return Value

Returns the index of the element that was removed.


 DhBulletedList.setItem

DhBulletedList.setItem

Sets or replaces the item at the specified index.

Syntax

public void setItem( int index, DhElement e )

Parameters

index

The index at which the item is set. If the index is less than 0 or greater than the length of the list, the item is added to the list.

e

The element to add to the list.

Remarks

If the specified index isn't present in the list, the item is added to the list.


 DhBulletedList.setItems

DhBulletedList.setItems

Sets all the items in the list.

Syntax

public void setItems( DhElement [ ] elements )

Parameters

elements

A DhElement array of the new items in the list.

Remarks

Any current items in the list are replaced.


 DhBulletedList.setListType

DhBulletedList.setListType

Sets the current list type.

Syntax

public void setListType( int newType )

Parameters

newType

The desired list type, which can be one of the constants provided in DhListType.

See Also getListType


DhButton Class

Implements an HTML push button control.

DhButtonBase
  |
  +--DhButton

package com.ms.wfc.html

public class DhButton
extends DhButtonBase

Remarks

This control can be used inside or outside of HTTP forms.


 DhButton Methods

DhButton Methods

Constructors | Description
DhButton | Creates a button.

Methods | Description
getEnabled | Retrieves the enabled state of the button.
getText | Retrieves the label from the button.
setEnabled | Sets the enabled state of the button.
setText | Sets the button's text label.


 DhButton.DhButton

DhButton.DhButton

Creates a button.

Syntax

public DhButton()

public DhButton( String strText )

Parameters

strText

The new button's label.

Remarks

The default constructor creates a button with a default text label of "button".


 DhButton.getEnabled

DhButton.getEnabled

Retrieves the enabled state of the button.

Syntax

public boolean getEnabled()

Return Value

Returns true if the button is enabled; otherwise, returns false.

See Also setEnabled


 DhButton.getText

DhButton.getText

Retrieves the label from the button.

Syntax

public String getText()

Return Value

Returns the current label string.

See Also setText


 DhButton.setEnabled

DhButton.setEnabled

Sets the enabled state of the button.

Syntax

public void setEnabled( boolean f )

Parameters

f

Set to true to enable the button; otherwise, set to false.

See Also getEnabled


 DhButton.setText

DhButton.setText

Sets the button's text label.

Syntax

public void setText( String strText )

Parameters

strText

The new label.

See Also getText


DhCantAddElementException Class

Signals that a request for a named element failed because an element with that name does not exist.

RunTimeException
  |
  +--WFCException
    |
    +--DhCantAddElementException

package com.ms.wfc.html

public class DhCantAddElementException
extends WFCException


 DhCantAddElementException Methods

DhCantAddElementException Methods

Constructors | Description
DhCantAddElementException | Creates a DhCantAddElementException object.


 DhCantAddElementException.DhCantAddElementException

DhCantAddElementException.DhCantAddElementException

Creates a DhCantAddElementException object.

Syntax

public DhCantAddElementException()

public DhCantAddElementException( String s )

Parameters

s

The detail message for the exception.

Remarks

The default constructor creates an exception with no detail message.


DhCantModifyElementException Class

Signals that an attempt has been made to modify a read-only element, such as one that has been sent from a server to a client.

RuntimeException
  |
  +--WFCException
    |
    +--DhCantModifyElementException

package com.ms.wfc.html

public class DhCantModifyElementException
extends WFCException

Remarks

This exception occurs only on server applications. It is thrown when a DhModule.write operation is attempted on the same element more than once. After the first write call, the element becomes read-only.


 DhCantModifyElementException Methods

DhCantModifyElementException Methods

Constructors | Description
DhCantModifyElementException | Creates a DhCantModifyElementException object.


 DhCantModifyElementException.DhCantModifyElementException

DhCantModifyElementException.DhCantModifyElementException

Creates a DhCantModifyElementException object.

Syntax

public DhCantModifyElementException()

public DhCantModifyElementException( String detail )

Parameters

detail

The detail message for the exception.

Remarks

The default constructor creates an exception with no detail message.


DhCell Class

Creates a table cell.

Component
  |
  +--DhStyleBase
     |
     +--DhElement
        |
        +--DhBaseContainer
        |
           +--DhForm
              |
              +--DhCell

package com.ms.wfc.html

public class DhCell
extends DhForm

Remarks

You can add any number of elements in any kind of layout to a cell using the add method.


 DhCell Methods

DhCell Methods

Constructors | Description
DhCell | Creates an empty cell.

Methods | Description
add | Adds an element to the cell.
getColSpan | Retrieves the number of columns this cell spans.
getColumnNumber | Retrieves the column number that this cell is in.
getRowNumber | Retrieves the row number that this cell is in.
getRowSpan | Retrieves the number of rows this cell spans.
getText | Retrieves the text of the cell.
getValue | Retrieves the numeric value displayed in the cell.
remove | Removes an element from this cell.
setColSpan | Sets the number of columns this cell spans.
setRowSpan | Determines how many rows this cell spans.
setText | Sets the text of the cell.
setValue | Sets a numeric value for the cell.


 DhCell.add

DhCell.add

Adds an element to the cell.

Syntax

public void add( DhElement e )

Parameters

e

The DhElement element to add.

See Also remove


 DhCell.DhCell

DhCell.DhCell

Creates an empty cell.

Syntax

public DhCell()

public DhCell( String text )

Parameters

text

The text contents of the cell.


 DhCell.getColSpan

DhCell.getColSpan

Retrieves the number of columns this cell spans.

Syntax

public int getColSpan()

Return Value

Returns the number of columns this cell spans.

See Also setColSpan


 DhCell.getColumnNumber

DhCell.getColumnNumber

Retrieves the column number that this cell is in.

Syntax

public int getColumnNumber()

Return Value

Returns the cell's column number, or returns -1 if the cell is not in a table.

Remarks

Because tables can have rows with differing numbers of columns (cells), the number returned reflects the column position in the row containing this cell.


 DhCell.getRowNumber

DhCell.getRowNumber

Retrieves the row number that this cell is in.

Syntax

public int getRowNumber()

Return Value

Returns the cell's row number, or returns -1 if the cell is not in a table.


 DhCell.getRowSpan

DhCell.getRowSpan

Retrieves the number of rows this cell spans.

Syntax

public int getRowSpan()

Return Value

Returns the number of rows this cell spans.

See Also setRowSpan


 DhCell.getText

DhCell.getText

Retrieves the text of the cell.

Syntax

public String getText()

Return Value

Returns the cell text.

See Also setText


 DhCell.getValue

DhCell.getValue

Retrieves the numeric value displayed in the cell.

Syntax

public int getValue()

Return Value

Returns an integer value.

See Also setValue, setText


 DhCell.remove

DhCell.remove

Removes an element from this cell.

Syntax

public int remove( DhElement e )

Parameters

e

The DHElement element to remove.

Return Value

Returns true if the element was removed successfully; otherwise, returns false.

See Also add


 DhCell.setColSpan

DhCell.setColSpan

Sets the number of columns this cell spans.

Syntax

public void setColSpan( int span )

Parameters

span

The number of columns this cell should span.

See Also getColSpan


 DhCell.setRowSpan

DhCell.setRowSpan

Determines how many rows this cell spans.

Syntax

public void setRowSpan( int span )

Parameters

span

Number of rows this cell should span.

See Also getRowSpan


 DhCell.setText

DhCell.setText

Sets the text of the cell.

Syntax

public void setText( String text )

Parameters

text

The string to display to user.

Remarks

Setting this value overwrites any previous call to setText or setValue.

See Also getText


 DhCell.setValue

DhCell.setValue

Sets a numeric value for the cell.

Syntax

public void setValue( int i )

Parameters

i

The int value to display in the cell.

Remarks

Setting this value overwrites any previous call to setText or setValue.

See Also getValue


DhCheckBox Class

Implements an intrinsic HTML check box control with a text label.

DhElement
  |
  +--DhBaseContainer
    |
    +--DhCheckBox

package com.ms.wfc.html

public class DhCheckBox
extends DhBaseContainer


 DhCheckBox Methods

DhCheckBox Methods

Constructors | Description
DhCheckBox | Creates a check box control.

Methods | Description
addOnCheckedChange | Assigns a delegate to the checkedChange event.
addOnGotFocus | Assigns a delegate to the gotFocus event.
addOnLostFocus | Assigns a delegate to the lostFocus event.
addOnResize | Assigns a delegate to the resize event.
addOnSelect | Assigns a delegate to the select event.
focus | Sets the input focus to this control.
getChecked | Retrieves the checked state of the check box.
getEnabled | Retrieves the enabled state of the check box.
getSubmitName | Retrieves the current NAME attribute for this check box.
getSubmitValue | Retrieves the submit value for this check box.
getText | Retrieves the current text label for the check box.
getTextAlign | Retrieves the current alignment.
removeOnCheckedChange | Removes the delegate that is assigned to the checkedChange event.
removeOnGotFocus | Removes the delegate that is assigned to the gotFocus event.
removeOnLostFocus | Removes the delegate that is assigned to the lostFocus event.
removeOnResize | Removes the delegate that is assigned to the resize event.
removeOnSelect | Removes the delegate that is assigned to the select event.
setChecked | Sets the checked state of the check box.
setEnabled | Sets the enabled state of the check box.
setSubmitName | Sets the HTTP submit name for this check box.
setSubmitValue | Sets the HTTP submit value for this check box.
setText | Sets the text label for the check box.
setTextAlign | Sets the current alignment.


 DhCheckBox.addOnCheckedChange

DhCheckBox.addOnCheckedChange

Assigns a delegate to the checkedChange event.

Syntax

final public void addOnCheckedChange ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

This event occurs when the user modifies the selected state of the button.

See Also removeOnCheckedChange


 DhCheckBox.addOnGotFocus

DhCheckBox.addOnGotFocus

Assigns a delegate to the gotFocus event.

Syntax

public final void addOnGotFocus ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when this element receives input focus.

See Also removeOnGotFocus


 DhCheckBox.addOnLostFocus

DhCheckBox.addOnLostFocus

Assigns a delegate to the lostFocus event.

Syntax

public final void addOnLostFocus ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when this element loses focus.

See Also removeOnLostFocus


 DhCheckBox.addOnResize

DhCheckBox.addOnResize

Assigns a delegate to the resize event.

Syntax

public final void addOnResize ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when this element is resized.

See Also removeOnResize


 DhCheckBox.addOnSelect

DhCheckBox.addOnSelect

Assigns a delegate to the select event.

Syntax

final public void addOnSelect ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

This event occurs when the user selects the control.

See Also removeOnSelect


 DhCheckBox.DhCheckBox

DhCheckBox.DhCheckBox

Creates a check box control.

Syntax

public DhCheckBox()

public DhCheckBox( String strText, boolean fChecked )

Parameters

strText

The text label.

fChecked

The initial checked state of the check box.

Remarks

The default constructor (with no parameters) has neither a label nor a check mark. The constructor with parameters has a right-aligned label by default.


 DhCheckBox.focus

DhCheckBox.focus

Sets the input focus to this control.

Syntax

public void focus()


 DhCheckBox.getChecked

DhCheckBox.getChecked

Retrieves the checked state of the check box.

Syntax

public boolean getChecked()

Return Value

Returns true if the box is checked; otherwise, returns false.

See Also setChecked


 DhCheckBox.getEnabled

DhCheckBox.getEnabled

Retrieves the enabled state of the check box.

Syntax

public boolean getEnabled()

Return Value

Returns true if the box is enabled; otherwise, returns false.

See Also setEnabled


 DhCheckBox.getSubmitName

DhCheckBox.getSubmitName

Retrieves the current NAME attribute for this check box.

Syntax

public String getSubmitName( )

Return Value

Returns the NAME attribute. This attribute is used only for Hypertext Transfer Protocol (HTTP) form submission; otherwise, it is not required.

See Also setSubmitName


 DhCheckBox.getSubmitValue

DhCheckBox.getSubmitValue

Retrieves the submit value for this check box.

Syntax

public String getSubmitValue( )

Return Value

Returns the current submit value.

See Also setSubmitValue


 DhCheckBox.getText

DhCheckBox.getText

Retrieves the current text label for the check box.

Syntax

public String getText( )

Return Value

Returns the current text label.

See Also setText


 DhCheckBox.getTextAlign

DhCheckBox.getTextAlign

Retrieves the current alignment.

Syntax

public int getTextAlign()

Return Value

Returns the current alignment, which can be either LeftRightAlignment.RIGHT or LeftRightAlignment.LEFT.

See Also setTextAlign


 DhCheckBox.removeOnCheckedChange

DhCheckBox.removeOnCheckedChange

Removes the delegate that is assigned to the checkedChange event.

Syntax

final public void removeOnCheckedChange ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

See Also addOnCheckedChange


 DhCheckBox.removeOnGotFocus

DhCheckBox.removeOnGotFocus

Removes the delegate that is assigned to the gotFocus event.

Syntax

public final void removeOnGotFocus ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The gotFocus event occurs when this container receives input focus.


 DhCheckBox.removeOnLostFocus

DhCheckBox.removeOnLostFocus

Removes the delegate that is assigned to the lostFocus event.

Syntax

public final void removeOnLostFocus ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The lostFocus event occurs when this container loses input focus.

See Also addOnLostFocus


 DhCheckBox.removeOnResize

DhCheckBox.removeOnResize

Removes the delegate that is assigned to the resize event.

Syntax

public final void removeOnResize ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The resize event occurs when this container is resized.

See Also addOnResize


 DhCheckBox.removeOnSelect

DhCheckBox.removeOnSelect

Removes the delegate that is assigned to the select event.

Syntax

final public void removeOnSelect ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The select event occurs when the check box control is selected.

See Also addOnSelect


 DhCheckBox.setChecked

DhCheckBox.setChecked

Sets the checked state of the check box.

Syntax

public void setChecked( boolean fChecked )

Parameters

fChecked

Set to true for a selected box; set to false for a cleared box.

See Also getChecked


 DhCheckBox.setEnabled

DhCheckBox.setEnabled

Sets the enabled state of the check box.

Syntax

public void setEnabled( boolean f )

Parameters

f

Set to true to enable the check box; set to false to disable it.

See Also getEnabled


 DhCheckBox.setSubmitName

DhCheckBox.setSubmitName

Sets the HTTP submit name for this check box.

Syntax

public void setSubmitName( String strName )

Parameters

strName

The NAME attribute. This name should be unique on the form.

Remarks

This name is used during HTTP form submission as the HTML NAME attribute.

See Also getSubmitName


 DhCheckBox.setSubmitValue

DhCheckBox.setSubmitValue

Sets the HTTP submit value for this check box.

Syntax

public void setSubmitValue( String strValue )

Parameters

strName

The new submit value.

Remarks

This name is used during HTTP form submission as the HTML VALUE attribute.

See Also getSubmitValue


 DhCheckBox.setText

DhCheckBox.setText

Sets the text label for the check box.

Syntax

public void setText( String strText )

Parameters

strText

The label to display for the check box.

Remarks

The check box can be selected or cleared by clicking this label.

See Also getText


 DhCheckBox.setTextAlign

DhCheckBox.setTextAlign

Sets the current alignment.

Syntax

public void setTextAlign( int newAlignment )

Parameters

newAlignment

The new alignment, which can be either LeftRightAlignment.RIGHT or LeftRightAlignment.LEFT.

Remarks

The following example demonstrates check box alignment:

RIGHT:    Right Aligned Label
LEFT:      Left Aligned Label

See Also getTextAlign


DhComboBox Class

Implements an HTML drop-down combo box control.

Component
  |
  +--DhStyleBase
     |
     +--DhElement
        |
        +--DhBaseContainer
           |
           +--DhSelectBox
              |
              +--DhComboBox

package com.ms.wfc.html

public class DhComboBox
extends DhSelectBox


 DhComboBox Methods

DhComboBox Methods

Constructors | Description
DhComboBox | Creates an empty DhComboBox object.


 DhComboBox.DhComboBox

DhComboBox.DhComboBox

Creates an empty DhComboBox object.

Syntax

public DhComboBox( )


DhComponentWrapper Class

Wraps a Windows Foundation Classes for Java (WFC) control so that it is accessible from the HTML document.

Component
  |
  +--DhStyleBase
     |
     +--DhElement
        |
        +--DhBaseContainer
           |
           +--DhObjectFactory
              |
              +--DhComponentWrapper

package com.ms.wfc.html

public class DhComponentWrapper
extends DhObjectFactory


 DhComponentWrapper Methods

DhComponentWrapper Methods

Constructors | Description
DhComponentWrapper | Creates a DhComponentWrapper object.

Methods | Description
getControl | Retrieves the control wrapped by this element.
setControl | Sets the control to be wrapped as an element in the HTML document.


 DhComponentWrapper.DhComponentWrapper

DhComponentWrapper.DhComponentWrapper

Creates a DhComponentWrapper object.

Syntax

public DhComponentWrapper()

public DhComponentWrapper( Control c, boolean fEmbed )

Parameters

c

The WFC control that should be added to the document.

fEmbed

Set to true to cause the control to be embedded in the document; set to false if the control is to be activated as a top-level window.


 DhComponentWrapper.getControl

DhComponentWrapper.getControl

Retrieves the control wrapped by this element.

Syntax

public Control getControl()

Return Value

Returns the control wrapped by this element.

See Also setControl


 DhComponentWrapper.setControl

DhComponentWrapper.setControl

Sets the control to be wrapped as an element in the HTML document.

Syntax

public void setControl( Control c, boolean fEmbed )

Parameters

c

The WFC control to be added to the document.

fEmbed

Set to true to cause the control to be embedded in the document; set to false if the control is to be activated as a top-level window.

See Also getControl


DhCursor Class

Defines constants for controlling an element's cursor style.

Enum
  |
  +--DhCursor

package com.ms.wfc.html

public class DhCursor
extends Enum

Remarks

For more information on setting cursor styles, see DhStyleBase.setCursor.


 DhCursor Methods

DhCursor Methods

Methods | Description
valid | Determines whether a specified value is valid for this enumeration type.


 DhCursor.valid

DhCursor.valid

Determines whether a specified value is valid for this enumeration type.

Syntax

public static boolean valid( int n )

Parameters

n

The value to check.

Return Value

Returns true if the value is valid for this class; otherwise, returns false.

Remarks

You should override this method in your own enumeration classes.


 DhCursor Fields

DhCursor Fields

Fields | Description
AUTO | Specifies that the browser determines the cursor to display based on the current context.
CROSSHAIR | Specifies a simple cross-hair cursor.
DEFAULT | Specifies a platform-dependent default cursor (usually an arrow).
E_RESIZE | Specifies an arrow cursor indicating that an edge is to be moved in an eastern direction.
HAND | Specifies a hand pointer cursor.
HELP | Specifies an arrow cursor with a question mark indicating Help.
MOVE | Specifies a cursor with crossed arrows indicating something is to be moved.
N_RESIZE | Specifies an arrow cursor indicating that an edge is to be moved in a northern direction.
NE_RESIZE | Specifies an arrow cursor indicating that an edge is to be moved in a northeastern direction.
NW_RESIZE | Specifies an arrow cursor indicating that an edge is to be moved in a northwestern direction.
S_RESIZE | Specifies an arrow cursor indicating that an edge is to be moved in a southern direction.
SE_RESIZE | Specifies an arrow cursor indicating that an edge is to be moved in a southeastern direction.
SW_RESIZE | Specifies an arrow cursor indicating that an edge is to be moved in a southwestern direction.
TEXT | Specifies an editable text cursor (usually an I-bar).
W_RESIZE | Specifies an arrow cursor indicating that an edge is to be moved in a western direction.
WAIT | Specifies an hourglass or watch indicating that the program is busy and the user should wait.


 DhCursor.AUTO

DhCursor.AUTO

Specifies that the browser determines the cursor to display based on the current context.

Syntax

public static final int AUTO;


 DhCursor.CROSSHAIR

DhCursor.CROSSHAIR

Specifies a simple cross-hair cursor.

Syntax

public static final int CROSSHAIR;


 DhCursor.DEFAULT

DhCursor.DEFAULT

Specifies a platform-dependent default cursor (usually an arrow).

Syntax

public static final int DEFAULT;


 DhCursor.E_RESIZE

DhCursor.E_RESIZE

Specifies an arrow cursor indicating that an edge is to be moved in an eastern direction.

Syntax

public static final int E_RESIZE;


 DhCursor.HAND

DhCursor.HAND

Specifies a hand pointer cursor.

Syntax

public static final int HAND;


 DhCursor.HELP

DhCursor.HELP

Specifies an arrow cursor with a question mark indicating Help.

Syntax

public static final int HELP;


 DhCursor.MOVE

DhCursor.MOVE

Specifies a cursor with crossed arrows indicating something is to be moved.

Syntax

public static final int MOVE;


 DhCursor.N_RESIZE

DhCursor.N_RESIZE

Specifies an arrow cursor indicating that an edge is to be moved in a northern direction.

Syntax

public static final int N_RESIZE;


 DhCursor.NE_RESIZE

DhCursor.NE_RESIZE

Specifies an arrow cursor indicating that an edge is to be moved in a northeastern direction.

Syntax

public static final int NE_RESIZE;


 DhCursor.NW_RESIZE

DhCursor.NW_RESIZE

Specifies an arrow cursor indicating that an edge is to be moved in a northwestern direction.

Syntax

public static final int NW_RESIZE;


 DhCursor.S_RESIZE

DhCursor.S_RESIZE

Specifies an arrow cursor indicating that an edge is to be moved in a southern direction.

Syntax

public static final int S_RESIZE;


 DhCursor.SE_RESIZE

DhCursor.SE_RESIZE

Specifies an arrow cursor indicating that an edge is to be moved in a southeastern direction.

Syntax

public static final int SE_RESIZE;


 DhCursor.SW_RESIZE

DhCursor.SW_RESIZE

Specifies an arrow cursor indicating that an edge is to be moved in a southwestern direction.

Syntax

public static final int SW_RESIZE;


 DhCursor.TEXT

DhCursor.TEXT

Specifies an editable text cursor (usually an I-bar).

Syntax

public static final int TEXT;


 DhCursor.W_RESIZE

DhCursor.W_RESIZE

Specifies an arrow cursor indicating that an edge is to be moved in a western direction.

Syntax

public static final int W_RESIZE;


 DhCursor.WAIT

DhCursor.WAIT

Specifies an hourglass or watch indicating that the program is busy and the user should wait.

Syntax

public static final int WAIT;


DhDialogInfo Class

Represents an information class for dialog boxes.

Component
  |
  +--DhStyleBase
    |
    +--DhDialogInfo

package com.ms.wfc.html

public class DhDialogInfo
extends DhStyleBase

Remarks

This class is used by DhWindow.showModalDialog.


 DhDialogInfo Methods

DhDialogInfo Methods

Constructors | Description
DhDialogInfo | Creates a DhDialogInfo object.

Methods | Description
toString | Retrieves a string representation of this object.


 DhDialogInfo.DhDialogInfo

DhDialogInfo.DhDialogInfo

Creates a DhDialogInfo object.

Syntax

public DhDialogInfo()


 DhDialogInfo.toString

DhDialogInfo.toString

Retrieves a string representation of this object.

Syntax

public String toString()

Return Value

Returns a string displaying a yes or no value for each of the dialog box properties. For example, the default DhDialogInfo settings return the following string:

"help:no;minimize:no;maximize:no;center:yes"


 DhDialogInfo Fields

DhDialogInfo Fields

Fields | Description
showCentered | Displays the dialog box centered on the desktop.
showHelpButton | Adds or removes a Help button on the dialog box's title bar.
showMaximizeButton | Adds or removes a Maximize button on the dialog box's title bar.
showMinimizeButton | Adds or removes a Minimize button on the dialog box's title bar.


 DhDialogInfo.showCentered

DhDialogInfo.showCentered

Displays the dialog box centered on the desktop.

Syntax

public boolean showCentered;

Remarks


 DhDialogInfo.showHelpButton

DhDialogInfo.showHelpButton

Adds or removes a Help button on the dialog box's title bar.

Syntax

public boolean showHelpButton;


 DhDialogInfo.showMaximizeButton

DhDialogInfo.showMaximizeButton

Adds or removes a Maximize button on the dialog box's title bar.

Syntax

public boolean showMaximizeButton;


 DhDialogInfo.showMinimizeButton

DhDialogInfo.showMinimizeButton

Adds or removes a Minimize button on the dialog box's title bar.

Syntax

public boolean showMinimizeButton;


DhDocument Class

Represents a Hypertext Markup Language (HTML) document.

Component
  |
  +--DhStyleBase
     |
     +--DhElement
        |
        +--DhBaseContainer
           |
           +--DhDocument

package com.ms.wfc.html

public class DhDocument
extends DhBaseContainer

Remarks

Use this class to bind to an existing HTML page and traverse the elements on that page. Alternatively, you can create new elements and add them to the page through this class. Objects in this class cannot be created directly; instead, you must extend this class in your Visual J++ project.

See Also DhStyle, DhModule, DhText, DhForm


 DhDocument Methods

DhDocument Methods

Methods | Description
add | Adds an element into this container.
addOnReadyStateChange | Assigns a delegate to the readyStateChange event.
addText | Appends a text string to the current document.
createElement | Creates an element from the name of an HTML tag if possible. This method is used internally by the package.
dispose | Frees all resources associated with this element.
dumpDHTML | Provides a diagnostic snapshot dump of the Dynamic HTML (DHTML) code.
dumpHTML | Displays a diagnostic snapshot dump of the Dynamic HTML code as currently seen by the document host.
enumerate | Returns an enumerator that represents the collection of elements.
findElement | Searches for an element in the document.
findStyle | Retrieves a DhStyle object with the named style for this document.
getAllElements | Recursively retrieves all child elements and their children.
getDocumentURL | Retrieves the URL source of the current document.
getDomain | Retrieves the host name of the server the page is from.
getElement | Retrieves the corresponding derivation of DhElement given the underlying HTML element peer.
getElements | Retrieves the child elements of this element.
getHandle | Retrieves a window handle for the browser document.
getHTML | Retrieves the representative HTML of this document (also known as the page).
getLastModified | Retrieves the last modified date of the current document.
getLocation | Retrieves the current location of the document.
getModule | Retrieves the DhModule associated with this document.
getPeer | Retrieves the underlying HTML peer element for this class.
getProtocol | Retrieves the long name of the protocol.
getReferrer | Retrieves the referring document.
getScroll | Retrieves the current scroll mode.
getServerMode | Determines if the document is on the server or client.
getSize | Retrieves the viewable size of the document.
getStyles | Retrieves all styles in this document.
getTitle | Retrieves the title of the document.
getWindow | Retrieves the Window object of this document.
getWindowPeer | Retrieves the window peer of this document.
importHTML | Imports HTML into the document.
messageBox | Displays a modal user message box.
moveElement | Moves an element to a new numeric order in the layout flow.
newLine | Appends a new line to the current document.
onDocumentBeforeUnload | Implements an event handler for the beforeUnload event.
onDocumentLoad | Implements an event handler for the load event.
onDocumentUnload | Implements an event handler for the unload event.
recreateElements | Deserializes HTML text generated by getHTML.
removeOnReadyStateChange | Removes the delegate that is assigned to the readyStateChange event.
setBoundElements | Binds the elements of the specified array to their peers.
setDomain | Sets the host domain for the page.
setGenerateTags | Determines whether HEAD and TITLE tags are generated by the getHTML method.
setScroll | Sets the current scroll mode.
setTitle | Sets the title of the document.
writeHTML | Writes a diagnostic snapshot dump of the DHTML code, as currently seen by the document host, to a file.


 DhDocument.add

DhDocument.add

Adds an element into this container.

Syntax

public void add( DhElement element )

public void add( DhElement element, int insertFlag )

public void add( DhElement element, DhElement relativeTo, int insertFlag )

public void add( DhStyle newStyle )

Parameters

element

The element to add to the end of the flow of this container.

insertFlag

One of the applicable insert constants from DhInsertOptions. The valid values for insertFlag are END, BEGINNING, BEFORE, and AFTER.

relativeTo

An element to which the insertFlags parameter relates (this can be null depending on the value of insertFlags).

newStyle

The DhStyle object to add to this document. You usually do not need to call this form of the DhDocument.add method; when you call DhElement.setStyle, the document style is set automatically.

Remarks

The form of this method without the insertFlag parameter adds the element following all other elements. The forms with the insertFlag parameter are used to add the element either at the beginning or at the end of this container. Use the form of this method that includes relativeTo to add an element before or after another element.

For information on this method and other available add methods, see DhForm.add.


 DhDocument.addOnReadyStateChange

DhDocument.addOnReadyStateChange

Assigns a delegate to the readyStateChange event.

Syntax

final public void addOnReadyStateChange ( ReadyStateEventHandler h )

Parameters

h

The ReadyStateEventHandler delegate to be notified when this event occurs.

Remarks

The readyStateChange event is triggered whenever the ready state of the document has changed. The possible ready state values for DhDocument are uninitialized, loading, interactive, and complete. For more information, see ReadyStateEvent.

See Also removeOnReadyStateChange


 DhDocument.addText

DhDocument.addText

Appends a text string to the current document.

Syntax

public void addText( String text )

Parameters

text

The text string.


 DhDocument.createElement

DhDocument.createElement

Creates an element from the name of an HTML tag if possible. This method is used internally by the package.

Syntax

public DhElement createElement( String tagTypes, String tagID )

Parameters

tagTypes

The type of HTML element to created (for example <BR>).

tagID

The identifer to assign to the newly created element.

Return Value

If the tagTypes tag name is not recognized by this package, it returns an instance of the DhRawHTML class.

Remarks

Calling this method represents a very advanced usage scenario. Typically, you would never use this method.


 DhDocument.dispose

DhDocument.dispose

Frees all resources associated with this element.

Syntax

public void dispose()

Remarks

This method might not be called at run time. Any resources used by the element should be set up to be released when the element is released for garbage collection. Inheriting classes should always call super.dispose.


 DhDocument.dumpDHTML

DhDocument.dumpDHTML

Provides a diagnostic snapshot dump of the Dynamic HTML (DHTML) code.

Syntax

public void dumpDHTML( Object sender, Event e )

Parameters

sender

The source of the event.

e

An Event object.

Remarks

You can use this method as a convenient place to route click events when you want to do a diagnostic snapshot dump of the Dynamic HTML code as currently seen by the document host.

See Also dumpHTML()


 DhDocument.dumpHTML

DhDocument.dumpHTML

Displays a diagnostic snapshot dump of the Dynamic HTML code as currently seen by the document host.

Syntax

public void dumpHTML()

Remarks

This method opens a new browser window and displays the source to the generated Dynamic HTML code that is currently running. This is a developer diagnostic tool, not an end-user feature.


 DhDocument.enumerate

DhDocument.enumerate

Returns an enumerator that represents the collection of elements.

Syntax

public DhEnumeration enumerate( int type )

Parameters

type

One of the types enumerated by the DhEnumeration class.

Return Value

Returns a DhEnumeration enumerator that represents the collection of elements of the types defined by the type parameter. This can be one of the following:

  • ELEMENTS, which include all elements (tags including the HEAD and BODY).
  • IMAGES, which include only the images (such as IMG tags).
  • HLINKS, which include only the links (such as A tags).


 DhDocument.findElement

DhDocument.findElement

Searches for an element in the document.

Syntax

public DhElement findElement( String id )

Parameters

id

The HTML ID attribute of the element to search for. For example, to find an element marked as

ID="Caption1", the id parameter would be set to "Caption1".

Return Value

Returns the DhElement representing the element in the document. This element can then be cast to the actual element type (for example, DhText).

Remarks

This method can be used to find any element in the document by the HTML ID attribute.


 DhDocument.findStyle

DhDocument.findStyle

Retrieves a DhStyle object with the named style for this document.

Syntax

public DhStyle findStyle( String style )

Parameters

style

The string name of the style you are looking for (for example, ".myClass").

Return Value

Returns the style object that corresponds to the style parameter, or returns null if no such style exists in this document.

Remarks

This method is not used in the normal course of programming this package.


 DhDocument.getAllElements

DhDocument.getAllElements

Recursively retrieves all child elements and their children.

Syntax

public DhElement[] getAllElements()

Return Value

Returns an array of all child elements in the document.

Overrides DhBaseContainer.getAllElements


 DhDocument.getDocumentURL

DhDocument.getDocumentURL

Retrieves the URL source of the current document.

Syntax

public String getDocumentURL()

Return Value

Returns the URL string, or returns null if it is unavailable.


 DhDocument.getDomain

DhDocument.getDomain

Retrieves the host name of the server the page is from.

Syntax

public String getDomain()

Return Value

Returns the current host server domain, or returns a null string if it is unavailable.

See Also setDomain


 DhDocument.getElement

DhDocument.getElement

Retrieves the corresponding derivation of DhElement given the underlying HTML element peer.

Syntax

public DhElement getElement( IHTMLElement peer )

Parameters

peer

The underlying HTML element peer. This peer may have been acquired using DhForm.getPeer.

Return Value

Returns the specific derivation that corresponds to the peer parameter.

Remarks

Calling this method represents a very advanced usage scenario. Typically, you would never use this method.


 DhDocument.getElements

DhDocument.getElements

Retrieves the child elements of this element.

Syntax

public DhElement[] getElements()

Return Value

Returns an array of direct child elements.

Overrides DhBaseContainer.getElements


 DhDocument.getHandle

DhDocument.getHandle

Retrieves a window handle for the browser document.

Syntax

public int getHandle

Return Value

Returns a windows handle or -1 if one cannot be returned (typically when running on a server). This handle can be used as a parent for objects derived from Control.

See Also com.ms.wfc.ui.Form


 DhDocument.getHTML

DhDocument.getHTML

Retrieves the representative HTML of this document (also known as the page).

Syntax

public String getHTML()

Return Value

Returns the generated or bound HTML text.


 DhDocument.getLastModified

DhDocument.getLastModified

Retrieves the last modified date of the current document.

Syntax

public String getLastModified()

Return Value

Returns the document's last modified date in the form MM/DD/YY HH:MM:SS, or returns a null string if it is unavailable.


 DhDocument.getLocation

DhDocument.getLocation

Retrieves the current location of the document.

Syntax

public Point getLocation()

Return Value

Returns a Point object containing the document's location as offset from the top left corner of the browser.


 DhDocument.getModule

DhDocument.getModule

Retrieves the DhModule associated with this document.

Syntax

public DhModule getModule()

Return Value

Returns the DhModule associated with this document.


 DhDocument.getPeer

DhDocument.getPeer

Retrieves the underlying HTML peer element for this class.

Syntax

public IUnknown getPeer()

Return Value

Returns the element peer underlying the HTML peer for this class.

Remarks

This method can return null if the document is not bound to this class. Java code that is running in a trusted environment can freely cast the resulting reference to a specific element peer type. This method always returns null if the code is running in a Web server environment.

Note Calling this method represents a very advanced usage scenario. Typically, you would never use this method.


 DhDocument.getProtocol

DhDocument.getProtocol

Retrieves the long name of the protocol.

Syntax

public String getProtocol()

Return Value

Returns the name of the protocol, for example, "Hypertext Transfer Protocol" or "File Protocol".


 DhDocument.getReferrer

DhDocument.getReferrer

Retrieves the referring document.

Syntax

public String getReferrer()

Return Value

Returns the Uniform Resource Locator (URL) of the referring document, or returns a null string if it is unavailable.

Remarks

This is the document that contains the hyperlink to the current document.


 DhDocument.getScroll

DhDocument.getScroll

Retrieves the current scroll mode.

Syntax

public int getScroll()

Return Value

Returns the current scrolling mode. This can be one of the following DhScrollBars values:

  • AUTO indicates that the browser determines scrolling.
  • YES indicates scrolling is enabled.
  • NO indicates scrolling is disabled.

Note AUTO and YES are equivalent.

See Also com.ms.wfc.html.DhScrollBars, setScroll


 DhDocument.getServerMode

DhDocument.getServerMode

Determines if the document is on the server or client.

Syntax

public boolean getServerMode()

Return Value

Returns true if the document is on the server; otherwise, returns false.


 DhDocument.getSize

DhDocument.getSize

Retrieves the viewable size of the document.

Syntax

public Point getSize()

Return Value

Returns a Point object containing the document's size where width is represented as Point.x and height is represented as Point.y.


 DhDocument.getStyles

DhDocument.getStyles

Retrieves all styles in this document.

Syntax

public DhStyle[] getStyles()

Return Value

Returns an array of DhStyle objects found on this document.

Remarks

Style objects can be applied to any element using the setStyle method.


 DhDocument.getTitle

DhDocument.getTitle

Retrieves the title of the document.

Syntax

public String getTitle()

Return Value

Returns the title of document.

Remarks

For a browser, the title appears in the caption of the browser window.

See Also setTitle


 DhDocument.getWindow

DhDocument.getWindow

Retrieves the Window object of this document.

Syntax

final public DhWindow getWindow()

Return Value

Returns the Window object of the document.


 DhDocument.getWindowPeer

DhDocument.getWindowPeer

Retrieves the window peer of this document.

Syntax

protected IHTMLWindow2 getWindowPeer()

Return Value

Returns the WindowPeer object related to this the document.

Remarks

Calling this method represents a very advanced usage scenario. Typically, you would never use this method.


 DhDocument.importHTML

DhDocument.importHTML

Imports HTML into the document.

Syntax

public DhForm importHTML( String html )

public DhForm importHTMLFromStream( IDataStream inputDataStream )

Parameters

html

The string containing the HTML to import.

inputDataStream

A com.ms.wfc.io.IDataStream stream to read the HTML from.

Return Value

Returns a DhForm object.

Remarks

This HTML will replace any existing document contents.


 DhDocument.messageBox

DhDocument.messageBox

Displays a modal user message box.

Syntax

final public void messageBox( String s )

Parameters

s

The message string to display.


 DhDocument.moveElement

DhDocument.moveElement

Moves an element to a new numeric order in the layout flow.

Syntax

public void moveElement( DhElement element, int newOrder )

Parameters

element

The element to move.

newOrder

The new numeric order in the flow of this container.


 DhDocument.newLine

DhDocument.newLine

Appends a new line to the current document.

Syntax

public void newLine()

Remarks

All elements added after this call will be on a new line. This is equivalent to calling add(new DhBreak()).


 DhDocument.onDocumentBeforeUnload

DhDocument.onDocumentBeforeUnload

Implements an event handler for the beforeUnload event.

Syntax

protected void onDocumentBeforeUnload ( Object sender, Event event )

Parameters

sender

The object invoking this event.

event

The Event object.


 DhDocument.onDocumentLoad

DhDocument.onDocumentLoad

Implements an event handler for the load event.

Syntax

protected void onDocumentLoad ( Object sender, Event event )

Parameters

sender

The object invoking this event.

event

The Event object.


 DhDocument.onDocumentUnload

DhDocument.onDocumentUnload

Implements an event handler for the unload event.

Syntax

protected void onDocumentUnload ( Object sender, Event event )

Parameters

sender

The object invoking this event.

event

The Event object.

Remarks

A subclass of DhDocument should override this method if it has any operation that it wants to perform each time the document is unloaded. The implementation of this method provided by the DhDocument class does nothing.


 DhDocument.recreateElements

DhDocument.recreateElements

Deserializes HTML text generated by getHTML.

Syntax

public DhElement[] recreateElements( String html )

public DhElement[] recreateElements( String html, boolean fHonorIDs )

Parameters

html

The text that was generated by calling getHTML on a specified DhElement.

fHonorIDs

Set to true to prevent destruction of ID attributes.

Return Value

Returns the corresponding tree of derivations of DhElement that originally created the text in the html parameter.

Remarks

The default case of calling this method ignores the ID attributes of the HTML and overrides those attributes with identifiers that are unique to this document. To control this behavior, use recreateElements(String, boolean).

Passing true to fHonorIDs instructs this method not to overwrite the ID attributes of the HTML tags in the html parameter. This is a very advanced usage of this method. If ID attributes conflict with elements already on the page, the resulting behavior is undefined in the rest of the package.


 DhDocument.removeOnReadyStateChange

DhDocument.removeOnReadyStateChange

Removes the delegate that is assigned to the readyStateChange event.

Syntax

final public void removeOnReadyStateChange ( ReadyStateEventHandler h )

Parameters

h

The ReadyStateEventHandler delegate that is to be removed.

See Also addOnReadyStateChange


 DhDocument.setBoundElements

DhDocument.setBoundElements

Binds the elements of the specified array to their peers.

Syntax

public void setBoundElements( DhElement[] elems )

Parameters

elems

Array of elements to be bound to their peers.

Exceptions

com.ms.wfc.core.WFCException thrown if any of the following conditions are met:

  • The ID does not match HTML content.
  • The element is already bound to another object (through findElement).
  • The class type of the peer and the specified Java object do not match.


 DhDocument.setDomain

DhDocument.setDomain

Sets the host domain for the page.

Syntax

public void setDomain( String strDomain )

Parameters

strDomain

The domain to set.

Remarks

Pages on different frames can have their domains set to the same host to allow communication between frames.

See Also getDomain


 DhDocument.setGenerateTags

DhDocument.setGenerateTags

Determines whether HEAD and TITLE tags are generated by the getHTML method.

Syntax

public void setGenerateTags( boolean fGenerate )

Parameters

fGenerate

Set to true to generate <HEAD> and <TITLE> tags in a call to getHTML; otherwise, set to false.


 DhDocument.setScroll

DhDocument.setScroll

Sets the current scroll mode.

Syntax

public void setScroll( int scrollMode )

Parameters

scrollMode

The desired scrolling mode. This can be one of the following DhScrollBars values:

  • AUTO indicates that the browser determines scrolling.
  • YES indicates scrolling is enabled.
  • NO indicates scrolling is disabled.

Note AUTO and YES are equivalent.

See Also DhScrollBars, getScroll


 DhDocument.setTitle

DhDocument.setTitle

Sets the title of the document.

Syntax

public void setTitle( String newTitle )

Parameters

newTitle

The text that goes into the caption of the host.

Remarks

For a browser, the title appears in the caption of the browser window.

See Also getTitle


 DhDocument.writeHTML

DhDocument.writeHTML

Writes a diagnostic snapshot dump of the DHTML code, as currently seen by the document host, to a file.

Syntax

public void writeHTML( IDataStream stream )

Parameters

stream

The IDataStream object to dump the contents to.

Remarks

This method writes the source of the generated DHTML code that is currently running to a data stream specified by the stream parameter. This is a developer diagnostic tool, not an end-user feature, and requires that the code be fully trusted.


DhEdit Class

Implements an HTML edit box control.

Component
  |
  +--DhStyleBase
     |
     +--DhElement
        |
        +--DhEdit

package com.ms.wfc.html

public class DhEdit
extends DhElement

Remarks

Edit boxes can be multiline, single line, or single line password styles. Password edit boxes behave like single line edit boxes. However, their contents are masked by the asterisk (*) and are not displayed in the HTML representation at run time.


 DhEdit Methods

DhEdit Methods

Constructors | Description
DhEdit | Creates an edit box.

Methods | Description
addOnChange | Assigns a delegate to the change event.
addOnGotFocus | Assigns a delegate to the gotFocus event.
addOnLostFocus | Assigns a delegate to the lostFocus event.
addOnResize | Assigns a delegate to the resize event.
addOnScroll | Assigns a delegate to the scroll event.
addOnSelect | Assigns a delegate to the select event.
clear | Clears the text from the edit box.
focus | Sets the input focus to this edit box.
getCols | Retrieves the width, in characters, of the edit box.
getEnabled | Retrieves the enabled state of the edit box.
getMaxLength | Retrieves the current maximum input length for the edit.
getMultiline | Indicates whether the edit control allows editing on more than one line.
getPassword | Indicates whether the edit control is being used for password input and must conceal its value.
getReadOnly | Retrieves the current read-only mode.
getRows | Retrieves the current number of rows for a multiline edit box.
getSubmitName | Retrieves the name of the edit box.
getText | Retrieves the current text for the edit.
getWordWrap | Retrieves the current wrapping mode.
removeOnChange | Removes the delegate that is assigned to the change event.
removeOnGotFocus | Removes the delegate that is assigned to the focus event.
removeOnLostFocus | Removes the delegate that is assigned to the lostFocus event.
removeOnResize | Removes the delegate that is assigned to the resize event.
removeOnScroll | Removes the delegate that is assigned to the scroll event.
RemoveOnSelect | Removes the delegate that is assigned to the select event.
setCols | Sets the number of columns (characters) for the edit box width.
setEnabled | Sets the enabled state of the edit box.
setMaxLength | Sets the current maximum input length of the edit control in characters.
setMultiline | Indicates whether the edit control allows editing on more than one line.
setPassword | Specifies whether the edit control is being used for password input and must conceal its value.
setReadOnly | Sets the read-only mode for the edit control.
setRows | Sets the number of rows in a multiline edit box.
setSubmitName | Sets the name of the edit box.
setText | Sets the current text display of the edit box.
setWordWrap | Sets the wrapping mode for a multiline edit box.
shouldPersistText | Indicates whether text has changed from its default value.


 DhEdit.addOnChange

DhEdit.addOnChange

Assigns a delegate to the change event.

Syntax

public final void addOnChange( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when the current element's contents are changed.

See Also removeOnChange


 DhEdit.addOnGotFocus

DhEdit.addOnGotFocus

Assigns a delegate to the gotFocus event.

Syntax

public final void addOnGotFocus( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when the current element receives input focus.

See Also removeOnGotFocus


 DhEdit.addOnLostFocus

DhEdit.addOnLostFocus

Assigns a delegate to the lostFocus event.

Syntax

public final void addOnLostFocus( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when the current element loses focus.

See Also removeOnLostFocus


 DhEdit.addOnResize

DhEdit.addOnResize

Assigns a delegate to the resize event.

Syntax

public final void addOnResize( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when the current element is resized.

See Also removeOnResize


 DhEdit.addOnScroll

DhEdit.addOnScroll

Assigns a delegate to the scroll event.

Syntax

public final void addOnScroll( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when the current element is scrolled.

See Also removeOnScroll


 DhEdit.addOnSelect

DhEdit.addOnSelect

Assigns a delegate to the select event.

Syntax

public final void addOnSelect( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when the current element is selected.

See Also removeOnSelect


 DhEdit.clear

DhEdit.clear

Clears the text from the edit box.

Syntax

public void clear()


 DhEdit.DhEdit

DhEdit.DhEdit

Creates an edit box.

Syntax

public DhEdit()

public DhEdit( String strText )

public DhEdit( String strText, boolean multiline )

Parameters

strText

The initial text contents of DhEdit.

multiline

Set to true if the edit box has multiple lines; otherwise, set to false.

Remarks

This constructor creates a single line DhEdit edit box control. The default constructor (without parameters) creates an edit box without initial text.


 DhEdit.focus

DhEdit.focus

Sets the input focus to this edit box.

Syntax

public void focus()


 DhEdit.getCols

DhEdit.getCols

Retrieves the width, in characters, of the edit box.

Syntax

public int getCols()

Return Value

Returns the width in characters.

See Also setCols


 DhEdit.getEnabled

DhEdit.getEnabled

Retrieves the enabled state of the edit box.

Syntax

public boolean getEnabled()

Return Value

Returns true if the box is enabled; otherwise, returns false.

See Also setEnabled


 DhEdit.getMaxLength

DhEdit.getMaxLength

Retrieves the current maximum input length for the edit.

Syntax

public int getMaxLength()

Return Value

Returns the maximum input length, in characters. This value can be up to Integer.MAX_VALUE.

See Also setMaxLength


 DhEdit.getMultiline

DhEdit.getMultiline

Indicates whether the edit control allows editing on more than one line.

Syntax

public boolean getMultiline()

Return Value

Returns true if editing of more than one line is allowed; otherwise, returns false.

Remarks

By default, only one line of editing is permitted, and ENTER characters are ignored.

See Also setCols


 DhEdit.getPassword

DhEdit.getPassword

Indicates whether the edit control is being used for password input and must conceal its value.

Syntax

public boolean getPassword()

Remarks

Password edit boxes behave like single line edit boxes. However, their contents are masked by the asterisk (*) and are not displayed at run time.

See Also setPassword


 DhEdit.getReadOnly

DhEdit.getReadOnly

Retrieves the current read-only mode.

Syntax

public boolean getReadOnly()

Return Value

Returns true if control is read-only; otherwise, returns false.

See Also setReadOnly


 DhEdit.getRows

DhEdit.getRows

Retrieves the current number of rows for a multiline edit box.

Syntax

public int getRows()

Return Value

Returns the number of rows.

Remarks

Always returns 1 if the edit box style is not multiline.

See Also setRows


 DhEdit.getSubmitName

DhEdit.getSubmitName

Retrieves the name of the edit box.

Syntax

public String getSubmitName()

Return Value

Returns the name of the edit box.

Remarks

The name represents the HTML NAME attribute that is used for HTTP form submission.

See Also setSubmitName


 DhEdit.getText

DhEdit.getText

Retrieves the current text for the edit.

Syntax

public String getText()

Return Value

Returns the currently displayed string in the edit.

Remarks

For password style edit boxes, this returns the actual string, not the mask.

See Also setText


 DhEdit.getWordWrap

DhEdit.getWordWrap

Retrieves the current wrapping mode.

Syntax

public boolean getWordWrap()

Return Value

Returns true if wrapping is active; otherwise, returns false.

See Also setWordWrap


 DhEdit.removeOnChange

DhEdit.removeOnChange

Removes the delegate that is assigned to the change event.

Syntax

public final void removeOnChange( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The event handler is triggered when the current element's contents are changed.

See Also addOnChange


 DhEdit.removeOnGotFocus

DhEdit.removeOnGotFocus

Removes the delegate that is assigned to the focus event.

Syntax

public final void removeOnGotFocus( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The event handler is triggered when the current element receives input focus.

See Also addOnGotFocus


 DhEdit.removeOnLostFocus

DhEdit.removeOnLostFocus

Removes the delegate that is assigned to the lostFocus event.

Syntax

public final void removeOnLostFocus( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The event handler is triggered when the current element loses focus.

See Also addOnLostFocus


 DhEdit.removeOnResize

DhEdit.removeOnResize

Removes the delegate that is assigned to the resize event.

Syntax

public final void removeOnResize( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The event handler is triggered when the current element's contents are resized.

See Also addOnResize


 DhEdit.removeOnScroll

DhEdit.removeOnScroll

Removes the delegate that is assigned to the scroll event.

Syntax

public final void removeOnScroll( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The event handler is triggered when the current element is scrolled.

See Also addOnScroll


 DhEdit.removeOnSelect

DhEdit.removeOnSelect

Removes the delegate that is assigned to the select event.

Syntax

public final void removeOnSelect( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The event handler is triggered when the current element is selected.

See Also addOnSelect


 DhEdit.setCols

DhEdit.setCols

Sets the number of columns (characters) for the edit box width.

Syntax

public void setCols( int cols )

Parameters

cols

The width of the edit box in characters. This number must be greater than zero.

See Also getCols


 DhEdit.setEnabled

DhEdit.setEnabled

Sets the enabled state of the edit box.

Syntax

public void setEnabled( boolean f )

Parameters

f

Set to true to enable the edit box; set to false to disable it.

See Also getEnabled


 DhEdit.setMaxLength

DhEdit.setMaxLength

Sets the current maximum input length of the edit control in characters.

Syntax

public void setMaxLength( int nMaxLength )

Parameters

nMaxLength

Maximum input length, in characters. This value can be up to Integer.MAX_VALUE.

Remarks

This value is independent of the current column width and applies only to password or single line edit boxes. Strings set from code can exceed this length; only user input is restricted.

See Also getMaxLength


 DhEdit.setMultiline

DhEdit.setMultiline

Indicates whether the edit control allows editing on more than one line.

Syntax

public void setMultiline( boolean multiline )

Parameters

multiline

Set to true if editing of more than one line is allowed; otherwise, set to false.

Remarks

By default, only one line of editing is permitted, and ENTER characters are ignored.

See Also getMultiline


 DhEdit.setPassword

DhEdit.setPassword

Specifies whether the edit control is being used for password input and must conceal its value.

Syntax

public void setPassword( boolean value )

Parameters

value

Set to true if the control is used to enter passwords; otherwise, set to false.

Remarks

Password controls must be single line. If this is set to true, the Multiline property becomes false.

See Also getPassword


 DhEdit.setReadOnly

DhEdit.setReadOnly

Sets the read-only mode for the edit control.

Syntax

public void setReadOnly( boolean fReadOnly )

Parameters

fReadOnly

Set to true for read-only; set to false for read/write.

See Also getReadOnly


 DhEdit.setRows

DhEdit.setRows

Sets the number of rows in a multiline edit box.

Syntax

public void setRows( int rows )

Parameters

rows

The number of rows.

Exceptions

WFCInvalidArgumentException thrown if the rows parameter is less than or equal to 0 or if the rows parameter is greater than 1 and the edit box style is not multiline.

See Also getRows


 DhEdit.setSubmitName

DhEdit.setSubmitName

Sets the name of the edit box.

Syntax

public void setSubmitName( String strName )

Parameters

strName

The name to assign the control. This should be unique on the form.

Exceptions

WFCInvalidArgumentException thrown if strName is a null string.

Remarks

The name represents the HTML NAME attribute. This method is useful when submitting edit box content through an HTML form.

See Also getSubmitName


 DhEdit.setText

DhEdit.setText

Sets the current text display of the edit box.

Syntax

public void setText( String strText )

Parameters

strText

The text to display.

See Also getText


 DhEdit.setWordWrap

DhEdit.setWordWrap

Sets the wrapping mode for a multiline edit box.

Syntax

public void setWordWrap( boolean wrap )

Parameters

wrap

Set to true to cause text to wrap to the next line at the edge of the edit control; set to false to cause text to continue past the viewable area of the control.

See Also getWordWrap


 DhEdit.shouldPersistText

DhEdit.shouldPersistText

Indicates whether text has changed from its default value.

Syntax

public boolean shouldPersistText()

Return Value

Returns true if text has been set; otherwise, returns false.


DhElement Class

Represents the superclass for all user interface (UI) elements in this package.

DhStyleBase
  |
  +--DhElement

package com.ms.wfc.html

public class DhElement
extends DhStyleBase

Remarks

An instance of this class should be thought of as the Java representation of a specified user interface element in a Hypertext Markup Language (HTML) document. DhElement objects are never created directly. Instead, you instantiate a derivation of this class and then add the instance to the document (or a container destined for or already on the document). Alternatively, you can call the DhDocument.findElement method to locate and bind to an existing element and then cast the return value to the proper derivation.

See Also DhStyle, DhText, DhDocument, DhForm


 DhElement Methods

DhElement Methods

Methods | Description
addOnAfterUpdate | Assigns a delegate to the afterUpdate event.
addOnBeforeUpdate | Assigns a delegate to the beforeUpdate event.
addOnClick | Assigns a delegate to the click event.
addOnDataAvailable | Assigns a delegate to the dataAvailable event.
addOnDataSetChanged | Assigns a delegate to the dataSetChanged event.
addOnDataSetComplete | Assigns a delegate to the dataSetComplete event.
addOnDoubleClick | Assigns a delegate to the doubleClick event.
addOnDragStart | Assigns a delegate to the dragStart event.
addOnErrorUpdate | Assigns a delegate to the errorUpdate event.
addOnFilterChange | Assigns a delegate to the filterChange event.
addOnHelp | Assigns a delegate to the help event.
addOnKeyDown | Assigns a delegate to the keyDown event.
addOnKeyPress | Assigns a delegate to the keyPress event.
addOnKeyUp | Assigns a delegate to the keyUp event.
addOnMouseDown | Assigns a delegate to the mouseDown event.
addOnMouseEnter | Assigns a delegate to the mouseEnter event.
addOnMouseLeave | Assigns a delegate to the mouseLeave event.
addOnMouseMove | Assigns a delegate to the mouseMove event.
addOnMouseUp | Assigns a delegate to the mouseUp event.
addOnRowEnter | Assigns a delegate to the rowEnter event.
addOnRowExit | Assigns a delegate to the rowExit event.
addOnSelectStart | Assigns a delegate to the selectStart event.
addOnSetParent | Assigns a delegate to the setParent event.
dispose | Frees all resources associated with this element.
getAlign | Returns the alignment of the element.
getDocument | Retrieves the document object associated with this element.
getDOMAttributeInt | Retrieves an integer attribute, given the name of the attribute according to the Document Object Model (DOM) of Dynamic HTML.
getDOMAttributeString | Retrieves a string attribute, given the name of the attribute according to the Document Object Model (DOM) of Dynamic HTML.
getElementCount | Retrieves the number of elements contained by this element.
getElements | Retrieves an array of all elements contained by this element.
getEvents | Retrieves the event object for this element.
getHTML | Retrieves a string that contains the representative HTML text for this element and all its child elements.
getHTMLGenerator | Retrieves the current HTML generator for this element.
getID | Retrieves the ID attribute of the HTML element underlying this class.
getLocation | Retrieves the position (or location) of the element.
getModule | Retrieves the module object associated with element.
getParent | Retrieves the parent element that contains this element.
getPeer | Retrieves the underlying HTML peer element for this class.
getSize | Retrieves the size of the element.
getStyle | Retrieves the DhStyle style object associated with this element.
getTagName | Retrieves the string that contains the tag name that corresponds to this element given its current state (for example, "SPAN").
getTagNameID | Retrieves the string identifier that will be generated when the getHTML method is called.
getToolTip | Retrieves the string that represents the ToolTip that appears when the user's mouse pointer is hovering over this element.
hasPeer | Return the underlying HTML peer element for this class.
initFromPeer | Called when an instance is created from an existing HTML element.
onPeerAvailable | Called when the HTML for this element is added to the running browser document.
onSetParent | Called when the DhElement-derived parent has been set or changed for this element.
onSetPeer | This method is called when the IHTMLElement Document Object Model peer is set or reset for an element.
removeAttribute | Removes an attribute.
removeOnAfterUpdate | Removes the delegate that is assigned to the afterUpdate event.
removeOnBeforeUpdate | Removes the delegate that is assigned to the beforeUpdate event.
removeOnClick | Removes the delegate that is assigned to the click event.
removeOnDataAvailable | Removes the delegate that is assigned to the dataAvailable event.
removeOnDataSetChanged | Removes the delegate that is assigned to the dataSetChanged event.
removeOnDataSetComplete | Removes the delegate that is assigned to the dataSetComplete event.
removeOnDoubleClick | Removes the delegate that is assigned to the doubleClick event.
removeOnDragStart | Removes the delegate that is assigned to the dragStart event.
removeOnErrorUpdate | Removes the delegate that is assigned to the errorUpdate event.
removeOnFilterChange | Removes the delegate that is assigned to the filterChange event.
removeOnHelp | Removes the delegate that is assigned to the help event.
removeOnKeyDown | Removes the delegate that is assigned to the keyDown event.
removeOnKeyPress | Removes the delegate that is assigned to the keyPress event.
removeOnKeyUp | Removes the delegate that is assigned to the keyUp event.
removeOnMouseDown | Removes the delegate that is assigned to the mouseDown event.
removeOnMouseEnter | Removes the delegate that is assigned to the mouseEnter event.
removeOnMouseLeave | Removes the delegate that is assigned to the mouseLeave event.
removeOnMouseMove | Removes the delegate that is assigned to the mouseMove event.
removeOnMouseUp | Removes the delegate that is assigned to the mouseUp event.
removeOnRowEnter | Removes the delegate that is assigned to the rowEnter event.
removeOnRowExit | Removes the delegate that is assigned to the rowExit event.
removeOnSelectStart | Removes the delegate that is assigned to the selectStart event.
removeOnSetParent | Removes the delegate that is assigned to the setParent event.
resetAlign | Clears any align property.
resetID | Creates a new default ID for this element.
resetStyle | Clears any class set with setStyle.
resetToolTip | Resets the ToolTip to the default (usually blank).
setAlign | Sets the alignment of the element.
setBindID | Sets the ID for the element being bound.
setDOMAttribute | Sets a string attribute, given the name of the attribute according to the Document Object Model (DOM) of Dynamic HTML.
setDOMAttributeInt | Sets an integer attribute, given the name of the attribute according to the Document Object Model (DOM) of Dynamic HTML.
setElementPeer | Sets the peer for this element in the HTML document.
setHeightUnit | Sets the height of the element using one of the DhUnits constants to express the units of measurement.
setHTMLGenerator | Sets the HTML generator to use for this element.
setID | Sets the ID attribute of the HTML element underlying this class.
setSize | Sets the size of the element.
setStyle | Sets the style object associated with this element.
setToolTip | Sets the ToolTip that appears when the user's mouse pointer is hovering over this element.
setWidthUnit | Sets the width of the element using one of the DhUnits constants to express the units of measurement.


 DhElement.addOnAfterUpdate

DhElement.addOnAfterUpdate

Assigns a delegate to the afterUpdate event.

Syntax

public final void addOnAfterUpdate( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The afterUpdate event is triggered after the transfer of data from the element to the data provider.

See Also removeOnAfterUpdate


 DhElement.addOnBeforeUpdate

DhElement.addOnBeforeUpdate

Assigns a delegate to the beforeUpdate event.

Syntax

public final void addOnBeforeUpdate( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The beforeUpdate event is triggered before the transfer of data from the element to the data provider. It is also triggered when an element loses focus or the element is attempting to unload when its value has changed from when it received focus.

See Also removeOnBeforeUpdate


 DhElement.addOnClick

DhElement.addOnClick

Assigns a delegate to the click event.

Syntax

final public void addOnClick ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

Not all elements support all events exposed in DhElement.

See Also removeOnClick


 DhElement.addOnDataAvailable

DhElement.addOnDataAvailable

Assigns a delegate to the dataAvailable event.

Syntax

public final void addOnDataAvailable( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

How frequently this handler is triggered depends on the data source object.

See Also removeOnDataAvailable


 DhElement.addOnDataSetChanged

DhElement.addOnDataSetChanged

Assigns a delegate to the dataSetChanged event.

Syntax

public final void addOnDataSetChanged( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The handler is also triggered when initial data is available from a data source object.

See Also removeOnDataSetChanged


 DhElement.addOnDataSetComplete

DhElement.addOnDataSetComplete

Assigns a delegate to the dataSetComplete event.

Syntax

public final void addOnDataSetComplete( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

See Also removeOnDataSetComplete


 DhElement.addOnDoubleClick

DhElement.addOnDoubleClick

Assigns a delegate to the doubleClick event.

Syntax

final public void addOnDoubleClick ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

Not all elements support all events exposed in DhElement.

See Also removeOnDoubleClick


 DhElement.addOnDragStart

DhElement.addOnDragStart

Assigns a delegate to the dragStart event.

Syntax

final public void addOnDragStart ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

This delegate specifies a method that is called at the beginning of a drag-drop operation.

Not all elements support all events exposed in DhElement.

See Also removeOnDragStart


 DhElement.addOnErrorUpdate

DhElement.addOnErrorUpdate

Assigns a delegate to the errorUpdate event.

Syntax

public final void addOnErrorUpdate( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The errorUpdate event is triggered in place of the afterUpdate event when the data transfer has been canceled. Canceling is performed by the beforeUpdate event handler.

See Also removeOnErrorUpdate


 DhElement.addOnFilterChange

DhElement.addOnFilterChange

Assigns a delegate to the filterChange event.

Syntax

public final void addOnFilterChange( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

See Also removeOnFilterChange


 DhElement.addOnHelp

DhElement.addOnHelp

Assigns a delegate to the help event.

Syntax

public final void addOnHelp( HelpEventHandler h )

Parameters

h

The HelpEventHandler delegate to be notified when the event occurs.

See Also removeOnHelp


 DhElement.addOnKeyDown

DhElement.addOnKeyDown

Assigns a delegate to the keyDown event.

Syntax

final public void addOnKeyDown ( KeyEventHandler h )

Parameters

h

The KeyEventHandler delegate to be notified when the event occurs.

Remarks

Not all elements support all events exposed in DhElement.

See Also removeOnKeyDown


 DhElement.addOnKeyPress

DhElement.addOnKeyPress

Assigns a delegate to the keyPress event.

Syntax

final public void addOnKeyPress ( KeyPressEventHandler h )

Parameters

h

The KeyPressEventHandler delegate to be notified when the event occurs.

Remarks

Not all elements support all events exposed in DhElement.

See Also removeOnKeyPress


 DhElement.addOnKeyUp

DhElement.addOnKeyUp

Assigns a delegate to the keyUp event.

Syntax

final public void addOnKeyUp ( KeyEventHandler h )

Parameters

h

The KeyEventHandler delegate to be notified when the event occurs.

Remarks

Not all elements support all events exposed in DhElement.

See Also removeOnKeyUp


 DhElement.addOnMouseDown

DhElement.addOnMouseDown

Assigns a delegate to the mouseDown event.

Syntax

final public void addOnMouseDown( MouseEventHandler h )

Parameters

h

The MouseEventHandler delegate to be notified when the event occurs.

Remarks

Not all elements support all events exposed in DhElement.

See Also removeOnMouseDown


 DhElement.addOnMouseEnter

DhElement.addOnMouseEnter

Assigns a delegate to the mouseEnter event.

Syntax

final public void addOnMouseEnter( MouseEventHandler h )

Parameters

h

The MouseEventHandler delegate to be notified when the event occurs.

Remarks

Not all elements support all events exposed in DhElement.

See Also removeOnMouseEnter


 DhElement.addOnMouseLeave

DhElement.addOnMouseLeave

Assigns a delegate to the mouseLeave event.

Syntax

final public void addOnMouseLeave ( MouseEventHandler h )

Parameters

h

The MouseEventHandler delegate to be notified when the event occurs.

Remarks

Not all elements support all events exposed in DhElement.

See Also removeOnMouseLeave


 DhElement.addOnMouseMove

DhElement.addOnMouseMove

Assigns a delegate to the mouseMove event.

Syntax

final public void addOnMouseMove( MouseEventHandler h )

Parameters

h

The MouseEventHandler delegate to be notified when the event occurs.

Remarks

Not all elements support all events exposed in DhElement.

See Also removeOnMouseMove


 DhElement.addOnMouseUp

DhElement.addOnMouseUp

Assigns a delegate to the mouseUp event.

Syntax

final public void addOnMouseUp ( MouseEventHandler h )

Parameters

h

The MouseEventHandler delegate to be notified when the event occurs.

Remarks

Not all elements support all events exposed in DhElement.

See Also removeOnMouseUp


 DhElement.addOnRowEnter

DhElement.addOnRowEnter

Assigns a delegate to the rowEnter event.

Syntax

public final void addOnRowEnter( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

See Also removeOnRowEnter


 DhElement.addOnRowExit

DhElement.addOnRowExit

Assigns a delegate to the rowExit event.

Syntax

public final void addOnRowExit( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

See Also removeOnRowExit


 DhElement.addOnSelectStart

DhElement.addOnSelectStart

Assigns a delegate to the selectStart event.

Syntax

protected void addOnSelectStart( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the parent is set on this element.

See Also removeOnSelectStart


 DhElement.addOnSetParent

DhElement.addOnSetParent

Assigns a delegate to the setParent event.

Syntax

protected void addOnSetParent( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the parent is set on this element.

See Also removeOnSetParent


 DhElement.dispose

DhElement.dispose

Frees all resources associated with this element.

Syntax

public void dispose( )

Remarks

This method might not be called at run time. Any resources used by the element should be set up to be released when the element is released for garbage collection. Inheriting classes should always call super.dispose.


 DhElement.getAlign

DhElement.getAlign

Returns the alignment of the element.

Syntax

public int getAlign( )

Return Value

Returns the desired alignment specified as one of the DhAlignment constants, or returns -1 if alignment is uninitialized.

See Also setAlign


 DhElement.getDocument

DhElement.getDocument

Retrieves the document object associated with this element.

Syntax

public final DhDocument getDocument()

Return Value

Returns the DhDocument that this element has associated with it.


 DhElement.getDOMAttributeInt

DhElement.getDOMAttributeInt

Retrieves an integer attribute, given the name of the attribute according to the Document Object Model (DOM) of Dynamic HTML.

Syntax

public int getDOMAttributeInt( String strAttr )

Parameters

strAttr

The string identifier of the attribute to retrieve.

Return Value

Returns the integer value of the attribute.

Remarks

Calling this method directly is not part of the normal operation when using this package. You should call specific attribute methods directly on the element.

See Also setDOMAttributeInt


 DhElement.getDOMAttributeString

DhElement.getDOMAttributeString

Retrieves a string attribute, given the name of the attribute according to the Document Object Model (DOM) of Dynamic HTML.

Syntax

public String getDOMAttributeString( String strAttr )

Parameters

StrAttr

The string identifier of the attribute to retrieve.

Return Value

Returns the value of the attribute.

Remarks

Calling this method directly is not part of the normal operation using this package. You should call specific attribute methods directly on the element.


 DhElement.getElementCount

DhElement.getElementCount

Retrieves the number of elements contained by this element.

Syntax

public int getElementCount()

Return Value

This implementation returns 0.


 DhElement.getElements

DhElement.getElements

Retrieves an array of all elements contained by this element.

Syntax

public DhElement[] getElements()

Return Value

This implementation returns null.


 DhElement.getEvents

DhElement.getEvents

Retrieves the event object for this element.

Syntax

public final DhEvents getEvents()

Return Value

Returns the com.ms.wfc.html.event.DhEvents object for this element.

Remarks

Although this method is public in this class, most derivations hide it.


 DhElement.getHTML

DhElement.getHTML

Retrieves a string that contains the representative HTML text for this element and all its child elements.

Syntax

public String getHTML()

Return Value

Returns the HTML string that represents this element and all its children.


 DhElement.getHTMLGenerator

DhElement.getHTMLGenerator

Retrieves the current HTML generator for this element.

Syntax

public DhHTMLGenerator getHTMLGenerator()

Return Value

Returns the current DhHTMLGenerator object.

See Also setHTMLGenerator


 DhElement.getID

DhElement.getID

Retrieves the ID attribute of the HTML element underlying this class.

Syntax

public final String getID()

Return Value

Returns the string used for the ID attribute of the element.

Remarks

This ID is one persisted with the getHTML method.

Calling this method is not typically part of the usage of this package. The package automatically generates an ID for all DhElement objects even if this method isn't called directly.

See Also setID


 DhElement.getLocation

DhElement.getLocation

Retrieves the position (or location) of the element.

Syntax

public Point getLocation()

Return Value

Returns the location of the element.

Overrides DhStyleBase.getLocation


 DhElement.getModule

DhElement.getModule

Retrieves the module object associated with element.

Syntax

public DhModule getModule()

Return Value

Returns the DhModule that this element has associated with it.


 DhElement.getParent

DhElement.getParent

Retrieves the parent element that contains this element.

Syntax

public final DhElement getParent()

Return Value

Returns the parent element that this element has associated with it.

See Also DhDocument.add, DhForm.add


 DhElement.getPeer

DhElement.getPeer

Retrieves the underlying HTML peer element for this class.

Syntax

public IUnknown getPeer()

Return Value

Returns the element peer underlying the HTML peer for this class.

Remarks

This method can return null if the element or its parent was never added to a document. The Java code that is running in a trusted environment can freely cast the resulting reference to a specific element peer type (for example, com.ms.wfc.html.om.IHTMLElement). This method always returns null if the code is running in a Web server environment.

Calling this method represents an advanced usage scenario. Typically, you would never use this method.


 DhElement.getSize

DhElement.getSize

Retrieves the size of the element.

Syntax

public Point getSize()

Return Value

Returns the element size.

Overrides DhStyleBase.getSize

See Also setSize


 DhElement.getStyle

DhElement.getStyle

Retrieves the DhStyle style object associated with this element.

Syntax

public final DhStyle getStyle()

Return Value

Returns the DhStyle style object associated with this element.

Exceptions

IllegalStateException thrown if neither the element nor the associated DhDocument object has a style.

See Also DhStyle, setStyle


 DhElement.getTagName

DhElement.getTagName

Retrieves the string that contains the tag name that corresponds to this element given its current state (for example, "SPAN").

Syntax

public String getTagName()

Remarks

This value can change during the life of the instance. In many cases, it depends on specific attribute settings known only to the derivation of this class. This method useful only in special cases.


 DhElement.getTagNameID

DhElement.getTagNameID

Retrieves the string identifier that will be generated when the getHTML method is called.

Syntax

protected int getTagNameID()

Return Value

Returns the string identifier for the tag name of this element. (The base class returns -1, an invalid ID.)


 DhElement.getToolTip

DhElement.getToolTip

Retrieves the string that represents the ToolTip that appears when the user's mouse pointer is hovering over this element.

Syntax

public final String getToolTip()

Return Value

Returns the ToolTip string.

See Also setToolTip


 DhElement.hasPeer

DhElement.hasPeer

Return the underlying HTML peer element for this class.

Syntax

public final IUnknown hasPeer()

Return Value

Returns the element peer underlying the HTML peer for this class, assuming it is available.

Remarks

This method can return null even if the element or its parent was added to a document, but there hasn't been occasion to bind to its peer. The Java code that is running in a trusted environment can freely cast the resulting reference to a specific element peer type (for example, com.ms.wfc.html.om.IHTMLElement). This method always returns null if the code is running in a Web server environment.

Calling getPeer retrieves the peer element even if the element hasn't had a chance to bind to the document yet.

Calling this method represents a very advanced usage scenario. Typically, you would never use this method.


 DhElement.initFromPeer

DhElement.initFromPeer

Called when an instance is created from an existing HTML element.

Syntax

protected void initFromPeer( IHTMLElement peer )

Parameters

peer

The existing peer element.

Remarks

Override this method to perform any special initialization when an instance is created from an existing HTML element.


 DhElement.onPeerAvailable

DhElement.onPeerAvailable

Called when the HTML for this element is added to the running browser document.

Syntax

protected void onPeerAvailable()

Remarks

Override this method to be notified when the peer object is available. For example, at this point, it is possible to retrieve the Document Object Model peer object that can be manipulated with this element.


 DhElement.onSetParent

DhElement.onSetParent

Called when the DhElement-derived parent has been set or changed for this element.

Syntax

protected void onSetParent(DhElement newParent )

Parameters

newParent

The new parent reference.


 DhElement.onSetPeer

DhElement.onSetPeer

This method is called when the IHTMLElement Document Object Model peer is set or reset for an element.

Syntax

protected void onSetPeer( IHTMLElement newPeer )

Parameters

newPeer

The new IHTMLElement peer item.

Remarks

The value of the peer that is associated with an element can change several times during the life of the element due to certain operations.


 DhElement.removeAttribute

DhElement.removeAttribute

Removes an attribute.

Syntax

public void removeAttribute( String strAttr )

Parameters

strAttr

The name of the custom attribute to remove.

Remarks

Calling this method directly is not part of the normal operation using this package. You should call specific attribute methods directly on the element.


 DhElement.removeOnAfterUpdate

DhElement.removeOnAfterUpdate

Removes the delegate that is assigned to the afterUpdate event.

Syntax

public final void removeOnAfterUpdate( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

See Also addOnAfterUpdate


 DhElement.removeOnBeforeUpdate

DhElement.removeOnBeforeUpdate

Removes the delegate that is assigned to the beforeUpdate event.

Syntax

public final void removeOnBeforeUpdate( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

See Also addOnBeforeUpdate


 DhElement.removeOnClick

DhElement.removeOnClick

Removes the delegate that is assigned to the click event.

Syntax

final public void removeOnClick ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

Not all elements support all events exposed in DhElement.

See Also addOnClick


 DhElement.removeOnDataAvailable

DhElement.removeOnDataAvailable

Removes the delegate that is assigned to the dataAvailable event.

Syntax

public final void removeOnDataAvailable( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

How frequently this handler is triggered depends on the data source object.

See Also addOnDataAvailable


 DhElement.removeOnDataSetChanged

DhElement.removeOnDataSetChanged

Removes the delegate that is assigned to the dataSetChanged event.

Syntax

public final void removeOnDataSetChanged( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

This is also triggered when initial data is available from a data source object.

See Also addOnDataSetChanged


 DhElement.removeOnDataSetComplete

DhElement.removeOnDataSetComplete

Removes the delegate that is assigned to the dataSetComplete event.

Syntax

public final void removeOnDataSetComplete( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

See Also addOnDataSetComplete


 DhElement.removeOnDoubleClick

DhElement.removeOnDoubleClick

Removes the delegate that is assigned to the doubleClick event.

Syntax

final public void removeOnDoubleClick ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

Not all elements support all events exposed in DhElement.

See Also addOnDoubleClick


 DhElement.removeOnDragStart

DhElement.removeOnDragStart

Removes the delegate that is assigned to the dragStart event.

Syntax

final public void removeOnDragStart ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

Not all elements support all events exposed in DhElement.

See Also addOnDragStart


 DhElement.removeOnErrorUpdate

DhElement.removeOnErrorUpdate

Removes the delegate that is assigned to the errorUpdate event.

Syntax

public final void removeOnErrorUpdate( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The errorUpdate event is triggered in place of the afterUpdate event when the data transfer has been canceled. Canceling is performed by the beforeUpdate event handler.

See Also addOnErrorUpdate


 DhElement.removeOnFilterChange

DhElement.removeOnFilterChange

Removes the delegate that is assigned to the filterChange event.

Syntax

public final void removeOnFilterChange( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

See Also addOnFilterChange


 DhElement.removeOnHelp

DhElement.removeOnHelp

Removes the delegate that is assigned to the help event.

Syntax

public final void removeOnHelp( HelpEventHandler h )

Parameters

h

The HelpEventHandler delegate that is to be removed.

See Also addOnHelp


 DhElement.removeOnKeyDown

DhElement.removeOnKeyDown

Removes the delegate that is assigned to the keyDown event.

Syntax

final public void removeOnKeyDown ( KeyEventHandler h )

Parameters

h

The KeyEventHandler delegate that is to be removed.

Remarks

Not all elements support all events exposed in DhElement.

See Also addOnKeyDown


 DhElement.removeOnKeyPress

DhElement.removeOnKeyPress

Removes the delegate that is assigned to the keyPress event.

Syntax

final public void removeOnKeyPress ( KeyPressEventHandler h )

Parameters

h

The KeyPressEventHandler delegate that is to be removed.

Remarks

Not all elements support all events exposed in DhElement.

See Also addOnKeyPress


 DhElement.removeOnKeyUp

DhElement.removeOnKeyUp

Removes the delegate that is assigned to the keyUp event.

Syntax

final public void removeOnKeyUp ( KeyEventHandler h )

Parameters

h

The KeyEventHandler delegate that is to be removed.

Remarks

Not all elements support all events exposed in DhElement.

See Also addOnKeyUp


 DhElement.removeOnMouseDown

DhElement.removeOnMouseDown

Removes the delegate that is assigned to the mouseDown event.

Syntax

final public void removeOnMouseDown( MouseEventHandler h )

Parameters

h

The MouseEventHandler delegate that is to be removed.

Remarks

Not all elements support all events exposed in DhElement.

See Also addOnMouseDown


 DhElement.removeOnMouseEnter

DhElement.removeOnMouseEnter

Removes the delegate that is assigned to the mouseEnter event.

Syntax

final public void removeOnMouseEnter( MouseEventHandler h )

Parameters

h

The MouseEventHandler delegate that to be removed.

Remarks

Not all elements support all events exposed in DhElement.

See Also addOnMouseEnter


 DhElement.removeOnMouseLeave

DhElement.removeOnMouseLeave

Removes the delegate that is assigned to the mouseLeave event.

Syntax

final public void removeOnMouseLeave ( MouseEventHandler h )

Parameters

h

The MouseEventHandler delegate that is to be removed.

Remarks

Not all elements support all events exposed in DhElement.

See Also addOnMouseLeave


 DhElement.removeOnMouseMove

DhElement.removeOnMouseMove

Removes the delegate that is assigned to the mouseMove event.

Syntax

final public void removeOnMouseMove( MouseEventHandler h )

Parameters

h

The MouseEventHandler delegate that is to be removed.

Remarks

Not all elements support all events exposed in DhElement.

See Also addOnMouseMove


 DhElement.removeOnMouseUp

DhElement.removeOnMouseUp

Removes the delegate that is assigned to the mouseUp event.

Syntax

final public void removeOnMouseUp ( MouseEventHandler h )

Parameters

h

The MouseEventHandler delegate that is to be removed.

Remarks

Not all elements support all events exposed in DhElement.

See Also addOnMouseUp


 DhElement.removeOnRowEnter

DhElement.removeOnRowEnter

Removes the delegate that is assigned to the rowEnter event.

Syntax

public final void removeOnRowEnter( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

See Also addOnRowEnter


 DhElement.removeOnRowExit

DhElement.removeOnRowExit

Removes the delegate that is assigned to the rowExit event.

Syntax

public final void removeOnRowExit( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

See Also addOnRowExit


 DhElement.removeOnSelectStart

DhElement.removeOnSelectStart

Removes the delegate that is assigned to the selectStart event.

Syntax

protected void removeOnSelectStart ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

Not all elements support all events exposed in DhElement.

See Also addOnSelectStart


 DhElement.removeOnSetParent

DhElement.removeOnSetParent

Removes the delegate that is assigned to the setParent event.

Syntax

protected void removeOnSetParent( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

Not all elements support all events exposed in DhElement.

See Also addOnSetParent


 DhElement.resetAlign

DhElement.resetAlign

Clears any align property.

Syntax

public final void resetAlign()

See Also getAlign


 DhElement.resetID

DhElement.resetID

Creates a new default ID for this element.

Syntax

public final void resetID()

See Also getID


 DhElement.resetStyle

DhElement.resetStyle

Clears any class set with setStyle.

Syntax

public final void resetStyle()

See Also getStyle


 DhElement.resetToolTip

DhElement.resetToolTip

Resets the ToolTip to the default (usually blank).

Syntax

public final void resetToolTip()

See Also getToolTip


 DhElement.setAlign

DhElement.setAlign

Sets the alignment of the element.

Syntax

public void setAlign( int nAlign )

Parameters

nAlign

The desired alignment, specified as one of the DhAlignment constants.

Remarks

This alignment property generally affects child elements if this element is a container; otherwise, it affects alignment relative to adjacent text. To center-align, left-align, or right-align an element relative to the document, wrap it with a DhForm container.

See Also getAlign


 DhElement.setBindID

DhElement.setBindID

Sets the ID for the element being bound.

Syntax

public final DhElement setBindID( String id )

Parameters

id

The string to use for the ID attribute of the element.

Return Value

Returns this DhElement object with the ID attribute set.


 DhElement.setDOMAttribute

DhElement.setDOMAttribute

Sets a string attribute, given the name of the attribute according to the Document Object Model (DOM) of Dynamic HTML.

Syntax

public void setDOMAttribute( String strAttr, String value )

Parameters

strAttr

The name of the custom attribute to set.

value

A string value.

Remarks

Calling this method directly is not part of the normal usage of this package. You should call specific attribute methods directly on the element, for example, DhImage.setURL.


 DhElement.setDOMAttributeInt

DhElement.setDOMAttributeInt

Sets an integer attribute, given the name of the attribute according to the Document Object Model (DOM) of Dynamic HTML.

Syntax

public void setDOMAttributeInt( String strAttr, int value )

Parameters

strAttr

The name of the custom attribute to set.

value

An integer value.

Remarks

Calling this method directly is not part of the normal usage of this package. You should call specific attribute methods directly on the element, for example, DhImage.setURL.

See Also getDOMAttributeInt


 DhElement.setElementPeer

DhElement.setElementPeer

Sets the peer for this element in the HTML document.

Syntax

protected void setElementPeer( IHTMLElement peer )

protected void setElementPeer( IHTMLElement peer, Boolean transition )

Parameters

peer

The existing peer element.

transition

Set to true to bind the peer element; otherwise, set to false.

Remarks

Calling this method represents an advanced usage scenario. Typically, you would never use this method.


 DhElement.setHeightUnit

DhElement.setHeightUnit

Sets the height of the element using one of the DhUnits constants to express the units of measurement.

Syntax

public void setHeightUnit( int h, int unit )

Parameters

h

The height value.

unit

One of DhUnits constants to express the units of measurement.

See Also DhStyleBase.getBounds


 DhElement.setHTMLGenerator

DhElement.setHTMLGenerator

Sets the HTML generator to use for this element.

Syntax

public void setHTMLGenerator( DhHTMLGenerator htmlGen )

Parameters

htmlGen

The DhHTMLGenerator to assign to this element.

Remarks

This allows you to override the library's default method of generating HTML syntax to represent an element.

See Also getHTMLGenerator


 DhElement.setID

DhElement.setID

Sets the ID attribute of the HTML element underlying this class.

Syntax

public final void setID( String id )

Parameters

id

The string to use for the ID attribute of the element.

Remarks

This ID is persisted with the getHTML method.

Calling this method is not normally part of the usage of this package. The package with automatically generate an ID for all DhElement objects even if this method isn't directly called.

See Also getID


 DhElement.setSize

DhElement.setSize

Sets the size of the element.

Syntax

public void setSize( int w, int h )

Parameters

w

The new width of the element.

h

The new height of the element.

See Also setWidthUnit, setHeightUnit, getSize


 DhElement.setStyle

DhElement.setStyle

Sets the style object associated with this element.

Syntax

public final void setStyle( DhStyle style )

Parameters

style

The style object associated with this element.

See Also getStyle


 DhElement.setToolTip

DhElement.setToolTip

Sets the ToolTip that appears when the user's mouse pointer is hovering over this element.

Syntax

public final void setToolTip( String string )

Parameters

string

The string to use for the ToolTip.

See Also getToolTip


 DhElement.setWidthUnit

DhElement.setWidthUnit

Sets the width of the element using one of the DhUnits constants to express the units of measurement.

Syntax

public void setWidthUnit( int w, int unit )

Parameters

w

The width values.

unit

One of DhUnits constants to express the units of measurement.

See Also DhStyleBase.getBounds


DhElementExistsInDocumentException Class

Signals that a specified element has already been added to the document. Elements can be added only once.

RuntimeException
  |
  +--WFCException
     |
     +--DhElementExistsInDocumentException

package com.ms.wfc.html

public class DhElementExistsInDocumentException
extends WFCException


 DhElementExistsInDocumentException Methods

DhElementExistsInDocumentException Methods

Constructors | Description
DhElementExistsInDocumentException | Creates an ElementExistsinDocumentException object.


 DhElementExistsInDocumentException.DhElementExistsInDocumentException

DhElementExistsInDocumentException.DhElementExistsInDocumentException

Creates an ElementExistsinDocumentException object.

Syntax

public DhElementExistsInDocumentException()

public DhElementExistsInDocumentException( String s )

Parameters

s

The detail message for the exception.

Remarks

The default constructor creates an exception with no detail message.


DhElementNotFoundException Class

Signals that a request for a specified element failed because an element with that name does not exist.

RuntimeException
  |
  +--WFCException
     |
     +--DhElementNotFoundException

package com.ms.wfc.html

public class DhElementNotFoundException
extends WFCException


 DhElementNotFoundException Methods

DhElementNotFoundException Methods

Constructors | Description
DhElementNotFoundException | Creates a DhElementNotFoundException object.


 DhElementNotFoundException.DhElementNotFoundException

DhElementNotFoundException.DhElementNotFoundException

Creates a DhElementNotFoundException object.

Syntax

public DhElementNotFoundException()

public DhElementNotFoundException( String s )

Parameters

s

The detail message for the exception.

Remarks

The default constructor creates an exception with no detail message.


DhEnumeration Class

Represents a collection of elements in the HTML document.

package com.ms.wfc.html

public class DhEnumeration
implements IEnumerator

Remarks

You can either create a DhEnumeration object class directly (using new) or call DhDocument.enumerate to get the collection.

Many HTML tags do not map one-to-one to Java classes in this package. When enumerating through the return of next, always check the result by calling instanceof.


 DhEnumeration Methods

DhEnumeration Methods

Constructors | Description
DhEnumeration | Creates a DhEnumeration object.

Methods | Description
hasMoreItems | Tests if this enumeration contains more elements.
next | Returns the next element of this enumeration.
nextItem | Returns the next element of this enumeration.
reset | Resets the enumerator to the beginning.


 DhEnumeration.DhEnumeration

DhEnumeration.DhEnumeration

Creates a DhEnumeration object.

Syntax

public DhEnumeration( DhDocument document, int enumType )

Parameters

document

A reference to a DhDocument.

enumType

One of the valid types of collections, which can be one of the following:

  • ELEMENTS, which include all elements (tags including the HEAD and BODY).
  • IMAGES, which include only the images (such as IMG tags).
  • HLINKS, which include only the links (such as A tags).

Remarks

You can use this constructor or call DhDocument.enumerate to get the collection.


 DhEnumeration.hasMoreItems

DhEnumeration.hasMoreItems

Tests if this enumeration contains more elements.

Syntax

public boolean hasMoreItems()

Return Value

Returns true if this enumeration contains more elements; otherwise, returns false.


 DhEnumeration.next

DhEnumeration.next

Returns the next element of this enumeration.

Syntax

public DhElement next()

Return Value

Returns the next element of this enumeration, or returns null if one does not exist.

Remarks

This method returns a DhElement object so there is no need to cast the result to a DhElement object. The result can be further cast (for example, to DhImage) depending on the type of enumeration this is.

Many HTML tags do not map one-to-one into Java classes in this package. When enumerating through the return of next, always check the result by calling instanceof.


 DhEnumeration.nextItem

DhEnumeration.nextItem

Returns the next element of this enumeration.

Syntax

public Object nextItem()

Return Value

Returns the next element of this enumeration.

Exceptions

WFCException thrown if no more elements exist.

See Also next


 DhEnumeration.reset

DhEnumeration.reset

Resets the enumerator to the beginning.

Syntax

public void reset()


 DhEnumeration Fields

DhEnumeration Fields

Fields | Description
ELEMENTS | Used by either DhDocument.enumerate or the DhEnumeration constructor to indicate a collection of all elements on the page.
HLINKS | Used by either DhDocument.enumerate or the DhEnumeration constructor to indicate a collection of all link (HREF) elements on the page.
IMAGES | Used by either DhDocument.enumerate or the DhEnumeration constructor to indicate a collection of all image (IMG) elements on the page.


 DhEnumeration.ELEMENTS

DhEnumeration.ELEMENTS

Used by either DhDocument.enumerate or the DhEnumeration constructor to indicate a collection of all elements on the page.

Syntax

public static final int ELEMENTS;


 DhEnumeration.HLINKS

DhEnumeration.HLINKS

Used by either DhDocument.enumerate or the DhEnumeration constructor to indicate a collection of all link (HREF) elements on the page.

Syntax

public static final int HLINKS;


 DhEnumeration.IMAGES

DhEnumeration.IMAGES

Used by either DhDocument.enumerate or the DhEnumeration constructor to indicate a collection of all image (IMG) elements on the page.

Syntax

public static final int IMAGES;


DhEventInfo Class

Carries event information from the event source to the event sink.

package com.ms.wfc.html

public class DhEventInfo

Remarks

When an event is triggered from an HTML element, the extendedInfo field of the Event object contains a DhEventInfo object. You use DhEventInfo to control subsequent actions taken by the event (such as bubbling) and to find out more about the context in which the event occurred.

The following example shows how to set up a basic event handler that displays the value of the DhEventInfo object for mouseMove events.

import com.ms.wfc.html.*;
import com.ms.wfc.html.event.*;

public class DumpEvent extends DhDocument
{
   DhText text;

   public void initForm()
   {
      text = new DhText();
      this.add(text,DhInsertOptions.BEGINNING);
      this.addOnMouseMove( new MouseEventHandler(this.onMouseMove ) );
   }

   public void onMouseMove( Object sender, Event event )
   {
      text.setText( event.toString() );
      /* If you want to use more advanced features of HTML eventing model,
         or get more information about HTML events, use the DhEventInfo as
         shown below. */
      DhEventInfo eventInfo = (DhEventInfo)event.getExtendedInfo();
      eventInfo.cancelBubble();

   }
}


 DhEventInfo Methods

DhEventInfo Methods

Methods | Description
cancelBubble | All event sources in HTML trigger the same events all the way up their containment hierarchy. Calling this method tells the HTML document to stop event bubbling.
getChar | Tests for the presence of any key and returns that keypress.
getClientPoint | Retrieves the current position of the mouse relative to the parent client area.
getDocument | Retrieves the document object on which this event was triggered.
getFromElement | Retrieves the element that the mouse was on before the mouseEnter or mouseLeave event.
getMouseButton | Tests for mouse button events.
getOffsetPoint | Retrieves the current position of the mouse relative to the element's client area.
getPeer | Retrieves the underlying HTML peer element for this class.
getPoint | Retrieves the current position of the mouse relative to the document client.
getReturnValue | Determines whether return data has been set.
getScreenPoint | Retrieves the current position of the mouse relative to the desktop.
getSource | Retrieves the original source of the event.
getToElement | Retrieves the element that the mouse was on following the mouseEnter or mouseLeave event.
isAltKey | Tests for the ALT key.
isCtrlKey | Tests for the CTRL key.
isShiftKey | Tests for the SHIFT key.
setChar | Sets the currently pressed key.
setReturnValue | Sets return data for the event.
toString | Converts this event object to a string.


 DhEventInfo.cancelBubble

DhEventInfo.cancelBubble

All event sources in HTML trigger the same events all the way up their containment hierarchy. Calling this method tells the HTML document to stop event bubbling.

Syntax

final public void cancelBubble()


 DhEventInfo.getChar

DhEventInfo.getChar

Tests for the presence of any key and returns that keypress.

Syntax

final public int getChar()

Return Value

Returns the key code of the currently pressed key (or 0 if no key is pressed).


 DhEventInfo.getClientPoint

DhEventInfo.getClientPoint

Retrieves the current position of the mouse relative to the parent client area.

Syntax

final public Point getClientPoint()

Return Value

Returns the current position of the mouse relative to the parent client area.

See Also toString


 DhEventInfo.getDocument

DhEventInfo.getDocument

Retrieves the document object on which this event was triggered.

Syntax

final public DhDocument getDocument()

Return Value

Returns the document object this event came from.


 DhEventInfo.getFromElement

DhEventInfo.getFromElement

Retrieves the element that the mouse was on before the mouseEnter or mouseLeave event.

Syntax

final public DhElement getFromElement()

Return Value

Returns the DhElement from which the mouse moved, or returns null if the event was neither mouseEnter nor mouseLeave. This can be a normal element, the containing DhDocument object, or null if the mouse has moved into the browser from outside it.

Remarks

This method is valid only following mouseEnter or mouseLeave event.

See Also getToElement


 DhEventInfo.getMouseButton

DhEventInfo.getMouseButton

Tests for mouse button events.

Syntax

final public int getMouseButton()

Return Value

Returns one of the mouse buttons constants from EVT_NOBUTTON, EVT_LEFTBUTTON, EVT_RIGHTBUTTON, or EVT_MIDDLEBUTTON.


 DhEventInfo.getOffsetPoint

DhEventInfo.getOffsetPoint

Retrieves the current position of the mouse relative to the element's client area.

Syntax

final public Point getOffsetPoint()

Return Value

Returns the current position of the mouse.

See Also toString


 DhEventInfo.getPeer

DhEventInfo.getPeer

Retrieves the underlying HTML peer element for this class.

Syntax

final public IUnknown getPeer()

Return Value

Returns the element peer underlying the HTML peer for this class.

Remarks

This method can return null if the event is not bound to the document. Java code that is running in a trusted environment can freely cast the resulting reference to a specific element peer type (for example, com.ms.wfc.html.om.IHTMLEventObj). This method always returns null if the code is running in a Web server environment.

Note Calling this method represents an advanced usage scenario. Typically, you would never use this method.


 DhEventInfo.getPoint

DhEventInfo.getPoint

Retrieves the current position of the mouse relative to the document client.

Syntax

final public Point getPoint()

Return Value

Returns the current position of the mouse.

See Also toString


 DhEventInfo.getReturnValue

DhEventInfo.getReturnValue

Determines whether return data has been set.

Syntax

final public Variant getReturnValue()

Remarks

Certain kinds of events require a response value. Use this method to determine whether another handler has set the return data to the event source.


 DhEventInfo.getScreenPoint

DhEventInfo.getScreenPoint

Retrieves the current position of the mouse relative to the desktop.

Syntax

final public Point getScreenPoint()

Return Value

Returns the current position of the mouse.

See Also toString


 DhEventInfo.getSource

DhEventInfo.getSource

Retrieves the original source of the event.

Syntax

final public DhElement getSource()

Return Value

Returns the element that first triggered this event.

Remarks

This can be the object you actually hooked the event on, or it can one of its children (because all events bubble up the containment hierarchy automatically).


 DhEventInfo.getToElement

DhEventInfo.getToElement

Retrieves the element that the mouse was on following the mouseEnter or mouseLeave event.

Syntax

final public DhElement getToElement()

Return Value

Returns the DhElement to which the mouse moved after the event, or returns null if the event was neither mouseEnter nor mouseLeave. This can be a normal element, the containing DhDocument object, or null if the mouse has moved into the browser from outside it.

See Also getFromElement


 DhEventInfo.isAltKey

DhEventInfo.isAltKey

Tests for the ALT key.

Syntax

final public boolean isAltKey()

Return Value

Returns true if the ALT key is pressed.


 DhEventInfo.isCtrlKey

DhEventInfo.isCtrlKey

Tests for the CTRL key.

Syntax

final public boolean isCtrlKey()

Return Value

Returns true if the CTRL key is pressed.


 DhEventInfo.isShiftKey

DhEventInfo.isShiftKey

Tests for the SHIFT key.

Syntax

final public boolean isShiftKey()

Return Value

Returns true if the SHIFT key is pressed.


 DhEventInfo.setChar

DhEventInfo.setChar

Sets the currently pressed key.

Syntax

final public void setChar( int c )

Parameters

c

The key character that will be returned by getChar.

See Also getChar


 DhEventInfo.setReturnValue

DhEventInfo.setReturnValue

Sets return data for the event.

Syntax

final public void setReturnValue( boolean b )

final public void setReturnValue( String s )

final public void setReturnValue( int i )

final public void setReturnValue( Variant v )

Parameters

b

The boolean value for the event to return.

s

The String value for the event to return.

i

The int value for the event to return.

v

The Variant value for the event to return.

Remarks

Certain kinds of events require a response value. Use this method to return data to the event source.


 DhEventInfo.toString

DhEventInfo.toString

Converts this event object to a string.

Syntax

public String toString()

Remarks

Use this method when performing diagnostics on your code.


 DhEventInfo Fields

DhEventInfo Fields

Fields | Description
EVT_LEFTBUTTON | Indicates that the left mouse button has been pressed.
EVT_MIDDLEBUTTON | Indicates that the middle mouse button has been pressed.
EVT_NOBUTTON | Indicates that no mouse button has been pressed.
EVT_RIGHTBUTTON | Indicates that the right mouse button has been pressed.


 DhEventInfo.EVT_LEFTBUTTON

DhEventInfo.EVT_LEFTBUTTON

Indicates that the left mouse button has been pressed.

Syntax

public static final int EVT_LEFTBUTTON;


 DhEventInfo.EVT_MIDDLEBUTTON

DhEventInfo.EVT_MIDDLEBUTTON

Indicates that the middle mouse button has been pressed.

Syntax

public static final int EVT_MIDDLEBUTTON;


 DhEventInfo.EVT_NOBUTTON

DhEventInfo.EVT_NOBUTTON

Indicates that no mouse button has been pressed.

Syntax

public static final int EVT_NOBUTTON;


 DhEventInfo.EVT_RIGHTBUTTON

DhEventInfo.EVT_RIGHTBUTTON

Indicates that the right mouse button has been pressed.

Syntax

public static final int EVT_RIGHTBUTTON;


DhForm Class

Represents an element container that uses traditional HTML one-dimensional flow layout.

Component
  |
  +--DhStyleBase
     |
     +--DhElement
        |
        +--DhBaseContainer
           |
           +--DhForm

package com.ms.wfc.html

public class DhForm
extends DhBaseContainer

Remarks

This class can represent either a FORM or a DIV HTML element. Use the getAsHTTPForm method to determine the type of element. If a DhResetButton or DhSubmitButton button is added, the element automatically becomes a FORM. When the element is a FORM, both the reset and formSubmit events can be handled by adding event handlers. By default, elements that are added to this kind of container are not positioned in x-y coordinates but rather "flow" around each other.


 DhForm Methods

DhForm Methods

Constructors | Description
DhForm | Creates a DhForm section container.

Methods | Description
add | Adds an element into this container, following all other elements.
addOnChange | Assigns a delegate to the change event.
addOnFormReset | Assigns a delegate to the formReset event.
addOnFormSubmit | Assigns a delegate to the formSubmit event.
addOnGotFocus | Assigns a delegate to the gotFocus event.
addOnLostFocus | Assigns a delegate to the lostFocus event.
addOnResize | Assigns a delegate to the resize event.
addOnScroll | Assigns a delegate to the scroll event.
addOnSelect | Assigns a delegate to the select event.
addText | Appends a text string to the current section.
getAsHTTPForm | Retrieves the current FORM/DIV state.
getSubmitMethod | Retrieves the current HTTP submit method.
getSubmitURL | Retrieves the current URL that will be called if the form's Submit button is clicked.
moveElement | Moves an element to a new numeric order in the flow.
newLine | Appends a new line to the current section.
remove | Removes an element from this container.
removeAll | Removes all child elements from this container.
removeOnChange | Removes the delegate that is assigned to the change event.
removeOnFormReset | Removes the delegate that is assigned to the formReset event.
removeOnFormSubmit | Removes the delegate that is assigned to the formSubmit event.
removeOnGotFocus | Removes the delegate that is assigned to the gotFocus event.
removeOnLostFocus | Removes the delegate that is assigned to the lostFocus event.
removeOnResize | Removes the delegate that is assigned to the resize event.
removeOnScroll | Removes the delegate that is assigned to the scroll event.
removeOnSelect | Removes the delegate that is assigned to the select event.
setAsHTTPForm | Forces this DhForm to produce an HTML FORM or DIV section.
setSubmitMethod | Sets the method to use for submitting the form data.
setSubmitURL | Sets the URL to be called when the form's DhSubmit button is clicked.


 DhForm.add

DhForm.add

Adds an element into this container, following all other elements.

Syntax

public void add( DhElement element )

public void add( DhElement element, int insertFlag )

public void add( DhElement element, DhElement relativeTo, int insertFlag )

Parameters

element

The DhElement to add to the end of the flow of this container.

insertFlag

One of the valid and applicable DhInsertOptions insert constants. The valid values are:

  • END inserts at the end of the flow or into this container. The relativeTo parameter must be null if used.
  • BEGINNING inserts at the beginning of the flow or this container. The relativeTo parameter must be null if used.
  • BEFORE inserts before the element referred to by the relativeTo parameter. The relativeTo parameter must not be null.
  • AFTER insert after the element referred to by the relativeTo parameter. The relativeTo parameter must not be null.

relativeTo

The DhElement referred to when using the BEFORE or AFTER constants for the insertFlag parameter.

See Also remove


 DhForm.addOnChange

DhForm.addOnChange

Assigns a delegate to the change event.

Syntax

final public void addOnChange ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

This event occurs when the user modifies the form or moves the focus to a different window.

See Also removeOnChange


 DhForm.addOnFormReset

DhForm.addOnFormReset

Assigns a delegate to the formReset event.

Syntax

public void addOnFormReset( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The formReset event occurs when a reset button on the form is pressed.


 DhForm.addOnFormSubmit

DhForm.addOnFormSubmit

Assigns a delegate to the formSubmit event.

Syntax

public void addOnFormSubmit( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The formSubmit event occurs when a submit button on the form is pressed.

See Also removeOnFormSubmit


 DhForm.addOnGotFocus

DhForm.addOnGotFocus

Assigns a delegate to the gotFocus event.

Syntax

public final void addOnGotFocus ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when this element receives input focus.

See Also removeOnGotFocus


 DhForm.addOnLostFocus

DhForm.addOnLostFocus

Assigns a delegate to the lostFocus event.

Syntax

public final void addOnLostFocus ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when this element loses focus.

See Also removeLostFocus


 DhForm.addOnResize

DhForm.addOnResize

Assigns a delegate to the resize event.

Syntax

public final void addOnResize ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when this element is resized.

See Also removeOnResize


 DhForm.addOnScroll

DhForm.addOnScroll

Assigns a delegate to the scroll event.

Syntax

public final void addOnScroll ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when this element is scrolled.

See Also removeOnScroll


 DhForm.addOnSelect

DhForm.addOnSelect

Assigns a delegate to the select event.

Syntax

final public void addOnSelect ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

This event occurs when the user sets or modifies the selected region of the form.

See Also removeOnSelect


 DhForm.addText

DhForm.addText

Appends a text string to the current section.

Syntax

public void addText( String text )

Parameters

text

The text string to append.


 DhForm.DhForm

DhForm.DhForm

Creates a DhForm section container.

Syntax

public DhForm()


 DhForm.getAsHTTPForm

DhForm.getAsHTTPForm

Retrieves the current FORM/DIV state.

Syntax

public boolean getAsHTTPForm( )

Return Value

Returns true if set to FORM; returns false if set to DIV.

Remarks

The FORM state can be set by using setAsHTTPForm or adding a DhSubmitButton into the DhForm.

See Also setAsHTTPForm


 DhForm.getSubmitMethod

DhForm.getSubmitMethod

Retrieves the current HTTP submit method.

Syntax

public int getSubmitMethod()

Return Value

Returns the current HTTP submit method. This can be either METHOD_GET or METHOD_POST.

See Also setSubmitMethod


 DhForm.getSubmitURL

DhForm.getSubmitURL

Retrieves the current URL that will be called if the form's Submit button is clicked.

Syntax

public String getSubmitURL( )

Return Value

Returns the URL to be called when the form is submitted.

See Also setSubmitURL


 DhForm.moveElement

DhForm.moveElement

Moves an element to a new numeric order in the flow.

Syntax

public void moveElement( DhElement element, int newOrder )

Parameters

element

The DhElement to move.

newOrder

The new numeric order in the flow of this container.


 DhForm.newLine

DhForm.newLine

Appends a new line to the current section.

Syntax

public void newLine()

Remarks

All elements added after this call will be on a new line.


 DhForm.remove

DhForm.remove

Removes an element from this container.

Syntax

public int remove( DhElement element )

Parameters

element

The DhElement to remove from this container.

Return Value

Returns the original ordinal position of the removed element.

Exceptions

WFCInvalidArgumentException thrown if the element is not a child of this container.

Remarks

The element must be a direct child of this container. If you don't have the a direct handle to the parent of the element you want to remove, call the getParent method of element, and remove the element.

If the element was visible prior to this call, it will not be visible after the call.

See Also add


 DhForm.removeAll

DhForm.removeAll

Removes all child elements from this container.

Syntax

public void removeAll()

Remarks

These elements will no longer be visible if they were added prior to this call.


 DhForm.removeOnChange

DhForm.removeOnChange

Removes the delegate that is assigned to the change event.

Syntax

final public void removeOnChange ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The change event occurs when the user modifies the contents of the form and then presses the ENTER key or moves the focus to a different window or control.

See Also addOnChange


 DhForm.removeOnFormReset

DhForm.removeOnFormReset

Removes the delegate that is assigned to the formReset event.

Syntax

public void removeOnFormReset( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The formReset event occurs when a reset button on the form is pressed.


 DhForm.removeOnFormSubmit

DhForm.removeOnFormSubmit

Removes the delegate that is assigned to the formSubmit event.

Syntax

public void removeOnFormSubmit( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The formSubmit event occurs when a submit button on the form is pressed.

See Also addOnFormSubmit


 DhForm.removeOnGotFocus

DhForm.removeOnGotFocus

Removes the delegate that is assigned to the gotFocus event.

Syntax

public final void removeOnGotFocus ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The gotFocus event occurs when this container receives input focus.


 DhForm.removeOnLostFocus

DhForm.removeOnLostFocus

Removes the delegate that is assigned to the lostFocus event.

Syntax

public final void removeOnLostFocus ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The lostFocus event occurs when this container loses input focus.


 DhForm.removeOnResize

DhForm.removeOnResize

Removes the delegate that is assigned to the resize event.

Syntax

public final void removeOnResize ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The resize event occurs when this container is resized.

See Also addOnResize


 DhForm.removeOnScroll

DhForm.removeOnScroll

Removes the delegate that is assigned to the scroll event.

Syntax

final public void removeOnScroll ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The scroll event occurs when this element is scrolled.

See Also addOnScroll


 DhForm.removeOnSelect

DhForm.removeOnSelect

Removes the delegate that is assigned to the select event.

Syntax

final public void removeOnSelect ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The select event occurs when the user sets or modifies the selected region of the form.

See Also addOnSelect


 DhForm.setAsHTTPForm

DhForm.setAsHTTPForm

Forces this DhForm to produce an HTML FORM or DIV section.

Syntax

public void setAsHTTPForm( boolean fAsForm )

Parameters

fAsForm

Set to true to set the DhForm element as FORM; set to false to set the DhForm element as DIV.

See Also getAsHTTPForm


 DhForm.setSubmitMethod

DhForm.setSubmitMethod

Sets the method to use for submitting the form data.

Syntax

public void setSubmitMethod( int newMethod )

Parameters

newMethod

The new HTTP submit method. This can be either METHOD_GET or METHOD_POST.

Remarks

HTTP commands can be submitted to server as a POST, meaning no reply is expected after sending the data, or as a GET, meaning a reply is expected from the server. Most forms use GET. When a form is submitted as a GET, the submit string is appended to the URL and then opened as if the resulting string were a new anchor.

See Also getSubmitMethod


 DhForm.setSubmitURL

DhForm.setSubmitURL

Sets the URL to be called when the form's DhSubmit button is clicked.

Syntax

public void setSubmitURL( String strActionURL )

Parameters

strActionURL

The URL to be called when the submit button is clicked.

Remarks

Parameters from form fields are concatenated onto this URL.

See Also getSubmitURL


 DhForm Fields

DhForm Fields

Fields | Description
METHOD_GET | Indicates that the server is expected to respond after the form is submitted. This is used when the form contains a DhSubmitButton control.
METHOD_POST | Indicates that the server is not expected to respond after the form is submitted. This is used when the form contains a DhSubmitButton control.


 DhForm.METHOD_GET

DhForm.METHOD_GET

Indicates that the server is expected to respond after the form is submitted. This is used when the form contains a DhSubmitButton control.

Syntax

public static final int METHOD_GET;


 DhForm.METHOD_POST

DhForm.METHOD_POST

Indicates that the server is not expected to respond after the form is submitted. This is used when the form contains a DhSubmitButton control.

Syntax

public static final int METHOD_POST;


DhHorizontalRule Class

Represents an HTML horizontal rule (<HR>) element, which creates a horizontal divider bar on the page.

Component
  |
  +--DhStyleBase
    |
    +--DhElement
      |
      +--DhHorizontalRule

package com.ms.wfc.html

public class DhHorizontalRule
extends DhElement


 DhHorizontalRule Methods

DhHorizontalRule Methods

Constructors | Description
DhHorizontalRule | Creates a DhHorizontalRule object (a horizontal rule element).


 DhHorizontalRule.DhHorizontalRule

DhHorizontalRule.DhHorizontalRule

Creates a DhHorizontalRule object (a horizontal rule element).

Syntax

public DhHorizontalRule()


DhHotSpot Class

Implements an object that represents a hotspot in an image map.

Component
  |
  +--DhStyleBase
     |
     +--DhElement
        |
        +--DhHotSpot

package com.ms.wfc.html

public class DhHotSpot
extends DhElement

Remarks

A hotspot is an area within an image map that a user can click to jump to a URL. DhHotSpot objects are to be added to DhImage objects.


 DhHotSpot Methods

DhHotSpot Methods

Constructors | Description
DhHotSpot | Creates a DhHotSpot object.

Methods | Description
addOnGotFocus | Assigns a delegate to the gotFocus event.
addOnLostFocus | Assigns a delegate to the lostFocus event.
getAltText | Retrieves the current alternate text string that is displayed if the browser cannot display the image.
getCoordsIntArray | Retrieves an array of integers representing the current coordinate string.
getCoordsString | Retrieves the current coordinate string.
getShape | Retrieves the current shape constant.
getTargetWindow | Retrieves the target window for this hotspot.
getURL | Retrieves the URL to navigate to if the user selects this hotspot.
removeOnGotFocus | Removes the delegate that is assigned to the gotFocus event.
removeOnLostFocus | Removes the delegate that is assigned to the lostFocus event.
setAltText | Sets the alternate text for the hotspot if the browser cannot display the image.
setCoords | Sets the coordinate string for this DhHotSpot using an integer array, a string, or a rectangle.
setShape | Sets the shape of this hotspot.
setTargetWindow | Sets the target window for this hotspot.
setURL | Sets the URL for this DhHotSpot to navigate to when clicked.


 DhHotSpot.addOnGotFocus

DhHotSpot.addOnGotFocus

Assigns a delegate to the gotFocus event.

Syntax

public final void addOnGotFocus ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when this element receives input focus.

See Also removeOnGotFocus


 DhHotSpot.addOnLostFocus

DhHotSpot.addOnLostFocus

Assigns a delegate to the lostFocus event.

Syntax

public final void addOnLostFocus ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when this element loses focus.


 DhHotSpot.DhHotSpot

DhHotSpot.DhHotSpot

Creates a DhHotSpot object.

Syntax

public DhHotSpot()

public DhHotSpot( int nShape, int[] coords)

public DhHotSpot( int nShape, int[] coords, String strUrl )

public DhHotSpot( Rectangle r )

Parameters

nShape

The shape of the hotspot, which can be one of the constants defined in DhHotSpotShapes.

coords

An integer array containing coordinates appropriate to the shape.

strUrl

The Uniform Resource Locator (URL) to navigate to when the hotpot is clicked.

r

The Rectangle object containing the rectangle dimensions of the hotspot.

Remarks

The default constructor creates a DhHotSpot with a rectangle shape of 0 height and 0 width.


 DhHotSpot.getAltText

DhHotSpot.getAltText

Retrieves the current alternate text string that is displayed if the browser cannot display the image.

Syntax

public String getAltText()

Returns

Returns the HTML alternate text string.

See Also setAltText


 DhHotSpot.getCoordsIntArray

DhHotSpot.getCoordsIntArray

Retrieves an array of integers representing the current coordinate string.

Syntax

public Point[] getCoordsIntArray()

Return Value

Returns an array of integers.

See Also setCoords


 DhHotSpot.getCoordsString

DhHotSpot.getCoordsString

Retrieves the current coordinate string.

Syntax

public String getCoordsString()

Return Value

Returns a string containing the current coordinates.

See Also setCoords


 DhHotSpot.getShape

DhHotSpot.getShape

Retrieves the current shape constant.

Syntax

public int getShape()

Return Value

Returns the shape.

See Also setShape, DhHotSpotShapes


 DhHotSpot.getTargetWindow

DhHotSpot.getTargetWindow

Retrieves the target window for this hotspot.

Syntax

public String getTargetWindow()

Return Value

Returns the target window name.

See Also setTargetWindow


 DhHotSpot.getURL

DhHotSpot.getURL

Retrieves the URL to navigate to if the user selects this hotspot.

Syntax

public String getURL()

Return Value

Returns the current URL.


 DhHotSpot.removeOnGotFocus

DhHotSpot.removeOnGotFocus

Removes the delegate that is assigned to the gotFocus event.

Syntax

public final void removeOnGotFocus ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The gotFocus event occurs when this element receives input focus.

See Also addOnGotFocus


 DhHotSpot.removeOnLostFocus

DhHotSpot.removeOnLostFocus

Removes the delegate that is assigned to the lostFocus event.

Syntax

public final void removeOnLostFocus ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The lostFocus event occurs when this element loses input focus.

See Also addOnLostFocus


 DhHotSpot.setAltText

DhHotSpot.setAltText

Sets the alternate text for the hotspot if the browser cannot display the image.

Syntax

public void setAltText( String strAltText )

Parameters

strAltText

The new alternate text string.

See Also getAltText


 DhHotSpot.setCoords

DhHotSpot.setCoords

Sets the coordinate string for this DhHotSpot using an integer array, a string, or a rectangle.

Syntax

public void setCoords( int[] nCoordArray )

public void setCoords( String strCoords )

public void setCoords( Rectangle r )

Parameters

nCoordArray

An integer array containing the coordinates. For example, a four-sided shape has coordinates specified as top, left, width, and height (for example, {5,5,10,20}).

strCoords

A string of coordinates appropriate for this shape type. For example, a four-sided shape has coordinates specified as top, left, width, and height (for example, "5,5,10,20").

r

The Rectangle object containing the rectangle dimensions of the hotspot.

Exceptions

WFCException thrown if the coordinates do not match the current shape type.

See Also getCoordsString, getCoordsIntArray


 DhHotSpot.setShape

DhHotSpot.setShape

Sets the shape of this hotspot.

Syntax

public void setShape( int nShape )

Parameters

nShape

The new shape constant defined in DhHotSpotShapes.

See Also getShape


 DhHotSpot.setTargetWindow

DhHotSpot.setTargetWindow

Sets the target window for this hotspot.

Syntax

public void setTargetWindow( String strTargetWnd )

Parameters

strTargetWnd

The name of the new target window.

See Also getTargetWindow


 DhHotSpot.setURL

DhHotSpot.setURL

Sets the URL for this DhHotSpot to navigate to when clicked.

Syntax

public void setURL( String strUrl )

Parameters

strUrl

The URL for this DhHotSpot object.

See Also getURL


DhHotSpotShapes Class

Provides constants for DhHotspot shapes.

Enum
  |
  +--DhHotSpotShapes

package com.ms.wfc.html

public class DhHotSpotShapes
extends Enum


 DhHotSpotShapes Methods

DhHotSpotShapes Methods

Methods | Description
valid | Determines whether a specified value is valid for this enumeration type.


 DhHotSpotShapes.valid

DhHotSpotShapes.valid

Determines whether a specified value is valid for this enumeration type.

Syntax

public static boolean valid( int n )

Parameters

n

The value to check.

Return Value

Returns true if the value is valid for this class; otherwise, returns false.

Remarks

You should override this method in your own enumeration classes.


 DhHotSpotShapes Fields

DhHotSpotShapes Fields

Fields | Description
CIRCLE | Specifies that the hotspot has a circular shape.
POLYGON | Specifies that the hotspot has a polygon shape.
RECTANGLE | Specifies that the hotspot has a rectangular shape.


 DhHotSpotShapes.CIRCLE

DhHotSpotShapes.CIRCLE

Specifies that the hotspot has a circular shape.

Syntax

public static final int CIRCLE;

Remarks

Coordinates are specified as "center x, center y, radius"; for example, the following coordinates create a circle with a center at x=12, y=19 and a radius of 7.

setCoords(new int[] {12, 19, 7})


 DhHotSpotShapes.POLYGON

DhHotSpotShapes.POLYGON

Specifies that the hotspot has a polygon shape.

Syntax

public static final int POLYGON;

Remarks

Coordinates are specified as three or more coordinate pairs; for example, the following coordinates create a triangle.

setCoords(new int[] {10,10,15,15,5,15})


 DhHotSpotShapes.RECTANGLE

DhHotSpotShapes.RECTANGLE

Specifies that the hotspot has a rectangular shape.

Syntax

public static final int RECTANGLE;

Remarks

Coordinates are specified as "top, left, width, and height"; for example, the following coordinates create a rectangle.

setCoords(new int[] {5,5,10,20})


DhHTMLGenerator Class

Represents a base class for Hypertext Markup Language (HTML) generation.

package com.ms.wfc.html

public class DhHTMLGenerator

Remarks

Override this class to create alternate HTML generations from the package. Call DhElement.setHTMLGenerator with an instance of your override to enable. On each tag, style, and attribute, the appropriate function is called, and you can manipulate the element in any way you choose.

The following is an example of a simple alternate generator that maps some cascading style sheet styles to format tags and changes any <DIV> tags to <P> tags:

public class MyHTMLGenerator {
    public final static STYLE_FONT_WEIGHT = 0;
    public final static STYLE_FONT_STYLE = 1;
    public final static TAG_DIV = 2;

    public MyHTMLGenerator(){
       registerName("font-weight", STYLE_FONT_WEIGHT );
       registerName("font-style", STYLE_FONT_STYLE );
       registerName( "DIV",TAG_DIV );
    }

    // Override this method to replace tags.
    public boolean onTagGenerate( int key, String strTagName ){
       switch ( key ){
          case TAG_DIV:
             setTagName( "P" );
             // Return false to cancel the default behavior.
             return false;
             break;
          }
        // Return true to proceed with the default behavior.
        return true;
    }

    // Override this method to manipulate style output.
    public boolean onStyleGenerate( int key, String styleName, String styleValue ){
       switch ( key ){
          case STYLE_FONT_WEIGHT:
             if ( styleValue.indexOf( "BOLD" ) != -1 ){
                addEnclosingTag( "B", null, true );
                return false;
             }
             break;
          case STYLE_FONT_STYLE:
             if ( styleValue.equalsIgnoreCase( "ITALIC" ) ){
                addEnclosingTag( "I", null, true );
                return false;
             }
             break;
       }
       return true;
    }
}


 DhHTMLGenerator Methods

DhHTMLGenerator Methods

Methods | Description
addAttrString | Adds an attribute inside the current tag's less-than (<) and greater-than (>) characters.
addEnclosingTag | Adds an enclosing tag around the current tag.
addInnerTag | Adds an inner tag inside the current tag, but encloses its contents.
addStyleString | Adds an attribute inside the current tag's STYLE attribute.
generateHTML | Generates browser-targeted HTML for the specified DhElement.
getAttributeValue | Retrieves the value of a specified attribute.
getContent | Retrieves the current content string, which is the string between the HTML start and end tags.
getNameKey | Retrieves the integer key associated with the specified name.
getStyleValue | Retrieves the value of a specified style.
getSupportsCSS | Retrieves target's ability to support cascading style sheets.
getSupportsOM | Retrieves the target's ability to support the Document Object Model.
getTagName | Retreives the tag name for the current generation.
onAttrGenerate | Invokes a callback for each attribute.
onStyleGenerate | Invokes a callback for each style-attribute pair.
onTagGenerate | Invokes a callback with the default name for the current tag.
registerName | Associates an integer value with a style or attribute name or tag.
setContent | Replaces the current content, destroying any existing content.
setFormatItems | Sets the delimiter items.
setSupportsCSS | Specifies whether the target browser supports style sheets.
setSupportsOM | Specifies whether the target browser supports an object model.
setTagName | Replaces the current tag name with the new value.


 DhHTMLGenerator.addAttrString

DhHTMLGenerator.addAttrString

Adds an attribute inside the current tag's less-than (<) and greater-than (>) characters.

Syntax

protected final void addAttrString( String strAttr, String strValue )

Parameters

strAttr

The name of the attribute to add.

strValue

The string value of the new attribute.


 DhHTMLGenerator.addEnclosingTag

DhHTMLGenerator.addEnclosingTag

Adds an enclosing tag around the current tag.

Syntax

protected final void addEnclosingTag( String strTag, String strAttrs, boolean fClose )

Parameters

strTag

The new enclosing tag name.

strAttrs

The new enclosing tag's attribute string or strings.

fClose

Set to true to additionally add the closing tag for this tag.

Remarks

This tag also encloses any existing enclosing tags.

As an example of using this method, supposed you have the following as HTML content:

<SPAN id=span1>Hello!</SPAN>

After calling addEnclosingTag( "B", "id=theBold", true ), the HTML appears as follows:

<B id=theBold><SPAN id=span1>Hello!</SPAN></B>


 DhHTMLGenerator.addInnerTag

DhHTMLGenerator.addInnerTag

Adds an inner tag inside the current tag, but encloses its contents.

Syntax

protected final void addInnerTag( String strTag, String strAttrs, boolean fClose )

Parameters

strTag

The new inner tag name.

strAttrs

The new inner tag's attribute string(s).

fClose

Set to true to also add the closing tag for this tag; otherwise, set to false.

Remarks

This tag appears between the contents and any existing inner tags.

For example, consider the following original HTML:

<SPAN id=span1>Hello!</SPAN>

After calling addInnerTag( "B", "id=theBold", true ), the HTML appears as follows:

<SPAN id=span1><B id=theBold>Hello!</B></SPAN>


 DhHTMLGenerator.addStyleString

DhHTMLGenerator.addStyleString

Adds an attribute inside the current tag's STYLE attribute.

Syntax

protected final void addStyleString( String strStyle, String strValue )

Parameters

strStyle

The name of the style to add.

strValue

The string value of the new style.

Remarks

These styles are added only if supportsCSS is true.

See Also getSupportsCSS, setSupportsCSS


 DhHTMLGenerator.generateHTML

DhHTMLGenerator.generateHTML

Generates browser-targeted HTML for the specified DhElement.

Syntax

public StringBuffer generateHTML( DhElement e )

Parameters

e

The DhElement to generate code for based on this DhHTMLGenerator object.

Return Value

Returns a StringBuffer with the generated HTML.


 DhHTMLGenerator.getAttributeValue

DhHTMLGenerator.getAttributeValue

Retrieves the value of a specified attribute.

Syntax

protected final String getAttributeValue( String strAttrName )

Parameters

strAttrName

The name of the attribute.

Return Value

Returns the value of the attribute, or returns null if it is not present.


 DhHTMLGenerator.getContent

DhHTMLGenerator.getContent

Retrieves the current content string, which is the string between the HTML start and end tags.

Syntax

protected final String getContent()

Return Value

Returns the current content string.

See Also setContent


 DhHTMLGenerator.getNameKey

DhHTMLGenerator.getNameKey

Retrieves the integer key associated with the specified name.

Syntax

protected int getNameKey( String strName )

Parameters

strName

The name of the tag, attribute, or style to retrieve a key for.

Return Value

Returns the key for the name, or returns UNKNOWN_KEY if it is not present.

Remarks

This function is not case sensitive.

See Also registerName, UNKNOWN_KEY


 DhHTMLGenerator.getStyleValue

DhHTMLGenerator.getStyleValue

Retrieves the value of a specified style.

Syntax

protected final String getStyleValue( String strStyleName )

Parameters

strStyleName

The name of the style.

Return Value

Returns the value of the style, or returns null if it is not present.


 DhHTMLGenerator.getSupportsCSS

DhHTMLGenerator.getSupportsCSS

Retrieves target's ability to support cascading style sheets.

Syntax

public final boolean getSupportsCSS()

Return Value

Returns true if cascading style sheets are supported.

See Also setSupportsCSS


 DhHTMLGenerator.getSupportsOM

DhHTMLGenerator.getSupportsOM

Retrieves the target's ability to support the Document Object Model.

Syntax

public final boolean getSupportsOM()

Return Value

Returns true if the Document Object Model is supported (currently Microsoft Internet Explorer version 4.0 or later only).

See Also setSupportsOM


 DhHTMLGenerator.getTagName

DhHTMLGenerator.getTagName

Retreives the tag name for the current generation.

Syntax

protected final String getTagName()

Return Value

Returns the current tag name string.

See Also setTagName


 DhHTMLGenerator.onAttrGenerate

DhHTMLGenerator.onAttrGenerate

Invokes a callback for each attribute.

Syntax

public boolean onAttrGenerate( String strName, String strValue )

public boolean onAttrGenerate( int key, String strName, String strValue )

Parameters

key

The key for this style, if registered; otherwise, -1.

strName

The default name of the attribute.

strValue

The default value for the attribute.

Return Value

Returns true to generate the default tag, or returns false to skip it.

Remarks

You can perform any desired additions or manipulations for the specified attribute. The following is an example of moving WIDTH attribute into style text:

if ( strName.equalsIgnoreCase( "WIDTH" ) ){
    addStyleString( "width", strValue );
 return false;
}

See Also addEnclosingTag, addInnerTag, addStyleString, addAttrString


 DhHTMLGenerator.onStyleGenerate

DhHTMLGenerator.onStyleGenerate

Invokes a callback for each style-attribute pair.

Syntax

public boolean onStyleGenerate( int key, String strName, String strValue )

public boolean onStyleGenerate( String strName, String strValue )

Parameters

key

The key for this style, if registered; otherwise, -1.

strName

The default name of the attribute.

strValue

The default value for the attribute.

Return Value

Returns true to generate the default tag, or returns false to skip it.

Remarks

Override this method to perform any desired additions or manipulations for the specified style. The following is an example of code that is not compatible with the cascading style sheet for font color:

if ( strName.equalsIgnoreCase( "color" ) ){
  addEnclosingTag( "FONT", "COLOR=" + strValue );
  return false;
}

See Also addEnclosingTag, addInnerTag, addStyleString, addAttrString


 DhHTMLGenerator.onTagGenerate

DhHTMLGenerator.onTagGenerate

Invokes a callback with the default name for the current tag.

Syntax

public boolean onTagGenerate( int key, String strTagName )

public boolean onTagGenerate( String strTagName )

Parameters

key

The key for this tag, if registered; otherwise, -1.

strTagName

The default name for the current tag.

Return Value

Returns true to use the default tag.

Remarks

You can perform any desired operations within your override. The following is an example of replacing <STRONG> with <BOLD>:

if ( strTagName.equalsIgnoreCase( "STRONG" ) ){
  setTagName( "BOLD" );
  return false;
}

See Also setTagName, getTagName


 DhHTMLGenerator.registerName

DhHTMLGenerator.registerName

Associates an integer value with a style or attribute name or tag.

Syntax

protected boolean registerName( String strName, int key )

Parameters

strName

The tag, attribute name, or style name.

key

The key you want to associate with that value. It cannot be -1 because this is what is passed to these functions when the key is not registered.

Return Value

Returns true if the name was successfully registered, or returns false if -1 is used or the key is already assigned to another name.

Remarks

If registered, you will receive this value with the name in calls to onTagGenerate, onAttrGenerate, and onStyleGenerate. Registering a key allows you to avoid string comparison in your handler functions.

The following is an example of this method:

 public class MyHTMLGenerator{
     public final static TAG_BR = 0;
     public final static TAG_DIV = 1;
     public MyHTMLGenerator(){
        registerName( "BR", TAG_BR );
        registerName( "DIV", TAG_DIV );
     }

    // ...

    public boolean onTagGenerate( int key, String strTagName ){
        switch ( key ){
           case TAG_BR:
           case TAG_DIV:
              setTagName( "P" );
              return false;
              break;
        }
        return true;
     }
}


 DhHTMLGenerator.setContent

DhHTMLGenerator.setContent

Replaces the current content, destroying any existing content.

Syntax

protected final void setContent( String strNewContent )

Parameters

strNewContent

The new content string.

See Also getContent


 DhHTMLGenerator.setFormatItems

DhHTMLGenerator.setFormatItems

Sets the delimiter items.

Syntax

public final void setFormatItems( char cAttrAssign, char cAttrSeparator, char cAttrQuote, char cStyleAssign, char cStyleSeparator, char cStyleQuote )

Parameters

cAttrAssign

Assignment character for attributes (default is '=').

cAttrSeparator

Separator character between attributes (default is ' ').

cAttrQuote

Delimiter to place around attribute values (default is '"').

cStyleAssign

Assignment character for styles (default is ':').

cStyleSeparator

Separator character between styles (default is ';').

cStyleQuote

Delimiter to place around style values (default is "'").


 DhHTMLGenerator.setSupportsCSS

DhHTMLGenerator.setSupportsCSS

Specifies whether the target browser supports style sheets.

Syntax

public final void setSupportsCSS( boolean supportsCSS )

Parameters

supportsCSS

Set to true if the target supports the style sheets; otherwise, set to false.

Remarks

The default is false.

See Also getSupportsCSS


 DhHTMLGenerator.setSupportsOM

DhHTMLGenerator.setSupportsOM

Specifies whether the target browser supports an object model.

Syntax

public final void setSupportsOM( boolean supportsOM )

Parameters

supportsCSS

Set to true if the target supports the Document Object Model; otherwise, set to false.

Remarks

The default is false.

See Also getSupportsOM


 DhHTMLGenerator.setTagName

DhHTMLGenerator.setTagName

Replaces the current tag name with the new value.

Syntax

protected final void setTagName( String strNewName )

Parameters

strNewName

The replacement tag name, which can be null.


 DhHTMLGenerator Fields

DhHTMLGenerator Fields

Fields | Description
UNKNOWN_KEY | This value is returned by getNameKey if the name is not registered.


 DhHTMLGenerator.UNKNOWN_KEY

DhHTMLGenerator.UNKNOWN_KEY

This value is returned by getNameKey if the name is not registered.

Syntax

public static final int UNKNOWN_KEY;


DhHyperlink Class

Creates a jump in the document to a bookmark or element in the current document or to a different document.

Component
  |
  +--DhStyleBase
    |
    +--DhElement
      |
      +--DhBaseContainer
        |
        +--DhForm
          |
          +--DhHyperlink

package com.ms.wfc.html

public class DhHyperlink
extends DhForm

Remarks

The following simple example shows how to create a hyperlink to another URL.

public class Class1 extends DhDocument
{
   protected void initForm()
   {
     DhHyperlink h;
     this.add(new DhText("This is a link to the "));
     this.add(h = new DhHyperlink("http://www.microsoft.com/visualj","Visual J++"));
     this.add(new DhText(" Web site."));
   }
}

To link to a bookmark on the current page, use the setJumpPoint method and pass it the DhElement associated with the element to jump to, as shown in the following sample:

public class Class1 extends DhDocument
{
   protected void initForm()
   {
      DhHyperlink h;
      add(h = new DhHyperlink(null, "click me"));
      DhText t;
      for (int i = 0; i < 100; i++) newLine();
      add(t=new DhText("jump here"));
      h.setJumpPoint(t);
   }
}


 DhHyperlink Methods

DhHyperlink Methods

Constructors | Description
DhHyperlink | Creates a DhHyperlink object.

Methods | Description
getEnabled | Retrieves the enabled state of the hyperlink.
getJumpPoint | Returns the local target of the jump.
getStockTargetWindow | Returns the window identifier where the browser will put the document when it is jumped to.
getTargetWindow | Retrieves the name of the window where the browser will put the document when it is jumped to.
getText | Retrieves the hyperlink text.
getURL | Retrieves the target URL for the hyperlink.
setEnabled | Sets the enabled state of the hyperlink.
setJumpPoint | Sets the destination of this hyperlink to be some element on the current page.
setStockTargetWindow | Determines the window, by identifier, that the browser will put the document into.
setTargetWindow | Determines the window, by name, that the browser will put the document into.
setText | Sets the text the user sees in the hyperlink.
setURL | Sets the pointer to the document.


 DhHyperlink.DhHyperlink

DhHyperlink.DhHyperlink

Creates a DhHyperlink object.

Syntax

public DhHyperlink()

public DhHyperlink( String url, String text )

Parameters

url

The URL of the document or anchor in the current document to link to.

text

The text that the user sees as the hyperlink.

See Also setURL, setJumpPoint, setText


 DhHyperlink.getEnabled

DhHyperlink.getEnabled

Retrieves the enabled state of the hyperlink.

Syntax

public final boolean getEnabled()

Return Value

Returns true if the hyperlink is enabled; otherwise, returns false.

See Also setEnabled


 DhHyperlink.getJumpPoint

DhHyperlink.getJumpPoint

Returns the local target of the jump.

Syntax

public final DhElement getJumpPoint()

See Also setJumpPoint


 DhHyperlink.getStockTargetWindow

DhHyperlink.getStockTargetWindow

Returns the window identifier where the browser will put the document when it is jumped to.

Syntax

public final int getStockTargetWindow()

Return Value

Returns one of the stock window identifiers in DhLinkTarget.

See Also setStockTargetWindow, getTargetWindow


 DhHyperlink.getTargetWindow

DhHyperlink.getTargetWindow

Retrieves the name of the window where the browser will put the document when it is jumped to.

Syntax

public final String getTargetWindow()

Return Value

Returns the target window.

See Also setStockTargetWindow, getStockTargetWindow


 DhHyperlink.getText

DhHyperlink.getText

Retrieves the hyperlink text.

Syntax

public final String getText()

Return Value

Returns the text that is displayed in the hyperlink.

See Also setText


 DhHyperlink.getURL

DhHyperlink.getURL

Retrieves the target URL for the hyperlink.

Syntax

public final String getURL()

Return Value

Returns the current URL of the hyperlink.

See Also setURL


 DhHyperlink.setEnabled

DhHyperlink.setEnabled

Sets the enabled state of the hyperlink.

Syntax

public final void setEnabled( boolean f )

Parameters

f

Set to true to enable the hyperlink; set to false to disable it.

See Also getEnabled


 DhHyperlink.setJumpPoint

DhHyperlink.setJumpPoint

Sets the destination of this hyperlink to be some element on the current page.

Syntax

public final void setJumpPoint( DhElement target )

Parameters

target

The local element that users will jump to after clicking this hyperlink.

See Also setJumpPoint


 DhHyperlink.setStockTargetWindow

DhHyperlink.setStockTargetWindow

Determines the window, by identifier, that the browser will put the document into.

Syntax

public final void setStockTargetWindow( int targetID )

Parameters

targetID

One of the stock window identifiers in DhLinkTarget.

See Also setTargetWindow, getStockTargetWindow


 DhHyperlink.setTargetWindow

DhHyperlink.setTargetWindow

Determines the window, by name, that the browser will put the document into.

Syntax

public final void setTargetWindow( String winName )

Parameters

winName

The name of a window in a frameset.

See Also setStockTargetWindow, getTargetWindow


 DhHyperlink.setText

DhHyperlink.setText

Sets the text the user sees in the hyperlink.

Syntax

public final void setText( String text )

Parameters

text

The string displayed to the user.

See Also getText


 DhHyperlink.setURL

DhHyperlink.setURL

Sets the pointer to the document.

Syntax

public final void setURL( String url )

Parameters

url

The URL of a document.

See Also getURL


DhImage Class

Implements an image object that displays a bitmap file in the document.

Component
  |
  +--DhStyleBase
    |
    +--DhElement
      |
      +--DhImage

package com.ms.wfc.html

public class DhImage
extends DhElement

Remarks

To create a DhImage object on your page, use setURL to specify the URL of the image to display.


 DhImage Methods

DhImage Methods

Constructors | Description
DhImage | Creates a DhImage object.

Methods | Description
addHotSpot | Adds a DhHotSpot object to this image.
addOnAbort | Assigns a delegate to the abort event.
addOnError | Assigns a delegate to the error event.
addOnGotFocus | Assigns a delegate to the gotFocus event.
addOnLoad | Assigns a delegate to the load event.
addOnLostFocus | Assigns a delegate to the lostFocus event.
addOnReadyStateChange | Assigns a delegate to the readyStateChange event.
getHotSpots | Retrieves an array of the DhHotSpot objects contained in this image.
getLoadComplete | Determines whether the image has been fully loaded.
getReadyState | Returns the current state of the image object.
getSize | Retrieves the size of the displayed image.
getURL | Retrieves the current URL that refers to the location of the image file.
removeHotSpot | Removes the specified DhHotSpot from the image.
removeOnAbort | Removes the delegate that is assigned to the abort event.
removeOnError | Removes the delegate that is assigned to the error event.
removeOnGotFocus | Removes the delegate that is assigned to the gotFocus event.
removeOnLoad | Removes the delegate that is assigned to the load event.
removeOnLostFocus | Removes the delegate that is assigned to the lostFocus event.
removeOnReadyStateChange | Removes the delegate that is assigned to the readyStateChange event.
setURL | Sets the URL of the image file.


 DhImage.addHotSpot

DhImage.addHotSpot

Adds a DhHotSpot object to this image.

Syntax

final public void addHotSpot( DhHotSpot hs )

final public void addHotSpot( int nShape, int[] coords, String strUrl )

final public void addHotSpot( int nShape, int[] coords, EventHandler h )

Parameters

hs

The new DhHotSpot to add to this image.

nShape

The shape of the hotspot as a constant from DhHotSpotShapes.

coords

An integer array containing coordinates appropriate to the shape specified in nShape. For details, see DhHotSpot.

strUrl

The String Uniform Resource Locator (URL) to navigate to when the hotspot is clicked.

h

The EventHandler to trigger when the hotspot is clicked.

See Also removeHotSpot


 DhImage.addOnAbort

DhImage.addOnAbort

Assigns a delegate to the abort event.

Syntax

final public void addOnAbort ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The abort event is triggered when the user aborts loading an image.

See Also removeOnAbort


 DhImage.addOnError

DhImage.addOnError

Assigns a delegate to the error event.

Syntax

public final void addOnError( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

This event occurs when an error occurs.

See Also removeOnError


 DhImage.addOnGotFocus

DhImage.addOnGotFocus

Assigns a delegate to the gotFocus event.

Syntax

public final void addOnGotFocus ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when this element receives input focus.

See Also removeOnGotFocus


 DhImage.addOnLoad

DhImage.addOnLoad

Assigns a delegate to the load event.

Syntax

final public void addOnLoad ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when the image completes loading.

See Also removeOnAbort


 DhImage.addOnLostFocus

DhImage.addOnLostFocus

Assigns a delegate to the lostFocus event.

Syntax

public final void addOnLostFocus ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when this element loses focus.

See Also removeOnLostFocus


 DhImage.addOnReadyStateChange

DhImage.addOnReadyStateChange

Assigns a delegate to the readyStateChange event.

Syntax

final public void addOnReadyStateChange ( ReadyStateEventHandler h )

Parameters

h

The ReadyStateEventHandler delegate to be notified when the event occurs.

See Also removeOnReadStateChange


 DhImage.DhImage

DhImage.DhImage

Creates a DhImage object.

Syntax

public DhImage()

public DhImage( String url )

Parameters

url

The URL that refers to the image file to display. The URL can be relative to the HTML document.


 DhImage.getHotSpots

DhImage.getHotSpots

Retrieves an array of the DhHotSpot objects contained in this image.

Syntax

public DhHotSpot[] getHotSpots()

Return Value

Returns the DhHotSpot array.


 DhImage.getLoadComplete

DhImage.getLoadComplete

Determines whether the image has been fully loaded.

Syntax

final public boolean getLoadComplete()

Return Value

Returns true if loading of the image is complete; otherwise, returns false.

See Also addOnReadyStateChange, getReadyState, addOnLoad


 DhImage.getReadyState

DhImage.getReadyState

Returns the current state of the image object.

Syntax

final public String getReadyState()

Return Value

Returns the current state. Possible return string values include:

  • "uninitialized", indicating the object is not initialized with data.
  • "loading", indicating the object is currently loading its data.
  • "interactive", indicating the object can be interacted with even though it is not fully loaded.
  • "complete", indicating the image is completely loaded.


 DhImage.getSize

DhImage.getSize

Retrieves the size of the displayed image.

Syntax

final public Point getSize()

Return Value

If the image is an active document in the browser, its actual size (as specified by setSize) is returned.

Exceptions

WFCException thrown if the image is not available (typically because it is still loading).

Overrides DhElement.getSize


 DhImage.getURL

DhImage.getURL

Retrieves the current URL that refers to the location of the image file.

Syntax

final public String getURL()

Return Value

Returns the URL that refers to the image file to display.

See Also setUrl


 DhImage.removeHotSpot

DhImage.removeHotSpot

Removes the specified DhHotSpot from the image.

Syntax

final public void removeHotSpot( DhHotSpot hs )

Parameters

hs

The DhHotSpot to remove.


 DhImage.removeOnAbort

DhImage.removeOnAbort

Removes the delegate that is assigned to the abort event.

Syntax

final public void removeOnAbort ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The abort event is triggered when the user aborts loading an image.

See Also addOnAbort


 DhImage.removeOnError

DhImage.removeOnError

Removes the delegate that is assigned to the error event.

Syntax

public final void removeOnError( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

See Also addOnError


 DhImage.removeOnGotFocus

DhImage.removeOnGotFocus

Removes the delegate that is assigned to the gotFocus event.

Syntax

public final void removeOnGotFocus ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The gotFocus event occurs when this element receives input focus.

See Also addOnGotFocus


 DhImage.removeOnLoad

DhImage.removeOnLoad

Removes the delegate that is assigned to the load event.

Syntax

public final void removeOnLoad ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The load event occurs when the image finishes loading.


 DhImage.removeOnLostFocus

DhImage.removeOnLostFocus

Removes the delegate that is assigned to the lostFocus event.

Syntax

public final void removeOnLostFocus ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The lostFocus event occurs when this element loses input focus.

See Also addOnLostFocus


 DhImage.removeOnReadyStateChange

DhImage.removeOnReadyStateChange

Removes the delegate that is assigned to the readyStateChange event.

Syntax

final public void removeOnReadyStateChange ( ReadyStateEventHandler h )

Parameters

h

The ReadyStateEventHandler delegate that is to be removed.

See Also addOnReadyStateChange


 DhImage.setURL

DhImage.setURL

Sets the URL of the image file.

Syntax

final public void setURL( String url )

Parameters

url

The URL that refers to the bitmap file to display. The URL can be relative to the HTML document.

See Also getURL


DhInlineFrame Class

Represents an inline frame (<IFRAME>) element.

Component
  |
  +--DhStyleBase
     |
     +--DhElement
        |
        +--DhInlineFrame

package com.ms.wfc.html

public class DhInlineFrame
extends DhElement


 DhInlineFrame Methods

DhInlineFrame Methods

Constructors | Description
DhInlineFrame | Creates a frame.

Methods | Description
addOnDocumentReady | Assigns a delegate to the documentReady event.
addOnGotFocus | Assigns a delegate to the gotFocus event.
addOnLostFocus | Assigns a delegate to the lostFocus event.
addOnResize | Assigns a delegate to the resize event.
getFrameDocument | Retrieves the current document in the frame.
getScroll | Retrieves the current scrolling mode.
getURL | Retrieves the Uniform Resource Locator (URL) that defines the location of the contents of this frame.
removeOnDocumentReady | Removes the delegate that is assigned to the documentReady event.
removeOnGotFocus | Removes the delegate that is assigned to the gotFocus event.
removeOnLostFocus | Removes the delegate that is assigned to the lostFocus event.
removeOnResize | Removes the delegate that is assigned to the resize event.
setScroll | Sets the current scroll mode.
setURL | Sets the URL that defines the location of the contents of this frame.


 DhInlineFrame.addOnDocumentReady

DhInlineFrame.addOnDocumentReady

Assigns a delegate to the documentReady event.

Syntax

public final void addOnDocumentReady( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The event handler specifies a method that is called whenever the IFRAME document is ready to be accessed.

See Also removeOnDocumentReady


 DhInlineFrame.addOnGotFocus

DhInlineFrame.addOnGotFocus

Assigns a delegate to the gotFocus event.

Syntax

public final void addOnGotFocus ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when this element receives input focus.

See Also removeOnGotFocus


 DhInlineFrame.addOnLostFocus

DhInlineFrame.addOnLostFocus

Assigns a delegate to the lostFocus event.

Syntax

public final void addOnLostFocus ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when this element loses focus.


 DhInlineFrame.addOnResize

DhInlineFrame.addOnResize

Assigns a delegate to the resize event.

Syntax

public final void addOnResize ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when the frame is resized.

See Also removeOnResize


 DhInlineFrame.DhInlineFrame

DhInlineFrame.DhInlineFrame

Creates a frame.

Syntax

public DhInlineFrame()

public DhInlineFrame( String url )

Parameters

url

The source of the frame.

Remarks

The default constructor creates an empty frame.


 DhInlineFrame.getFrameDocument

DhInlineFrame.getFrameDocument

Retrieves the current document in the frame.

Syntax

public DhDocument getFrameDocument()

Return Value

The DhDocument object associated with this frame.

Remarks

This method may return null if it is not possible to access the document in the frame. Documents that are open on a different server from the enclosing page can generally not be accessed because of browser security restrictions.


 DhInlineFrame.getScroll

DhInlineFrame.getScroll

Retrieves the current scrolling mode.

Syntax

public int getScroll()

Return Value

Returns the current scrolling mode. This can be:

  • DhScrollBars.AUTO, indicating that the browser determines scrolling.
  • DhScrollBars.YES, indicating that scrolling is enabled.
  • DhScrollBars.NO, indicating that scrolling is disabled.

See Also DhScrollBars, setScroll


 DhInlineFrame.getURL

DhInlineFrame.getURL

Retrieves the Uniform Resource Locator (URL) that defines the location of the contents of this frame.

Syntax

public String getURL()

Return Value

Returns the location of the URL for this frame.

See Also setURL


 DhInlineFrame.removeOnDocumentReady

DhInlineFrame.removeOnDocumentReady

Removes the delegate that is assigned to the documentReady event.

Syntax

public final void removeOnDocumentReady( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The event handler specifies a method that is called whenever the IFRAME document is ready to be accessed.

See Also addOnDocumentReady


 DhInlineFrame.removeOnGotFocus

DhInlineFrame.removeOnGotFocus

Removes the delegate that is assigned to the gotFocus event.

Syntax

public final void removeOnGotFocus ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The gotFocus event occurs when this element receives input focus.

See Also addOnGotFocus


 DhInlineFrame.removeOnLostFocus

DhInlineFrame.removeOnLostFocus

Removes the delegate that is assigned to the lostFocus event.

Syntax

public final void removeOnLostFocus ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The lostFocus event occurs when this element loses input focus.

See Also addOnLostFocus


 DhInlineFrame.removeOnResize

DhInlineFrame.removeOnResize

Removes the delegate that is assigned to the resize event.

Syntax

public final void removeOnResize ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The resize event occurs when this container is resized.

See Also addOnResize


 DhInlineFrame.setScroll

DhInlineFrame.setScroll

Sets the current scroll mode.

Syntax

public void setScroll( int scrollMode )

Parameters

scrollMode

The desired scrolling mode. This can be:

  • DhScrollBars.AUTO, indicating that the browser determines scrolling.
  • DhScrollBars.YES, indicating that scrolling is enabled.
  • DhScrollBars.NO, indicating that scrolling is disabled.

See Also DhScrollBars, getScroll


 DhInlineFrame.setURL

DhInlineFrame.setURL

Sets the URL that defines the location of the contents of this frame.

Syntax

public void setURL( String url )

Parameters

url

The location URL of the frame.

See Also getURL


DhInsertOptions Class

Provides constants for inserting DhElement items into containers.

Enum
  |
  +--DhInsertOptions

package com.ms.wfc.html

public class DhInsertOptions
extends Enum

Remarks

This class is used by the DhDocument.add, DhForm.add, and DhTable.add methods.


 DhInsertOptions Methods

DhInsertOptions Methods

Methods | Description
valid | Determines whether a specified value is valid for this enumeration type.


 DhInsertOptions.valid

DhInsertOptions.valid

Determines whether a specified value is valid for this enumeration type.

Syntax

public static boolean valid( int n )

Parameters

n

The value to check.

Return Value

Returns true if the value is valid for this class; otherwise, returns false.

Remarks

You should override this method in your own enumeration classes.


 DhInsertOptions Fields

DhInsertOptions Fields

Fields | Description
AFTER | Specifies that the item is inserted after the designated item in the list.
BEFORE | Specifies that the item is inserted before the designated item in the list.
BEGINNING | Specifies that the item is inserted at the beginning of the current list.
END | Specifies that the item is inserted at the end of the current list.


 DhInsertOptions.AFTER

DhInsertOptions.AFTER

Specifies that the item is inserted after the designated item in the list.

Syntax

public static final int AFTER;


 DhInsertOptions.BEFORE

DhInsertOptions.BEFORE

Specifies that the item is inserted before the designated item in the list.

Syntax

public static final int BEFORE;


 DhInsertOptions.BEGINNING

DhInsertOptions.BEGINNING

Specifies that the item is inserted at the beginning of the current list.

Syntax

public static final int BEGINNING;


 DhInsertOptions.END

DhInsertOptions.END

Specifies that the item is inserted at the end of the current list.

Syntax

public static final int END;


DhJumpPoint Class

Represents a bookmark within a document.

Component
  |
  +--DhStyleBase
     |
     +--DhElement
        |
        +--DhJumpPoint

package com.ms.wfc.html

public class DhJumpPoint
extends DhElement

Remarks

A jump point, or bookmark, is the HTML anchor tag with a NAME attribute (<A NAME=...>).


 DhJumpPoint Methods

DhJumpPoint Methods

Constructors | Description
DhJumpPoint | Creates a DhJumpPoint object.

Methods | Description
getName | Retrieves the current jump point name.
setName | Sets the jump point name.


 DhJumpPoint.DhJumpPoint

DhJumpPoint.DhJumpPoint

Creates a DhJumpPoint object.

Syntax

public DhJumpPoint() public DhJumpPoint( String name )

Parameters

name

The name of the jump point. This is the text that is assigned to a NAME attribute in HTML. For example, if name is "anchor2", the corresponding HTML anchor tag would be <A NAME="anchor2"></A>


 DhJumpPoint.getName

DhJumpPoint.getName

Retrieves the current jump point name.

Syntax

public String getName()

Return Value

Returns the name, or returns a null string if one does not exist. This is the text that is assigned to a NAME attribute in HTML. For example, if "anchor2" is returned, the corresponding HTML anchor tag would be <A NAME="anchor2"></A>

See Also setName


 DhJumpPoint.setName

DhJumpPoint.setName

Sets the jump point name.

Syntax

public void setName( String n )

Parameters

n

The new jump point name. This is the text that is assigned to a NAME attribute in HTML. For example, if n is "anchor2", the corresponding HTML anchor tag would be <A NAME="anchor2"></A>

Exceptions

WFCInvalidArgumentException thrown if n is null.

See Also getName


DhLinkTarget Class

Provides constants for setting the document's target window.

Enum
  |
  +--DhLinkTarget

package com.ms.wfc.html

public class DhLinkTarget
extends Enum

Remarks

These constants are used by the DhHyperlink.setStockTargetWindow and DhHyperlink.getStockTargetWindow methods.


 DhLinkTarget Methods

DhLinkTarget Methods

Methods | Description
valid | Determines whether a specified value is valid for this enumeration type.


 DhLinkTarget.valid

DhLinkTarget.valid

Determines whether a specified value is valid for this enumeration type.

Syntax

public static boolean valid( int n )

Parameters

n

The value to check.

Return Value

Returns true if the value is valid for this class; otherwise, returns false.

Remarks

You should override this method in your own enumeration classes.


 DhLinkTarget Fields

DhLinkTarget Fields

Fields | Description
NEW_WINDOW | Instructs the browser to put the document into a new top-level browser window.
PARENT_DOC | Instructs the browser to put the document into the window that is the parent of the current window.
THIS_FRAME | Instructs the browser to put the document into the current frame of the frameset.
TOP_FRAME | Instructs the browser to put the document into the top-most window, replacing the current frameset.


 DhLinkTarget.NEW_WINDOW

DhLinkTarget.NEW_WINDOW

Instructs the browser to put the document into a new top-level browser window.

Syntax

public static final int NEW_WINDOW;


 DhLinkTarget.PARENT_DOC

DhLinkTarget.PARENT_DOC

Instructs the browser to put the document into the window that is the parent of the current window.

Syntax

public static final int PARENT_DOC;


 DhLinkTarget.THIS_FRAME

DhLinkTarget.THIS_FRAME

Instructs the browser to put the document into the current frame of the frameset.

Syntax

public static final int THIS_FRAME;


 DhLinkTarget.TOP_FRAME

DhLinkTarget.TOP_FRAME

Instructs the browser to put the document into the top-most window, replacing the current frameset.

Syntax

public static final int TOP_FRAME;


DhListBox Class

Implements an HTML list box control.

Component
  |
  +--DhStyleBase
     |
     +--DhElement
        |
        +--DhBaseContainer
           |
           +--DhSelectBox
              |
              +--DhListBox

package com.ms.wfc.html

public class DhListBox
extends DhSelectBox

Remarks

This class manages adding, removing, and selecting items, as well as scrolling. The list box control can be used within a form (see DhForm) to transmit data.


 DhListBox Methods

DhListBox Methods

Constructors | Description
DhListBox | Creates a DhListBox control.

Methods | Description
getAlignment | Retrieves the current alignment value of the list box.
getSelectionMode | Retrieves the current selection mode of the list box.
getVisibleRows | Retrieves the number of currently visible rows.
setAlignment | Sets the alignment of the list box relative to the text around it.
setSelectionMode | Determines how many items at a time can be selected in the list box.
setVisibleRows | Sets the number of visible rows in the list box.


 DhListBox.DhListBox

DhListBox.DhListBox

Creates a DhListBox control.

Syntax

public DhListBox( )

public DhListBox( int nRows, int selectionMode )

Parameters

nRows

The initial number of visible rows. This must be greater than 1.

selectionMode

A value determining whether the user can select multiple rows. This can be any value in com.ms.wfc.ui.SelectionMode.

Remarks

This default constructor creates a list box control with two visible rows, which allows only single selections.


 DhListBox.getAlignment

DhListBox.getAlignment

Retrieves the current alignment value of the list box.

Syntax

public int getAlignment()

Remarks

Returns one of the alignment constant values in DhAlignment.

See Also setAlignment


 DhListBox.getSelectionMode

DhListBox.getSelectionMode

Retrieves the current selection mode of the list box.

Syntax

public int getSelectionMode()

Return Value

Returns the selection mode. Possible values are:

  • SelectionMode.ONE indicates that only one item can be selected at a time.
  • SelectionMode.MULTI_EXTENDED indicates that more than one item at a time can be selected and that keyboard characters, such as SHIFT and CTRL, can be used to assist in the selection.

See Also com.ms.wfc.ui.SelectionMode, setSelectionMode


 DhListBox.getVisibleRows

DhListBox.getVisibleRows

Retrieves the number of currently visible rows.

Syntax

public int getVisibleRows( )

Return Value

Returns the number of rows.

See Also setVisibleRows


 DhListBox.setAlignment

DhListBox.setAlignment

Sets the alignment of the list box relative to the text around it.

Syntax

public void setAlignment( int nAlignment )

Parameters

nAlignment

The new alignment, which can be one of the alignment constant values in DhAlignment.

See Also getAlignment


 DhListBox.setSelectionMode

DhListBox.setSelectionMode

Determines how many items at a time can be selected in the list box.

Syntax

public void setSelectionMode( int value )

Parameters

value

The new selection mode. Possible values are:

  • SelectionMode.ONE indicates that only one item can be selected at a time.
  • SelectionMode.MULTI_EXTENDED indicates that more than one item at a time can be selected and that keyboard characters, such as SHIFT and CTRL, can be used to assist in the selection.

Note NONE and MULTI_SIMPLE are not valid for DhListBox.

Exceptions

WFCInvalidArgumentException thrown if value is not ONE or MULTI_EXTENDED.

See Also getSelectionMode


 DhListBox.setVisibleRows

DhListBox.setVisibleRows

Sets the number of visible rows in the list box.

Syntax

public void setVisibleRows( int nRows )

Parameters

nRows

Number of rows. This must be greater than 1.

Exceptions

WFCInvalidArgumentException thrown if nRow is less than 2.

See Also getVisibleRows


DhListType Class

Provides constants and support for list types in a DhBulletedList control.

Enum
  |
  +--DhListType

package com.ms.wfc.html

public class DhListType
extends Enum


 DhListType Methods

DhListType Methods

Methods | Description
valid | Determines whether a specified value is valid for this enumeration type.


 DhListType.valid

DhListType.valid

Determines whether a specified value is valid for this enumeration type.

Syntax

public static boolean valid( int n )

Parameters

n

The value to check.

Return Value

Returns true if the value is valid for this class; otherwise, returns false.

Remarks

You should override this method in your own enumeration classes.


 DhListType Fields

DhListType Fields

Fields | Description
BULLETED | Represents a list in which each item has a small bullet.
DIR | Represents a list in which each item has a large bullet.
LARGE_LETTER | Represents a list in which each item has an assigned uppercase letter.
LARGE_ROMAN | Represents a list in which each item has an assigned uppercase roman numeral.
MENU | Represents a list in which each item has a large bullet.
NUMBERED | Represents a list in which each item has an assigned number.
SMALL_LETTER | Represents a list in which each item has an assigned lowercase letter.
SMALL_ROMAN | Represents a list in which each item has an assigned lowercase roman numeral.


 DhListType.BULLETED

DhListType.BULLETED

Represents a list in which each item has a small bullet.

Syntax

public final static int BULLETED;


 DhListType.DIR

DhListType.DIR

Represents a list in which each item has a large bullet.

Syntax

public final static int DIR;


 DhListType.LARGE_LETTER

DhListType.LARGE_LETTER

Represents a list in which each item has an assigned uppercase letter.

Syntax

public final static int LARGE_LETTER;


 DhListType.LARGE_ROMAN

DhListType.LARGE_ROMAN

Represents a list in which each item has an assigned uppercase roman numeral.

Syntax

public final static int LARGE_ROMAN;


 DhListType.MENU

DhListType.MENU

Represents a list in which each item has a large bullet.

Syntax

public final static int MENU;


 DhListType.NUMBERED

DhListType.NUMBERED

Represents a list in which each item has an assigned number.

Syntax

public final static int NUMBERED;


 DhListType.SMALL_LETTER

DhListType.SMALL_LETTER

Represents a list in which each item has an assigned lowercase letter.

Syntax

public final static int SMALL_LETTER;


 DhListType.SMALL_ROMAN

DhListType.SMALL_ROMAN

Represents a list in which each item has an assigned lowercase roman numeral.

Syntax

public final static int SMALL_ROMAN;


DhMargins Class

Provides constant definitions for margin style manipulation.

Enum
  |
  +--DhMargins

package com.ms.wfc.html

public class DhMargins
extends Enum

Remarks

These constants can be combined using the bitwise OR to specify more than one margin.


 DhMargins Methods

DhMargins Methods

Methods | Description
valid | Determines whether a specified value is valid for this enumeration type.


 DhMargins.valid

DhMargins.valid

Determines whether a specified value is valid for this enumeration type.

Syntax

public static boolean valid( int n )

Parameters

n

The value to check.

Return Value

Returns true if the value is valid for this class; otherwise, returns false.

Remarks

You should override this method in your own enumeration classes.


 DhMargins Fields

DhMargins Fields

Fields | Description
ALL | Specifies the combination of all constants. This is equivalent to (TOP | RIGHT | BOTTOM | LEFT).
BOTTOM | Specifies a bottom margin.
LEFT | Specifies a left margin.
RIGHT | Specifies a right margin.
TOP | Specifies a top margin.


 DhMargins.ALL

DhMargins.ALL

Specifies the combination of all constants. This is equivalent to (TOP | RIGHT | BOTTOM | LEFT).

Syntax

public static final int ALL;


 DhMargins.BOTTOM

DhMargins.BOTTOM

Specifies a bottom margin.

Syntax

public static final int BOTTOM;


 DhMargins.LEFT

DhMargins.LEFT

Specifies a left margin.

Syntax

public static final int LEFT;


 DhMargins.RIGHT

DhMargins.RIGHT

Specifies a right margin.

Syntax

public static final int RIGHT;


 DhMargins.TOP

DhMargins.TOP

Specifies a top margin.

Syntax

public static final int TOP;


DhMarginWidthInfo Class

Provides structured information about an element's margin settings.

package com.ms.wfc.html

public class DhMarginWidthInfo

Remarks

This class is used by the DhStyleBase class and the classes that extend it.

See Also DhUnits


 DhMarginWidthInfo Methods

DhMarginWidthInfo Methods

Constructors | Description
DhMarginWidthInfo | Constructs a DhMarginWidthInfo object.


 DhMarginWidthInfo.DhMarginWidthInfo

DhMarginWidthInfo.DhMarginWidthInfo

Constructs a DhMarginWidthInfo object.

Syntax

public DhMarginWidthInfo()

public DhMarginWidthInfo( DhMarginWidthInfo mwi )

Parameters

mwi

The object used to initialize current settings.

Remarks

The constructor that takes a parameter that initializes values from an existing DhMarginWidthInfo object.


 DhMarginWidthInfo Fields

DhMarginWidthInfo Fields

Fields | Description
bottomUnit | Specifies the bottom margin width unit as one of the DhUnits constants.
bottomWidth | Specifies the bottom margin width in units specified by bottomUnit.
leftUnit | Specifies the left margin width unit as one of the DhUnits constants.
leftWidth | Specifies the left margin width in units specified by leftUnit.
rightUnit | Specifies the right margin width unit as one of the DhUnits constants.
rightWidth | Specifies the right margin width in units specified by rightUnit.
topUnit | Specifies the top margin width unit as one of the DhUnits constants.
topWidth | Specifies the top margin width in units specified by topUnit.


 DhMarginWidthInfo.bottomUnit

DhMarginWidthInfo.bottomUnit

Specifies the bottom margin width unit as one of the DhUnits constants.

Syntax

public int bottomUnit;


 DhMarginWidthInfo.bottomWidth

DhMarginWidthInfo.bottomWidth

Specifies the bottom margin width in units specified by bottomUnit.

Syntax

public int bottomWidth;


 DhMarginWidthInfo.leftUnit

DhMarginWidthInfo.leftUnit

Specifies the left margin width unit as one of the DhUnits constants.

Syntax

public int leftUnit;


 DhMarginWidthInfo.leftWidth

DhMarginWidthInfo.leftWidth

Specifies the left margin width in units specified by leftUnit.

Syntax

public int leftWidth;


 DhMarginWidthInfo.rightUnit

DhMarginWidthInfo.rightUnit

Specifies the right margin width unit as one of the DhUnits constants.

Syntax

public int rightUnit;


 DhMarginWidthInfo.rightWidth

DhMarginWidthInfo.rightWidth

Specifies the right margin width in units specified by rightUnit.

Syntax

public int rightWidth;


 DhMarginWidthInfo.topUnit

DhMarginWidthInfo.topUnit

Specifies the top margin width unit as one of the DhUnits constants.

Syntax

public int topUnit;


 DhMarginWidthInfo.topWidth

DhMarginWidthInfo.topWidth

Specifies the top margin width in units specified by topUnit.

Syntax

public int topWidth;


DhModule Class

Provides siting services for the com.ms.wfc.html package.

package com.ms.wfc.html

public class DhModule
extends com.ms.wfc.core.Component
implements IObjectWithSite, IPersistPropertyBag, DhStringIDs, ISiteable

Remarks

You should never create a DhModule object; it is created automatically either by placing it on a client HTML page as an OBJECT tag or by invoking it from an Active Server Pages (ASP) file on a server.


 DhModule Methods

DhModule Methods

Methods | Description
addOnBeforeUnload | Assigns a delegate to the beforeUnload event.
addOnError | Assigns a delegate to the error event.
addOnGotFocus | Assigns a delegate to the gotFocus event.
addOnHelp | Assigns a delegate to the help event.
addOnLoad | Assigns a delegate to the load event.
addOnLostFocus | Assigns a delegate to the lostFocus event.
addOnResize | Assigns a delegate to the resize event.
addOnScroll | Assigns a delegate to the scroll event.
addOnUnload | Assigns a delegate to the unload event.
appendEventHandlers | Appends the event handlers of a given module to this module's event handler list.
doMain | Initializes a DhModule that was invoked from the console (typically using JView).
GetCodeClass | Retrieves the name of the document class for this module (which should be a class extending DhDocument).
getDocument | Retrieves the current DhDocument object associated with this module.
getDocumentObject | Retrieves the current document associated with this module as an Object for scripting purposes.
getModuleHost | Retrieves a string indicating how the module is hosted.
getPeer | Retrieves the underlying HTML peer element for this class.
getQueryParameter | Retrieves a query parameter.
getRequest | Obtains the server Request object, if available (for example, if the module is running on the server).
getResponse | Obtains the server Response object, if available (for example, if the module is running on the server).
getServerMode | Determines if this DhModule object was sited on IIS.
LoadParameters | This is the first and last time this module has a chance to look at the parameters that were authored into the PARAM tags of the hosting HTML document.
removeOnBeforeUnload | Removes the delegate that is assigned to the beforeUnload event.
removeOnError | Removes the delegate that is assigned to the error event.
removeOnGotFocus | Removes the delegate that is assigned to the gotFocus event.
removeOnHelp | Removes the delegate that is assigned to the help event.
removeOnLoad | Removes the delegate that is assigned to the load event.
removeOnLostFocus | Removes the delegate that is assigned to the lostFocus event.
removeOnResize | Removes the delegate that is assigned to the resize event.
removeOnScroll | Removes the delegate that is assigned to the scroll event.
removeOnUnload | Removes the delegate that is assigned to the lostFocus event.
setCodeClass | Sets the name of the class of DhDocument that is created for the HTML document containing this module.
setHTMLDocument | Sets the import document file name for server-side operations.
write | Writes the specified HTML string to the current site.


 DhModule.addOnBeforeUnload

DhModule.addOnBeforeUnload

Assigns a delegate to the beforeUnload event.

Syntax

public final void addOnBeforeUnload ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

This delegate specifies a method that is called when the document is about to be unloaded. This event is automatically routed to onDocumentUnload.

See Also removeOnBeforeUnload


 DhModule.addOnError

DhModule.addOnError

Assigns a delegate to the error event.

Syntax

public final void addOnError( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

This delegate specifies a method that is called when an error occurs.

See Also removeOnError


 DhModule.addOnGotFocus

DhModule.addOnGotFocus

Assigns a delegate to the gotFocus event.

Syntax

final public void addOnGotFocus ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

This delegate specifies a method that is called when the document receives focus.

See Also removeOnGotFocus


 DhModule.addOnHelp

DhModule.addOnHelp

Assigns a delegate to the help event.

Syntax

public final void addOnHelp( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

This delegate specifies a method that is called when help is requested by the user.

See Also removeOnHelp


 DhModule.addOnLoad

DhModule.addOnLoad

Assigns a delegate to the load event.

Syntax

final public void addOnLoad ( EventHandler h )

Parameters

h

The event handler callback method.

Remarks

This delegate specifies a method that is called when the document has finished loading. By default, this event is automatically routed to onDocumentLoad.

See Also removeOnLoad


 DhModule.addOnLostFocus

DhModule.addOnLostFocus

Assigns a delegate to the lostFocus event.

Syntax

final public void addOnLostFocus ( EventHandler h )

Parameters

h

The event handler callback method.

Remarks

This delegate specifies a method that is called when the document loses focus to another window.

See Also removeOnLostFocus


 DhModule.addOnResize

DhModule.addOnResize

Assigns a delegate to the resize event.

Syntax

public final void addOnResize ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when the window is resized.

See Also removeOnResize


 DhModule.addOnScroll

DhModule.addOnScroll

Assigns a delegate to the scroll event.

Syntax

public final void addOnScroll ( ScrollEventHandler h )

Parameters

h

The ScrollEventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when this element is scrolled.


 DhModule.addOnUnload

DhModule.addOnUnload

Assigns a delegate to the unload event.

Syntax

final public void addOnUnload ( EventHandler h )

Parameters

h

The event handler callback method.

Remarks

This delegate specifies a method that is called when the document is ready to unload. By default, this event is automatically routed to onDocumentUnload.

See Also removeOnUnload


 DhModule.appendEventHandlers

DhModule.appendEventHandlers

Appends the event handlers of a given module to this module's event handler list.

Syntax

public void appendEventHandlers( DhModule m )

Parameters

m

The module containing the event handler list to be added to this element.


 DhModule.doMain

DhModule.doMain

Initializes a DhModule that was invoked from the console (typically using JView).

Syntax

final public void doMain( String args[] )

Parameters

args

The argument list that was originally passed to main.

Remarks

Call this method only from your static main function.


 DhModule.getCodeClass

DhModule.getCodeClass

Retrieves the name of the document class for this module (which should be a class extending DhDocument).

Syntax

final public String getCodeClass()

Return Value

Returns the document class name.

Remarks

If this property is not set in the constructor for the DhModule-derived class, the framework will set it using the __CODECLASS attribute of the HTML <body> tag, if any.


 DhModule.getDocument

DhModule.getDocument

Retrieves the current DhDocument object associated with this module.

Syntax

public final DhDocument getDocument()

Return Value

Returns the current DhDocument, or returns null if the page has not finished loading.

Remarks

Calling this method is valid only after the document has been loaded. Call DhDocument.onDocumentLoad to be notified when this occurs.


 DhModule.getDocumentObject

DhModule.getDocumentObject

Retrieves the current document associated with this module as an Object for scripting purposes.

Syntax

public Object getDocumentObject()

Return Value

Returns the current document Object or returns null if the page has not finished loading.


 DhModule.getModuleHost

DhModule.getModuleHost

Retrieves a string indicating how the module is hosted.

Syntax

public String getModuleHost()

Return Value

Returns a string describing the host type. Currently the possible values are:

  • "IIS", indicating an Internet server.
  • "IE", indicating an Internet browser (client side).
  • "CONSOLE", indicating a console (typically using jview.exe).
  • "NONE", indicating an unknown host environment.
  • "other".

Remarks

You can call getModuleHost from your initForm method and adjust your module's behavior as appropriate. For example, if the host is "IIS", creating event handlers on HTML elements has no effect.


 DhModule.getPeer

DhModule.getPeer

Retrieves the underlying HTML peer element for this class.

Syntax

public IUnknown getPeer()

Return Value

Returns the element peer underlying the HTML peer for this class.

Remarks

This method can return null if the document is not bound to this class. Java code that is running in a trusted environment can freely cast the resulting reference to a specific element peer type. This method always returns null if the code is running in a Web server environment.

Note Calling this method represents an advanced usage scenario. Typically, you would never use this method.


 DhModule.getQueryParameter

DhModule.getQueryParameter

Retrieves a query parameter.

Syntax

public String getQueryParameter( String strParamName)

Parameters

strParamName

The query parameter name to retrieve a value for.

Return Value

Returns the parameter value from the Request object. If the parameter does not exist, returns an empty string.

See Also getServerMode, getRequest


 DhModule.getRequest

DhModule.getRequest

Obtains the server Request object, if available (for example, if the module is running on the server).

Syntax

public IRequest getRequest()

Return Value

Returns an IRequest interface that can be used to manipulate an IIS request. This is an interface to the Request object used in IIS.

Remarks

The Request object retrieves the values that the client browser passed to the server during an HTTP request. For more information on the Request object, see the Microsoft Active Server Pages (ASP) documentation.

See Also getServerMode, getResponse


 DhModule.getResponse

DhModule.getResponse

Obtains the server Response object, if available (for example, if the module is running on the server).

Syntax

public IResponse getResponse()

Return Value

Returns an IResponse interface that can be used to manipulate an IIS response. This is an interface to the Response object used in IIS.

Remarks

The Response object can used to send output to the client. For information on the Response object, see the Microsoft Active Server Pages (ASP) documentation.

See Also getServerMode, getRequest


 DhModule.getServerMode

DhModule.getServerMode

Determines if this DhModule object was sited on IIS.

Syntax

public boolean getServerMode()

Return Value

Returns true if DhModule is sited on a web server, or returns false if it is sited on a client or other container.


 DhModule.LoadParameters

DhModule.LoadParameters

This is the first and last time this module has a chance to look at the parameters that were authored into the PARAM tags of the hosting HTML document.

Syntax

public void LoadParameters( DhPropertyBag pb )

Parameters

pb

The collection of PARAM tags.


 DhModule.removeOnBeforeUnload

DhModule.removeOnBeforeUnload

Removes the delegate that is assigned to the beforeUnload event.

Syntax

public final void removeOnBeforeUnload( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

See Also addOnBeforeUnload


 DhModule.removeOnError

DhModule.removeOnError

Removes the delegate that is assigned to the error event.

Syntax

public final void removeOnError( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

See Also addOnError


 DhModule.removeOnGotFocus

DhModule.removeOnGotFocus

Removes the delegate that is assigned to the gotFocus event.

Syntax

public void removeOnGotFocus ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

See Also addOnGotFocus


 DhModule.removeOnHelp

DhModule.removeOnHelp

Removes the delegate that is assigned to the help event.

Syntax

public final void removeOnHelp( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

See Also addOnHelp


 DhModule.removeOnLoad

DhModule.removeOnLoad

Removes the delegate that is assigned to the load event.

Syntax

public void removeOnLoad ( EventHandler h)

Parameters

h

The EventHandler delegate that is to be removed.

See Also addOnLoad


 DhModule.removeOnLostFocus

DhModule.removeOnLostFocus

Removes the delegate that is assigned to the lostFocus event.

Syntax

public void removeOnLostFocus ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

See Also addOnLostFocus


 DhModule.removeOnResize

DhModule.removeOnResize

Removes the delegate that is assigned to the resize event.

Syntax

public final void removeOnResize ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The resize event occurs the window is resized.

See Also addOnResize


 DhModule.removeOnScroll

DhModule.removeOnScroll

Removes the delegate that is assigned to the scroll event.

Syntax

final public void removeOnScroll ( ScrollEventHandler h )

Parameters

h

The ScrollEventHandler delegate that is to be removed.

See Also addOnScroll


 DhModule.removeOnUnload

DhModule.removeOnUnload

Removes the delegate that is assigned to the lostFocus event.

Syntax

public void removeOnUnload ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

See Also addOnUnload


 DhModule.setCodeClass

DhModule.setCodeClass

Sets the name of the class of DhDocument that is created for the HTML document containing this module.

Syntax

final public void setCodeClass( String strCodeClass )

Parameters

strCodeClass

The class name of the DhDocument-derived class to use.

Remarks

If this property is not set in the constructor for the DhModule-derived class, the framework sets it using the __CODECLASS attribute of the HTML <body> tag, when running on Internet Explorer.

See Also getCodeClass


 DhModule.setHTMLDocument

DhModule.setHTMLDocument

Sets the import document file name for server-side operations.

Syntax

final public void setHTMLDocument( String fileName )

final public void setHTMLDocument( IDataStream inputStream )

Parameters

fileName

The fully qualified path to the HTML template, or an empty string ("") if no template is to be used.

inputStream

The import document stream (com.ms.wfc.io.IDataStream) object pointing to the HTML template.

Remarks

This method is not meant to be called when bound to a browser and can only be called after a call to setCodeClass. If you do not have a template, call this method with a null-string file name; otherwise, use setBoundElements to associate DhElement items with the HTML in a template.

See Also com.ms.wfc.io.File


 DhModule.write

DhModule.write

Writes the specified HTML string to the current site.

Syntax

public void write( String strHTML )

public void write( DhElement element )

public void write( Throwable exception, boolean stackTrace )

Parameters

strHTML

The HTML string to write.

element

The element to write.

exception

The exception or error to write.

stackTrace

Set to true to write the stack trace; otherwise, set to false. If stackTrace is specified, the stack trace is also written.

Remarks

If running in server mode, the string or element is written to the output stream; otherwise, it is added to the end of the current document body.


DhObjectFactory Class

Creates an object from an existing ActiveX/COM or Java object and adds it to the document.

Component
  |
  +--DhStyleBase
     |
     +--DhElement
        |
        +--DhBaseContainer
           |
           +--DhObjectFactory

package com.ms.wfc.html

public class DhObjectFactory
extends DhBaseContainer

Remarks

To use this class, create a DhObjectFactory object specifying the object's class identifier (CLASSID). This is equivalent to using the OBJECT tag in Hypertext Markup Language (HTML).


 DhObjectFactory Methods

DhObjectFactory Methods

Constructors | Description
DhObjectFactory | Creates a DhObjectFactory object.

Methods | Description
add | Adds an element as the child of the object tag.
addOnError | Assigns a delegate to the error event.
addOnReadyStateChange | Assigns a delegate to the readyStateChange event.
addParam | Adds a new parameter to the object.
getClassid | Retrieves the object's class identifier, which is equivalent to the CLASSID parameter of the OBJECT tag in HTML.
getClsid | Retrieves the object's current class identifier, which is equivalent to the CLASSID parameter of the OBJECT tag in HTML.
getCodeBase | Retrieves the object's current codebase, which is equivalent to the CODEBASE parameter of the OBJECT tag in HTML.
getCodeClassName | Sets the Java class name of the object, which is equivalent to the CODE parameter of the OBJECT tag in HTML.
getContent | Retrieves a string representing the HTML of the contents.
getDispatchPeer | Retrieves the IDispatch interface implemented by the object currently instantiated.
getObjectPeer | Retrieves the object representing the HTML OBJECT instantiated.
getProgid | Retrieves the object's current programmatic identifer (ProgID), which is equivalent to the PROGID parameter of the OBJECT tag.
getValue | Retrieves the value of the parameter.
initFromPeer | Called when an instance is created from an existing HTML element.
removeOnError | Removes the delegate that is assigned to the error event.
removeOnReadyStateChange | Removes the delegate that is assigned to the readyStateChange event.
removeParam | Removes a parameter from the list of parameters for the OBJECT.
setClassid | Sets the object's current class identifier, which is equivalent to the CLASSID parameter of the OBJECT tag in HTML.
setClsid | Sets the object's class identifier, which is equivalent to the CLASSID parameter of the OBJECT tag in HTML.
setCodeBase | Sets the object's code base, which is equivalent to the CODEBASE parameter of the OBJECT tag in HTML.
setCodeClassName | Sets the Java class name of the object, which is equivalent to the CODE parameter of the OBJECT tag in HTML.
setProgid | Sets the object's programmatic identifier (ProgID).


 DhObjectFactory.add

DhObjectFactory.add

Adds an element as the child of the object tag.

Syntax

protected void add( DhElement h )

Parameters

h

The DhElement object to be added.


 DhObjectFactory.addOnError

DhObjectFactory.addOnError

Assigns a delegate to the error event.

Syntax

public final void addOnError ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when this element generates an error.

See Also removeOnError


 DhObjectFactory.addOnReadyStateChange

DhObjectFactory.addOnReadyStateChange

Assigns a delegate to the readyStateChange event.

Syntax

public final void addOnReadyStateChange( ReadyStateEventHandler h )

Parameters

h

The ReadyStateEventHandler delegate to be notified when the event occurs.

See Also removeOnReadyStateChange


 DhObjectFactory.addParam

DhObjectFactory.addParam

Adds a new parameter to the object.

Syntax

public void addParam( String param, String value )

Parameters

param

The name of the parameter. This can be any parameter supported by the OBJECT tag in HTML.

value

The value of the parameter.

See Also removeParam


 DhObjectFactory.DhObjectFactory

DhObjectFactory.DhObjectFactory

Creates a DhObjectFactory object.

Syntax

public DhObjectFactory()

public DhObjectFactory( String classid )

public DhObjectFactory( _Guid iid )

Parameters

classid

The class identifier (CLSID) of an existing object.

iid

The _Guid object to instantiate.

Remarks

You can instantiate Java applets with the OBJECT tag by using the the Java moniker name (for example "java:myapplet") as the CLASSID parameter value.

See Also com.ms.com._Guid


 DhObjectFactory.getClassid

DhObjectFactory.getClassid

Retrieves the object's class identifier, which is equivalent to the CLASSID parameter of the OBJECT tag in HTML.

Syntax

public String getClassid()

Return Value

Returns the object's class identifier.

See Also setClassid


 DhObjectFactory.getClsid

DhObjectFactory.getClsid

Retrieves the object's current class identifier, which is equivalent to the CLASSID parameter of the OBJECT tag in HTML.

Syntax

public _Guid getClsid()

Return Value

Returns the object's class identifier.

See Also setClsid


 DhObjectFactory.getCodeBase

DhObjectFactory.getCodeBase

Retrieves the object's current codebase, which is equivalent to the CODEBASE parameter of the OBJECT tag in HTML.

Syntax

public String getCodeBase()

Return Value

Returns the object's code base.

See Also setCodeBase


 DhObjectFactory.getCodeClassName

DhObjectFactory.getCodeClassName

Sets the Java class name of the object, which is equivalent to the CODE parameter of the OBJECT tag in HTML.

Syntax

public String getCodeClassName()

Return Value

Returns the object's Java class name.

See Also setCodeClassName


 DhObjectFactory.getContent

DhObjectFactory.getContent

Retrieves a string representing the HTML of the contents.

Syntax

protected StringBuffer getContent( StringBuffer sb )

Parameters

sb

The HTML content string.

Return Value

Returns the StringBuffer representing the HTML of the contents.


 DhObjectFactory.getDispatchPeer

DhObjectFactory.getDispatchPeer

Retrieves the IDispatch interface implemented by the object currently instantiated.

Syntax

public Object getDispatchPeer()

Return Value

Returns the object representing the IDispatch interface of the object.

Remarks

This object can be used along with the com.ms.com.Dispatch class to invoke methods exposed through the controls' IDispatch interface.


 DhObjectFactory.getObjectPeer

DhObjectFactory.getObjectPeer

Retrieves the object representing the HTML OBJECT instantiated.

Syntax

public Object getObjectPeer()

Return Value

Returns the object representing the HTML OBJECT instantiated.


 DhObjectFactory.getProgid

DhObjectFactory.getProgid

Retrieves the object's current programmatic identifer (ProgID), which is equivalent to the PROGID parameter of the OBJECT tag.

Syntax

public String getProgid()

Return Value

Returns the ProgID representing the object. ProgIDs present a human-readable version of the class identifier.

See Also setProgid


 DhObjectFactory.getValue

DhObjectFactory.getValue

Retrieves the value of the parameter.

Syntax

public String getValue( String param )

Parameters

param

The name of the parameter.


 DhObjectFactory.initFromPeer

DhObjectFactory.initFromPeer

Called when an instance is created from an existing HTML element.

Syntax

protected void initFromPeer( IHTMLElement peer )

Parameters

peer

The existing peer element.

Remarks

Override this method to perform any special initialization when an instance is created from an existing HTML element.


 DhObjectFactory.removeOnError

DhObjectFactory.removeOnError

Removes the delegate that is assigned to the error event.

Syntax

public final void removeOnError ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The error event occurs when this container generates an error.

See Also addOnError


 DhObjectFactory.removeOnReadyStateChange

DhObjectFactory.removeOnReadyStateChange

Removes the delegate that is assigned to the readyStateChange event.

Syntax

public final void removeOnReadyStateChange( ReadyStateEventHandler h )

Parameters

h

The ReadyStateEventHandler delegate that is to be removed.

See Also addOnReadyStateChange


 DhObjectFactory.removeParam

DhObjectFactory.removeParam

Removes a parameter from the list of parameters for the OBJECT.

Syntax

public void removeParam( String param )

Parameters

param

The name of the parameter to remove.

Exceptions

WFCInvalidStateException thrown if the object is currently bound.

See Also addParam


 DhObjectFactory.setClassid

DhObjectFactory.setClassid

Sets the object's current class identifier, which is equivalent to the CLASSID parameter of the OBJECT tag in HTML.

Syntax

public void setClassid( String classid )

Parameters

classid

The object's class identifier string.

See Also com.ms.com._Guid, getClassid


 DhObjectFactory.setClsid

DhObjectFactory.setClsid

Sets the object's class identifier, which is equivalent to the CLASSID parameter of the OBJECT tag in HTML.

Syntax

public void setClsid( _Guid guid )

Parameters

guid

The globally unique identifier (GUID) representing the object.

See Also getClsid


 DhObjectFactory.setCodeBase

DhObjectFactory.setCodeBase

Sets the object's code base, which is equivalent to the CODEBASE parameter of the OBJECT tag in HTML.

Syntax

public void setCodeBase( String url )

Parameters

url

Specifies a Uniform Resource Locator (URL) referencing where to find the implementation of the object.

See Also getCodeBase


 DhObjectFactory.setCodeClassName

DhObjectFactory.setCodeClassName

Sets the Java class name of the object, which is equivalent to the CODE parameter of the OBJECT tag in HTML.

Syntax

public void setCodeClassName( String className )

Parameters

className

The name of the file containing the compiled Java class.

See Also getCodeClassName


 DhObjectFactory.setProgid

DhObjectFactory.setProgid

Sets the object's programmatic identifier (ProgID).

Syntax

public void setProgid( String progid )

Parameters

progid

The ProgID representing the object. ProgIDs present a human-readable version of the class identifier (ClassID) used to identify COM/ActiveX objects.

See Also getProdid


DhPaddings Class

Provides constant definitions for padding style manipulation.

Enum
  |
  +--DhPaddings

package com.ms.wfc.html

public class DhPaddings
extends com.ms.wfc.core.Enum

Remarks

This class is used by the DhStyleBase.setPaddingWidth method to specify the side to which to apply the padding width. Padding constants can be combined using the bitwise OR to specify more than one padding side.


 DhPaddings Methods

DhPaddings Methods

Methods | Description
valid | Determines whether a specified value is valid for this enumeration type.


 DhPaddings.valid

DhPaddings.valid

Determines whether a specified value is valid for this enumeration type.

Syntax

public static boolean valid( int n )

Parameters

n

The value to check.

Return Value

Returns true if the value is valid for this class; otherwise, returns false.

Remarks

You should override this method in your own enumeration classes.


 DhPaddings Fields

DhPaddings Fields

Fields | Description
ALL | Specifies a combination of all padding constants.
BOTTOM | Specifies bottom padding.
LEFT | Specifies left padding.
RIGHT | Specifies right padding.
TOP | Specifies top padding.


 DhPaddings.ALL

DhPaddings.ALL

Specifies a combination of all padding constants.

Syntax

public static final int ALL;

Remarks

This is equivalent to (TOP | RIGHT | BOTTOM | LEFT).


 DhPaddings.BOTTOM

DhPaddings.BOTTOM

Specifies bottom padding.

Syntax

public static final int BOTTOM;


 DhPaddings.LEFT

DhPaddings.LEFT

Specifies left padding.

Syntax

public static final int LEFT;


 DhPaddings.RIGHT

DhPaddings.RIGHT

Specifies right padding.

Syntax

public static final int RIGHT;


 DhPaddings.TOP

DhPaddings.TOP

Specifies top padding.

Syntax

public static final int TOP;


DhPaddingWidthInfo Class

Provides information about an element's padding width settings.

package com.ms.wfc.html

public class DhPaddingWidthInfo

Remarks

These constants are used by DhStyleBase.getPaddingWidthInfo and DhStyleBase.setPaddingWidthInfo.


 DhPaddingWidthInfo Methods

DhPaddingWidthInfo Methods

Constructors | Description
DhPaddingWidthInfo | Creates a DhPaddingWidthInfo object.


 DhPaddingWidthInfo.DhPaddingWidthInfo

DhPaddingWidthInfo.DhPaddingWidthInfo

Creates a DhPaddingWidthInfo object.

Syntax

public DhPaddingWidthInfo()

public DhPaddingWidthInfo( DhPaddingWidthInfo mwi )

Parameters

mwi

Values from an existing DhPaddingWidthInfo object to initialize settings to.


 DhPaddingWidthInfo Fields

DhPaddingWidthInfo Fields

Fields | Description
bottomUnit | Specifies the bottom padding width unit as one of the DhUnits constants.
bottomWidth | Specifies the bottom padding width in units specified by bottomUnit.
leftUnit | Specifies the left padding width unit as one of the DhUnits constants.
leftWidth | Specifies the left padding width in units specified by leftUnit.
rightUnit | Specifies the right padding width unit as one of the DhUnits constants.
rightWidth | Specifies the right padding width in units specified by rightUnit.
topUnit | Specifies the top padding width unit as one of the DhUnits constants.
topWidth | Specifies the top padding width in units specified by topUnit.


 DhPaddingWidthInfo.bottomUnit

DhPaddingWidthInfo.bottomUnit

Specifies the bottom padding width unit as one of the DhUnits constants.

Syntax

public int bottomUnit;


 DhPaddingWidthInfo.bottomWidth

DhPaddingWidthInfo.bottomWidth

Specifies the bottom padding width in units specified by bottomUnit.

Syntax

public int bottomWidth;


 DhPaddingWidthInfo.leftUnit

DhPaddingWidthInfo.leftUnit

Specifies the left padding width unit as one of the DhUnits constants.

Syntax

public int leftUnit;


 DhPaddingWidthInfo.leftWidth

DhPaddingWidthInfo.leftWidth

Specifies the left padding width in units specified by leftUnit.

Syntax

public int leftWidth;


 DhPaddingWidthInfo.rightUnit

DhPaddingWidthInfo.rightUnit

Specifies the right padding width unit as one of the DhUnits constants.

Syntax

public int rightUnit;


 DhPaddingWidthInfo.rightWidth

DhPaddingWidthInfo.rightWidth

Specifies the right padding width in units specified by rightUnit.

Syntax

public int rightWidth;


 DhPaddingWidthInfo.topUnit

DhPaddingWidthInfo.topUnit

Specifies the top padding width unit as one of the DhUnits constants.

Syntax

public int topUnit;


 DhPaddingWidthInfo.topWidth

DhPaddingWidthInfo.topWidth

Specifies the top padding width in units specified by topUnit.

Syntax

public int topWidth;


DhPropertyBag Class

Retrieves attribute values in the module's PARAM tags.

package com.ms.wfc.html

public class DhPropertyBag

Remarks

You never actually create this class; instead, an instance of this class is passed along to DhModule.LoadParameters.


 DhPropertyBag Methods

DhPropertyBag Methods

Methods | Description
getInt | Retrieves the VALUE attribute of a PARAM tag given the NAME attribute.
getString | Retrieves the VALUE attribute of a PARAM tag given the NAME attribute.


 DhPropertyBag.getInt

DhPropertyBag.getInt

Retrieves the VALUE attribute of a PARAM tag given the NAME attribute.

Syntax

public int getInt( String name )

Parameters

name

The NAME attribute of the PARAM tag.

Return Value

Returns the corresponding numeric VALUE attribute of the same PARAM tag.

Remarks

For example, for the construction <PARAM NAME=fee VALUE=33>, this method retrieves the value 33 when getInt("fee") is called.


 DhPropertyBag.getString

DhPropertyBag.getString

Retrieves the VALUE attribute of a PARAM tag given the NAME attribute.

Syntax

public String getString( String name )

Parameters

name

The NAME attribute of the PARAM tag.

Return Value

Returns the corresponding VALUE attribute of the same PARAM tag.

Remarks

For example, for the construction <PARAM NAME=weekday VALUE=monday>, this method retrieves the string "monday" when getString("weekday") is called.


DhRadioButton Class

Implements an intrinsic HTML radio button control with a text label.

Component
  |
  +--DhStyleBase
     |
     +--DhElement
        |
        +--DhBaseContainer
           |
           +--DhRadioButton

package com.ms.wfc.html

public class DhRadioButton
extends DhBaseContainer

Remarks

Radio button groups allow for mutually exclusive choices from a list of options.


 DhRadioButton Methods

DhRadioButton Methods

Constructors | Description
DhRadioButton | Creates a DhRadioButton object.

Methods | Description
addOnCheckedChange | Assigns a delegate to the change event.
addOnGotFocus | Assigns a delegate to the gotFocus event.
addOnLostFocus | Assigns a delegate to the lostFocus event.
addOnResize | Assigns a delegate to the resize event.
addOnSelect | Assigns a delegate to the select event.
focus | Sets the input focus to this control.
getChecked | Retrieves the selected state of the radio button.
getEnabled | Retrieves the enabled state of the button.
getName | Retrieves the name of the button.
getSubmitName | Retrieves the submit name for this radio button control.
getSubmitValue | Retrieves the submit value for this radio button control.
getText | Retrieves the current text label for the radio button.
getTextAlign | Retrieves the current alignment.
removeOnCheckedChange | Removes the delegate that is assigned to the change event.
removeOnGotFocus | Removes the handler for the gotFocus event.
removeOnLostFocus | Removes the delegate that is assigned to the lostFocus event.
removeOnResize | Removes the delegate that is assigned to the resize event.
removeOnSelect | Removes the delegate that is assigned to the select event.
setChecked | Sets the selected state of the radio button.
setEnabled | Sets the enabled state of the button.
setName | Sets the name of the button.
setSubmitName | Sets the submit name for this radio button.
setSubmitValue | Sets the submit value for this radio button.
setText | Sets the text label of the button.
setTextAlign | Sets the current alignment.


 DhRadioButton.addOnCheckedChange

DhRadioButton.addOnCheckedChange

Assigns a delegate to the change event.

Syntax

final public void addOnCheckedChange ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

This event occurs when the user modifies the selected state of the button.

See Also removeOnCheckedChange


 DhRadioButton.addOnGotFocus

DhRadioButton.addOnGotFocus

Assigns a delegate to the gotFocus event.

Syntax

public final void addOnGotFocus ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when this element receives input focus.

See Also removeOnGotFocus


 DhRadioButton.addOnLostFocus

DhRadioButton.addOnLostFocus

Assigns a delegate to the lostFocus event.

Syntax

public final void addOnLostFocus ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when this element loses focus.

See Also removeOnLostFocus


 DhRadioButton.addOnResize

DhRadioButton.addOnResize

Assigns a delegate to the resize event.

Syntax

public final void addOnResize ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when this element is resized.

See Also removeOnResize


 DhRadioButton.addOnSelect

DhRadioButton.addOnSelect

Assigns a delegate to the select event.

Syntax

final public void addOnSelect ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

This event occurs when the user selects the control.

See Also removeOnSelect


 DhRadioButton.DhRadioButton

DhRadioButton.DhRadioButton

Creates a DhRadioButton object.

Syntax

public DhRadioButton()

public DhRadioButton( String strText, boolean fChecked )

Parameters

strText

The label text to display with the button.

fChecked

The initial selected state of the button.

Remarks

The default constructor creates a blank radio button with no check or text label. You set the values to initialize them. The constructor with parameters creates a radio button with right-aligned text (LeftRightAlignment.RIGHT).


 DhRadioButton.focus

DhRadioButton.focus

Sets the input focus to this control.

Syntax

public void focus()


 DhRadioButton.getChecked

DhRadioButton.getChecked

Retrieves the selected state of the radio button.

Syntax

public boolean getChecked()

Returns

Returns true if the radio button is selected; otherwise, returns false.

See Also setSubmitName, getSubmitName, setChecked


 DhRadioButton.getEnabled

DhRadioButton.getEnabled

Retrieves the enabled state of the button.

Syntax

public boolean getEnabled()

Return Value

Returns true if the button is enabled; otherwise, returns false.

See Also setEnabled


 DhRadioButton.getName

DhRadioButton.getName

Retrieves the name of the button.

Syntax

public String getName()

Return Value

Returns the button name.

See Also setName


 DhRadioButton.getSubmitName

DhRadioButton.getSubmitName

Retrieves the submit name for this radio button control.

Syntax

public String getSubmitName()

Return Value

Returns the submit (group) name.

Remarks

The submit name designates which groups of radio buttons are connected. Only one DhRadioButton in a group can be selected at a time.

See Also setSubmitName


 DhRadioButton.getSubmitValue

DhRadioButton.getSubmitValue

Retrieves the submit value for this radio button control.

Syntax

public String getSubmitValue()

Return Value

Returns the submit (group) name.

See Also setSubmitValue


 DhRadioButton.getText

DhRadioButton.getText

Retrieves the current text label for the radio button.

Syntax

public String getText()

Return Value

Returns the text label.

See Also setText


 DhRadioButton.getTextAlign

DhRadioButton.getTextAlign

Retrieves the current alignment.

Syntax

public int getTextAlign()

Return Value

Returns the current alignment, which can be either right-aligned (LeftRightAlignment.RIGHT) or left-aligned (LeftRight Alignment.LEFT).

See Also setTextAlign


 DhRadioButton.removeOnCheckedChange

DhRadioButton.removeOnCheckedChange

Removes the delegate that is assigned to the change event.

Syntax

final public void removeOnCheckedChange ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

See Also addOnCheckedChange


 DhRadioButton.removeOnGotFocus

DhRadioButton.removeOnGotFocus

Removes the handler for the gotFocus event.

Syntax

public final void removeOnGotFocus ( EventHandler h )

Parameters

h

The EventHandler delegate specifying the event handler method.

Remarks

This event occurs when this element receives input focus.

See Also addOnGotFocus


 DhRadioButton.removeOnLostFocus

DhRadioButton.removeOnLostFocus

Removes the delegate that is assigned to the lostFocus event.

Syntax

public final void removeOnLostFocus ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The lostFocus event occurs when this element loses input focus.

See Also addOnLostFocus


 DhRadioButton.removeOnResize

DhRadioButton.removeOnResize

Removes the delegate that is assigned to the resize event.

Syntax

public final void removeOnResize ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The resize event occurs when this container loses input focus.

See Also addOnResize


 DhRadioButton.removeOnSelect

DhRadioButton.removeOnSelect

Removes the delegate that is assigned to the select event.

Syntax

final public void removeOnSelect ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The select event occurs when the radio button is selected.

See Also addOnSelect


 DhRadioButton.setChecked

DhRadioButton.setChecked

Sets the selected state of the radio button.

Syntax

public void setChecked( boolean fValue )

Parameters

fValue

Set to true to select the radio button; set to false to clear it.

Remarks

If this button is bound and is a member of a group, setting its value can affect other DhRadioButton items in the group.

See Also setSubmitName, getSubmitName, setChecked


 DhRadioButton.setEnabled

DhRadioButton.setEnabled

Sets the enabled state of the button.

Syntax

public void setEnabled( boolean f )

Parameters

f

Set to true to enable the button; set to false to disable it.

See Also getEnabled


 DhRadioButton.setName

DhRadioButton.setName

Sets the name of the button.

Syntax

public void setName( String n )

Parameters

n

The name of the button.

See Also getName


 DhRadioButton.setSubmitName

DhRadioButton.setSubmitName

Sets the submit name for this radio button.

Syntax

public void setSubmitName( String strName )

Parameters

strName

The submit name, also known as the group name. Group names must be unique in each document.

Note The strName parameter cannot contain any spaces; otherwise, an exception is thrown.

Exceptions

WFCInvalidArgumentException thrown if strName is not a valid alignment.

Remarks

DhRadioButton objects within the same group are mutually exclusive; that is, only one can be selected at a given time. Additionally, group names are used for HTTP form submission. This name is used during HTTP form submission as the HTML NAME attribute.

See Also getSubmitName


 DhRadioButton.setSubmitValue

DhRadioButton.setSubmitValue

Sets the submit value for this radio button.

Syntax

public void setSubmitValue( String strValue )

Parameters

strValue

The submit value. This name is used during HTTP form submission as the HTML VALUE attribute.

Remarks

DhRadioButtons within the same group are mutually exclusive; that is, only one can be selected at a given time. Additionally, group names are used for HTTP form submission. This property represents the HTML VALUE attribute.

See Also getSubmitValue


 DhRadioButton.setText

DhRadioButton.setText

Sets the text label of the button.

Syntax

public void setText( String strText )

Parameters

strText

The text label of the button.

See Also getText


 DhRadioButton.setTextAlign

DhRadioButton.setTextAlign

Sets the current alignment.

Syntax

public void setTextAlign( int newAlignment )

Parameters

newAlignment

This can be either right-aligned (LeftRightAlignment.RIGHT) or left-aligned (LeftRight Alignment.LEFT).

Exceptions

WFCInvalidEnumException thrown if newAlignment is not a valid alignment.

Remarks

The following example demonstrates radio button alignment:

RIGHT: Right-Aligned Label
LEFT:  Left-Aligned Label

See Also getTextAlign


DhRawHTML Class

Enables output of arbitrary raw HTML to the document.

Component
  |
  +--DhStyleBase
     |
     +--DhElement
        |
        +--DhRawHTML

package com.ms.wfc.html

public class DhRawHTML
extends DhElement

Remarks

To add arbitrary HTML text to the document, create a DhRawHTML object, adding the HTML string either when you create it or afterward using setHTML. Then add the DhRawHTML element to the document or a container in the document.


 DhRawHTML Methods

DhRawHTML Methods

Constructors | Description
DhRawHTML | Creates a DhRawHTML object.

Methods | Description
getHTML | Retrieves the current HTML string.
setHTML | Sets the HTML string to output to the document.


 DhRawHTML.DhRawHTML

DhRawHTML.DhRawHTML

Creates a DhRawHTML object.

Syntax

public DhRawHTML()

public DhRawHTML( String html )

Parameters

html

The initial HTML string.

See Also setHTML


 DhRawHTML.getHTML

DhRawHTML.getHTML

Retrieves the current HTML string.

Syntax

public String getHTML()

Return Value

Returns the HTML string, or returns null if one is not set.

See Also setHTML


 DhRawHTML.setHTML

DhRawHTML.setHTML

Sets the HTML string to output to the document.

Syntax

public void setHTML( String html )

Parameters

html

The string to output.

See Also getHTML


DhResetButton Class

Implements a reset button control for HTTP form submission.

Component
  |
  +--DhStyleBase
    |
    +--DhElement
      |
      +--DhButtonBase
        |
        +--DhResetButton

package com.ms.wfc.html

public class DhResetButton
extends DhButtonBase

Remarks

This button resets the state of all controls on a form to the initial values. Adding a DhResetButton object to a DhForm object causes the DhForm to represent an HTML Form element. For more information on Form elements, including reset and submit buttons, see the Internet Client SDK documention. This can be found in the Platform SDK section of the MSDN compact disc under Internet/Intranet/Extranet Services. It can also be found in the MSDN online SDK documentation (http://www.microsoft.com/msdn/sdk/inetsdk/help).

See Also DhForm, DhSubmitButton


 DhResetButton Methods

DhResetButton Methods

Constructors | Description
DhResetButton | Creates a DhResetButton object.

Methods | Description
getText | Retrieves the button's current text caption.
setText | Sets the button caption.


 DhResetButton.DhResetButton

DhResetButton.DhResetButton

Creates a DhResetButton object.

Syntax

public DhResetButton()

public DhResetButton( String caption )

Parameters

caption

The caption for the new reset button.

Remarks

The default constructor creates a reset button with the caption "Reset".


 DhResetButton.getText

DhResetButton.getText

Retrieves the button's current text caption.

Syntax

public String getText()

Return Value

Returns the button caption.

See Also setText


 DhResetButton.setText

DhResetButton.setText

Sets the button caption.

Syntax

public void setText( String strCaption )

Parameters

strCaption

The new caption string.

See Also getText


DhRow Class

Implements a row in a DhTable table.

DhElement
  |
  +--DhBaseContainer
    |
    +--DhRow

package com.ms.wfc.html

public class DhRow
extends DhBaseContainer


 DhRow Methods

DhRow Methods

Constructors | Description
DhRow | Creates a DhRow object.

Methods | Description
add | Adds a cell to end of this row.
addOnGotFocus | Assigns a delegate to the gotFocus event.
addOnLostFocus | Assigns a delegate to the lostFocus event.
addOnResize | Assigns a delegate to the resize event.
getCell | Returns the cell at the specified ordinal position.
getCells | Returns the array of cells in this row.
getColumnCount | Returns the number of columns in this row.
getRecordNumber | Retrieves the ordinal record number displayed by the current row.
getRowNumber | Retrieves the row number for this row if it is currently within a table.
remove | Removes an cell from this row.
removeOnGotFocus | Removes the delegate that is assigned to the gotFocus event.
removeOnLostFocus | Removes the delegate that is assigned to the lostFocus event.
removeOnResize | Removes the delegate that is assigned to the resize event.


 DhRow.add

DhRow.add

Adds a cell to end of this row.

Syntax

public void add( DhCell cell )

Parameters

cell

The DhCell to add to this row.


 DhRow.addOnGotFocus

DhRow.addOnGotFocus

Assigns a delegate to the gotFocus event.

Syntax

public final void addOnGotFocus ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when this element receives input focus.

See Also removeOnGotFocus


 DhRow.addOnLostFocus

DhRow.addOnLostFocus

Assigns a delegate to the lostFocus event.

Syntax

public final void addOnLostFocus ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when this element loses focus.


 DhRow.addOnResize

DhRow.addOnResize

Assigns a delegate to the resize event.

Syntax

public final void addOnResize ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when this element is resized.

See Also removeOnResize


 DhRow.DhRow

DhRow.DhRow

Creates a DhRow object.

Syntax

public DhRow()

Remarks

This constructor creates an empty row.


 DhRow.getCell

DhRow.getCell

Returns the cell at the specified ordinal position.

Syntax

public DhCell getCell( int nCol )

Parameters

nCol

The ordinal column position of the cell.

Return Value

Returns the cell at position nCol. If no cell exists at this position, returns null.


 DhRow.getCells

DhRow.getCells

Returns the array of cells in this row.

Syntax

public DhCell[] getCells( )

Return Value

Returns the array of DhCell objects. If no cell exists at this position, returns null.


 DhRow.getColumnCount

DhRow.getColumnCount

Returns the number of columns in this row.

Syntax

public int getColumnCount()

Return Value

Returns the number of columns.


 DhRow.getRecordNumber

DhRow.getRecordNumber

Retrieves the ordinal record number displayed by the current row.

Syntax

public int getRecordNumber()

Return Value

Returns the corresponding absolute record number to this row. If the row is not data bound, returns -1.

Remarks

This method is valid only when the cell is data bound.


 DhRow.getRowNumber

DhRow.getRowNumber

Retrieves the row number for this row if it is currently within a table.

Syntax

public int getRowNumber()

Return Value

Returns the row number, or returns -1 if the row isn't in a table.


 DhRow.remove

DhRow.remove

Removes an cell from this row.

Syntax

public int remove( DhCell cell )

Parameters

cell

The DhCell to remove.

Return Value

Returns true if the cell was removed successfully; otherwise, returns false.


 DhRow.removeOnGotFocus

DhRow.removeOnGotFocus

Removes the delegate that is assigned to the gotFocus event.

Syntax

public final void removeOnGotFocus ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The gotFocus event occurs when this element receives input focus.

See Also addOnGotFocus


 DhRow.removeOnLostFocus

DhRow.removeOnLostFocus

Removes the delegate that is assigned to the lostFocus event.

Syntax

public final void removeOnLostFocus ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The lostFocus event occurs when this element loses input focus.

See Also addOnLostFocus


 DhRow.removeOnResize

DhRow.removeOnResize

Removes the delegate that is assigned to the resize event.

Syntax

public final void removeOnResize ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The resize event occurs when this container loses input focus.

See Also addOnResize


DhScrollBars Class

Defines constants for scroll bars.

Enum
  |
  +--DhScrollBars

package com.ms.wfc.html

public class DhScrollBars
extends Enum

Remarks

This class is used by the getScroll and setScroll methods in the DhDocument, DhInlineFrame, and DhWindow classes.


 DhScrollBars Methods

DhScrollBars Methods

Methods | Description
valid | Determines whether a specified value is valid for this enumeration type.


 DhScrollBars.valid

DhScrollBars.valid

Determines whether a specified value is valid for this enumeration type.

Syntax

public static boolean valid( int n )

Parameters

n

The value to check.

Return Value

Returns true if the value if valid for the class; otherwise, returns false.

Remarks

You should override this in your derived class.


 DhScrollBars Fields

DhScrollBars Fields

Fields | Description
AUTO | Indicates that the browser will add scroll bars as needed.
NO | Indicates that scrolling is disabled.
YES | Indicates that scrolling is enabled.


 DhScrollBars.AUTO

DhScrollBars.AUTO

Indicates that the browser will add scroll bars as needed.

Syntax

public static final int AUTO;


 DhScrollBars.NO

DhScrollBars.NO

Indicates that scrolling is disabled.

Syntax

public static final int NO;


 DhScrollBars.YES

DhScrollBars.YES

Indicates that scrolling is enabled.

Syntax

public static final int YES;


DhSelectBox Class

Represents the base class for the DhComboBox and DhListBox controls.

Component
  |
  +--DhStyleBase
     |
     +--DhElement
        |
        +--DhBaseContainer
           |
           +--DhSelectBox

package com.ms.wfc.html

public abstract class DhSelectBox
extends DhBaseContainer

Remarks

This base class is not intended to be instantiated.


 DhSelectBox Methods

DhSelectBox Methods

Methods | Description
addItem | Adds an item to the end of the list.
addOnGotFocus | Assigns a delegate to the gotFocus event.
addOnLostFocus | Assigns a delegate to the lostFocus event.
addOnResize | Assigns a delegate to the resize event.
addOnSelectedIndexChanged | Adds a delegate to the selectIndexChanged event.
findString | Finds the first item in the list that starts with the specified string.
findStringExact | Finds the first item in the list that matches the specified string exactly.
focus | Sets the input focus to this control.
getEnabled | Retrieves the enabled state of the element.
getItemCount | Retrieves the number of items currently in the list.
getItemsSubmitValue | Retrieves an array of text items corresponding to the submit value of the items in the list.
getItemsText | Retrieves an array of the text items in the list.
getItemSubmitValue | Retrieves the submit value for the item at index.
getItemText | Retrieves the text for the item at the specified index.
getSelected | Retrieves the current selected state of an item.
getSelectedIndex | Retrieves the index of the currently selected item.
getSelectedIndices | Retrieves an array that contains the zero-based indices of all currently selected items.
getSelectedSubmitValue | Retrieves the value for the selected item.
getSubmitName | Retrieves the name of the select box.
getText | Retrieves the text for the currently selected item.
insertItem | Inserts an item into the list at the selected index.
removeAll | Removes all items from the control.
removeItem | Removes an indexed item from the list.
removeOnGotFocus | Removes the delegate that is assigned to the onGotFocus event.
removeOnLostFocus | Removes the delegate that is assigned to the lostFocus event.
removeOnResize | Removes the delegate that is assigned to the resize event.
removeOnSelectedIndexChanged | Removes the delegate that is assigned to the selectedIndexChanged event.
setEnabled | Sets the enabled state of the element.
setItem | Updates the attributes of a particular item.
setItems | Sets the items in the list.
setItemSubmitValue | Updates the value attribute of an item.
setItemText | Sets the text attribute of the specified item.
setSelected | Sets the selected state of a particular item in the list.
setSelectedIndex | Sets the current selected index.
setSubmitName | Sets the name of the select box.


 DhSelectBox.addItem

DhSelectBox.addItem

Adds an item to the end of the list.

Syntax

public void addItem( String strText )

public void addItem( String strText, boolean fSelected )

public void addItem( String strText, boolean fSelected, String strValue )

Parameters

strText

The text for the new item.

fSelected

Sets the item's selected state. Set to true if the item is selected; otherwise, set to false.

strValue

Sets the VALUE attribute for this item. This is useful for Hypertext Transfer Protocol (HTTP) form submit strings.

Remarks

Adds an item to the end of the list.

See Also removeItem


 DhSelectBox.addOnGotFocus

DhSelectBox.addOnGotFocus

Assigns a delegate to the gotFocus event.

Syntax

public final void addOnGotFocus ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when the current element receives input focus.

See Also removeOnGotFocus


 DhSelectBox.addOnLostFocus

DhSelectBox.addOnLostFocus

Assigns a delegate to the lostFocus event.

Syntax

public final void addOnLostFocus ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when this element loses focus.

See Also removeOnLostFocus


 DhSelectBox.addOnResize

DhSelectBox.addOnResize

Assigns a delegate to the resize event.

Syntax

public final void addOnResize ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when this element is resized.

See Also removeOnResize


 DhSelectBox.addOnSelectedIndexChanged

DhSelectBox.addOnSelectedIndexChanged

Adds a delegate to the selectIndexChanged event.

Syntax

public final void addOnSelectedIndexChanged ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when the current selection of the element is changed.

See Also removeOnSelectedIndexChanged


 DhSelectBox.findString

DhSelectBox.findString

Finds the first item in the list that starts with the specified string.

Syntax

public int findString ( String s )

public final int findString ( String s, int startIndex )

Parameters

s

The string to match. Any string that begins with the specified characters is considered a match.

startIndex

The zero-based index of the item before the first item to be located. Set to -1 to search from the beginning of the list.

Return Value

Returns the zero-based index of the item found; returns -1 if no match is found.


 DhSelectBox.findStringExact

DhSelectBox.findStringExact

Finds the first item in the list that matches the specified string exactly.

Syntax

public int findStringExact ( String s )

public final int findStringExact ( String s, int startIndex )

Parameters

s

The string to match exactly.

startIndex

The zero-based index of the item before the first item to be located. Set to -1 to search from the beginning of the list.

Return Value

Returns the zero-based index of the item found; returns -1 if no match is found.


 DhSelectBox.focus

DhSelectBox.focus

Sets the input focus to this control.

Syntax

public void focus()


 DhSelectBox.getEnabled

DhSelectBox.getEnabled

Retrieves the enabled state of the element.

Syntax

public boolean getEnabled()

Return Value

Returns true if enabled; otherwise, returns false.

See Also setEnabled


 DhSelectBox.getItemCount

DhSelectBox.getItemCount

Retrieves the number of items currently in the list.

Syntax

public int getItemCount()

Return Value

Returns the number of items.


 DhSelectBox.getItemsSubmitValue

DhSelectBox.getItemsSubmitValue

Retrieves an array of text items corresponding to the submit value of the items in the list.

Syntax

public String[ ] getItemsSubmitValue()

Return Value

Returns an array of the items' submit values, or returns an empty array if there are no items.


 DhSelectBox.getItemsText

DhSelectBox.getItemsText

Retrieves an array of the text items in the list.

Syntax

public String[ ] getItemsText()

Return Value

Returns an array of the items in the list, or returns null if there are no items in the list.


 DhSelectBox.getItemSubmitValue

DhSelectBox.getItemSubmitValue

Retrieves the submit value for the item at index.

Syntax

public String getItemSubmitValue ( int index )

Parameters

index

The zero-based index of the item for which you want the submit value, or -1 for the currently selected item.

Return Value

Returns the submit value string for the item index.

Remarks

The submit value is used in HTTP form submissions.

See Also setItemSubmitValue


 DhSelectBox.getItemText

DhSelectBox.getItemText

Retrieves the text for the item at the specified index.

Syntax

public String getItemText ( int index )

Parameters

index

The zero-based index of the item for which you want the text, or -1 for the currently selected item.

Return Value

Returns the text of the item specified by index, or returns an empty string ("") if -1 is specified and no item is selected.

See Also setItemText


 DhSelectBox.getSelected

DhSelectBox.getSelected

Retrieves the current selected state of an item.

Syntax

public boolean getSelected ( int index )

Parameters

index

The zero-based index of the item to query.

Return Value

Returns true if the item is selected; otherwise, returns false. Also returns false if index does not correspond to an item in the list.

See Also setSelected


 DhSelectBox.getSelectedIndex

DhSelectBox.getSelectedIndex

Retrieves the index of the currently selected item.

Syntax

public int getSelectedIndex()

Return Value

Returns the zero-based index of the first selected item.

Remarks

If multiple items are selected in a DhListBox, this method retrieves the first selected item.


 DhSelectBox.getSelectedIndices

DhSelectBox.getSelectedIndices

Retrieves an array that contains the zero-based indices of all currently selected items.

Syntax

public int[ ] getSelectedIndices()

Return Value

Returns an integer array containing the zero-based indices of all currently selected items. In a single-selection list box, returns an array containing a single element. If there are no selected items in the list box, returns an empty array.


 DhSelectBox.getSelectedSubmitValue

DhSelectBox.getSelectedSubmitValue

Retrieves the value for the selected item.

Syntax

public String getSelectedSubmitValue()

Return Value

Returns the submit value of the first selected item, or returns an empty string ("") if no items are selected. If multiple items are selected, the submit value of the first selected item is returned.


 DhSelectBox.getSubmitName

DhSelectBox.getSubmitName

Retrieves the name of the select box.

Syntax

public String getSubmitName()

Return Value

Returns the name of the select box.

Remarks

The NAME attribute is used for HTTP form submissions.

See Also setSubmitName


 DhSelectBox.getText

DhSelectBox.getText

Retrieves the text for the currently selected item.

Syntax

public String getText()

Return Value

Returns the text of the currently selected item, or returns an empty string ("") if no items are selected. If multiple items are selected, the text of the first selected item is returned.


 DhSelectBox.insertItem

DhSelectBox.insertItem

Inserts an item into the list at the selected index.

Syntax

public void insertItem( int index, String strText )

public void insertItem( int index, String strText, boolean fSelected )

public void insertItem( int index, String strText, boolean fSelected, String strValue )

Parameters

index

The zero-based index at which to add new item. If less than 0 or greater than the current number of items, the item is added to the end of the list.

strText

The text for the new item.

fSelected

The selected state of the new item.

strValue

The VALUE attribute for this item (for HTTP form submissions).


 DhSelectBox.removeAll

DhSelectBox.removeAll

Removes all items from the control.

Syntax

public void removeAll()


 DhSelectBox.removeItem

DhSelectBox.removeItem

Removes an indexed item from the list.

Syntax

public void removeItem( int index )

Parameters

index

The zero-based index of the item to be removed.

See Also addItem


 DhSelectBox.removeOnGotFocus

DhSelectBox.removeOnGotFocus

Removes the delegate that is assigned to the onGotFocus event.

Syntax

public final void removeOnGotFocus ( EventHandler h )

Parameters

h

The EventHandler delegate specifying the event handler method.

Remarks

This event occurs when the current element receives input focus.


 DhSelectBox.removeOnLostFocus

DhSelectBox.removeOnLostFocus

Removes the delegate that is assigned to the lostFocus event.

Syntax

public final void removeOnLostFocus ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

This event occurs when the current element loses input focus.

See Also addOnLostFocus


 DhSelectBoxBox.removeOnResize

DhSelectBoxBox.removeOnResize

Removes the delegate that is assigned to the resize event.

Syntax

public final void removeOnResize ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

This event occurs when the current element is resized.

See Also addOnResize


 DhSelectBox.removeOnSelectedIndexChanged

DhSelectBox.removeOnSelectedIndexChanged

Removes the delegate that is assigned to the selectedIndexChanged event.

Syntax

final public void removeOnSelectedIndexChanged ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

This event occurs when the current selection of the element is changed.

See Also addOnSelectedIndexChanged


 DhSelectBox.setEnabled

DhSelectBox.setEnabled

Sets the enabled state of the element.

Syntax

public void setEnabled( boolean f )

Parameters

f

Set to true to enable the control; set to false to disable it.

See Also getEnabled


 DhSelectBox.setItem

DhSelectBox.setItem

Updates the attributes of a particular item.

Syntax

public void setItem( int index, String strText, boolean fSel, String strValue )

Parameters

index

The index of the item to be updated.

strText

The new text of the item.

fSel

The new selected state of the item.

strValue

The new VALUE attribute of the item (for HTTP form submissions).

Remarks

If index does not correspond to an item currently in the list, a new item with the specified attributes is added to the list.

Specifying a parameter as null leaves its value unchanged. Use an empty string ("") to clear a string value.


 DhSelectBox.setItems

DhSelectBox.setItems

Sets the items in the list.

Syntax

public final void setItems( String [ ] strings )

public final void setItems( String [ ] strings, boolean [ ] selected )

public final void setItems( String [ ] strings, boolean [ ] selected, String [ ] submitValues )

Parameters

strings

An array of String items set into the list.

selected

An array of boolean items specifying if the corresponding items are selected.

submitValues

An array of String items set as the submit values of the corresponding items.

Remarks

All items in the list are replaced.


 DhSelectBox.setItemSubmitValue

DhSelectBox.setItemSubmitValue

Updates the value attribute of an item.

Syntax

public void setItemSubmitValue( int index, String stringValue )

Parameters

index

The index of the referenced item.

stringValue

The new item value string.

Exceptions

WFCInvalidArgumentException thrown if the index is not in the list.

See Also getItemSubmitValue


 DhSelectBox.setItemText

DhSelectBox.setItemText

Sets the text attribute of the specified item.

Syntax

public void setItemText( int index, String strText )

Parameters

index

The zero-based index of the item.

strText

The new text for the item.

Exceptions

WFCInvalidArgumentException thrown if the index is outside the list's range.

See Also getItemText


 DhSelectBox.setSelected

DhSelectBox.setSelected

Sets the selected state of a particular item in the list.

Syntax

public void setSelected( int index, boolean value )

Parameters

index

The zero-based index of the item to update.

value

Set to true to select; set to false to clear.

Remarks

If the list is enabled for multiple selections, this item will not affect other selected items. Otherwise, other selections will be cleared.

See Also getSelected


 DhSelectBox.setSelectedIndex

DhSelectBox.setSelectedIndex

Sets the current selected index.

Syntax

public void setSelectedIndex( int index )

Parameters

index

The zero-based index of the item to select.


 DhSelectBox.setSubmitName

DhSelectBox.setSubmitName

Sets the name of the select box.

Syntax

public void setSubmitName( String strName )

Parameters

strName

The name to be transmitted for the select box.

Exceptions

WFCInvalidArgumentException thrown if strName is not a valid name (contains spaces).

Remarks

This is used for HTTP form submissions and represents the HTML NAME attribute.

See Also getSubmitName


DhStyle Class

Represents a collection of properties that can be freely applied to any element.

Component
  |
  +--DhStyleBase
        |
        +--DhStyle

package com.ms.wfc.html

public class DhStyle
extends DhStyleBase

Remarks

The fundamental usage scenario for this class is to create instances of this class and apply them using the DhElement.setStyle method.


 DhStyle Methods

DhStyle Methods

Constructors | Description
DhStyle | Creates a DhStyle object.

Methods | Description
getName | Retrieves the underlying name for this style object as seen by the HTML object.
setName | Sets the underlying name for the style object as seen by the HTML object.


 DhStyle.DhStyle

DhStyle.DhStyle

Creates a DhStyle object.

Syntax

public DhStyle()

public DhStyle( String name )

Parameters

name

The name of the style to use for underlying HTML generation.

Remarks

Use the constructor with the name parameter to name your style and control the underlying HTML code that is generated by this object.

Note This is completely handled for you in the default (empty) constructor.


 DhStyle.getName

DhStyle.getName

Retrieves the underlying name for this style object as seen by the HTML object.

Syntax

public String getName()

Return Value

Returns the string name of the style rule.

Remarks

This is an advanced feature and is not part of normal usage scenarios.

See Also setName


 DhStyle.setName

DhStyle.setName

Sets the underlying name for the style object as seen by the HTML object.

Syntax

public void setName( String name )

Parameters

name

The string name of the style rule.

Remarks

This is an advanced feature and is not part of normal usage scenarios.

See Also getName


DhStyleBase Class

Provides the superclass for classes that support styles, such as DhStyle and DhElement objects.

Component
  |
  +--DhStyleBase

package com.ms.wfc.html

public abstract class DhStyleBase
extends Component

Remarks

Classes that extend DhStyleBase have certain typographical and visual properties, such as colors and fonts. This class is abstract and therefore cannot be instantiated.

See Also DhStyle, DhElement


 DhStyleBase Methods

DhStyleBase Methods

Methods | Description
dispose | Frees all resources associated with this element.
getBackColor | Retrieves the background color property.
getBorderInfo | Retrieves the DhBorderInfo class with information about the current border state.
getBounds | Retrieves the position and size of the element.
getClipRect | Retrieves the current clipping rectangle.
getCSSStyleInt | Retrieves the style number of the cascading style sheet.
getCSSStyleString | Retrieves the style of the cascading style sheet.
getCSSStyleText | Retrieves the underlying text string in the cascading style sheet.
getCursor | Retrieves the cursor style for this element.
getCursorString | Retrieves the cursor style for this element.
getFont | Retrieves the current font.
getForeColor | Retrieves the text foreground color property.
getHeightUnit | Retrieves the height unit.
getLeftUnit | Retrieves the left position unit.
getLocation | Retrieves the position (or location) of the element.
getMarginWidthInfo | Retrieves a DhMarginWidthInfo class describing the current margin settings for this element.
getPaddingWidthInfo | Retrieves a DhPaddingWidthInfo class describing the current padding width settings for this element.
getPosAbsolute | Determines whether the position style in the cascading style sheet is set to absolute.
getPosRelative | Determines whether the position style in the cascading style sheet is set to relative.
getSize | Retrieves the size of the element.
getTextAlign | Retrieves the current text alignment setting.
getTextVerticalAlign | Retrieves the current text alignment setting.
getTopUnit | Retrieves the top position unit.
getVisible | Retrieves the visibility state of this element.
getWidthUnit | Retrieves the width unit.
getZIndex | Retrieves the z-index (layering) ordering of this element with respect to its container.
hasStyleText | Determines whether an underlying cascading style sheet text string exists for the style.
invoke | Executes the specified delegate on the thread that owns this element's underlying peer.
resetBackColor | Resets the background color to the default inherited setting.
resetBorder | Clears the current border settings.
resetClip | Resets the clipping region to the default inherited setting.
resetCursor | Resets the current cursor style to the default.
resetFont | Clears any font settings from the element and allows them to be inherited.
resetForeColor | Resets the foreground color to the default inherited setting.
resetLocation | Clears the location and allows the element to be positioned by the layout engine (usually Microsoft Internet Explorer).
resetMargin | Clears the current margin settings.
resetPadding | Clears the current padding settings.
resetSize | Clears any size attributes and allows the element to be sized by the layout engine (usually Microsoft Internet Explorer).
resetTextAlign | Clears any existing text alignment property.
resetTextVerticalAlign | Clears any existing vertical text alignment property.
resetZIndex | Clears any z-index setting.
setBackColor | Sets the background color of the element.
setBorder | Sets border values for all sides of the item.
setBorderColor | Sets the border color to the specified Color value.
setBorderInfo | Updates the border styles for this element.
setBorderStyle | Sets the style to specified value constant.
setBorderWidth | Sets the border width to the value and unit specified.
setBounds | Sets the position and size of the element.
setClip | Sets the clipping rectangle.
setCSSStyle | Sets the style by its cascading style sheet's string value.
setCSSStyleInt | Sets the style by its cascading style sheet's integer value.
setCSSStyleText | Modifies the read-only style settings of an element on the page.
setCursor | Sets the cursor style for this element.
setFont | Sets the font value for this element.
setForeColor | Sets the text color (and other foreground objects).
setHeightUnit | Sets the height of the element.
setLeftUnit | Sets the left position of the element.
setLocation | Sets the position of the element.
setMarginWidth | Sets the width of all the margins to the specified value.
setMarginWidthInfo | Sets the margins widths.
setPaddingWidth | Sets the width of all paddings to the specified value.
setPaddingWidthInfo | Sets the padding widths according to those in the DhPaddingWidthInfo class.
setPosAbsolute | Sets the cascading style sheet's position style to absolute.
setPosRelative | Sets the cascading style sheet's position style to relative.
setSize | Sets the size of the element.
setTextAlign | Sets the text alignment style.
setTextVerticalAlign | Sets the text vertical alignment style.
setTopUnit | Sets the top position of the element.
setVisible | Sets the visiblility of the element.
setWidthUnit | Sets the width of the element.
setZIndex | Sets the z-index (layering) order of this element relative to the other elements in its container.
shouldPersistBackColor | Determines whether the background color will be persisted.
shouldPersistBorder | Determines whether the border settings will be persisted.
shouldPersistClip | Determines whether the clipping region should be persisted.
shouldPersistFont | Determines whether the font settings will be persisted.
shouldPersistForeColor | Determines whether the foreground color will be persisted.
shouldPersistMargin | Determines whether the margin settings will be persisted.
shouldPersistPadding | Determines whether the padding settings will be persisted.


 DhStyleBase.dispose

DhStyleBase.dispose

Frees all resources associated with this element.

Syntax

public void dispose()

Remarks

This method might not be called at run time. Any resources used by the element should be set up to be released when the element is released for garbage collection. Inheriting classes should always call super.dispose.


 DhStyleBase.getBackColor

DhStyleBase.getBackColor

Retrieves the background color property.

Syntax

final public Color getBackColor()

Return Value

Returns a Color object with the current background color.

See Also setBackColor


 DhStyleBase.getBorderInfo

DhStyleBase.getBorderInfo

Retrieves the DhBorderInfo class with information about the current border state.

Syntax

public DhBorderInfo getBorderInfo()

Return Value

Returns the DhBorderInfo border information class.

See Also setBorderInfo


 DhStyleBase.getBounds

DhStyleBase.getBounds

Retrieves the position and size of the element.

Syntax

final public Rectangle getBounds()

Return Value

Returns the location of the element as a Rectangle object.

See Also getWidthUnit, getHeightUnit, getTopUnit, getLeftUnit, setBounds


 DhStyleBase.getClipRect

DhStyleBase.getClipRect

Retrieves the current clipping rectangle.

Syntax

public Rectangle getClipRect()

Return Value

Returns a Rectangle object with the current clipping rectangle values. If the values are either undefined or defined as "auto" using the String parameter of setClip, -1 is returned for all fields of the Rectangle object.


 DhStyleBase.getCSSStyleInt

DhStyleBase.getCSSStyleInt

Retrieves the style number of the cascading style sheet.

Syntax

public int getCSSStyleInt( String strStyleKey )

Parameters

strStyleKey

The name of the style to get.

Return Value

Returns the style number of the cascading style sheet.

Remarks

Calling this method directly is not part of the normal usage of this package. You should use more specific style methods.

See Also setCSSStyleInt


 DhStyleBase.getCSSStyleString

DhStyleBase.getCSSStyleString

Retrieves the style of the cascading style sheet.

Syntax

public String getCSSStyleString( String strStyleKey )

Parameters

strStyleKey

The name of the style to retrieve.

Return Value

Returns the style string.

Remarks

Calling this method directly is not part of the normal usage of this package. You should use more specific style methods.


 DhStyleBase.getCSSStyleText

DhStyleBase.getCSSStyleText

Retrieves the underlying text string in the cascading style sheet.

Syntax

public String getCSSStyleText()

Return Value

Returns the underlying cascading style sheet text string for this object.

Remarks

This is a very advanced feature of the library and is not part of normal usage scenarios.

See Also setCSSStyleText


 DhStyleBase.getCursor

DhStyleBase.getCursor

Retrieves the cursor style for this element.

Syntax

public int getCursor()

Return Value

Returns the current cursor type defined in the DhCursor class.

See Also setCursor


 DhStyleBase.getCursorString

DhStyleBase.getCursorString

Retrieves the cursor style for this element.

Syntax

public String getCursorString()

Return Value

Returns the current cursor type.

Remarks

For details, see the cursor entry in the CSS Attributes Reference section of the Internet Client SDK. This can be found in the Platform SDK section of the MSDN compact disc under DHTML References in Internet/Intranet/Extranet Services. It can also be found in the MSDN online SDK documentation (http://www.microsoft.com/msdn/sdk/inetsdk/help).


 DhStyleBase.getFont

DhStyleBase.getFont

Retrieves the current font.

Syntax

public Font getFont()

Return Value

Returns a Font object with the current font.

See Also setFont


 DhStyleBase.getForeColor

DhStyleBase.getForeColor

Retrieves the text foreground color property.

Syntax

final public Color getForeColor()

Return Value

Returns the current foreground Color object.

See Also setForeColor


 DhStyleBase.getHeightUnit

DhStyleBase.getHeightUnit

Retrieves the height unit.

Syntax

final public int getHeightUnit()

Return Value

Returns one of DhUnits constants to express the units of measurement.

See Also getBounds, setHeightUnit


 DhStyleBase.getLeftUnit

DhStyleBase.getLeftUnit

Retrieves the left position unit.

Syntax

final public int getLeftUnit()

Return Value

Returns one of DhUnits constants to express the units of measurement.

See Also getBounds, setLeftUnit


 DhStyleBase.getLocation

DhStyleBase.getLocation

Retrieves the position (or location) of the element.

Syntax

public Point getLocation()

Return Value

Returns the location of the element.

See Also getTopUnit, getLeftUnit, setLocation


 DhStyleBase.getMarginWidthInfo

DhStyleBase.getMarginWidthInfo

Retrieves a DhMarginWidthInfo class describing the current margin settings for this element.

Syntax

public DhMarginWidthInfo getMarginWidthInfo()

Return Value

Returns a DhMarginWidthInfo class.

See Also setMarginWidthInfo


 DhStyleBase.getPaddingWidthInfo

DhStyleBase.getPaddingWidthInfo

Retrieves a DhPaddingWidthInfo class describing the current padding width settings for this element.

Syntax

public DhPaddingWidthInfo getPaddingWidthInfo()

Return Value

Returns a DhPaddingWidthInfo class.

See Also setPaddingWidthInfo


 DhStyleBase.getPosAbsolute

DhStyleBase.getPosAbsolute

Determines whether the position style in the cascading style sheet is set to absolute.

Syntax

public boolean getPosAbsolute()

Return Value

Returns true if the position style is set to absolute; otherwise, returns false.

Remarks

Absolute positioning sets the element at an offset from the origin of its first positioned parent by the left and top settings.

See Also getPosRelative, setPosAbsolute, setPosRelative


 DhStyleBase.getPosRelative

DhStyleBase.getPosRelative

Determines whether the position style in the cascading style sheet is set to relative.

Syntax

public boolean getPosRelative()

Return Value

Returns true if the position style is set to relative; otherwise, returns false.

Remarks

Relative positioning sets the element at an offset from where it would normally be positioned in the HTML layout by the left and top settings.

See Also getPosAbsolute, setPosAbsolute, setPosRelative


 DhStyleBase.getSize

DhStyleBase.getSize

Retrieves the size of the element.

Syntax

public Point getSize()

Return Value

Returns the size of the element as a Point object.

See Also getWidthUnit, getHeightUnit, setSize


 DhStyleBase.getTextAlign

DhStyleBase.getTextAlign

Retrieves the current text alignment setting.

Syntax

public int getTextAlign()

Return Value

Returns the current alignment as one of the following DhAlignment values:

  • LEFT (default)
  • RIGHT
  • CENTER
  • JUSTIFY

See Also setTextAlign


 DhStyleBase.getTextVerticalAlign

DhStyleBase.getTextVerticalAlign

Retrieves the current text alignment setting.

Syntax

public int getTextVerticalAlign()

Return Value

Returns the current alignment as one of the following DhAlignment values:

  • BASELINE (default)
  • SUBSCRIPT
  • SUPERSCRIPT

See Also setTextVerticalAlign


 DhStyleBase.getTopUnit

DhStyleBase.getTopUnit

Retrieves the top position unit.

Syntax

final public int getTopUnit()

Return Value

Returns one of DhUnits constants to express the units of measurement.

See Also getBounds, setTopUnit


 DhStyleBase.getVisible

DhStyleBase.getVisible

Retrieves the visibility state of this element.

Syntax

public boolean getVisible()

Return Value

Returns true if element is visible; otherwise, returns false.

See Also setVisible


 DhStyleBase.getWidthUnit

DhStyleBase.getWidthUnit

Retrieves the width unit.

Syntax

final public int getWidthUnit()

Return Value

Returns one of DhUnits constants to express the units of measurement.

See Also getBounds, setWidthUnit


 DhStyleBase.getZIndex

DhStyleBase.getZIndex

Retrieves the z-index (layering) ordering of this element with respect to its container.

Syntax

public int getZIndex()

Return Value

Returns the z-index value set by setZIndex.

See Also setZIndex


 DhStyleBase.hasStyleText

DhStyleBase.hasStyleText

Determines whether an underlying cascading style sheet text string exists for the style.

Syntax

protected boolean hasStyleText()

Return Value

Returns true if style text exists; otherwise, returns false.

Remarks

Calling this method directly is not part of the normal usage of this package. You should use the more specific style methods instead.


 DhStyleBase.invoke

DhStyleBase.invoke

Executes the specified delegate on the thread that owns this element's underlying peer.

Syntax

public final Object invoke( Delegate method )

public final Object invoke( Delegate method, Object args[] )

Parameters

method

A delegate that contains the method to be called in the element's thread context. The delegate can be an EventHandler object, in which case the sender parameter will contain this element, and the event parameter will contain Event.EMPTY. The delegate can also be a MethodInvoker object or any other delegate that takes a void parameter list. A call to an EventHandler or MethodInvoker delegate is faster than a call to another type of delegate. When using the form of invoke that takes an args parameter, this delegate must point to a method that contains the same number and type of arguments specified in args.

args

An array of objects to pass as arguments to the specified method. This can be null if no arguments are needed.

Return Value

Returns the return value of the invoked delegate; returns null if the delegate has no return value.

Exceptions

WFCSystemException thrown if the element's thread is blocked.

Remarks

Exceptions that are raised during the call are propagated back to the caller.


 DhStyleBase.resetBackColor

DhStyleBase.resetBackColor

Resets the background color to the default inherited setting.

Syntax

final public void resetBackColor()

See Also getBackColor


 DhStyleBase.resetBorder

DhStyleBase.resetBorder

Clears the current border settings.

Syntax

public void resetBorder()


 DhStyleBase.resetClip

DhStyleBase.resetClip

Resets the clipping region to the default inherited setting.

Syntax

public void resetClip()


 DhStyleBase.resetCursor

DhStyleBase.resetCursor

Resets the current cursor style to the default.

Syntax

public void resetCursor()

See Also getCursor


 DhStyleBase.resetFont

DhStyleBase.resetFont

Clears any font settings from the element and allows them to be inherited.

Syntax

public void resetFont()

See Also getFont


 DhStyleBase.resetForeColor

DhStyleBase.resetForeColor

Resets the foreground color to the default inherited setting.

Syntax

final public void resetForeColor()

See Also getForeColor


 DhStyleBase.resetLocation

DhStyleBase.resetLocation

Clears the location and allows the element to be positioned by the layout engine (usually Microsoft Internet Explorer).

Syntax

public void resetLocation()

See Also getLocation


 DhStyleBase.resetMargin

DhStyleBase.resetMargin

Clears the current margin settings.

Syntax

public void resetMargin()


 DhStyleBase.resetPadding

DhStyleBase.resetPadding

Clears the current padding settings.

Syntax

public void resetPadding()


 DhStyleBase.resetSize

DhStyleBase.resetSize

Clears any size attributes and allows the element to be sized by the layout engine (usually Microsoft Internet Explorer).

Syntax

public void resetSize()

See Also getSize


 DhStyleBase.resetTextAlign

DhStyleBase.resetTextAlign

Clears any existing text alignment property.

Syntax

public void resetTextAlign()

See Also getTextAlign


 DhStyleBase.resetTextVerticalAlign

DhStyleBase.resetTextVerticalAlign

Clears any existing vertical text alignment property.

Syntax

public void resetTextVerticalAlign()

See Also getTextVerticalAlign


 DhStyleBase.resetZIndex

DhStyleBase.resetZIndex

Clears any z-index setting.

Syntax

public void resetZIndex()

See Also getZIndex


 DhStyleBase.setBackColor

DhStyleBase.setBackColor

Sets the background color of the element.

Syntax

final public void setBackColor( Color color )

Parameters

color

The Color object with the new background color for this element.

Remarks

If never set, the background color of the container is used.

See Also getBackColor


 DhStyleBase.setBorder

DhStyleBase.setBorder

Sets border values for all sides of the item.

Syntax

public void setBorder( int borderStyle, int borderWidth, int borderWidthUnit, Color borderColor )

Parameters

borderStyle

The border style. This must be one of the DhBorderStyle constants.

borderWidth

The integer border width.

borderWidthUnit

The border width unit. This must be one of the DhUnits constants.

borderColor

The border color.

See Also DhBorderStyle, DhUnits, Color


 DhStyleBase.setBorderColor

DhStyleBase.setBorderColor

Sets the border color to the specified Color value.

Syntax

public void setBorderColor( int borderMask, Color color )

public void setBorderColor( Color color )

Parameters

borderMask

The border sides you want to set, which can be any combination of the constants in DhBorders.

color

A Color object to be the new border color.


 DhStyleBase.setBorderInfo

DhStyleBase.setBorderInfo

Updates the border styles for this element.

Syntax

public void setBorderInfo( DhBorderInfo biNew )

Parameters

biNew

The DhBorderInfo class containing the new state of the borders. String values are used over integer settings in the structure.

See Also getBorderInfo


 DhStyleBase.setBorderStyle

DhStyleBase.setBorderStyle

Sets the style to specified value constant.

Syntax

public void setBorderStyle( int borderMask, int borderStyle )

public void setBorderStyle( int borderStyle )

Parameters

borderMask

The border sides you want to set, which can be any combination of the constants in DhBorders.

borderStyle

The border styles you want to set, which can be any combination of the constants in DhBorderStyle.


 DhStyleBase.setBorderWidth

DhStyleBase.setBorderWidth

Sets the border width to the value and unit specified.

Syntax

public void setBorderWidth( int borderMask, int nWidth, int nUnitKey )

public void setBorderWidth( int nWidth, int nUnitKey )

Parameters

borderMask

The border sides you want to set, which can be any combination of the constants in DhBorders.

nWidth

The numerical width of the border.

nUnitKey

The unit key to assign to the width. For values, see DhUnits.


 DhStyleBase.setBounds

DhStyleBase.setBounds

Sets the position and size of the element.

Syntax

final public void setBounds( int x, int y, int width, int height )

final public void setBounds( Rectangle rect )

Parameters

x

The left coordinate of the position.

y

The top coordinate of the position.

width

The new width of the element.

height

The new height of the element.

rect

The position and dimensions of the element.

See Also setWidthUnit, setHeightUnit, setTopUnit, setLeftUnit, setSize, setLocation, getBounds


 DhStyleBase.setClip

DhStyleBase.setClip

Sets the clipping rectangle.

Syntax

public void setClip( Rectangle r )

public void setClip( String strClip )

Parameters

r

The clipping Rectangle object.

strClip

The clip string. This can be in the format of "rect( top, right, bottom, left )" where top, left, bottom or right can be either "auto" or a length measurement.

Remarks

Regions outside the clipping rectangle will not be drawn.


 DhStyleBase.setCSSStyle

DhStyleBase.setCSSStyle

Sets the style by its cascading style sheet's string value.

Syntax

public void setCSSStyle( String strStyleKey, String value )

Parameters

strStyleKey

The name of the style to set.

value

A string value.

Remarks

Calling this method directly is not part of the normal usage of this package. You should use the more specific style methods (for example, DhStyleBase.setFont).


 DhStyleBase.setCSSStyleInt

DhStyleBase.setCSSStyleInt

Sets the style by its cascading style sheet's integer value.

Syntax

public void setCSSStyleInt( String strStyleKey, int value )

Parameters

strStyleKey

The name of the style to set.

value

An integer value.

Remarks

Calling this method directly is not part of the normal usage of this package. You should use more specific style methods (for example, DhStyleBase.setFont).

See Also getCSSStyleInt


 DhStyleBase.setCSSStyleText

DhStyleBase.setCSSStyleText

Modifies the read-only style settings of an element on the page.

Syntax

protected void setCSSStyleText( String strStyleName, String strValue, boolean fCaseSensitive )

Parameters

strStyleName

The string name of the style to modify. This is the actual cascading style sheet's style, not the style element property.

strValue

The new value to set.

fCaseSensitive

Set to true to use case-sensitive search; otherwise, set to false.

Remarks

For details on read-only styles, see the Internet Client SDK documentation.

See Also getCSSStyleText


 DhStyleBase.setCursor

DhStyleBase.setCursor

Sets the cursor style for this element.

Syntax

public void setCursor( int nCursor )

public void setCursor( String strCursor )

Parameters

nCursor

The DhCursor cursor type.

strCursor

The name of the desired cursor.

See Also getCursor


 DhStyleBase.setFont

DhStyleBase.setFont

Sets the font value for this element.

Syntax

public void setFont( Font font )

Parameters

font

The font to apply as a Font object.

See Also getFont


 DhStyleBase.setForeColor

DhStyleBase.setForeColor

Sets the text color (and other foreground objects).

Syntax

final public void setForeColor( Color color )

Parameters

color

The new foreground color as a Color object.

See Also getForeColor


 DhStyleBase.setHeightUnit

DhStyleBase.setHeightUnit

Sets the height of the element.

Syntax

public void setHeightUnit( int h, int unit )

Parameters

h

The height value.

unit

One of DhUnits constants to express the units of measurement.

See Also setBounds, getHeightUnit


 DhStyleBase.setLeftUnit

DhStyleBase.setLeftUnit

Sets the left position of the element.

Syntax

final public void setLeftUnit( int v, int unit )

Parameters

v

The left position value.

unit

One of DhUnits constants to express the units of measurement.

See Also setBounds, getLeftUnit


 DhStyleBase.setLocation

DhStyleBase.setLocation

Sets the position of the element.

Syntax

public void setLocation( int x, int y )

public void setLocation( Point pt )

Parameters

x

The left coordinate of the position.

y

The top coordinate of the position.

pt

The new location of the element.

See Also setTopUnit, setLeftUnit, getLocation


 DhStyleBase.setMarginWidth

DhStyleBase.setMarginWidth

Sets the width of all the margins to the specified value.

Syntax

public void setMarginWidth( int nWidth, int nUnit )

public void setMarginWidth( int nMarginMask, int nWidth, int nUnit )

Parameters

nWidth

The width of the margins.

nUnit

The unit of the margins widths. For margin width values, see DhUnits.

nMarginMask

A combination of the margins you want apply. For margin mask values, see DhMargins.


 DhStyleBase.setMarginWidthInfo

DhStyleBase.setMarginWidthInfo

Sets the margins widths.

Syntax

public void setMarginWidthInfo( DhMarginWidthInfo mwi )

Parameters

mni

The DhMarginWidthInfo margin width settings.

See Also getMarginWidthInfo


 DhStyleBase.setPaddingWidth

DhStyleBase.setPaddingWidth

Sets the width of all paddings to the specified value.

Syntax

public void setPaddingWidth( int nWidth, int nUnit )

public void setPaddingWidth( int nPaddingMask, int nWidth, int nUnit )

Parameters

nWidth

The padding widths.

nUnit

The DhUnits padding width unit.

nPaddingMask

A combination of the paddings you want to apply. For details, see DhPaddings.


 DhStyleBase.setPaddingWidthInfo

DhStyleBase.setPaddingWidthInfo

Sets the padding widths according to those in the DhPaddingWidthInfo class.

Syntax

public void setPaddingWidthInfo( DhPaddingWidthInfo mwi )

Parameters

mwi

The new padding width settings. For appropriate values, see DhPaddingWidthInfo.

See Also getPaddingWidthInfo


 DhStyleBase.setPosAbsolute

DhStyleBase.setPosAbsolute

Sets the cascading style sheet's position style to absolute.

Syntax

public void setPosAbsolute()

Remarks

Absolute positioning sets the element at an offset from the origin of its first positioned parent by the cascading style sheet's left and top settings.

See Also getPosRelative, getPosAbsolute, setPosRelative


 DhStyleBase.setPosRelative

DhStyleBase.setPosRelative

Sets the cascading style sheet's position style to relative.

Syntax

public void setPosRelative()

Remarks

Relative positioning sets the element at an offset from where it would typically be positioned in the HTML layout by the cascading style sheet's left and top settings.

See Also getPosAbsolute, setPosAbsolute, getPosRelative


 DhStyleBase.setSize

DhStyleBase.setSize

Sets the size of the element.

Syntax

public void setSize( int w, int h )

public void setSize( Point pt )

Parameters

width

The new width of the element.

height

The new height of the element.

pt

The new width and height of the element.

Exceptions

WFCInvalidArgumentException thrown if either width or height is less than 0.

See Also setWidthUnit, setHeightUnit, getSize


 DhStyleBase.setTextAlign

DhStyleBase.setTextAlign

Sets the text alignment style.

Syntax

public void setTextAlign( int nAlignment )

Parameters

nAlignment

The new alignment setting. This can be one of following values defined in DhAlignment:

  • LEFT (default)
  • RIGHT
  • CENTER
  • JUSTIFY

Exceptions

WFCInvalidArgumentException thrown if nAlignment is not one of the correct values.

See Also getTextAlign


 DhStyleBase.setTextVerticalAlign

DhStyleBase.setTextVerticalAlign

Sets the text vertical alignment style.

Syntax

public void setTextVerticalAlign( int nVerticalAlign )

Parameters

nVerticalAlign

The new alignment setting. This can be one of following values found in DhAlignment:

  • BASELINE (default)
  • SUBSCRIPT
  • SUPERSCRIPT

Exceptions

WFCInvalidArgumentException thrown if nAlignment is not one of the above values.

See Also getTextVerticalAlign


 DhStyleBase.setTopUnit

DhStyleBase.setTopUnit

Sets the top position of the element.

Syntax

final public void setTopUnit( int t, int unit )

Parameters

t

The top position value.

unit

One of DhUnits constants to express the units of measurement.

See Also setBounds, getTopUnit


 DhStyleBase.setVisible

DhStyleBase.setVisible

Sets the visiblility of the element.

Syntax

public void setVisible( boolean visible )

Parameters

visible

Set to true to allow the element to be rendered; otherwise, set to false.

See Also getVisible


 DhStyleBase.setWidthUnit

DhStyleBase.setWidthUnit

Sets the width of the element.

Syntax

public void setWidthUnit( int w, int unit )

Parameters

w

The width value.

unit

One of DhUnits constants to express the units of measurement.

See Also getBounds, getWidthUnit


 DhStyleBase.setZIndex

DhStyleBase.setZIndex

Sets the z-index (layering) order of this element relative to the other elements in its container.

Syntax

public void setZIndex( int i )

Parameters

i

The z-index value of this element.

Remarks

The element with the highest number z-index in any specified container is displayed over all other elements. Elements with lower numbers are progressively farther back in the display layering.

See Also getZIndex


 DhStyleBase.shouldPersistBackColor

DhStyleBase.shouldPersistBackColor

Determines whether the background color will be persisted.

Syntax

public boolean shouldPersistBackColor()

Return Value

Returns true if the background color is set to be persisted; otherwise, returns false.


 DhStyleBase.shouldPersistBorder

DhStyleBase.shouldPersistBorder

Determines whether the border settings will be persisted.

Syntax

public boolean shouldPersistBorder()

Return Value

Returns true if the border settings will be persisted; otherwise, returns false.


 DhStyleBase.shouldPersistClip

DhStyleBase.shouldPersistClip

Determines whether the clipping region should be persisted.

Syntax

public boolean shouldPersistClip()

Return Value

Returns true if the clipping region is set to be persisted; otherwise, returns false.


 DhStyleBase.shouldPersistFont

DhStyleBase.shouldPersistFont

Determines whether the font settings will be persisted.

Syntax

public boolean shouldPersistFont()

Return Value

Returns true if the font settings will be persisted; otherwise, returns false.


 DhStyleBase.shouldPersistForeColor

DhStyleBase.shouldPersistForeColor

Determines whether the foreground color will be persisted.

Syntax

public boolean shouldPersistForeColor()

Return Value

Returns true if the foreground color is set to be persisted; otherwise, returns false.


 DhStyleBase.shouldPersistMargin

DhStyleBase.shouldPersistMargin

Determines whether the margin settings will be persisted.

Syntax

public boolean shouldPersistMargin()

Return Value

Returns true if the margin settings will be persisted; otherwise, returns false.


 DhStyleBase.shouldPersistPadding

DhStyleBase.shouldPersistPadding

Determines whether the padding settings will be persisted.

Syntax

public boolean shouldPersistPadding()

Return Value

Returns true if the padding settings will be persisted; otherwise, returns false.


 DhStyleBase Fields

DhStyleBase Fields

Fields | Description
UNINITIALIZED | Indicates that the style has not been set.


 DhStyleBase.UNINITIALIZED

DhStyleBase.UNINITIALIZED

Indicates that the style has not been set.

Syntax

public final int UNINITIALIZED;


DhSubmitButton Class

Implements a submit button control for HTTP form submission.

Component
  |
  +--DhStyleBase
    |
    +--DhElement
      |
      +--DhButtonBase
        |
        +--DhSubmitButton

package com.ms.wfc.html

public class DhSubmitButton
extends DhButtonBase

Remarks

The submit button invokes the URL specified in the form's ACTION attribute. Adding a DhSubmitButton to a DhForm object causes the DhForm to represent an HTML form element.

When a form is submitted to the server, the name and value of each of the form's controls are appended onto a single string and submitted to the server. For more information on Form elements, including reset and submit buttons, see the Internet Client SDK documention. This can be found in the Platform SDK section of the MSDN compact disc under Internet/Intranet/Extranet Services. It can also be found in the MSDN online SDK documentation (http://www.microsoft.com/msdn/sdk/inetsdk/help).

See Also DhForm, DhResetButton


 DhSubmitButton Methods

DhSubmitButton Methods

Constructors | Description
DhSubmitButton | Creates a DhSubmitButton object.

Methods | Description
getText | Retrieves the button's current text caption.
setText | Sets the button caption.


 DhSubmitButton.DhSubmitButton

DhSubmitButton.DhSubmitButton

Creates a DhSubmitButton object.

Syntax

public DhSubmitButton()

public DhSubmitButton( String strCaption )

Parameters

strCaption

The initial caption for the new button.

Remarks

The default constructor creates a DhSubmitButton with "Submit" as its caption string.


 DhSubmitButton.getText

DhSubmitButton.getText

Retrieves the button's current text caption.

Syntax

public String getText()

Return Value

Returns the button caption.

See Also setText


 DhSubmitButton.setText

DhSubmitButton.setText

Sets the button caption.

Syntax

public void setText( String strCaption )

Parameters

strCaption

The new caption string.

See Also getText


DhTable Class

Creates a table element that can be populated with rows and columns.

Component
  |
  +--DhStyleBase
     |
     +--DhElement
        |
        +--DhBaseContainer
           |
           +--DhTable

package com.ms.wfc.html

final public class DhTable
extends DhBaseContainer


 DhTable Methods

DhTable Methods

Constructors | Description
DhTable | Creates a DhTable object.

Methods | Description
add | Adds a row to this table either at the top or at the bottom or before or after another row, depending on the DhInsertOptions insertFlag parameter.
addOnReadyStateChange | Assigns a delegate to the readyStateChange event.
getAutoHeader | Retrieves the current header generation mode.
getBodyCell | Retrieves the cell at the specified location from the table body.
getBodyRow | Retrieves the specified row.
getBodyRowCount | Retrieves the number of body rows in the table.
getBodyRows | Retrieves an array of all rows in the table body (excluding the header and footer).
getBorder | Retrieves the default (non-CSS) border thickness of the table.
getCellPadding | Retrieves the table CELLPADDING attribute.
getCellSpacing | Retrieves the table CELLSPACING attribute.
getDataBindings | Retrieves the DataBinding objects that are associated with elements in the template repeater row.
getDataMember | Retrieves the currently selected data member.
getDataSource | Retrieves the currently set com.ms.wfc.data.IDataSource object.
getFooterRow | Retrieves the footer row if there is one.
getHeaderRow | Retrieves the header row if there is one.
getPageSize | Retrieves the current data page size, in rows, to display in a databound operation.
getRangeEnd | Retrieves the end of the current record range.
getRangeStart | Retrieves the beginning of the current record range.
getRepeaterRow | Retrieves the current template repeater row.
getTotalRowCount | Retrieves the number of rows in the table, including header and footer rows.
refresh | Refreshes the table's data if it is bound to the document.
removeAll | Removes all rows from the table.
removeBodyRows | Removes rows that are not header or footer rows from the table.
removeOnReadyStateChange | Removes the delegate that is assigned to the onReadyStateChange event.
setAlign | Sets the alignment of the table.
setAutoHeader | Enables or disables automatic generation of column headers.
setBorder | Sets the default (non-CSS) border width for this table.
setCellPadding | Set the table's CELLPADDING attribute.
setCellSpacing | Sets the table's CELLSPACING attribute.
setDataBindings | Sets the DataBinding objects that are to be associated with elements in the template repeater row.
setDataMember | Sets the currently selected data member to retrieve.
setDataSource | Sets the data source for this table.
setFooterRow | Sets the footer row to the DhRow element specified.
setHeaderRow | Sets the header row to the DhRow specified.
setPageSize | Sets the display page size for this table when bound to data.
setRecordRange | Sets the range of records that will be displayed in the table.
setRepeaterRow | Specifies the template row that will be cloned for each record of data in the recordset.
showNextPage | Displays the next page of data in the table.
showPreviousPage | Displays the previous page of data in the table.


 DhTable.add

DhTable.add

Adds a row to this table either at the top or at the bottom or before or after another row, depending on the DhInsertOptions insertFlag parameter.

Syntax

final public void add( DhRow row, DhRow relativeTo, int insertFlag )

final public void add( DhRow row, int insertFlag )

final public void add( DhRow row )

Parameters

row

The DhRow row to add to this table.

relativeTo

The row referred to when using the BEFORE or AFTER constants for the insertFlag parameter.

insertFlag

One of the valid and applicable insert constants. The valid values for insertFlag are:

  • END inserts the row at the bottom of this table. The relativeTo parameter must be null.
  • BEGINNING inserts the row at the top of this table. The relativeTo parameter must be null.
  • BEFORE inserts the row before the row referred to by the relativeTo parameter. The relativeTo parameter must not be null.
  • AFTER inserts the row after the row referred to by the relativeTo parameter. The relativeTo parameter must not be null.


 DhTable.addOnReadyStateChange

DhTable.addOnReadyStateChange

Assigns a delegate to the readyStateChange event.

Syntax

final public void addOnReadyStateChange( ReadyStateEventHandler h )

Parameters

h

The ReadyStateEventHandler delegate to call on a ready state change.

Remarks

The readyStateChange event is triggered when the ready state is changed due to content changes within the table.

See Also removeOnReadyStateChange


 DhTable.DhTable

DhTable.DhTable

Creates a DhTable object.

Syntax

public DhTable()

public DhTable( IDataSource dataSource )

public DhTable( IDataSource dataSource, String dataMember, DataBinding[] dataBindings, DhRow repeaterRow )

Parameters

dataSource

The com.ms.wfc.data.IDataSource object to display in this table.

dataMember

The data member.

dataBindings

An array of com.ms.wfc.data.ui.DataBinding objects that describe the data bindings within the repeaterRow.

repeaterRow

The DhRow object with the desired elements and formatting that are bound to the DataBinding object.

Remarks

This default constructor creates an empty table element.

See Also setRepeaterRow, setDataBindings


 DhTable.getAutoHeader

DhTable.getAutoHeader

Retrieves the current header generation mode.

Syntax

public boolean getAutoHeader()

Return Value

Returns true if a header row will be created if a template row is not specified; otherwise, returns false.

Remarks

Auto headers are generated only in tables that do not have a repeater row specified.

See Also setAutoHeader


 DhTable.getBodyCell

DhTable.getBodyCell

Retrieves the cell at the specified location from the table body.

Syntax

final public DhCell getBodyCell( int nRow, int nCol )

Parameters

nRow

The zero-based row number.

nCol

The zero-based column number.

Return Value

Returns the cell at the requested position.

Exceptions

DhElementNotFoundException if there is no cell at the specified location.


 DhTable.getBodyRow

DhTable.getBodyRow

Retrieves the specified row.

Syntax

final public DhRow getBodyRow( int nRow )

Parameters

nRow

The row to retrieve.

Return Value

Returns the row at position nRow.

Exceptions

DhElementNotFoundException thrown if the row is not in the table.

Remarks

If a header row exists, 0 is specified for the header row; otherwise, it specifies the first row in the table body.


 DhTable.getBodyRowCount

DhTable.getBodyRowCount

Retrieves the number of body rows in the table.

Syntax

public int getBodyRowCount()

Return Value

Returns the number of body rows.

Remarks

Body rows are rows that are not in the header or footer portions of the table.


 DhTable.getBodyRows

DhTable.getBodyRows

Retrieves an array of all rows in the table body (excluding the header and footer).

Syntax

final public DhRow[] getBodyRows()

Return Value

Returns array of DhRow elements.


 DhTable.getBorder

DhTable.getBorder

Retrieves the default (non-CSS) border thickness of the table.

Syntax

final public int getBorder()

Return Value

Returns the thickness of the border.

See Also setBorder


 DhTable.getCellPadding

DhTable.getCellPadding

Retrieves the table CELLPADDING attribute.

Syntax

final public int getCellPadding()

Return Value

Returns the integer padding value.

See Also setCellPadding


 DhTable.getCellSpacing

DhTable.getCellSpacing

Retrieves the table CELLSPACING attribute.

Syntax

final public int getCellSpacing()

Return Value

Returns the integer padding value.

See Also setCellSpacing


 DhTable.getDataBindings

DhTable.getDataBindings

Retrieves the DataBinding objects that are associated with elements in the template repeater row.

Syntax

public DataBinding[] getDataBindings()

Return Value

Returns an array of com.ms.wfc.data.ui.DataBinding objects.

Remarks

Each DataBinding object must reference a column in the current recordset and an object in the repeater row. If no repeater row is specified, these bindings are ignored, and the table displays the default data formatting.

See Also setRepeaterRow, setDataBindings


 DhTable.getDataMember

DhTable.getDataMember

Retrieves the currently selected data member.

Syntax

public String getDataMember()

Return Value

Returns the currently selected data member. If none has been set, returns "" or null.

See Also setDataMember


 DhTable.getDataSource

DhTable.getDataSource

Retrieves the currently set com.ms.wfc.data.IDataSource object.

Syntax

public IDataSource getDataSource()

Return Value

Returns the currently set IDataSource object, or returns null if none is set.

See Also setDataSource


 DhTable.getFooterRow

DhTable.getFooterRow

Retrieves the footer row if there is one.

Syntax

final public DhRow getFooterRow()

Return Value

Returns the footer DhRow, or returns null if no footer row exists.

See Also setFooterRow


 DhTable.getHeaderRow

DhTable.getHeaderRow

Retrieves the header row if there is one.

Syntax

final public DhRow getHeaderRow()

Return Value

Returns the header DhRow, or returns null if no header row exists.

See Also setHeaderRow


 DhTable.getPageSize

DhTable.getPageSize

Retrieves the current data page size, in rows, to display in a databound operation.

Syntax

final public int getPageSize()

Return Value

Returns the number of rows in the page.

See Also setPageSize


 DhTable.getRangeEnd

DhTable.getRangeEnd

Retrieves the end of the current record range.

Syntax

public int getRangeEnd()

Return Value

Returns the end of the record range. The default is -1, indicating records will be displayed until end of recordset.

See Also setRecordRange


 DhTable.getRangeStart

DhTable.getRangeStart

Retrieves the beginning of the current record range.

Syntax

public int getRangeStart()

Return Value

Returns the beginning of the record range. The default is 0.

See Also setRecordRange


 DhTable.getRepeaterRow

DhTable.getRepeaterRow

Retrieves the current template repeater row.

Syntax

public DhRow getRepeaterRow()

Return Value

Returns the current template repeater row, or returns null if none is set.

See Also setRepeaterRow


 DhTable.getTotalRowCount

DhTable.getTotalRowCount

Retrieves the number of rows in the table, including header and footer rows.

Syntax

public int getTotalRowCount()

Return Value

Returns the total number of rows.


 DhTable.refresh

DhTable.refresh

Refreshes the table's data if it is bound to the document.

Syntax

public void refresh()


 DhTable.removeAll

DhTable.removeAll

Removes all rows from the table.

Syntax

public void removeAll()

Remarks

This method removes header, body, and footer rows from the table.


 DhTable.removeBodyRows

DhTable.removeBodyRows

Removes rows that are not header or footer rows from the table.

Syntax

final public void removeBodyRows()

Remarks

In HTML, body rows are any rows that are contained within a THEAD or TFOOT tag. The header and footer rows will not be removed.


 DhTable.removeOnReadyStateChange

DhTable.removeOnReadyStateChange

Removes the delegate that is assigned to the onReadyStateChange event.

Syntax

final public void removeOnReadyStateChange( ReadyStateEventHandler h )

Parameters

h

The ReadyStateEventHandler delegate that is to be removed.

Remarks

The readyStateChange event is triggered when the ready state is changed due to content changes within the table.

See Also addOnReadyStateChange


 DhTable.setAlign

DhTable.setAlign

Sets the alignment of the table.

Syntax

public void setAlign( int alignType )

Parameters

alignType

One of the constants defined in the DhAlignment class. (Text-specific alignments cannot be used.)

Exceptions

WFCInvalidArgumentException thrown if alignType represents a text-specific alignment. The text-specific alignments in the DhAlignment class include JUSTIFY, SUBSCRIPT, and SUPERSCRIPT.


 DhTable.setAutoHeader

DhTable.setAutoHeader

Enables or disables automatic generation of column headers.

Syntax

public void setAutoHeader( boolean fAuto )

Parameters

fAuto

Set to true to enable auto-generation; set to false to disable it.

Exceptions

WFCInvalidStateException thrown if fAuto is true and the table has a repeater row.

Remarks

If enabled, a header row with the column names is automatically added to the table when it is generated.

Note This method pertains only to tables generated without a repeater template row.

See Also getAutoHeader


 DhTable.setBorder

DhTable.setBorder

Sets the default (non-CSS) border width for this table.

Syntax

final public void setBorder( int width )

Parameters

width

The thickness of the border.

See Also getBorder


 DhTable.setCellPadding

DhTable.setCellPadding

Set the table's CELLPADDING attribute.

Syntax

final public void setCellPadding( int padding )

Parameters

padding

The integer padding value.

See Also getCellPadding


 DhTable.setCellSpacing

DhTable.setCellSpacing

Sets the table's CELLSPACING attribute.

Syntax

final public void setCellSpacing( int spacing )

Parameters

spacing

The integer padding value.

See Also getCellSpacing


 DhTable.setDataBindings

DhTable.setDataBindings

Sets the DataBinding objects that are to be associated with elements in the template repeater row.

Syntax

public void setDataBindings( DataBinding[] dataBindings )

Parameters

dataBindings

An array of com.ms.wfc.data.ui.DataBinding objects.

Remarks

Each data binding must reference a column in the current recordset and an object in the repeater row. If no repeater row is specified, these bindings are ignored,and the table displays the default data formatting.

See Also setRepeaterRow, getDataBindings


 DhTable.setDataMember

DhTable.setDataMember

Sets the currently selected data member to retrieve.

Syntax

public void setDataMember( String dataMember )

Parameters

dataMember

The currently selected data member. Set to null to select the default ("") data member.

See Also getDataMember


 DhTable.setDataSource

DhTable.setDataSource

Sets the data source for this table.

Syntax

public void setDataSource( IDataSource dataSource )

Parameters

dataSource

The com.ms.wfc.data.IDataSource object to associate with the table.

Remarks

If the table has existing body rows, they will be replaced when the table's data is generated.

See Also getDataSource, com.ms.wfc.data.Recordset


 DhTable.setFooterRow

DhTable.setFooterRow

Sets the footer row to the DhRow element specified.

Syntax

final public void setFooterRow( DhRow r )

Parameters

r

The new footer row. Set to null to clear the existing footer row.

See Also getFooterRow


 DhTable.setHeaderRow

DhTable.setHeaderRow

Sets the header row to the DhRow specified.

Syntax

final public void setHeaderRow( DhRow r )

Parameters

r

The new header row. Set to null to clear the existing header row.

See Also getHeaderRow


 DhTable.setPageSize

DhTable.setPageSize

Sets the display page size for this table when bound to data.

Syntax

public void setPageSize( int nPageSize )

Parameters

nPageSize

Number of rows to display per page.

See Also getPageSize


 DhTable.setRecordRange

DhTable.setRecordRange

Sets the range of records that will be displayed in the table.

Syntax

public void setRecordRange( int nStartRecord, int nEndRecord )

Parameters

nStartRecord

The first record to display.

nEndRecord

The final record to display.

Remarks

These numbers reflect absolute, zero-based record positions.


 DhTable.setRepeaterRow

DhTable.setRepeaterRow

Specifies the template row that will be cloned for each record of data in the recordset.

Syntax

public void setRepeaterRow( DhRow repeaterRow )

Parameters

repeaterRow

A DhRow object with the desired formatting and data bound elements.

Remarks

Specify elements within the row that you would like to have bound to data by attaching them to a com.ms.wfc.data.ui.DataBinding object. If there are events set on elements within the repeaterRow, they will be duplicated for all rows of the data. Be aware that event duplication is expensive and adding many events to the repeater row slows table generation considerably. It is often better to set the event on just the row or table and use event bubbling to handle it.

See Also getRepeaterRow


 DhTable.showNextPage

DhTable.showNextPage

Displays the next page of data in the table.

Syntax

public void showNextPage()

See Also setPageSize


 DhTable.showPreviousPage

DhTable.showPreviousPage

Displays the previous page of data in the table.

Syntax

public void showPreviousPage()

See Also setPageSize


DhText Class

Represents static text in an HTML document.

DhStyleBase
  |
  +--DhElement
     |
      +--DhText

package com.ms.wfc.html

public class DhText
extends DhElement

Remarks

This element is displayed in one of two modes: freely formatted (the default) or honoring white space. The latter means that all white space (including carriage returns) is maintained, and the element is rendered as a block element with a leading and trailing line feed (unless otherwise positioned).


 DhText Methods

DhText Methods

Constructors | Description
DhText | Creates a DhText object.

Methods | Description
addOnChange | Assigns a delegate to the change event.
addOnGotFocus | Assigns a delegate to the gotFocus event.
addOnLostFocus | Assigns a delegate to the lostFocus event.
addOnResize | Assigns a delegate to the resize event.
addOnScroll | Assigns a delegate to the scroll event.
addOnSelect | Assigns a delegate to the select event.
getDisplayMode | Retrieves the current display mode as one of the DhTextMode constants.
getText | Retrieves the text this element currently displays when rendered.
removeOnChange | Removes the delegate that is assigned to the change event.
removeOnGotFocus | Removes the delegate that is assigned to the gotFocus event.
removeOnLostFocus | Removes the delegate that is assigned to the lostFocus event.
removeOnResize | Removes the delegate that is assigned to the resize event.
removeOnScroll | Removes the delegate that is assigned to the scroll event.
removeOnSelect | Removes the delegate that is assigned to the select event.
setDisplayMode | Sets the current display mode as one of the DhTextMode constants.
setText | Sets (or resets) the text to display in this element.
shouldPersistText | Determines whether the text in the object is set to persist.


 DhText.addOnChange

DhText.addOnChange

Assigns a delegate to the change event.

Syntax

final public void addOnChange ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

This event occurs when the user modifies the text or moves the focus to a different window.

See Also removeOnChange


 DhText.addOnGotFocus

DhText.addOnGotFocus

Assigns a delegate to the gotFocus event.

Syntax

public final void addOnGotFocus ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when this element receives input focus.

See Also removeOnGotFocus


 DhText.addOnLostFocus

DhText.addOnLostFocus

Assigns a delegate to the lostFocus event.

Syntax

public final void addOnLostFocus ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when this element loses focus.

See Also removeOnLostFocus


 DhText.addOnResize

DhText.addOnResize

Assigns a delegate to the resize event.

Syntax

public final void addOnResize ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when this element is resized.

See Also removeOnResize


 DhText.addOnScroll

DhText.addOnScroll

Assigns a delegate to the scroll event.

Syntax

public final void addOnScroll ( ScrollEventHandler h )

Parameters

h

The ScrollEventHandler delegate to be notified when the event occurs.

Remarks

The delegate specifies a method that is called when this element is scrolled.

See Also removeOnScroll


 DhText.addOnSelect

DhText.addOnSelect

Assigns a delegate to the select event.

Syntax

final public void addOnSelect ( EventHandler h )

Parameters

h

The EventHandler delegate to be notified when the event occurs.

Remarks

This event occurs when the user sets or modifies the selected region of the text box.

See Also removeOnSelect


 DhText.DhText

DhText.DhText

Creates a DhText object.

Syntax

public DhText()

public DhText( String text, int mode )

public DhText( String text )

Parameters

text

The text to display.

mode

The initial display mode (one of the DhTextMode fields: FLOW, RESPECT_SPACE, or NO_BREAK).

Remarks

For one-step construction, the text is what will be displayed in this element, and mode is the initial display mode.


 DhText.getDisplayMode

DhText.getDisplayMode

Retrieves the current display mode as one of the DhTextMode constants.

Syntax

public int getDisplayMode()

Return Value

Returns the current text mode.

Remarks

DhTextMode.FLOW is the default.

See Also DhTextMode, setDisplayMode


 DhText.getText

DhText.getText

Retrieves the text this element currently displays when rendered.

Syntax

public String getText()

Return Value

Returns the text this element displays.


 DhText.removeOnChange

DhText.removeOnChange

Removes the delegate that is assigned to the change event.

Syntax

final public void removeOnChange ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The change event occurs when the user modifies the contents of the DhText control or moves the focus to a different window or control.

See Also addOnChange


 DhText.removeOnGotFocus

DhText.removeOnGotFocus

Removes the delegate that is assigned to the gotFocus event.

Syntax

public final void removeOnGotFocus ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The gotFocus event occurs when this element receives input focus.

See Also addOnGotFocus


 DhText.removeOnLostFocus

DhText.removeOnLostFocus

Removes the delegate that is assigned to the lostFocus event.

Syntax

public final void removeOnLostFocus ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The lostFocus event occurs when this element loses input focus.

See Also addOnLostFocus


 DhText.removeOnResize

DhText.removeOnResize

Removes the delegate that is assigned to the resize event.

Syntax

public final void removeOnResize ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The resize event occurs when this container loses input focus.

See Also addOnResize


 DhText.removeOnScroll

DhText.removeOnScroll

Removes the delegate that is assigned to the scroll event.

Syntax

final public void removeOnScroll ( ScrollEventHandler h )

Parameters

h

The ScrollEventHandler delegate that is to be removed.

See Also addOnScroll


 DhText.removeOnSelect

DhText.removeOnSelect

Removes the delegate that is assigned to the select event.

Syntax

final public void removeOnSelect ( EventHandler h )

Parameters

h

The EventHandler delegate that is to be removed.

Remarks

The select event occurs when the user sets or modifies the selected region of the text box.

See Also addOnSelect


 DhText.setDisplayMode

DhText.setDisplayMode

Sets the current display mode as one of the DhTextMode constants.

Syntax

public void setDisplayMode( int mode )

Parameters

mode

The desired text mode (one of the DhTextMode fields: FLOW, RESPECT_SPACE, or NO_BREAK).

Remarks

DhTextMode.FLOW is the default display mode if this method is not called.

See Also getDisplayMode


 DhText.setText

DhText.setText

Sets (or resets) the text to display in this element.

Syntax

public void setText( String s )

Parameters

s

The text to display.


 DhText.shouldPersistText

DhText.shouldPersistText

Determines whether the text in the object is set to persist.

Syntax

public boolean shouldPersistText()

Return Value

Returns true if the text is set to persist; otherwise, returns false.


DhTextMode Class

Defines mode constants for the DhText class.

Enum
  |
  +--DhTextMode

package com.ms.wfc.html

public class DhTextMode
extends com.ms.wfc.core.Enum


 DhTextMode Methods

DhTextMode Methods

Methods | Description
valid | Determines whether a specified value is valid for this enumeration type.


 DhTextMode.valid

DhTextMode.valid

Determines whether a specified value is valid for this enumeration type.

Syntax

public static boolean valid( int n )

Parameters

n

The value to check.

Return Value

Returns true if the value is valid for this class; otherwise, returns false.

Remarks

You should override this method in your own enumeration classes.


 DhTextMode Fields

DhTextMode Fields

Fields | Description
FLOW | Specifies that the text contents will behave with normal HTML flow.
NO_BREAK | Specifies that the text contents will be rendered with no line breaks and will be clipped at the edge of the document rather than wrapping.
RESPECT_SPACE | Specifies that the text contents will be rendered in a fixed font and all white space, such as spaces, tabs, carriage returns, and line feeds, will also be rendered.


 DhTextMode.FLOW

DhTextMode.FLOW

Specifies that the text contents will behave with normal HTML flow.

Syntax

public final static int FLOW;


 DhTextMode.NO_BREAK

DhTextMode.NO_BREAK

Specifies that the text contents will be rendered with no line breaks and will be clipped at the edge of the document rather than wrapping.

Syntax

public final static int NO_BREAK;


 DhTextMode.RESPECT_SPACE

DhTextMode.RESPECT_SPACE

Specifies that the text contents will be rendered in a fixed font and all white space, such as spaces, tabs, carriage returns, and line feeds, will also be rendered.

Syntax

public final static int RESPECT_SPACE;

Remarks

The element will also appear as a block element with a leading and trailing linebreak, unless otherwise positioned.


DhUnits Class

Provides constants for various unit types in DHTML.

Enum
  |
  +--DhUnits

package com.ms.wfc.html

public class DhUnits
extends Enum

Remarks

This class is when setting units in the DhElement and DhStyleBase classes.

See Also DhPaddingWidthInfo, DhBorderInfo, DhMarginWidthInfo


 DhUnits Methods

DhUnits Methods

Methods | Description
valid | Determines whether a specified value is valid for this enumeration type.


 DhUnits.valid

DhUnits.valid

Determines whether a specified value is valid for this enumeration type.

Syntax

public static boolean valid( int n )

Parameters

n

The value to check.

Return Value

Returns true if the value is valid for this class; otherwise, returns false.

Remarks

You should override this method in your own enumeration classes.


 DhUnits Fields

DhUnits Fields

Fields | Description
AUTO | Represents the auto type.
CM | Represents the centimeter (cm) type.
COLOR | Represents the color type.
EM | Represents the relative height of the element's font (em).
EX | Represents an x height (ex).
INCH | Represents an inches (in) type.
MM | Represents a millimeter (mm) type.
NULL | Represents an unspecified or absent type.
PC | Represents a pica (pc) type.
PERCENT | Represents the percentage (%) type.
PIXEL | Represents a pixel (px) type.
POINT | Represents a point (pt) type.


 DhUnits.AUTO

DhUnits.AUTO

Represents the auto type.

Syntax

public static final int AUTO;


 DhUnits.CM

DhUnits.CM

Represents the centimeter (cm) type.

Syntax

public static final int CM;


 DhUnits.COLOR

DhUnits.COLOR

Represents the color type.

Syntax

public static final int COLOR;


 DhUnits.EM

DhUnits.EM

Represents the relative height of the element's font (em).

Syntax

public static final int EM;


 DhUnits.EX

DhUnits.EX

Represents an x height (ex).

Syntax

public static final int EX;

Remarks

This is approximately the height of a lowercase x in the current element font.


 DhUnits.INCH

DhUnits.INCH

Represents an inches (in) type.

Syntax

public static final int INCH;


 DhUnits.MM

DhUnits.MM

Represents a millimeter (mm) type.

Syntax

public static final int MM;


 DhUnits.NULL

DhUnits.NULL

Represents an unspecified or absent type.

Syntax

public static final int NULL;


 DhUnits.PC

DhUnits.PC

Represents a pica (pc) type.

Syntax

public static final int PC;


 DhUnits.PERCENT

DhUnits.PERCENT

Represents the percentage (%) type.

Syntax

public static final int PERCENT;


 DhUnits.PIXEL

DhUnits.PIXEL

Represents a pixel (px) type.

Syntax

public static final int PIXEL;


 DhUnits.POINT

DhUnits.POINT

Represents a point (pt) type.

Syntax

public static final int POINT;


DhWindow Class

Encapsulates an HTML window.

package com.ms.wfc.html

public class DhWindow


 DhWindow Methods

DhWindow Methods

Methods | Description
close | Closes the window, and resets its document and window peers to null.
focus | Sets or removes the focus of the current window.
getBrowser | Retrieves a representation of the browser.
getClosed | Determines whether the window is closed.
getDialogArguments | Retrieves the arguments passed to a modal dialog window.
getDocument | Retrieves the document contained in this window.
getEventPeer | Retrieves a peer that handles events for this window.
getFrame | Retrieves the first frame that has the specified name.
getFrames | Retrieves an array of DhWindow objects, one for each frame enclosed in this window.
getHashString | Retrieves a hash string passed to the document.
getHistoryLength | Retrieves the number of entries in the window's history.
getName | Retrieves a string representing the name of the window.
getParent | Retrieves the parent of this window.
getPeer | Retrieves the underlying HTML peer element for this class.
getReturnValue | Retrieves the return value from a modal dialog window.
getScroll | Retrieves the current scroll mode.
getSearchString | Retrieves a search string passed to the document.
getTopWindow | Retrieves the topmost ancestor window of this window in the parenting heirarchy.
getURL | Retrieves a string representing the URL of the window's document.
getWindowPeer | Retrieves the underlying HTML peer element for this class.
goBackInHistory | Loads the previous URL in the history list.
goForwardInHistory | Loads the next URL in the history list.
goRelativeInHistory | Loads the previous URL in the history list.
messageBox | Displays a modal user message box.
navigate | Opens a new URL in this window with the specified name and properties.
open | Opens a new URL in this window with the specified name and properties.
setName | Sets the name of the current window.
setReturnValue | Sets the return value that will be returned from a modal dialog window.
setScroll | Sets the current scroll mode.
setStatus | Displays a string on the status bar of the window host (typically the browser).
showModalDialog | Opens an HTML dialog window using the URL as the source of the contents and DhDialogInfo to define the appearance of the dialog window.


 DhWindow.close

DhWindow.close

Closes the window, and resets its document and window peers to null.

Syntax

public void close()

See Also getClosed


 DhWindow.focus

DhWindow.focus

Sets or removes the focus of the current window.

Syntax

final public void focus( boolean focus )

Parameters

focus

Set to true to set the focus; set to false to remove focus.


 DhWindow.getBrowser

DhWindow.getBrowser

Retrieves a representation of the browser.

Syntax

final public DhBrowser getBrowser()

Return Value

Returns an object representing the browser.


 DhWindow.getClosed

DhWindow.getClosed

Determines whether the window is closed.

Syntax

final public boolean getClosed()

Return Value

Returns true if the window is closed; otherwise, returns false.

See Also close


 DhWindow.getDialogArguments

DhWindow.getDialogArguments

Retrieves the arguments passed to a modal dialog window.

Syntax

final public Variant getDialogArguments()

Return Value

Returns arguments passed to this dialog window through showModalDialog.


 DhWindow.getDocument

DhWindow.getDocument

Retrieves the document contained in this window.

Syntax

public DhDocument getDocument()

Return Value

Returns the document associated with this window.

Remarks

The result can be null if the document is not accessible (for example, because of security restrictions).


 DhWindow.getEventPeer

DhWindow.getEventPeer

Retrieves a peer that handles events for this window.

Syntax

final public IUnknown getEventPeer()

Return Value

Returns an IUnknown object containing a reference to the peer that handles events for this window.

Remarks

Calling this method represents an advanced usage scenario. Typically, you would never use this method.


 DhWindow.getFrame

DhWindow.getFrame

Retrieves the first frame that has the specified name.

Syntax

public DhWindow getFrame( String name )

Parameters

name

The name of the frame to locate.

Return Value

Returns the window defining the enclosed frame having the specified name.

Remarks

This name must be unique. Otherwise, this method returns null.


 DhWindow.getFrames

DhWindow.getFrames

Retrieves an array of DhWindow objects, one for each frame enclosed in this window.

Syntax

public DhWindow[] getFrames()

Return Value

Returns the array of windows defining the enclosed frames.


 DhWindow.getHashString

DhWindow.getHashString

Retrieves a hash string passed to the document.

Syntax

final public String getHashString()

Return Value

Returns hash segment of the window's URL.

Remarks

This is usually the string after the hash mark (#).


 DhWindow.getHistoryLength

DhWindow.getHistoryLength

Retrieves the number of entries in the window's history.

Syntax

final public int getHistoryLength()

Return Value

Returns the history length.


 DhWindow.getName

DhWindow.getName

Retrieves a string representing the name of the window.

Syntax

final public String getName()

Return Value

Returns the name of the window.

See Also setName


 DhWindow.getParent

DhWindow.getParent

Retrieves the parent of this window.

Syntax

public DhWindow getParent()

Return Value

Returns the parent window of this window.


 DhWindow.getPeer

DhWindow.getPeer

Retrieves the underlying HTML peer element for this class.

Syntax

final public IUnknown getPeer()

Return Value

Returns the element peer underlying the HTML peer for this class.

Remarks

This method returns null if the document is not bound to this class. Java code that is running in a trusted environment can freely cast the resulting reference to a specific element peer type (for example, com.ms.wfc.html.om.IHTMLWindow2). This method always returns null if the code is running in a Web server environment.

Calling this method represents a very advanced usage scenario. Typically, you would never use this method.


 DhWindow.getReturnValue

DhWindow.getReturnValue

Retrieves the return value from a modal dialog window.

Syntax

final public Variant getReturnValue()

Return Value

Returns the return value from a modal dialog window.

See Also setReturnValue


 DhWindow.getScroll

DhWindow.getScroll

Retrieves the current scroll mode.

Syntax

public int getScroll()

Return Value

Returns the current scrolling mode, which can be one of the following DhScrollBars values:

  • AUTO indicates that the browser determines scrolling.
  • YES indicates that scrolling is enabled.
  • NO indicates that scrolling is disabled.

Note AUTO and YES are equivalent.

See Also setScroll


 DhWindow.getSearchString

DhWindow.getSearchString

Retrieves a search string passed to the document.

Syntax

final public String getSearchString()

Return Value

Returns the search segment of the URL of the window.

Remarks

This is typically the string after the question mark (?).


 DhWindow.getTopWindow

DhWindow.getTopWindow

Retrieves the topmost ancestor window of this window in the parenting heirarchy.

Syntax

final public DhWindow getTopWindow()

Return Value

Returns the topmost DhWindow object.

Remarks

If this DhWindow is the top, it is returned.


 DhWindow.getURL

DhWindow.getURL

Retrieves a string representing the URL of the window's document.

Syntax

final public String getURL()

Return Value

Returns the location URL of the window.

See Also open


 DhWindow.getWindowPeer

DhWindow.getWindowPeer

Retrieves the underlying HTML peer element for this class.

Syntax

protected IHTMLWindow2 getWindowPeer()

Return Value

Returns the element peer underlying the HTML peer for this class.

Remarks

This method returns null if the document is not bound to this class. Java code that is running in a trusted environment can freely cast the resulting reference to a specific element peer type (for example, com.ms.wfc.html.om.IHTMLWindow2). This method always returns null if the code is running in a Web server environment.

Calling this method represents a very advanced usage scenario. Typically, you would never use this method.


 DhWindow.goBackInHistory

DhWindow.goBackInHistory

Loads the previous URL in the history list.

Syntax

final public void goBackInHistory( int delta, EventHandler h )

Parameters

delta

The number of pages to go back relative to the current page.

h

The EventHandler delegate specifying the event handler to call when the browser loads the previous URL.

See Also goRelativeInHistory, goForwardInHistory


 DhWindow.goForwardInHistory

DhWindow.goForwardInHistory

Loads the next URL in the history list.

Syntax

final public void goForwardInHistory( int delta, EventHandler h )

Parameters

delta

The number of pages to go forward relative to the current page.

h

The EventHandler delegate specifying the event handler to call when the browser loads the next URL.

See Also goBackInHistory, goRelativeInHistory


 DhWindow.goRelativeInHistory

DhWindow.goRelativeInHistory

Loads the previous URL in the history list.

Syntax

final public void goRelativeInHistory( int delta, EventHandler h )

Parameters

delta

The number of pages to go back or forward relative to the current page.

h

The EventHandler delegate specifying the event handler to call when the browser loads the relative URL.

Return Value

Returns a unique index representing this navigation.

See Also goBackInHistory, goForwardInHistory


 DhWindow.messageBox

DhWindow.messageBox

Displays a modal user message box.

Syntax

final public void MessageBox( String s )

Parameters

s

The message to display.


 DhWindow.navigate

DhWindow.navigate

Opens a new URL in this window with the specified name and properties.

Syntax

final public void navigate( String url, EventHandler h )

Parameters

url

A string defining the URL of the new location.

h

A EventHandler delegate specifying a method to call when URL being navigated has finished loading.

Returns

Returns a DhWindow handle to the newly opened window.


 DhWindow.open

DhWindow.open

Opens a new URL in this window with the specified name and properties.

Syntax

final public DhWindow open( String url, String name, DhWindowInfo wi, boolean fReplace )

Parameters

url

The string defining the URL of the new location.

name

The name of the window. This name cannot contain spaces.

wi

A DhWindowInfo object defining the appearance and size of the new window.

fReplace

Set to true to replace the current contents; set to false to keep the current contents.

Returns

Returns a DhWindow handle to the newly opened window.

See Also getURL


 DhWindow.setName

DhWindow.setName

Sets the name of the current window.

Syntax

final public void setName( String name )

Parameters

name

The name of the window. This name cannot contain punctuation.

See Also getName


 DhWindow.setReturnValue

DhWindow.setReturnValue

Sets the return value that will be returned from a modal dialog window.

Syntax

final public void setReturnValue( Variant retValue )

Parameters

retValue

The value to be returned from a modal dialog window.

See Also getReturnValue


 DhWindow.setScroll

DhWindow.setScroll

Sets the current scroll mode.

Syntax

public void setScroll( int scrollMode )

Parameters

scrollMode

The desired scrolling mode, which can be on of the following:

  • DhScrollBars.AUTO indicates that the browser determines scolling.
  • DhScrollBars.YES indicates that scrolling is enabled.
  • DhScrollBars.NO indicates that scrolling is disabled.

See Also DhScrollBars, getScroll


 DhWindow.setStatus

DhWindow.setStatus

Displays a string on the status bar of the window host (typically the browser).

Syntax

final public void setStatus( String s )

Parameters

s

The string to display on the status bar.


 DhWindow.showModalDialog

DhWindow.showModalDialog

Opens an HTML dialog window using the URL as the source of the contents and DhDialogInfo to define the appearance of the dialog window.

Syntax

final public Variant showModalDialog( String dialogUrl, Variant dialogArgs, DhDialogInfo di )

Parameters

dialogUrl

A string defining the URL of the dialog window contents.

dialogArgs

A com.ms.com.Variant object containing optional arguments to the document defining the contents.

di

A DhDialogInfo object that defines the appearance of the dialog window.

Return Value

Returns a com.ms.com.Variant object that packages the returned values or values of the dialog window.


DhWindowInfo Class

Provides constants for setting features for a new browser or modal dialog window.

package com.ms.wfc.html

public class DhWindowInfo

Remarks

An instance of this class is passed as a parameter to DhWindow.open when opening a new browser window.

See Also DhWindow.open


 DhWindowInfo Methods

DhWindowInfo Methods

Constructors | Description
DhWindowInfo | Creates a DhWindowInfo object.

Methods | Description
addFeature | Adds a new custom feature.
getValue | Retrieves the value of the custom feature.
removeFeature | Removes a custom feature.
toString | Retrieves a string representation of the DhWindowInfo object.


 DhWindowInfo.addFeature

DhWindowInfo.addFeature

Adds a new custom feature.

Syntax

public void addFeature( String name, String value )

Parameters

name

The name of the custom feature.

value

The value of the custom feature.

See Also removeFeature


 DhWindowInfo.DhWindowInfo

DhWindowInfo.DhWindowInfo

Creates a DhWindowInfo object.

Syntax

public DhWindowInfo()

public DhWindowInfo( Rectangle size )

Parameters

size

A Rectangle object describing the size of the window.


 DhWindowInfo.getValue

DhWindowInfo.getValue

Retrieves the value of the custom feature.

Syntax

public String getValue( String name )

Parameters

name

The name of the custom feature to add.


 DhWindowInfo.removeFeature

DhWindowInfo.removeFeature

Removes a custom feature.

Syntax

public void removeFeature( String name )

Parameters

name

The name of the custom feature to remove.

See Also addFeature


 DhWindowInfo.toString

DhWindowInfo.toString

Retrieves a string representation of the DhWindowInfo object.

Syntax

public String toString()


 DhWindowInfo Fields

DhWindowInfo Fields

Fields | Description
isResizable | Informs the browser to open a new window and make it resizable using resize handles.
showChannelMode | Informs the browser to open a new window in theater mode and show the channel band.
showDirectoryButtons | Informs the browser to open a new window and add directory buttons.
showFullScreen | Informs the browser to open a new window using the full screen as size.
showLocation | Informs the browser to open a new window and display the input field for entering Uniform Resource Locators (URLs) directly into the browser.
showMenubar | Informs the browser to open a new window with the menu bar showing.
showScrollbars | Informs the browser to open a new window with the scroll bars showing.
showStatusbar | Informs the browser to open a new window with the status bar showing.
showToolbar | Informs the browser to display the browser toolbar, making buttons such as Back, Forward, and Stop available.
size | Informs the browser to open a new window using the rectangle as the size.


 DhWindowInfo.isResizable

DhWindowInfo.isResizable

Informs the browser to open a new window and make it resizable using resize handles.

Syntax

public boolean isResizable;


 DhWindowInfo.showChannelMode

DhWindowInfo.showChannelMode

Informs the browser to open a new window in theater mode and show the channel band.

Syntax

public boolean showChannelMode;

Remarks

In theater mode, the Internet Explorer main window fills the entire screen and displays a toolbar with a minimal set of navigational buttons. A status bar is also provided in the upper-right corner of the screen. Channels, Search, History, and Favorites browser bars appear (if enabled) as an autohide pane on the left edge of the screen in theater mode.

See Also DhWindow.open


 DhWindowInfo.showDirectoryButtons

DhWindowInfo.showDirectoryButtons

Informs the browser to open a new window and add directory buttons.

Syntax

public boolean showDirectoryButtons;


 DhWindowInfo.showFullScreen

DhWindowInfo.showFullScreen

Informs the browser to open a new window using the full screen as size.

Syntax

public boolean showFullScreen;


 DhWindowInfo.showLocation

DhWindowInfo.showLocation

Informs the browser to open a new window and display the input field for entering Uniform Resource Locators (URLs) directly into the browser.

Syntax

public boolean showLocation;


 DhWindowInfo.showMenubar

DhWindowInfo.showMenubar

Informs the browser to open a new window with the menu bar showing.

Syntax

public boolean showMenubar;


 DhWindowInfo.showScrollbars

DhWindowInfo.showScrollbars

Informs the browser to open a new window with the scroll bars showing.

Syntax

public boolean showScrollbars;


 DhWindowInfo.showStatusbar

DhWindowInfo.showStatusbar

Informs the browser to open a new window with the status bar showing.

Syntax

public boolean showStatusbar;


 DhWindowInfo.showToolbar

DhWindowInfo.showToolbar

Informs the browser to display the browser toolbar, making buttons such as Back, Forward, and Stop available.

Syntax

public boolean showToolbar;


 DhWindowInfo.size

DhWindowInfo.size

Informs the browser to open a new window using the rectangle as the size.

Syntax

public Rectangle size;

Remarks

The Rectangle object should have width and height fields with a minimum value of 100. The y field specifies the top position in pixels relative to the upper-left corner of the screen. The x field specifies the left position in pixels relative to the upper-left corner of the screen.


Package com.ms.wfc.io

Provides classes for working with data streams.

Classes

BufferedStream

Implements a buffered data stream.

CodePage

Defines constants that specify the identifier of a code page that is supported by the system.

DataStream

Provides a base implementation of the IDataStream interface.

EOFException

Represents an end-of-file (EOF) exception.

File

Implements access to files.

FileAccess

Defines constants that specify file access.

FileAttribute

Defines constants that specify file attributes.

FileEnumerator

Searches the file system for files that match a specified pattern.

FileMode

Defines constants that specify file modes.

FileShare

Defines constants that specify file sharing.

IOException

Represents an input/output (I/O) exception.

MemoryStream

Implements an in-memory data stream.

Reader

Represents a reader that can read a sequential stream of characters.

StringReader

Implements a reader that reads from a string.

StringWriter

Implements a writer that writes to a string buffer and allows the resulting sequence of characters to be presented as a string.

Text

Provides fields that represent the standard input, output, and error files of a process.

TextReader

Implements a reader that can read a sequential stream of characters from an IByteStream object or from a named file.

TextWriter

Implements a writer that can write a sequential stream of characters to an IByteStream object or to a named file.

WinIOException

Creates a Windows input/output (I/O) error exception class.

Writer

Represents a writer that can write a sequential stream of characters.

Interfaces

IByteStream

Represents a stream for reading and writing of data in the form of bytes.

IDataStream

Represents a stream that allows the reading and writing of data in a variety of formats.

IReader

Defines an interface that can read a sequential stream of characters.

IWriter

Represents a writer that can write a sequential stream of characters.


BufferedStream Class

Implements a buffered data stream.

DataStream
  |
  +--BufferedStream

package com.ms.wfc.io

public class BufferedStream
extends DataStream

Remarks

An instance of BufferedStream can be put before any IByteStream object to provide buffering of input/output (I/O) operations. Buffering can increase performance when a large number of fairly small read or write operations are performed on a stream. A stream's characteristics are determined by its class and by customized insertion and extraction operators.


 BufferedStream Methods

BufferedStream Methods

Constructors | Description
BufferedStream | Creates a buffered data stream.

Methods | Description
close | Closes the buffer.
flush | Forces any data remaining in the buffer to be written to the file.
getLength | Retrieves the length of the stream in bytes.
getPosition | Retrieves the position of this stream.
getStream | Retrieves the current buffered stream.
read | Reads the next byte of data from this stream.
readByte | Reads a byte from this stream.
readChar | Reads a character from this stream.
readCore | Implements the core array read method.
readInt | Reads an integer from this stream.
readShort | Reads a short value from this stream.
readStringCharsAnsi | Reads an American National Standards Institute (ANSI) string from this stream.
readStringNull | Reads a null-terminated Unicode string from this stream.
readStringNullAnsi | Reads a null-terminated ANSI string from this stream.
setLength | Sets the length of this stream.
setPosition | Sets the position of this stream.
write | Writes a single byte of data to this stream.
writeByte | Writes a byte to this stream.
writeChar | Writes a character to this stream.
writeCore | Implements the core array write method.
writeInt | Writes an integer to this stream.
writeShort | Writes a short value to this stream.


 BufferedStream.BufferedStream

BufferedStream.BufferedStream

Creates a buffered data stream.

Syntax

public BufferedStream( IByteStream stream )

public BufferedStream( IByteStream stream, int bufferSize )

Parameters

stream

The data stream to act on.

bufferSize

The length of the buffer in bytes.


 BufferedStream.close

BufferedStream.close

Closes the buffer.

Syntax

public void close()


 BufferedStream.flush

BufferedStream.flush

Forces any data remaining in the buffer to be written to the file.

Syntax

public void flush()


 BufferedStream.getLength

BufferedStream.getLength

Retrieves the length of the stream in bytes.

Syntax

public long getLength()

Return Value

Returns the length of the stream.

Remarks

The default implementation raises an IOException, but a subclass can override this method to provide the appropriate functionality.


 BufferedStream.getPosition

BufferedStream.getPosition

Retrieves the position of this stream.

Syntax

public long getPosition()

Return Value

Returns the current position of the stream.


 BufferedStream.getStream

BufferedStream.getStream

Retrieves the current buffered stream.

Syntax

public IByteStream getStream()

Return Value

Returns the current buffered stream.


 BufferedStream.read

BufferedStream.read

Reads the next byte of data from this stream.

Syntax

public int read()

Return Value

Returns the next byte of data from this stream.


 BufferedStream.readByte

BufferedStream.readByte

Reads a byte from this stream.

Syntax

public byte readByte()

Return Value

Returns a byte of data from this stream.


 BufferedStream.readChar

BufferedStream.readChar

Reads a character from this stream.

Syntax

public char readChar()

Return Value

Returns a character of data from this stream.


 BufferedStream.readCore

BufferedStream.readCore

Implements the core array read method.

Syntax

protected int readCore( Object array, int offset, int count )

Parameters

buffer

An array of a primitive type.

offset

The byte offset into the buffer.

count

The number of bytes to read.

Return Value

Returns an array of data from this stream.

Exceptions

IOException thrown if an error occurs or if the stream does not support reading.

Overrides DataStream.readCore


 BufferedStream.readInt

BufferedStream.readInt

Reads an integer from this stream.

Syntax

public int readInt()

Return Value

Returns an integer from this stream.


 BufferedStream.readShort

BufferedStream.readShort

Reads a short value from this stream.

Syntax

public short readShort()

Return Value

Returns the short value read.


 BufferedStream.readStringCharsAnsi

BufferedStream.readStringCharsAnsi

Reads an American National Standards Institute (ANSI) string from this stream.

Syntax

public String readStringCharsAnsi( int length )

Parameters

length

The length of the buffer in bytes.

Return Value

Returns the string value read.


 BufferedStream.readStringNull

BufferedStream.readStringNull

Reads a null-terminated Unicode string from this stream.

Syntax

public String readStringNull()


 BufferedStream.readStringNullAnsi

BufferedStream.readStringNullAnsi

Reads a null-terminated ANSI string from this stream.

Syntax

public String readStringNullAnsi()

Return Value

Returns the string value read.


 BufferedStream.setLength

BufferedStream.setLength

Sets the length of this stream.

Syntax

public void setLength( long length )

Parameters

length

The length of the data stream to set.


 BufferedStream.setPosition

BufferedStream.setPosition

Sets the position of this stream.

Syntax

public void setPosition( long position )

Parameters

position

The position in the data stream to set.


 BufferedStream.write

BufferedStream.write

Writes a single byte of data to this stream.

Syntax

public void write( int value )

Parameters

value

The value to write.


 BufferedStream.writeByte

BufferedStream.writeByte

Writes a byte to this stream.

Syntax

public void writeByte( byte value )

Parameters

value

The value to write.


 BufferedStream.writeChar

BufferedStream.writeChar

Writes a character to this stream.

Syntax

public void writeChar( char value )

Parameters

value

The value to write.


 BufferedStream.writeCore

BufferedStream.writeCore

Implements the core array write method.

Syntax

protected void writeCore( Object array, int index, int count )

Parameters

array

An array of a primitive type.

index

The byte offset into the buffer.

count

The number of bytes to write.

Overrides DataStream.writeCore


 BufferedStream.writeInt

BufferedStream.writeInt

Writes an integer to this stream.

Syntax

public void writeInt( int value )

Parameters

value

The value to write.


 BufferedStream.writeShort

BufferedStream.writeShort

Writes a short value to this stream.

Syntax

public void writeShort( short value )

Parameters

value

The value to write.


CodePage Class

Defines constants that specify the identifier of a code page that is supported by the system.

package com.ms.wfc.io

public class CodePage


 CodePage Fields

CodePage Fields

Fields | Description
ANSI | Specifies an American National Standards Institute (ANSI) code page.
MAC | Specifies a code page for the Apple Macintosh operating system.
OEM | Specifies a code page for an original equipment manufactuer (OEM).


 CodePage.ANSI

CodePage.ANSI

Specifies an American National Standards Institute (ANSI) code page.

Syntax

public static final int ANSI;


 CodePage.MAC

CodePage.MAC

Specifies a code page for the Apple Macintosh operating system.

Syntax

public static final int MAC;


 CodePage.OEM

CodePage.OEM

Specifies a code page for an original equipment manufactuer (OEM).

Syntax

public static final int OEM;


DataStream Class

Provides a base implementation of the IDataStream interface.

package com.ms.wfc.io

public class DataStream
implements IDataStream

Remarks

To create an implementation of IDataStream, you typically inherit from this class.

To support reading, a subclass must minimally implement the read and readCore methods. To support writing, a subclass must minimally implement the write and writeCore methods. To support random access seeking, a subclass must implement the getLength, setLength, getPosition, and setPosition methods. Finally, the close and flush methods can be overridden if required.

See Also BufferedStream, File, IByteStream, MemoryStream


 DataStream Methods

DataStream Methods

Constructors | Description
DataStream | Creates a DataStream object.

Methods | Description
canRead | Determines whether this stream supports reading.
canSeek | Determines whether this stream supports seeking.
canWrite | Determines whether this stream supports reading.
close | Closes this stream.
flush | Flushes this stream.
fromComStream | Retrieves an IDataStream object for an IStream object.
getComStream | Retrieves an IStream for this stream.
getLength | Retrieves the length of this stream.
getPosition | Retrieves the position of this stream.
read | Reads the next byte of data from this stream.
readBoolean | Reads a boolean value from this stream.
readByte | Reads a byte from this stream.
readBytes | Reads a block of bytes from this stream.
readChar | Reads a character from this stream.
readChars | Reads the specified number of characters from this stream.
readCore | Implements the core array read method.
readDouble | Reads a double value from this stream.
readDoubles | Reads the specified number of doubles from this stream into a double array.
readFloat | Reads a float value from this stream.
readFloats | Reads a specified number of float values from this stream into a float array.
readInt | Reads an integer from this stream.
readInts | Reads the specified number of integers from this stream into an integer array.
readLong | Reads a long value from this stream.
readLongs | Reads the specified number of long integers from this stream into a long array.
readShort | Reads a short value from this stream.
readShorts | Reads the specified number of short integers from this stream into a short array.
readString | Reads a length-prefixed Unicode string from this stream.
readStringChars | Reads a Unicode string from this stream.
readStringCharsAnsi | Reads an American National Standards Institute (ANSI) string from this stream.
readStringNull | Reads a null-terminated Unicode string from this stream.
readStringNullAnsi | Reads a null-terminated ANSI string from this stream.
readToEnd | Reads all data from the current position to the end of this stream.
readUTF | Reads a string from this stream using a length-prefixed UTF-8 format.
setLength | Sets the length of this stream.
setPosition | Sets the position of this stream.
toComStream | Retrieves an IStream object for an IDataStream object.
write | Writes bytes of data to this stream.
writeBoolean | Writes a boolean value to this stream.
writeByte | Writes a byte to this stream.
writeBytes | Writes a block of bytes to this stream.
writeChar | Writes a character to this stream.
writeChars | Writes the contents of the specified character array to this stream.
writeCore | Implements the core array write method.
writeDouble | Writes a double value to this stream.
writeDoubles | Writes the contents of the specified double array to this stream.
writeFloat | Writes a float value to this stream.
writeFloats | Writes the contents of the specified float array to this stream.
writeInt | Writes an integer to this stream.
writeInts | Writes the contents of the specified integer array to this stream.
writeLong | Writes a long value to this stream.
writeLongs | Writes the contents of the specified long integer array to this stream.
writeShort | Writes a short value to this stream.
writeShorts | Writes the contents of the specified short integer array to this stream.
writeString | Writes a length-prefixed Unicode string to this stream.
writeStringChars | Writes a Unicode string to this stream.
writeStringCharsAnsi | Writes an ANSI string to this stream.
writeStringNull | Writes a null-terminated Unicode string to this stream.
writeStringNullAnsi | Writes a null-terminated ANSI string to this stream.
writeUTF | Writes a string to this stream using a length-prefixed UTF-8 format.


 DataStream.canRead

DataStream.canRead

Determines whether this stream supports reading.

Syntax

public boolean canRead()

Return Value

Returns true if the stream supports reading; otherwise, returns false.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support reading.

Remarks

This method implements the IByteStream.canRead method. The default method always returns true, but a subclass can override this method to provide the appropriate functionality.

See Also read


 DataStream.canSeek

DataStream.canSeek

Determines whether this stream supports seeking.

Syntax

public boolean canSeek()

Return Value

Returns true if the stream supports seeking; otherwise, returns false.

Exceptions

IOException thrown if an I/O error occurs.

Remarks

This method implements the IByteStream.canSeek method. This default method always returns true, but a subclass can override this method to provide the appropriate functionality.

See Also write


 DataStream.canWrite

DataStream.canWrite

Determines whether this stream supports reading.

Syntax

public boolean canWrite()

Return Value

Returns true if the stream supports writing; otherwise, returns false.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support writing.

Remarks

This method implements the IByteStream.canWrite method. This default method always returns true, but a subclass can override this method to provide the appropriate functionality.

See Also write


 DataStream.close

DataStream.close

Closes this stream.

Syntax

public void close()

Remarks

This method implements the IByteStream.close method. The default method is empty, but a subclass can override it to provide the appropriate functionality.


 DataStream.DataStream

DataStream.DataStream

Creates a DataStream object.

Syntax

protected DataStream()

Remarks

This constructor is protected to prevent instantiation of this class.


 DataStream.flush

DataStream.flush

Flushes this stream.

Syntax

public void flush()

Remarks

This method implements the IByteStream.flush method. The default method is empty, but a subclass can override it to provide the appropriate functionality.


 DataStream.fromComStream

DataStream.fromComStream

Retrieves an IDataStream object for an IStream object.

Syntax

public static IDataStream fromComStream( IStream comStream )

Parameters

comStream

The com.ms.com.IStream object to create an IDataStream object from.

Return Value

Returns an IDataStream object for the specified IStream object, or returns null if the comStream parameter is null.

Remarks

If you have a COM-compatible IStream object but need an IDataStream object, you can use this method to create an adapter.

See Also getComStream, toComStream


 DataStream.getComStream

DataStream.getComStream

Retrieves an IStream for this stream.

Syntax

public IStream getComStream()

Return Value

Returns a COM-compatible com.ms.com.IStream implementation for this stream. This object is cached and returned by subsequent calls to getComStream.

See Also fromComStream, toComStream


 DataStream.getLength

DataStream.getLength

Retrieves the length of this stream.

Syntax

public long getLength()

Return Value

Returns the length of this stream.

Remarks

This method implements the IByteStream.getLength method. The default implementation raises an IOException, but a subclass can override the method to provide the appropriate functionality.


 DataStream.getPosition

DataStream.getPosition

Retrieves the position of this stream.

Syntax

public long getPosition()

Remarks

This method implements the IByteStream.getPosition method. The default implementation raises an IOException, but a subclass can override the method to provide the appropriate functionality.

Return Value

Returns the current position of the stream.


 DataStream.read

DataStream.read

Reads the next byte of data from this stream.

Syntax

public int read()

public int read( byte[] buffer, int index, int count )

Parameters

buffer

The array to read data into.

index

The starting index into the array.

count

The number of bytes to read.

Return Value

Returns the number of bytes that were read.

Remarks

This method implements the IByteStream.read method. The default implementation raises an IOException, but a subclass can override the method to provide the appropriate functionality. The first syntax reads the next byte of data from the stream. The second syntax validates the arguments and then calls the readCore method to read the data.


 DataStream.readBoolean

DataStream.readBoolean

Reads a boolean value from this stream.

Syntax

public boolean readBoolean()

Return Value

Returns true if the byte is non-zero, or returns false if the byte is zero.

Remarks

This method implements the IDataStream.readBoolean method. This method calls the read method to read a byte.


 DataStream.readByte

DataStream.readByte

Reads a byte from this stream.

Syntax

public byte readByte()

Return Value

Returns a byte of data from this stream.

Remarks

This method implements the IDataStream.readByte method. This method calls the read method to read the byte.


 DataStream.readBytes

DataStream.readBytes

Reads a block of bytes from this stream.

Syntax

public byte[] readBytes( int count )

public void readBytes( byte[] buffer, int index, int count )

Parameters

buffer

The array to read data into.

index

The starting index in the array.

count

The number of bytes to read.

Return Value

Returns a byte of array containing the data that was read.

Remarks

This method implements the IDataStream.readBytes method. This method calls the read method to read the data.


 DataStream.readChar

DataStream.readChar

Reads a character from this stream.

Syntax

public char readChar()

Return Value

Returns a character of data from this stream.

Remarks

This method implements the IDataStream.readChar method. This method calls the read method to read two bytes and combine them into a character.


 DataStream.readChars

DataStream.readChars

Reads the specified number of characters from this stream.

Syntax

public char[] readChars( int count )

public void readChars( char[] buffer, int index, int count )

Parameters

buffer

The array to read data into.

index

The starting index in the array.

count

The number of characters to read.

Return Value

Returns an array of characters containing the data that was read.

Remarks

This method implements the IDataStream.readChars method. This method validates the arguments and then calls the readCore method to read the data.


 DataStream.readCore

DataStream.readCore

Implements the core array read method.

Syntax

protected int readCore( Object buffer, int offset, int count )

Parameters

buffer

An array of primitive types to be read.

offset

The byte offset into buffer.

count

The number of bytes in buffer to read.

Return Value

Returns an array of data from this stream.

Exceptions

IOException thrown if an error occurs or if the stream does not support reading.

Remarks

This method is called from the other array reading methods of this class. This method reads count bytes of data into buffer starting at offset. The buffer parameter is guaranteed to be of type byte[], char[], short[], int[], long[], float[], or double[]. The default implementation throws an IOException, but a subclass can override the method to provide the appropriate functionality.


 DataStream.readDouble

DataStream.readDouble

Reads a double value from this stream.

Syntax

public double readDouble()

Return Value

Returns the double value that was read.

Remarks

This method implements the IDataStream.readDouble method. This method calls the readLong method to read a long value and then converts the bits to a double value.


 DataStream.readDoubles

DataStream.readDoubles

Reads the specified number of doubles from this stream into a double array.

Syntax

public double[] readDoubles( int count )

public void readDoubles( double[] buffer, int index, int count )

Parameters

count

The number of double values to read.

buffer

The array to read data into.

index

The starting index in the array.

Return Value

Returns a double array containing the data that was read.

Remarks

This method implements the IDataStream.readDoubles method. This method validates the arguments and then calls the readCore method to read the data.


 DataStream.readFloat

DataStream.readFloat

Reads a float value from this stream.

Syntax

public float readFloat()

Return Value

Returns the float value that was read.

Remarks

This method implements the IDataStream.readFloat method. This method calls the readInt method to read an integer and then converts the bits to a float value.

See Also writeFloat


 DataStream.readFloats

DataStream.readFloats

Reads a specified number of float values from this stream into a float array.

Syntax

public float[] readFloats( int count )

public void readFloats( float[] buffer, int index, int count )

Parameters

buffer

The array to read data into.

index

The starting index in the array.

count

The number of float values to read.

Return Value

Returns a float array containing the data read.

Remarks

This method implements the IDataStream.readFloats method. This method validates the arguments and then calls the readCore method to read the data.


 DataStream.readInt

DataStream.readInt

Reads an integer from this stream.

Syntax

public int readInt()

Return Value

Returns an integer from this stream.

Remarks

This method implements the IDataStream.readInt method. This method calls the read method to read four bytes and then combine them into an integer.


 DataStream.readInts

DataStream.readInts

Reads the specified number of integers from this stream into an integer array.

Syntax

public int[] readInts( int count )

public void readInts( int[] buffer, int index, int count )

Parameters

buffer

The array to read data into.

index

The starting index in the array.

count

The number of integers to read.

Return Value

Returns an integer array containing the data that was read.

Remarks

This method implements the IDataStream.readInts method. This method validates the arguments and then calls the readCore method to read the data.


 DataStream.readLong

DataStream.readLong

Reads a long value from this stream.

Syntax

public long readLong()

Return Value

Returns the long value that was read.

Remarks

This method implements the IDataStream.readLong method. This method calls the readInt method twice and then combines the two integers into a long integer.


 DataStream.readLongs

DataStream.readLongs

Reads the specified number of long integers from this stream into a long array.

Syntax

public long[] readLongs( int count )

public void readLongs( long[] buffer, int index, int count )

Parameters

count

The number of long integers to read.

buffer

The array to read data into.

index

The starting index in the array.

Return Value

Returns a long integer array containing the data that was read.

Remarks

This method implements the IDataStream.readLongs method. This method validates the arguments and then calls the readCore method to read the data.


 DataStream.readShort

DataStream.readShort

Reads a short value from this stream.

Syntax

public short readShort()

Return Value

Returns the short value that was read.

Remarks

This method implements the IDataStream.readShort method. This method calls the read method to read two bytes and then combines them into a short integer.


 DataStream.readShorts

DataStream.readShorts

Reads the specified number of short integers from this stream into a short array.

Syntax

public short[] readShorts( int count )

public void readShorts( short[] buffer, int index, int count )

Parameters

count

The number of short integers to read.

buffer

The starting index in the array.

index

The byte offset into the buffer.

Return Value

Returns a short integer array containing the data that was read.

Remarks

This method implements the IDataStream.readShorts method. This method validates the arguments and then calls the readCore method to read the data.


 DataStream.readString

DataStream.readString

Reads a length-prefixed Unicode string from this stream.

Syntax

public String readString()

Return Value

Returns the string value that was read.

Remarks

This method implements the IDataStream.readString method.


 DataStream.readStringChars

DataStream.readStringChars

Reads a Unicode string from this stream.

Syntax

public String readStringChars( int length )

Parameters

length

The number of characters to read.

Return Value

Returns the string value that was read.

Remarks

This method implements the IDataStream.readStringChars method.


 DataStream.readStringCharsAnsi

DataStream.readStringCharsAnsi

Reads an American National Standards Institute (ANSI) string from this stream.

Syntax

public String readStringCharsAnsi( int length )

Parameters

length

The length of the buffer in bytes.

Return Value

Returns the string value that was read.

Remarks

This method implements the IDataStream.readStringCharsAnsi method.


 DataStream.readStringNull

DataStream.readStringNull

Reads a null-terminated Unicode string from this stream.

Syntax

public String readStringNull()

Return Value

Returns the string value that was read.

Remarks

This method implements the IDataStream.readStringNull method.


 DataStream.readStringNullAnsi

DataStream.readStringNullAnsi

Reads a null-terminated ANSI string from this stream.

Syntax

public String readStringNullAnsi()

Return Value

Returns the string value that was read.

Remarks

This method implements the IDataStream.readStringNullAnsi method.


 DataStream.readToEnd

DataStream.readToEnd

Reads all data from the current position to the end of this stream.

Syntax

public byte[] readToEnd()

Return Value

Returns a byte array containing the data that was read.

Remarks

This method implements the IDataStream.readToEnd method.


 DataStream.readUTF

DataStream.readUTF

Reads a string from this stream using a length-prefixed UTF-8 format.

Syntax

public String readUTF()

Return Value

Returns the string that was read.

Remarks

This method implements the IDataStream.readUTF method.


 DataStream.setLength

DataStream.setLength

Sets the length of this stream.

Syntax

public void setLength( long length )

Parameters

length

The new length of this stream.

Remarks

This method implements the IByteStream.setLength method. The default implementation throws an IOException, but a subclass can override this method to provide the appropriate functionality.


 DataStream.setPosition

DataStream.setPosition

Sets the position of this stream.

Syntax

public void setPosition( long position )

Parameters

position

The new position of the stream.

Remarks

This method implements the IByteStream.setPosition method. The default implementation throws an IOException, but a subclass can override this method to provide the appropriate functionality.


 DataStream.toComStream

DataStream.toComStream

Retrieves an IStream object for an IDataStream object.

Syntax

public static IStream toComStream( IDataStream dataStream )

Parameters

dataStream

The IDataStream object to create an IStream object from.

Return Value

Returns a com.ms.com.IStream for the specified IDataStream object.

Remarks

If you have an IDataStream object but need a COM-compatible IStream object, you can use this method to create an adapter.

If the specified IDataStream object is null, this method returns null. Otherwise, the getComStream method is called to create an IStream object from the IDataStream object.

See Also fromComStream, getComStream


 DataStream.write

DataStream.write

Writes bytes of data to this stream.

Syntax

public void write( int value )

public void write( byte[] buffer, int index, int count )

Parameters

value

The value to write.

buffer

The array containing the data to write.

index

The starting index in the buffer.

count

The number of bytes to write.

Remarks

This method implements the IByteStream.write method. The first syntax writes the next byte of data. The second syntax validates the arguments and then calls the writeCore method to write the data.


 DataStream.writeBoolean

DataStream.writeBoolean

Writes a boolean value to this stream.

Syntax

public void writeBoolean( boolean value )

Parameters

value

The value to write.

Remarks

This method implements the IDataStream.writeBoolean method. This method calls the write method to write a byte to the stream with the value 0 for false or the value 1 for true.


 DataStream.writeByte

DataStream.writeByte

Writes a byte to this stream.

Syntax

public void writeByte( byte value )

Parameters

value

The value to write.

Remarks

This method implements the IDataStream.writeByte method. This method calls the write method to write the byte to the stream.


 DataStream.writeBytes

DataStream.writeBytes

Writes a block of bytes to this stream.

Syntax

public void writeBytes( byte[] buffer )

Parameters

buffer

The buffer block to write.

Remarks

This method implements the IDataStream.writeBytes method. This method calls the write method to write the data.


 DataStream.writeChar

DataStream.writeChar

Writes a character to this stream.

Syntax

public void writeChar( char value )

Parameters

value

The value to write.

Remarks

This method implements the IDataStream.writeChar method. This method calls the write method to write two bytes to the stream.


 DataStream.writeChars

DataStream.writeChars

Writes the contents of the specified character array to this stream.

Syntax

public void writeChars( char[] buffer )

public void writeChars( char[] buffer, int index, int count )

Parameters

buffer

The array containing the data to write.

index

The starting index in the array.

count

The number of characters to write.

Remarks

This method implements the IDataStream.writeChars method. This method validates the arguments and then calls the writeCore method to write the data.


 DataStream.writeCore

DataStream.writeCore

Implements the core array write method.

Syntax

protected void writeCore( Object buffer, int offset, int count )

Parameters

buffer

An array of primitive types to write.

offset

The byte offset into buffer.

count

The number of bytes in buffer to write.

Exceptions

IOException thrown if an error occurs or if the stream does not support writing.

Remarks

This method is called from the other array writing methods of this class. The method writes count bytes of data from buffer starting at offset. The buffer parameter is guaranteed to be of type byte[], char[], short[], int[], long[], float[], or double[]. The default implementation throws an IOException, but a subclass can override this method to provide the appropriate functionality.


 DataStream.writeDouble

DataStream.writeDouble

Writes a double value to this stream.

Syntax

public void writeDouble( double value )

Parameters

value

The double value to write.

Remarks

This method implements the IDataStream.writeDouble method. This method converts the bits of the double value to a long integer and then calls writeLong to write the value to the stream.


 DataStream.writeDoubles

DataStream.writeDoubles

Writes the contents of the specified double array to this stream.

Syntax

public void writeDoubles( double[] buffer )

public void writeDoubles( double[] buffer, int index, int count )

Parameters

buffer

An array of primitive types to write.

index

The byte offset into buffer.

count

The number of double values to write.

Remarks

This method implements the IDataStream.writeDoubles method. This method validates the arguments and then calls the writeCore method to write the data.


 DataStream.writeFloat

DataStream.writeFloat

Writes a float value to this stream.

Syntax

public void writeFloat( float value )

Parameters

value

The value to write.

Remarks

This method implements the IDataStream.writeFloat method. This method converts the bits of the float value to an integer and then calls the writeInt method to write the value to the stream.


 DataStream.writeFloats

DataStream.writeFloats

Writes the contents of the specified float array to this stream.

Syntax

public void writeFloats( float[] buffer )

public void writeFloats( float[] buffer, int index, int count )

Parameters

buffer

An array of primitive types to write.

index

The byte offset into buffer.

count

The number of float values to write.

Remarks

This method implements the IDataStream.writeFloats method. The first syntax calls the writeFloats method to write the data. The second syntax validates the arguments and then calls the writeCore method to write the data.


 DataStream.writeInt

DataStream.writeInt

Writes an integer to this stream.

Syntax

public void writeInt( int value )

Parameters

value

The value to write.

Remarks

This method implements the IDataStream.writeInt method. This method calls the write method to write four bytes to the stream.


 DataStream.writeInts

DataStream.writeInts

Writes the contents of the specified integer array to this stream.

Syntax

public void writeInts( int[] buffer )

public void writeInts( int[] buffer, int index, int count )

Parameters

buffer

An array of primitive types to write.

index

The byte offset into buffer.

count

The number of integers to write.

Remarks

This method implements the IDataStream.writeInts method. The first syntax calls the writeInts method to write the data. The second syntax validates the arguments and then calls the writeCore method to write the data.


 DataStream.writeLong

DataStream.writeLong

Writes a long value to this stream.

Syntax

public void writeLong( long value )

Parameters

value

The value to write.

Remarks

This method implements the IDataStream.writeLong method. This method calls the writeInt method twice to write the long value to the stream.


 DataStream.writeLongs

DataStream.writeLongs

Writes the contents of the specified long integer array to this stream.

Syntax

public void writeLongs( long[] buffer )

public void writeLongs( long[] buffer, int index, int count )

Parameters

buffer

An array of primitive types to write.

index

The byte offset into buffer.

count

The number of long integers to write.

Remarks

This method implements the IDataStream.writeLongs method. The first syntax calls the writeLongs method to write the data. The second syntax validates the arguments and then calls the writeCore method to write the data.


 DataStream.writeShort

DataStream.writeShort

Writes a short value to this stream.

Syntax

public void writeShort( short value )

Parameters

value

The value to write.

Remarks

This method implements the IDataStream.writeShort method. This method calls the write method to write two bytes to the stream.


 DataStream.writeShorts

DataStream.writeShorts

Writes the contents of the specified short integer array to this stream.

Syntax

public void writeShorts( short[] buffer )

public void writeShorts( short[] buffer, int index, int count )

Parameters

buffer

An array of primitive types to write.

index

The byte offset into buffer.

count

The number of short integers to write.

Remarks

This method implements the IDataStream.writeShorts method. The first syntax calls the writeShorts method to write the data. The second syntax validates the arguments and then calls the writeCore method to write the data.


 DataStream.writeString

DataStream.writeString

Writes a length-prefixed Unicode string to this stream.

Syntax

public void writeString( String value )

Parameters

value

The string to write.

Remarks

This method implements the IDataStream.writeString method.


 DataStream.writeStringChars

DataStream.writeStringChars

Writes a Unicode string to this stream.

Syntax

public void writeStringChars( String value )

Parameters

value

The string to write.

Remarks

This method implements the IDataStream.writeStringChars method.


 DataStream.writeStringCharsAnsi

DataStream.writeStringCharsAnsi

Writes an ANSI string to this stream.

Syntax

public void writeStringCharsAnsi( String value )

Parameters

value

The string to write.

Remarks

This method implements the IDataStream.writeStringCharsAnsi method.


 DataStream.writeStringNull

DataStream.writeStringNull

Writes a null-terminated Unicode string to this stream.

Syntax

public void writeStringNull( String value )

Parameters

value

The string to write.

Remarks

This method implements the IDataStream.writeStringNull method.


 DataStream.writeStringNullAnsi

DataStream.writeStringNullAnsi

Writes a null-terminated ANSI string to this stream.

Syntax

public void writeStringNullAnsi( String value )

Parameters

value

The string to write.

Remarks

This method implements the IDataStream.writeStringNullAnsi method.


 DataStream.writeUTF

DataStream.writeUTF

Writes a string to this stream using a length-prefixed UTF-8 format.

Syntax

public void writeUTF( String value )

Parameters

value

The string to write.

Remarks

This method implements the IDataStream.writeUTF method.


EOFException Class

Represents an end-of-file (EOF) exception.

IOException
  |
  +--EOFException

package com.ms.wfc.io

public class EOFException
extends IOException

Remarks

This exception is raised by the read methods of IDataStream implementations when the end of the stream is reached before the data has been completely read.


 EOFException Methods

EOFException Methods

Constructors | Description
EOFException | Creates an EOFException object.


 EOFException.EOFException

EOFException.EOFException

Creates an EOFException object.

Syntax

public EOFException()

public EOFException( String s )

Parameters

s

The text to be displayed when the exception occurs. If no string is passed, a default message is displayed.


File Class

Implements access to files.

DataStream
  |
  +--File

package com.ms.wfc.io

public class File
extends DataStream

Remarks

Provides the IDataStream interface for a file and also contains methods to perform file-, directory-, and path-oriented functions.

Instances of File can be created using the constructors in the class or the create, open, openRead, openStandardError, openStandardInput, or openStandardOutput static methods.

For a complete list of input/output (I/O) methods supported by a file, see the IByteStream and IDataStream interfaces.

The File class implements direct access to the underlying file with no buffering. If you are performing a large number of fairly small read or write operations, you can increase performance by putting a BufferedStream before the File object.

Errors that originate from the operating system while performing operations on a file are reported using the WinIOException class, which provides access to the underlying operating system error code.


 File Methods

File Methods

Constructors | Description
File | Creates a File object given a new or existing file.

Methods | Description
changeExtension | Changes the extension of a file path.
close | Closes this file.
combine | Combines two file paths.
copy | Copies an existing file to a new file.
copyOver | Copies an existing file to a new or existing file.
create | Creates a new file.
createDirectories | Creates all directories designated by the specified path.
createDirectory | Creates a new directory.
delete | Deletes a file.
exists | Determines whether a file exists.
finalize | Finalizes this File object by ensuring that the close method is called.
flush | Clears the buffers for this file and causes all buffered data to be written to the file.
getAttributes | Retrieves the attributes for the specified file or directory.
getCurrentDirectory | Retrieves the current directory.
getDirectory | Retrieves the directory path of a file path.
getExtension | Retrieves the extension of the specified path.
getFiles | Retrieves the names of the files that match the specified search path.
getFullPath | Expands the specified path to a fully qualified path.
getHandle | Retrieves the file handle associated with this File object.
getLength | Retrieves the length in bytes of this file.
getLogicalDrives | Retrieves the specification for the logical drives.
getName | Retrieves the name and extension of the specified path.
getPosition | Retrieves the current position of this file.
getRoot | Retrieves the root portion of the specified path.
hasExtension | Determines whether a path includes a file extension.
isDirectory | Determines whether the specified path refers to a directory.
isFile | Determines whether the specified path refers to a file.
isRooted | Determines whether the specified path contains a root.
lock | Locks a region in this file.
open | Opens an existing file for read and write access.
openRead | Opens an existing file for read access only.
openStandardError | Opens the standard error file.
openStandardInput | Opens the standard input file.
openStandardOutput | Opens the standard output file.
read | Reads the next byte of data from this file.
readByte | Reads a byte from this file.
readChar | Reads a character from this file.
readInt | Reads an integer from this file.
readLong | Reads a long value from this file.
readShort | Reads a short value from this file.
removeDirectory | Removes an existing empty directory.
rename | Renames an existing file or directory.
setAttributes | Sets the attributes of a file.
setCurrentDirectory | Sets the current directory.
setLength | Sets the length of this file to the specified value.
setPosition | Sets the current position of this file to the specified value.
unlock | Unlocks a region in this file.
write | Writes a byte of data to this file.
writeByte | Writes a byte to this file.
writeChar | Writes a character to this file.
writeInt | Writes an integer to this file.
writeLong | Writes a long value to this file.
writeShort | Writes a short value to this file.


 File.changeExtension

File.changeExtension

Changes the extension of a file path.

Syntax

public static String changeExtension( String path, String extension )

Parameters

path

The path for which to change the file extension.

extension

The new file extension (with a leading period) or null to remove the extension.

Return Value

Returns the path with the new file extension.

Remarks

This method returns a file path with the same root, directory, and base name parts as the path parameter, but the file extension changes to the specified extension. If the path parameter is null, the function returns null. If the path parameter does not contain a file extension, a new one is appended to the path. If the extension parameter is null, any existing extension is removed from the path parameter.

See Also getExtension, hasExtension


 File.close

File.close

Closes this file.

Syntax

public void close()

Remarks

Unless the File object was created from an existing file handle, the underlying file handle is closed using the CloseHandle Windows API function. Once closed, it is an error to perform operations on the file. Attempts to do so will raise an IOException. To reopen a file, create a new File object.

Overrides DataStream.close

See Also IByteStream.close


 File.combine

File.combine

Combines two file paths.

Syntax

public static String combine( String path1, String path2 )

Parameters

path1

The first path.

path2

The second path.

Return Value

Returns the combined path.

Remarks

If path2 does not include a root (for example, if path2 does not start with a backslash (\) or a drive specification), the result is a concatenation of the two paths, with an intervening backslash if required. If path2 includes a root, the result is path2. If either path1 or path2 is null, the result is a non-null string. If both path1 and path2 are null, the result is null.


 File.copy

File.copy

Copies an existing file to a new file.

Syntax

public static void copy( String sourceFileName, String destFileName )

Parameters

sourceFileName

The name of the file to copy.

destFileName

The name of the destination file to copy to.

Exceptions

WinIOException thrown if an error occurs or if the destination file exists.

Remarks

Use the copyOver method to allow an existing file to be overwritten.


 File.copyOver

File.copyOver

Copies an existing file to a new or existing file.

Syntax

public static void copyOver( String sourceFileName, String destFileName )

Parameters

sourceFileName

The name of the file to copy.

destFileName

The name of the destination file to copy to.

Exceptions

WinIOException thrown if an error occurs.

Remarks

Unlike the copy method, this method does not raise an exception if the destination file exists.


 File.create

File.create

Creates a new file.

Syntax

public static File create( String path )

Parameters

path

The name of the file to create.

Return Value

Returns a File object for the new file.

Exceptions

WinIOException thrown if an error occurs.

Remarks

If a file with the specified name exists, it is truncated to zero length. The returned File object will have both read and write access to the new file.

See Also close


 File.createDirectories

File.createDirectories

Creates all directories designated by the specified path.

Syntax

public static void createDirectories( String path )

Parameters

path

The path of directories to create.

Exceptions

WinIOException thrown if an error occurs.

Remarks

Unlike the createDirectory method, this method creates as many directories as are required to guarantee that the specified path is valid. It is not an error if some or all the specified directories exist. The path parameter specifies a directory path, not a file path. To ensure that all directories in a file path are created, use the constructor File.createDirectories(File.getDirectory(filePath)).


 File.createDirectory

File.createDirectory

Creates a new directory.

Syntax

public static void createDirectory( String path )

Parameters

path

The path of the directory to create.

Exceptions

WinIOException thrown if an error occurs.

Remarks

Except for the last element, the specified path must designate an existing directory. The last element in the path specifies the name of the new directory to create. It is an error if a file or directory with that name exists.

See Also createDirectories, removeDirectory


 File.delete

File.delete

Deletes a file.

Syntax

public static void delete( String path )

Parameters

path

The path of the file to delete.

Exceptions

WinIOException thrown if an error occurs.

Remarks

The file specified by the designated path is deleted. It is not an error if the specified file does not exist.


 File.exists

File.exists

Determines whether a file exists.

Syntax

public static boolean exists( String path )

Parameters

path

The path of the file to test.

Return Value

Returns true if the file specified by the designated path exists; otherwise, returns false.


 File.File

File.File

Creates a File object given a new or existing file.

Syntax

public File( String path, int mode, int access, int share)

public File( int handle )

public File( int handle, boolean owned )

Parameters

path

The path of the file to create or open.

mode

The mode used to open the file. Can be any value from the FileMode enumeration.

access

The access to the file. Can be any value from the FileAccess enumeration.

share

The share access that the file will support when opened. Can be any value from the FileShare enumeration.

handle

An existing file handle.

owned

specifies whether the File object owns the handle.

Exceptions

WinIOException thrown if an error occurs.

Remarks

The owned parameter specifies whether the File object owns the specified handle. A file handle that is not owned is not automatically closed when the close method is called or when the File object is released through garbage collection.

The specified handle parameter is considered to be externally managed and is not automatically closed when the close method is called or when the File object is released through garbage collection.

The designated file is created or opened according to the specified access, mode, and share parameters. The file remains open until the close method is called or until the File object is released through garbage collection. Following a call to close, any operations on the file will raise exceptions.

See Also close, create, open, openRead, openStandardError, openStandardInput, openStandardOutput


 File.finalize

File.finalize

Finalizes this File object by ensuring that the close method is called.

Syntax

protected void finalize() throws Throwable


 File.flush

File.flush

Clears the buffers for this file and causes all buffered data to be written to the file.

Syntax

public void flush()

Exceptions

WinIOException thrown if an error occurs or if the file has been closed.

Remarks

This method calls the FlushFileBuffers Windows API function.

Overrides DataStream.flush

See Also com.ms.wfc.io.IByteStream.flush


 File.getAttributes

File.getAttributes

Retrieves the attributes for the specified file or directory.

Syntax

public static int getAttributes( String path )

Parameters

path

The path of a file or directory.

Return Value

Returns the attributes of the file or directory.

Exceptions

WinIOException thrown if an error occurs.

Remarks

The return value is a combination of the ARCHIVE, COMPRESSED, DIRECTORY, HIDDEN, OFFLINE, READONLY, SYSTEM, and TEMPORARY FileAttribute flags.

See Also setAttributes


 File.getCurrentDirectory

File.getCurrentDirectory

Retrieves the current directory.

Syntax

public static String getCurrentDirectory()

Return Value

Returns the absolute path of the current directory.

Exceptions

WinIOException thrown if an error occurs.

See Also setCurrentDirectory


 File.getDirectory

File.getDirectory

Retrieves the directory path of a file path.

Syntax

public static String getDirectory( String path )

Parameters

path

The path of a file or directory.

Return Value

Returns the directory path of the specified path, or returns null if the specified path includes a root.

Remarks

This method effectively removes the last element of the specified file path; for example, it returns a string consisting of all characters up to but not including the last backslash (\) in the file path. The returned value is null if the file path is null or if the file path includes a root, such as backslash (\), C:, or \\server\share.

See Also getExtension, getName, getRoot, isRooted


 File.getExtension

File.getExtension

Retrieves the extension of the specified path.

Syntax

public static String getExtension( String path )

Parameters

path

The path of a file or directory.

Return Value

Returns the extension of the specified path, or returns null if the specified path is null or does not include an extension.

Remarks

The return value includes the period (.) in the extension, such as .exe or .java.

See Also changeExtension, getDirectory, getName, getRoot, hasExtension


 File.getFiles

File.getFiles

Retrieves the names of the files that match the specified search path.

Syntax

public static String[] getFiles( String path )

Parameters

path

The search path.

Return Value

Returns an array of strings containing the names of the files that match the search path.


 File.getFullPath

File.getFullPath

Expands the specified path to a fully qualified path.

Syntax

public static String getFullPath( String path )

Parameters

path

The path to be fully qualified.

Return Value

The fully qualified path.

Exceptions

WinIOException thrown if an error occurs.

Remarks

The resulting string consists of a drive letter, a colon, and a root relative path. This method does not verify whether the resulting path is valid or whether it refers to an existing file or directory on the associated volume.


 File.getHandle

File.getHandle

Retrieves the file handle associated with this File object.

Syntax

public int getHandle()

Return Value

Returns the file handle for this File object.

Remarks

The return value is -1 if the file has been closed.


 File.getLength

File.getLength

Retrieves the length in bytes of this file.

Syntax

public long getLength()

Return Value

Returns the length of the file.

Exceptions

WinIOException thrown if the length of the file cannot be determined or if the file has been closed.

Overrides DataStream.getLength

See Also IByteStream.getLength, setLength


 File.getLogicalDrives

File.getLogicalDrives

Retrieves the specification for the logical drives.

Syntax

public static String[] getLogicalDrives()

Return Value

Returns the specification for the logical drives.


 File.getName

File.getName

Retrieves the name and extension of the specified path.

Syntax

public static String getName( String path )

Parameters

path

The path of a file or directory.

Return Value

Returns the name and extension of the specified path.

Remarks

The resulting string contains the characters of the path parameter that follow the last backslash (\) or colon (:) in the path parameter. The resulting string is the entire path if the path parameter does not contain either a backslash or a colon. The resulting string is null if the path parameter is null.

See Also getDirectory, getExtension, getRoot


 File.getPosition

File.getPosition

Retrieves the current position of this file.

Syntax

public long getPosition()

Return Value

Returns the current position of the file.

Exceptions

WinIOException thrown if either an I/O error occurs or if the file does not allow positioning.

Overrides DataStream.getPosition

See Also IByteStream.getPosition, setPosition


 File.getRoot

File.getRoot

Retrieves the root portion of the specified path.

Syntax

public static String getRoot( String path )

Parameters

path

The path of a file or directory.

Return Value

Returns the root portion of the specified path.

Remarks

The resulting string consists of the rightmost characters that make up the root of the path. Possible patterns for the resulting string are:

  • An empty string (a relative path on the current drive).
  • \ An absolute path on the current drive.
  • x: A relative path on a specified drive, where x is the drive letter.
  • x:\ An absolute path on a specified drive.
  • \\server\share A universal naming convention (UNC) path for a specific server and share name.

The resulting string is null if path is null.

See Also getDirectory, getExtension, getName, isRooted


 File.hasExtension

File.hasExtension

Determines whether a path includes a file extension.

Syntax

public static boolean hasExtension( String path )

Parameters

path

The path to test.

Return Value

Returns true if the characters that follow the last backslash (\) or colon (:) in the path include a period (.); otherwise, returns false.

See Also changeExtension, getExtension


 File.isDirectory

File.isDirectory

Determines whether the specified path refers to a directory.

Syntax

public static boolean isDirectory( String path )

Parameters

path

The path to test.

Return Value

Returns true if the path refers to a directory; otherwise, returns false.

See Also exists, isFile


 File.isFile

File.isFile

Determines whether the specified path refers to a file.

Syntax

public static boolean isFile( String path )

Parameters

path

The path to test.

Return Value

Returns true if the path refers to a file; otherwise, returns false.

See Also exists, isDirectory


 File.isRooted

File.isRooted

Determines whether the specified path contains a root.

Syntax

public static boolean isRooted( String path )

Parameters

path

The path to test.

Return Value

Returns true if the path contains a root; otherwise, returns false.

Remarks

A path is considered to contain a root if it starts with either a backslash (\) or with a drive letter and a colon (:).

See Also getRoot


 File.lock

File.lock

Locks a region in this file.

Syntax

public void lock( long position, long length )

Parameters

position

The starting position of the range to be locked.

length

The length of the range to be locked.

Exceptions

WinIOException thrown if an error occurs or if the file has been closed.

Remarks

Locking a region in a file gives the locking process exclusive access to the specified region. File locks are not inherited by processes created by the locking process. Locking a region in a file denies all other processes both read and write access to the specified region. Locking a region that goes beyond the current end-of-file position is not an error. Locks cannot overlap an existing locked region in the file.

See Also unlock


 File.open

File.open

Opens an existing file for read and write access.

Syntax

public static File open( String path )

Parameters

path

The path of the file to open.

Return Value

Returns a File object for the opened file.

Exceptions

WinIOException thrown if an error occurs.

Remarks

This method is a convenient way of constructing a new File object with the FileMode.OPEN, FileAccess.READWRITE, and FileShare.NONE flags.

See Also openRead, close


 File.openRead

File.openRead

Opens an existing file for read access only.

Syntax

public static File openRead( String path )

Parameters

path

The path of the file to open.

Return Value

Returns a File object for the opened file.

Exceptions

WinIOException thrown if an error occurs.

Remarks

This method is a convenient way of constructing a new File object with the FileMode.OPEN, FileAccess.READ, and FileShare.READ flags.

See Also open, close


 File.openStandardError

File.openStandardError

Opens the standard error file.

Syntax

public static File openStandardError()

Return Value

Returns a File object for the standard error file.

Exceptions

WinIOException thrown if an error occurs.


 File.openStandardInput

File.openStandardInput

Opens the standard input file.

Syntax

public static File openStandardInput()

Return Value

Returns a File object for the standard input file.

Exceptions

WinIOException thrown if an error occurs.


 File.openStandardOutput

File.openStandardOutput

Opens the standard output file.

Syntax

public static File openStandardOutput()

Return Value

Returns a File object for the standard output file.

Exceptions

WinIOException thrown if an error occurs.


 File.read

File.read

Reads the next byte of data from this file.

Syntax

public int read()

Return Value

Returns the next byte of data from this file.

Overrides DataStream.read

See Also IByteStream.read


 File.readByte

File.readByte

Reads a byte from this file.

Syntax

public byte readByte()

Return Value

Returns a byte from this file.

Overrides DataStream.readByte

See Also IDataStream.readByte


 File.readChar

File.readChar

Reads a character from this file.

Syntax

public char readChar()

Return Value

Returns a character from this file.

Overrides DataStream.readChar

See Also IDataStream.readChar


 File.readInt

File.readInt

Reads an integer from this file.

Syntax

public int readInt()

Return Value

Returns an integer from this file.

Overrides DataStream.readInt

See Also IDataStream.readInt


 File.readLong

File.readLong

Reads a long value from this file.

Syntax

public long readLong()

Return Value

Returns a long value from this file.

Overrides DataStream.readLong

See Also IDataStream.readLong


 File.readShort

File.readShort

Reads a short value from this file.

Syntax

public short readShort()

Return Value

Returns a short value from this file.

Overrides DataStream.readShort

See Also IDataStream.readShort


 File.removeDirectory

File.removeDirectory

Removes an existing empty directory.

Syntax

public static void removeDirectory( String path )

Parameters

path

The path of the directory to remove.

Exceptions

WinIOException thrown if an error occurs.

Remarks

The path must specify an empty directory, and the calling process must have delete access to the directory.

See Also createDirectory


 File.rename

File.rename

Renames an existing file or directory.

Syntax

public static void rename( String curPath, String newPath )

Parameters

curPath

The path of the file or directory to rename.

newPath

The new path of the file or directory.

Exceptions

WinIOException thrown if an error occurs.

Remarks

The curPath parameter must refer to an existing file or directory. The newPath parameter specifies the new file name or directory name. The new name must not exist. A new file can be on a different file system or drive. A new directory must be on the same drive.


 File.setAttributes

File.setAttributes

Sets the attributes of a file.

Syntax

public static void setAttributes( String path, int attributes )

Parameters

path

The path of the file whose attributes to set.

attributes

The attributes for the file.

Exceptions

WinIOException is thrown if an error occurs.

Remarks

The path parameter must refer to an existing file. The attributes parameter must be a combination of the ARCHIVE, HIDDEN, OFFLINE, READONLY, SYSTEM, and TEMPORARY attribute flags defined in the FileAttribute class.

See Also getAttributes


 File.setCurrentDirectory

File.setCurrentDirectory

Sets the current directory.

Syntax

public static void setCurrentDirectory( String path )

Parameters

path

Path of the new current directory.

Exceptions

WinIOException thrown if an error occurs.

Remarks

The path parameter specifies the path to the new current directory. This parameter can be a relative path or a fully qualified path. In either case, the fully qualified path of the specified directory is calculated and stored as the current directory.

See Also getCurrentDirectory


 File.setLength

File.setLength

Sets the length of this file to the specified value.

Syntax

public void setLength( long value )

Parameters

value

The new length of the file.

Exceptions

WinIOException thrown if an error occurs or if the file has been closed.

Remarks

If this value is less than the current length of the file, the file is truncated. If it is larger than the current length of the file, the file is expanded. If the file is expanded, the contents of the file between the old and the new length are undefined.

See Also IByteStream.setLength, getLength


 File.setPosition

File.setPosition

Sets the current position of this file to the specified value.

Syntax

public void setPosition( long value )

Parameters

value

The new position of the file.

Exceptions

WinIOException thrown if an error occurs or if the file has been closed.

Remarks

It is not an error to set the current position beyond the length of the file.

See Also IByteStream.setPosition, getPosition


 File.unlock

File.unlock

Unlocks a region in this file.

Syntax

public void unlock( long position, long length )

Parameters

position

The starting position of the range to be unlocked.

length

The length of the range to be unlocked.

Exceptions

WinIOException thrown if an error occurs or if the file has been closed.

Remarks

Unlocking a region enables other processes to access the region. The region to unlock must correspond exactly to an existing locked region. For example, two adjacent regions of a file cannot be locked separately and then unlocked as a single region that spans both locked regions. A process should end with a portion of a file locked, and a file that has locked regions should not be closed.

See Also lock


 File.write

File.write

Writes a byte of data to this file.

Syntax

public void write( int value )

Parameters

value

The integer value to write to the file.

Overrides DataStream.write

See Also IByteStream.write


 File.writeByte

File.writeByte

Writes a byte to this file.

Syntax

public void writeByte( byte value )

Parameters

value

The byte value to write to the file.

Overrides DataStream.writeByte

See Also IDataStream.writeByte


 File.writeChar

File.writeChar

Writes a character to this file.

Syntax

public void writeChar( char value )

Parameters

value

The character value to write to the file.

Overrides DataStream.writeChar

See Also IDataStream.writeChar


 File.writeInt

File.writeInt

Writes an integer to this file.

Syntax

public void writeInt( int value )

Parameters

value

The integer value to write to the file.

Overrides DataStream.writeInt

See Also IDataStream.writeInt


 File.writeLong

File.writeLong

Writes a long value to this file.

Syntax

public void writeLong( long value )

Parameters

value

The long value to write to the file.

Overrides DataStream.writeLong

See Also IDataStream.writeLong


 File.writeShort

File.writeShort

Writes a short value to this file.

Syntax

public void writeShort( short value )

Parameters

value

The short value to write to the file.

Overrides DataStream.writeShort

See Also IDataStream.writeShort


FileAccess Class

Defines constants that specify file access.

Enum
  |
  +--FileAccess

package com.ms.wfc.io

public class FileAccess
extends Enum


 FileAccess Methods

FileAccess Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 FileAccess.valid

FileAccess.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 FileAccess Fields

FileAccess Fields

Fields | Description
READ | Specifies read access to the file.
READWRITE | Specifies read and write access to the file.
WRITE | Specifies write access to the file.


 FileAccess.READ

FileAccess.READ

Specifies read access to the file.

Syntax

public static final int READ;

Remarks

Reads data from the file, and moves the file pointer. Combine this flag with WRITE for read/write access.


 FileAccess.READWRITE

FileAccess.READWRITE

Specifies read and write access to the file.

Syntax

public static final int READWRITE;

Remarks

Writes data to the file, and moves the file pointer. Data can also be read from the file.


 FileAccess.WRITE

FileAccess.WRITE

Specifies write access to the file.

Syntax

public static final int WRITE;

Remarks

Writes data to the file, and moves the file pointer. Combine this flag with READ for read/write access.


FileAttribute Class

Defines constants that specify file attributes.

Enum
  |
  +--FileAttribute

package com.ms.wfc.io

public class FileAttribute
extends Enum


 FileAttribute Methods

FileAttribute Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 FileAttribute.valid

FileAttribute.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 FileAttribute Fields

FileAttribute Fields

Fields | Description
ARCHIVE | Specifies that the file is an archive file.
COMPRESSED | Specifies that the file or directory is compressed.
DIRECTORY | Specifies that the file is a directory.
HIDDEN | Specifies that the file is hidden.
OFFLINE | Specifies that the data of the file is not immediately available.
READONLY | Specifies that the file is read-only.
SYSTEM | Specifies that the file is part of or is used exclusively by the operating system.
TEMPORARY | Specifies that the file is being used for temporary storage.


 FileAttribute.ARCHIVE

FileAttribute.ARCHIVE

Specifies that the file is an archive file.

Syntax

public static final int ARCHIVE;

Remarks

Applications use this value to mark files for backup or removal.


 FileAttribute.COMPRESSED

FileAttribute.COMPRESSED

Specifies that the file or directory is compressed.

Syntax

public static final int COMPRESSED;

Remarks

For a file, this means that all of the data in the file is compressed. For a directory, this means that compression is the default for newly created files and subdirectories.


 FileAttribute.DIRECTORY

FileAttribute.DIRECTORY

Specifies that the file is a directory.

Syntax

public static final int DIRECTORY;


 FileAttribute.HIDDEN

FileAttribute.HIDDEN

Specifies that the file is hidden.

Syntax

public static final int HIDDEN;

Remarks

The file is not to be included in an ordinary directory listing.


 FileAttribute.OFFLINE

FileAttribute.OFFLINE

Specifies that the data of the file is not immediately available.

Syntax

public static final int OFFLINE;

Remarks

Indicates that the file data has been physically moved to offline storage.


 FileAttribute.READONLY

FileAttribute.READONLY

Specifies that the file is read-only.

Syntax

public static final int READONLY;

Remarks

Applications can read the file but cannot write to it or delete it.


 FileAttribute.SYSTEM

FileAttribute.SYSTEM

Specifies that the file is part of or is used exclusively by the operating system.

Syntax

public static final int SYSTEM;


 FileAttribute.TEMPORARY

FileAttribute.TEMPORARY

Specifies that the file is being used for temporary storage.

Syntax

public static final int TEMPORARY;

Remarks

Applications should write to the file only if absolutely necessary. Most of the file's data remains in memory without being flushed to the media because the file will soon be deleted.


FileEnumerator Class

Searches the file system for files that match a specified pattern.

package com.ms.wfc.io

public class FileEnumerator

Remarks

The following example shows how to use the FileEnumerator class to find and output the names of all Java files in and below a specified directory.

static void printJavaFiles(String path) {
    FileEnumerator e = new FileEnumerator(File.combine(path, "*.*"));
    while (e.hasMoreFiles()) {
        String name = e.getName();
        if ((e.getAttributes() & File.DIRECTORY) != 0) {
            if (!name.equals(".") && !name.equals("..")) {
                printJavaFiles(File.combine(path, name));
            }
        }
        else {
            String ext = File.getExtension(name);
            if (ext != null && ext.equalsIgnoreCase(".java")) {
                System.out.println(File.combine(path, name));
            }
        }
        e.getNextFile();
    }
}


 FileEnumerator Methods

FileEnumerator Methods

Constructors | Description
FileEnumerator | Creates a FileEnumerator object.

Methods | Description
close | Closes this file enumerator.
finalize | Ensures that the close method has been called for this file enumerator.
getAttributes | Retrieves the file attributes for the current file.
getCreationTime | Retrieves the creation time of the current file.
getLastAccessTime | Retrieves the last access time of the current file.
getLastWriteTime | Retrieves the last write time of the current file.
getName | Retrieves the name of the current file.
getNextFile | Finds the next file that matches the pattern of the file enumerator.
getSize | Retrieves the size in bytes of the current file.
hasMoreFiles | Detrmines whether additional files remain to be enumerated.


 FileEnumerator.close

FileEnumerator.close

Closes this file enumerator.

Syntax

public void close()

Remarks

System resources are released and any pending enumeration results are discarded. There is typcially no need to call this method because getNextFile automatically closes the enumerator when the last file has been processed.


 FileEnumerator.FileEnumerator

FileEnumerator.FileEnumerator

Creates a FileEnumerator object.

Syntax

public FileEnumerator( String path )

Parameters

path

The directory path and file name to enumerate.

Exceptions

WinIOException thrown if the specified path is invalid.

Remarks

The path parameter must specify a valid directory path and file name. The file name can contain wildcard characters (* and ?). Following the construction of a file enumerator, the hasMoreFiles method indicates whether at least one file was found that matches the specified pattern.


 FileEnumerator.finalize

FileEnumerator.finalize

Ensures that the close method has been called for this file enumerator.

Syntax

protected void finalize()


 FileEnumerator.getAttributes

FileEnumerator.getAttributes

Retrieves the file attributes for the current file.

Syntax

public int getAttributes()

Return Value

Returns a combination of the ARCHIVE, COMPRESSED, DIRECTORY, HIDDEN, OFFLINE, READONLY, SYSTEM, and TEMPORARY file attribute flags. These flags are defined in the FileAttribute class.


 FileEnumerator.getCreationTime

FileEnumerator.getCreationTime

Retrieves the creation time of the current file.

Syntax

public Time getCreationTime()

Return Value

Returns a Time object representing the creation time of the current file. The returned value is null if the file system containing the file does not support this time information.

See Also getLastAccessTime, getLastWriteTime


 FileEnumerator.getLastAccessTime

FileEnumerator.getLastAccessTime

Retrieves the last access time of the current file.

Syntax

public Time getLastAccessTime()

Return Value

Returns a Time object representing the last access time. The returned value is null if the file system containing the file does not support this time information.

See Also getCreationTime, getLastWriteTime


 FileEnumerator.getLastWriteTime

FileEnumerator.getLastWriteTime

Retrieves the last write time of the current file.

Syntax

public Time getLastWriteTime()

Return Value

Returns a Time object representing the last write time. The returned value is null if the file system containing the file does not support this time information.

See Also getCreationTime, getLastAccessTime


 FileEnumerator.getName

FileEnumerator.getName

Retrieves the name of the current file.

Syntax

public String getName()

Return Value

Returns the name of the file.


 FileEnumerator.getNextFile

FileEnumerator.getNextFile

Finds the next file that matches the pattern of the file enumerator.

Syntax

public void getNextFile()

Remarks

Following a call to this method, the hasMoreFiles method can be used to determine if more files remain in the enumeration.


 FileEnumerator.getSize

FileEnumerator.getSize

Retrieves the size in bytes of the current file.

Syntax

public long getSize()

Return Value

Returns the size of the file.


 FileEnumerator.hasMoreFiles

FileEnumerator.hasMoreFiles

Detrmines whether additional files remain to be enumerated.

Syntax

public boolean hasMoreFiles()

Return Value

Returns true if more files remain; otherwise, returns false.

See Also getNextFile


FileMode Class

Defines constants that specify file modes.

Enum
  |
  +--FileMode

package com.ms.wfc.io

public class FileMode
extends Enum


 FileMode Methods

FileMode Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 FileMode.valid

FileMode.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 FileMode Fields

FileMode Fields

Fields | Description
CREATE | Specifies that a new file is to be created; if the file already exists, it is overwritten.
CREATE_NEW | Specifies that a new file is to be created; an exception is thrown if the file already exists.
OPEN | Specifies that an existing file is to be opened; an exception is thrown if the file does not exist.
OPEN_OR_CREATE | Specifies that an existing file is to be opened; otherwise, a new file is created.
TRUNCATE | Specifies that an existing file it to be opened and then truncated so that its size is zero bytes.


 FileMode.CREATE

FileMode.CREATE

Specifies that a new file is to be created; if the file already exists, it is overwritten.

Syntax

public static final int CREATE;


 FileMode.CREATE_NEW

FileMode.CREATE_NEW

Specifies that a new file is to be created; an exception is thrown if the file already exists.

Syntax

public static final int CREATE_NEW;


 FileMode.OPEN

FileMode.OPEN

Specifies that an existing file is to be opened; an exception is thrown if the file does not exist.

Syntax

public static final int OPEN;


 FileMode.OPEN_OR_CREATE

FileMode.OPEN_OR_CREATE

Specifies that an existing file is to be opened; otherwise, a new file is created.

Syntax

public static final int OPEN_OR_CREATE;


 FileMode.TRUNCATE

FileMode.TRUNCATE

Specifies that an existing file it to be opened and then truncated so that its size is zero bytes.

Syntax

public static final int TRUNCATE;

Remarks

The calling process must open the file with at least write access. An exception is thrown if the file does not exist.


FileShare Class

Defines constants that specify file sharing.

Enum
  |
  +--FileShare

package com.ms.wfc.io

public class FileShare
extends Enum


 FileShare Methods

FileShare Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 FileShare.valid

FileShare.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 FileShare Fields

FileShare Fields

Fields | Description
NONE | Specifies that the file cannot be shared.
READ | Allows subsequent opening of the file for reading.
READWRITE | Allows subsequent opening of the file for writing or reading.
WRITE | Allows subsequent opening of the file for writing.


 FileShare.NONE

FileShare.NONE

Specifies that the file cannot be shared.

Syntax

public static final int NONE;

Remarks

Any request to open the file will fail until the file is closed.


 FileShare.READ

FileShare.READ

Allows subsequent opening of the file for reading.

Syntax

public static final int READ;

Remarks

If this flag is not specified, any request to open the file for reading will fail until the file is closed.


 FileShare.READWRITE

FileShare.READWRITE

Allows subsequent opening of the file for writing or reading.

Syntax

public static final int READWRITE;

Remarks

If this flag is not specified, any request to open the file for writing or reading will fail until the file is closed.


 FileShare.WRITE

FileShare.WRITE

Allows subsequent opening of the file for writing.

Syntax

public static final int WRITE;

Remarks

If this flag is not specified, any request to open the file for writing will fail until the file is closed.


IByteStream Interface

Represents a stream for reading and writing data in the form of bytes.

package com.ms.wfc.io

public interface IByteStream


 IByteStream Methods

IByteStream Methods

Methods | Description
canRead | Determines whether this stream supports reading.
canSeek | Clears all buffers for this stream and causes any buffered data to be written to the underlying device.
canWrite | Determines whether this stream supports writing.
close | Closes this stream and releases any system resources associated with the stream.
flush | Clears all buffers for this stream and causes any buffered data to be written to the underlying device.
getLength | Retrieves the length in bytes of this stream.
getPosition | Retrieves the current position of this stream.
read | Reads a specified number of bytes from this stream into an array starting at a specified position.
setLength | Sets the length of this stream to the specified value.
setPosition | Sets the current position of this stream to the specified value.
write | Writes a specified number of bytes into this stream from an array starting at a specified position.


 IByteStream.canRead

IByteStream.canRead

Determines whether this stream supports reading.

Syntax

public boolean canRead()

Return Value

Returns true if the stream supports reading; otherwise, returns false.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support reading.

Remarks

If a stream does not support reading, calls to the read method always raise exceptions.

See Also read


 IByteStream.canSeek

IByteStream.canSeek

Clears all buffers for this stream and causes any buffered data to be written to the underlying device.

Syntax

public boolean canSeek()

Return Value

Returns true if the stream supports seeking; otherwise, returns false.

See Also write


 IByteStream.canWrite

IByteStream.canWrite

Determines whether this stream supports writing.

Syntax

public boolean canWrite()

Return Value

Returns true if the stream supports writing; otherwise, returns false.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support writing.

Remarks

If a stream does not support writing, calls to the write method always raise exceptions.

See Also write


 IByteStream.close

IByteStream.close

Closes this stream and releases any system resources associated with the stream.

Syntax

public void close()

Remarks

Following a call to close, any operations on the stream can throw exceptions.


 IByteStream.flush

IByteStream.flush

Clears all buffers for this stream and causes any buffered data to be written to the underlying device.

Syntax

public void flush()

Exceptions

IOException thrown if an input/output (I/O) error occurs.


 IByteStream.getLength

IByteStream.getLength

Retrieves the length in bytes of this stream.

Syntax

public long getLength()

Return Value

Returns the length of the stream.

Exceptions

IOException thrown if an I/O error occurs or if the length of the stream cannot be determined.

See Also setLength


 IByteStream.getPosition

IByteStream.getPosition

Retrieves the current position of this stream.

Syntax

public long getPosition()

Return Value

Returns the current position of the stream.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support positioning.

See Also setPosition


 IByteStream.read

IByteStream.read

Reads a specified number of bytes from this stream into an array starting at a specified position.

Syntax

public int read( byte[] buffer, int index, int count )

Parameters

buffer

The byte array to read data into.

index

The starting index in the buffer.

count

The number of bytes to read.

Return Value

Returns the total number of bytes read into the buffer. This can be less than the number of bytes requested if that many bytes aren't currently available, or it can be zero if the end of the stream is reached.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support reading.

Remarks

Retrieves the actual number of bytes read. If the read operation is successful, the current position of the stream is advanced by the number of bytes read.

See Also write


 IByteStream.setLength

IByteStream.setLength

Sets the length of this stream to the specified value.

Syntax

public void setLength( long value )

Parameters

value

The new length of the stream.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support resizing.

Remarks

If this value is less than the current length of the stream, the stream is truncated. If it is greater than the current length of the stream, the stream is expanded. If the stream is expanded, the contents of the stream between the old and the new length are undefined.

See Also getLength


 IByteStream.setPosition

IByteStream.setPosition

Sets the current position of this stream to the specified value.

Syntax

public void setPosition( long value )

Parameters

value

The new position of the stream.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support positioning.

Remarks

While some streams support positioning beyond the length of the stream, others throw an exception.

See Also getPosition


 IByteStream.write

IByteStream.write

Writes a specified number of bytes into this stream from an array starting at a specified position.

Syntax

public void write( byte[] buffer, int index, int count )

Parameters

buffer

The byte array to write data from.

index

The starting index in the buffer.

count

The number of bytes to write.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support writing.

Remarks

If the write operation is successful, the current position of the stream is advanced by the specified number of bytes.

See Also read


IDataStream Interface

Represents a stream that allows the reading and writing of data in a variety of formats.

IByteStream
  |
  +--IDataStream

package com.ms.wfc.io

public interface IDataStream
extends IByteStream

Remarks

This interface is an extension of the IByteStream interface.

See Also BufferedStream, DataStream, File, MemoryStream


 IDataStream Methods

IDataStream Methods

Methods | Description
getComStream | Retrieves a COM-compatible IStream object for this stream.
readBoolean | Reads a single byte from this stream.
readByte | Reads a byte from this stream.
readBytes | Reads the specified number of bytes from this stream into a byte array.
readChar | Reads a character from this stream.
readChars | Reads the specified number of characters from this stream into a character array.
readDouble | Reads a double value from this stream.
readDoubles | Reads the specified number of double values from this stream into a double array.
readFloat | Reads a float value from this stream.
readFloats | Reads a specified number of float values from this stream into a float array.
readInt | Reads an integer from this stream.
readInts | Reads the specified number of integers from this stream into an integer array.
readLong | Reads a long value from this stream.
readLongs | Reads a specified number of long integers from this stream into a long integer array.
readShort | Reads a short value from this stream.
readShorts | Reads the specified number of short integers from this stream into a short integer array.
readString | Reads a length-prefixed Unicode string from this stream.
readStringChars | Reads a Unicode string from this stream.
readStringCharsAnsi | Reads an American National Standards Institute (ANSI) string from this stream.
readStringNull | Reads a null-terminated Unicode string from this stream.
readStringNullAnsi | Reads a null-terminated ANSI string from this stream.
readToEnd | Reads all data from the current position to the end of this stream into a byte array.
readUTF | Reads a string from this stream using a length-prefixed UTF-8 format.
writeBoolean | Writes a boolean value to this stream.
writeByte | Writes a byte to this stream.
writeBytes | Writes the contents of the specified byte array to this stream.
writeChar | Writes a character to this stream.
writeChars | Writes the contents of the specified character array to this stream.
writeDouble | Writes a double value to this stream.
writeDoubles | Writes the contents of the specified double array to this stream.
writeFloat | Writes a float value to this stream.
writeFloats | Writes the contents of the specified float array to this stream.
writeInt | Writes an integer value to this stream.
writeInts | Writes the contents of the specified integer array to this stream.
writeLong | Writes a long integer to this stream.
writeLongs | Writes the contents of the specified long integer array to this stream.
writeShort | Writes a short integer to this stream.
writeShorts | Writes the contents of the specified short integer array to this stream.
writeString | Writes a length-prefixed Unicode string to this stream.
writeStringChars | Writes a Unicode string to this stream.
writeStringCharsAnsi | Writes an ANSI string to this stream.
writeStringNull | Writes a null-terminated Unicode string to this stream.
writeStringNullAnsi | Writes a null-terminated ANSI string to this stream.
writeUTF | Writes a string to this stream using a length-prefixed UTF-8 format.


 IDataStream.getComStream

IDataStream.getComStream

Retrieves a COM-compatible IStream object for this stream.

Syntax

public IStream getComStream()

Return Value

Returns an IStream representation of this stream.

Remarks

The returned IStream object has the same current position and length as this stream. The streams remain synchronized during subsequent operations on either stream.

See Also com.ms.com.IStream


 IDataStream.readBoolean

IDataStream.readBoolean

Reads a single byte from this stream.

Syntax

public boolean readBoolean()

Return Value

Returns true if the byte is non-zero, or returns false if the byte is zero.

Exceptions

IOException thrown if an input/output (I/O) error occurs or if the stream does not support reading.

EOFException thrown if the stream is at the end.

Remarks

The current position of the stream is advanced by one byte.

See Also writeBoolean


 IDataStream.readByte

IDataStream.readByte

Reads a byte from this stream.

Syntax

public byte readByte()

Return Value

Returns the byte value that was read.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support reading.

EOFException thrown if the stream is at the end.

Remarks

The current position is advanced by one byte.

See Also writeByte


 IDataStream.readBytes

IDataStream.readBytes

Reads the specified number of bytes from this stream into a byte array.

Syntax

public byte[] readBytes( int count )

public void readBytes( byte[] buffer, int index, int count )

Parameters

count

The number of bytes to read.

buffer

The array to read data into.

index

The starting index in the array.

Return Value

Returns a byte array containing the data that was read.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support reading.

EOFException thrown if the end of the stream is reached while reading the data.

Remarks

The current position is advanced by count bytes.

See Also IByteStream.read, readToEnd, writeBytes


 IDataStream.readChar

IDataStream.readChar

Reads a character from this stream.

Syntax

public char readChar()

Return Value

Returns the character value that was read.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support reading.

EOFException thrown if the end of the stream is reached before two bytes could be read.

Remarks

The current position is advanced by two bytes.

See Also writeChar


 IDataStream.readChars

IDataStream.readChars

Reads the specified number of characters from this stream into a character array.

Syntax

public char[] readChars( int count )

public void readChars( char[] buffer, int index, int count )

Parameters

count

The number of characters to read.

buffer

The array to read data into.

index

The starting index in the array.

Return Value

Returns a character array containing the data that was read.

Remarks

The current position is advanced by count * 2 bytes.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support reading.

EOFException thrown if the end of the stream is reached while reading the data.

See Also writeChars


 IDataStream.readDouble

IDataStream.readDouble

Reads a double value from this stream.

Syntax

public double readDouble()

Return Value

Returns the double value that was read.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support reading.

EOFException thrown if the end of the stream is reached before eight bytes could be read.

Remarks

The current position is advanced by eight bytes.

See Also writeDouble


 IDataStream.readDoubles

IDataStream.readDoubles

Reads the specified number of double values from this stream into a double array.

Syntax

public double[] readDoubles( int count )

public void readDoubles( double[] buffer, int index, int count )

Parameters

count

The number of double values to read.

buffer

The array to read data into.

index

The starting index in the array.

Return Value

Returns a double array containing the data that was read.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support reading.

EOFException thrown if the end of the stream is reached while reading the data.

Remarks

The current position is advanced by count * 8 bytes.

See Also writeDoubles


 IDataStream.readFloat

IDataStream.readFloat

Reads a float value from this stream.

Syntax

public float readFloat()

Return Value

Returns the float value read.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support reading.

EOFException thrown if the end of the stream is reached before four bytes could be read.

Remarks

The current position is advanced by four bytes.

See Also writeFloat


 IDataStream.readFloats

IDataStream.readFloats

Reads a specified number of float values from this stream into a float array.

Syntax

public float[] readFloats( int count )

public void readFloats( float[] buffer, int index, int count )

Parameters

count

The number of float values to read.

buffer

The array to read data into.

index

The starting index in the array.

Return Value

Returns a float array containing the data that was read.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support reading.

EOFException thrown if the end of the stream is reached while reading the data.

Remarks

The current position is advanced by count * 4 bytes.

See Also writeFloats


 IDataStream.readInt

IDataStream.readInt

Reads an integer from this stream.

Syntax

public int readInt()

Return Value

Returns the integer value that was read.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support reading.

EOFException thrown if the end of the stream is reached before four bytes could be read.

Remarks

The current position is advanced by four bytes.

See Also writeInt


 IDataStream.readInts

IDataStream.readInts

Reads the specified number of integers from this stream into an integer array.

Syntax

public int[] readInts( int count )

public void readInts( int[] buffer, int index, int count )

Parameters

count

The number of integers to read.

buffer

The array to read data into.

index

The starting index in the array.

Return Value

Returns an integer array containing the data that was read.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support reading.

EOFException thrown if the end of the stream is reached while reading the data.

Remarks

The current position is advanced by count * 4 bytes.

See Also writeInts


 IDataStream.readLong

IDataStream.readLong

Reads a long value from this stream.

Syntax

public long readLong()

Return Value

Returns the long value that was read.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support reading.

EOFException thrown if the end of the stream is reached before eight bytes could be read.

Remarks

The current position is advanced by eight bytes.

See Also writeLong


 IDataStream.readLongs

IDataStream.readLongs

Reads a specified number of long integers from this stream into a long integer array.

Syntax

public long[] readLongs( int count )

public void readLongs( long[] buffer, int index, int count )

Parameters

count

The number of long integers to read.

buffer

The array to read data into.

index

The starting index in the array.

Return Value

Returns a long integer array containing the data that was read.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support reading.

EOFException thrown if the end of the stream is reached while reading the data.

Remarks

The current position is advanced by count * 8 bytes.

See Also writeLongs


 IDataStream.readShort

IDataStream.readShort

Reads a short value from this stream.

Syntax

public short readShort()

Return Value

Returns the short value that was read.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support reading.

EOFException thrown if the end of the stream is reached before two bytes could be read.

Remarks

The current position is advanced by two bytes.

See Also writeShort


 IDataStream.readShorts

IDataStream.readShorts

Reads the specified number of short integers from this stream into a short integer array.

Syntax

public short[] readShorts( int count )

public void readShorts( short[] buffer, int index, int count )

Parameters

count

The number of short integers to read.

buffer

The array to read data into.

index

The starting index in the array.

Return Value

Returns a short integer array containing the data that was read.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support reading.

EOFException thrown if the end of the stream is reached while reading the data.

Remarks

The current position is advanced by count * 2 bytes.

See Also writeShorts


 IDataStream.readString

IDataStream.readString

Reads a length-prefixed Unicode string from this stream.

Syntax

public String readString()

Return Value

Returns the string value that was read.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support reading.

EOFException thrown if the end of the stream is reached while reading the string.

Remarks

This method first reads the length of the string as a 32-bit unsigned integer and then reads that many 16-bit Unicode characters into the string.

See Also writeString


 IDataStream.readStringChars

IDataStream.readStringChars

Reads a Unicode string from this stream.

Syntax

public String readStringChars( int length )

Parameters

length

The number of characters to read.

Return Value

Returns the string value that was read.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support reading.

EOFException thrown if the end of the stream is reached while reading the string.

Remarks

This method reads length 16-bit Unicode characters from the stream and returns a string containing those characters.

See Also writeStringChars


 IDataStream.readStringCharsAnsi

IDataStream.readStringCharsAnsi

Reads an American National Standards Institute (ANSI) string from this stream.

Syntax

public String readStringCharsAnsi( int length )

Parameters

length

The number of characters to read.

Return Value

Returns the string value that was read.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support reading.

EOFException thrown if the end of the stream is reached while reading the string.

Remarks

This method reads length bytes from the stream and converts those bytes to a Unicode string using the system's default code page. The length of the resulting string is a function of the code page and can be less than the number of bytes read from the stream.

See Also writeStringCharsAnsi


 IDataStream.readStringNull

IDataStream.readStringNull

Reads a null-terminated Unicode string from this stream.

Syntax

public String readStringNull()

Return Value

Returns the string value that was read.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support reading.

EOFException thrown if the end of the stream is reached while reading the string.

Remarks

This method keeps reading 16-bit Unicode characters from the stream until a null character is read. The characters (excluding the terminating null character) are then converted to a string.

See Also writeStringNull


 IDataStream.readStringNullAnsi

IDataStream.readStringNullAnsi

Reads a null-terminated ANSI string from this stream.

Syntax

public String readStringNullAnsi()

Return Value

Returns the string value that was read.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support reading.

EOFException thrown if the end of the stream is reached while reading the string.

Remarks

This method keeps reading bytes from the stream until a null byte is read. The bytes (excluding the closing null byte) are then converted to a string using the system's default code page.

See Also writeStringNullAnsi


 IDataStream.readToEnd

IDataStream.readToEnd

Reads all data from the current position to the end of this stream into a byte array.

Syntax

public byte[] readToEnd()

Return Value

Returns a byte array containing the data read.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support reading.

Remarks

If the current position is at the beginning of the stream, this is equivalent to reading the entire stream into a byte array. If the read operation is successful, the current position is at the end of the stream.

See Also IByteStream.read, readBytes


 IDataStream.readUTF

IDataStream.readUTF

Reads a string from this stream using a length-prefixed UTF-8 format.

Syntax

public String readUTF()

Return Value

Returns the string value that was read.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support reading.

EOFException thrown if the end of the stream is reached while reading the string.

Remarks

UTF encoded strings are generally more space efficient than Unicode strings, but they also take more time to process.

See Also writeUTF


 IDataStream.writeBoolean

IDataStream.writeBoolean

Writes a boolean value to this stream.

Syntax

public void writeBoolean( boolean value )

Parameters

value

The boolean value to write.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support writing.

Remarks

A single byte is written to the stream with the value 0 representing false or the value 1 representing true.

See Also readBoolean


 IDataStream.writeByte

IDataStream.writeByte

Writes a byte to this stream.

Syntax

public void writeByte( byte value )

Parameters

value

The byte value to write.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support writing.

Remarks

The current position is advanced by one byte.

See Also readByte


 IDataStream.writeBytes

IDataStream.writeBytes

Writes the contents of the specified byte array to this stream.

Syntax

public void writeBytes( byte[] buffer )

Parameters

buffer

The byte array containing the data to write.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support writing.

Remarks

The number of bytes written to the stream is buffer.length.

See Also IByteStream.write, readBytes


 IDataStream.writeChar

IDataStream.writeChar

Writes a character to this stream.

Syntax

public void writeChar( char value )

Parameters

value

The character value to write.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support writing.

Remarks

The current position is advanced by two bytes.

See Also readChar


 IDataStream.writeChars

IDataStream.writeChars

Writes the contents of the specified character array to this stream.

Syntax

public void writeChars( char[] buffer )

public void writeChars( char[] buffer, int index, int count )

Parameters

buffer

The character array containing the data to write.

index

The starting index in the array.

count

The number of characters to write.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support writing.

Remarks

The number of bytes written to the stream is buffer.length * 2. The current position is advanced by count * 8 bytes.

See Also readChars


 IDataStream.writeDouble

IDataStream.writeDouble

Writes a double value to this stream.

Syntax

public void writeDouble( double value )

Parameters

value

The double value to write.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support writing.

Remarks

The current position is advanced by eight bytes.

See Also readDouble


 IDataStream.writeDoubles

IDataStream.writeDoubles

Writes the contents of the specified double array to this stream.

Syntax

public void writeDoubles( double[] buffer )

public void writeDoubles( double[] buffer, int index, int count )

Parameters

buffer

The double array containing the data to write.

index

The starting index in the array.

count

The number of doubles to write.

Exceptions

IOException If an I/O error occurs or if the stream does not support writing.

Remarks

The number of bytes written to the stream is buffer.length * 8. The current position is advanced by count * 8 bytes.

See Also readDoubles


 IDataStream.writeFloat

IDataStream.writeFloat

Writes a float value to this stream.

Syntax

public void writeFloat( float value )

Parameters

value

The float value to write.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support writing.

Remarks

The current position is advanced by four bytes.

See Also readFloat


 IDataStream.writeFloats

IDataStream.writeFloats

Writes the contents of the specified float array to this stream.

Syntax

public void writeFloats( float[] buffer )

public void writeFloats( float[] buffer, int index, int count )

Parameters

buffer

The float array containing the data to write.

index

The starting index in the array.

count

The number of floats to write.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support writing.

Remarks

The number of bytes written to the stream is buffer.length * 4. The current position is advanced by count * 4 bytes.

See Also readFloats


 IDataStream.writeInt

IDataStream.writeInt

Writes an integer value to this stream.

Syntax

public void writeInt( int value )

Parameters

value

The integer value to write.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support writing.

Remarks

The current position is advanced by four bytes.

See Also readInt


 IDataStream.writeInts

IDataStream.writeInts

Writes the contents of the specified integer array to this stream.

Syntax

public void writeInts( int[] buffer )

public void writeInts( int[] buffer, int index, int count )

Parameters

buffer

The integer array containing the data to write.

index

The starting index in the array.

count

The number of integers to write.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support writing.

Remarks

The number of bytes written to the stream is buffer.length * 4. The current position is advanced by count * 4 bytes.

See Also readInts


 IDataStream.writeLong

IDataStream.writeLong

Writes a long integer to this stream.

Syntax

public void writeLong( long value )

Parameters

value

The long integer to write.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support writing.

Remarks

The current position is advanced by eight bytes.

See Also readLong


 IDataStream.writeLongs

IDataStream.writeLongs

Writes the contents of the specified long integer array to this stream.

Syntax

public void writeLongs( long[] buffer )

public void writeLongs( long[] buffer, int index, int count )

Parameters

buffer

The long integer array containing the data to write.

index

The starting index in the array.

count

The number of long integers to write.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support writing.

Remarks

The number of bytes written to the stream is buffer.length * 8. The current position is advanced by count * 8 bytes.

See Also readLongs


 IDataStream.writeShort

IDataStream.writeShort

Writes a short integer to this stream.

Syntax

public void writeShort( short value )

Parameters

value

The short integer to write.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support writing.

Remarks

The current position is advanced by two bytes.

See Also readShort


 IDataStream.writeShorts

IDataStream.writeShorts

Writes the contents of the specified short integer array to this stream.

Syntax

public void writeShorts( short[] buffer )

public void writeShorts( short[] buffer, int index, int count )

Parameters

buffer

The short integer array containing the data to write.

index

The starting index in the array.

count

The number of short integers to write.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support writing.

Remarks

The number of bytes written to the stream is buffer.length * 2. The current position is advanced by count * 2 bytes.

See Also readShorts


 IDataStream.writeString

IDataStream.writeString

Writes a length-prefixed Unicode string to this stream.

Syntax

public void writeString( String value )

Parameters

value

The string value to write.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support writing.

Remarks

This method first writes the length of the string as a 32-bit unsigned integer and then writes that many 16-bit Unicode characters to the stream.

See Also readString


 IDataStream.writeStringChars

IDataStream.writeStringChars

Writes a Unicode string to this stream.

Syntax

public void writeStringChars( String value )

Parameters

value

The string value to write.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support writing.

Remarks

The number of Unicode characters written to the stream corresponds to the length of the string.

See Also readStringChars


 IDataStream.writeStringCharsAnsi

IDataStream.writeStringCharsAnsi

Writes an ANSI string to this stream.

Syntax

public void writeStringCharsAnsi( String value )

Parameters

value

The string value to write.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support writing.

Remarks

The specified string is converted to a sequence of bytes using the system's default code page. Those bytes are then written to the stream. The number of bytes written to the stream is a function of the code page and can be larger than the length of the string.

See Also readStringCharsAnsi


 IDataStream.writeStringNull

IDataStream.writeStringNull

Writes a null-terminated Unicode string to this stream.

Syntax

public void writeStringNull( String value )

Parameters

value

The string value to write.

Remarks

The characters of the string are written to the stream as a sequence of 16-bit Unicode characters followed by a 16-bit null character.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support writing.

See Also readStringNull


 IDataStream.writeStringNullAnsi

IDataStream.writeStringNullAnsi

Writes a null-terminated ANSI string to this stream.

Syntax

public void writeStringNullAnsi( String value )

Parameters

value

The string value to write.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support writing.

Remarks

The specified string is converted to a sequence of bytes using the system's default code page. Those bytes are then written to the stream followed by a null byte.

See Also readStringNullAnsi


 IDataStream.writeUTF

IDataStream.writeUTF

Writes a string to this stream using a length-prefixed UTF-8 format.

Syntax

public void writeUTF( String value )

Parameters

value

The string value to write.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support writing.

Remarks

UTF-encoded strings are generally more space efficient than Unicode strings, but they also take more time to process.

See Also readUTF


IOException Class

Represents an input/output (I/O) exception.

WFCException
  |
  +--IOException

package com.ms.wfc.io

public class IOException
extends WFCException

Remarks

This is the base exception class for exceptions raised by methods of classes in the com.ms.wfc.io package.


 IOException Methods

IOException Methods

Constructors | Description
IOException | Creates an IOException object.


 IOException.IOException

IOException.IOException

Creates an IOException object.

Syntax

public IOException()

public IOException( String s )

Parameters

s

The text describing the exception.


IReader Interface

Defines an interface that can read a sequential stream of characters.

package com.ms.wfc.io

public interface IReader

Remarks

The Reader class provides a default implementation of this interface.


 IReader Methods

IReader Methods

Methods | Description
close | Closes this Reader object and releases any system resources associated with the reader.
peek | Retrieves the next available character without actually reading it from the input stream.
read | Reads the next character from the input stream.
readLine | Reads a line.


 IReader.close

IReader.close

Closes this Reader object and releases any system resources associated with the reader.

Syntax

public void close()


 IReader.peek

IReader.peek

Retrieves the next available character without actually reading it from the input stream.

Syntax

public int peek()

Return Value

Returns the next character to be read, or returns -1 if no additional characters are available.


 IReader.read

IReader.read

Reads the next character from the input stream.

Syntax

public int read()

public int read( char[] buffer, int index, int count )

Parameters

buffer

The character array to read data into.

index

The starting index in the buffer.

count

The number of characters to read.

Return Value

The first syntax returns the next character from the input stream, or returns -1 if no additional characters are available. The second syntax returns the total number of characters read into the buffer. This can be fewer than the number of characters requested if that many characters aren't currently available, or it can be zero if the end of the stream is reached.


 IReader.readLine

IReader.readLine

Reads a line.

Syntax

public String readLine()

Return Value

Returns a line. This string does not contain the terminating carriage return and/or line feed. The return value is null if the end of the input stream has been reached.

Remarks

A line is defined as a sequence of characters followed by a carriage return (\r), a line feed (\n), or a carriage return immediately followed by a line feed.


IWriter Interface

Represents a writer that can write a sequential stream of characters.

package com.ms.wfc.io

public interface IWriter

Remarks

The Writer class provides a default implementation of this interface.


 IWriter Methods

IWriter Methods

Methods | Description
close | Closes this Writer object and releases any system resources associated with the writer.
flush | Clears all buffers for this Writer object and causes any buffered data to be written to the underlying device.
write | Writes the specified item to the text stream.
writeLine | Writes the specified item followed by a line terminator to the text stream.


 IWriter.close

IWriter.close

Closes this Writer object and releases any system resources associated with the writer.

Syntax

public void close()


 IWriter.flush

IWriter.flush

Clears all buffers for this Writer object and causes any buffered data to be written to the underlying device.

Syntax

public void flush()


 IWriter.write

IWriter.write

Writes the specified item to the text stream.

Syntax

public void write( char value )

public void write( char[] buffer )

public void write( char[] buffer, int index, int count )

public void write( boolean b_value )

public void write( int i_value )

public void write( long l_value )

public void write( float f_value )

public void write( double d_value )

public void write( String s_value )

public void write( Object o_value )

Parameters

value

The character to write to the text stream.

buffer

The character array to write to the text stream.

index

The starting index in the buffer.

count

The number of characters to write.

b_value

The boolean value to write.

i_value

The integer to write. The text of i_value is produced by calling the Integer.toString(int) method.

l_value

The long to write. The text of l_value is produced by calling the Long.toString(long) method.

f_value

The float to write. The text of f_value is produced by calling the Float.toString(float) method.

d_value

The double to write. The text of d_value is produced by calling the Double.toString(double) method.

s_value

The string to write. If the specified string is null, nothing is written to the text stream.

o_value

The object to write.


 IWriter.writeLine

IWriter.writeLine

Writes the specified item followed by a line terminator to the text stream.

Syntax

public void writeLine()

public void writeLine( char value )

public void writeLine( char[] buffer )

public void writeLine( char[] buffer, int index, int count )

public void writeLine( boolean b_value )

public void writeLine( int i_value )

public void writeLine( long l_value )

public void writeLine( float f_value )

public void writeLine( double d_value )

public void writeLine( String s_value )

public void writeLine( Object o_value )

Parameters

value

The character to write to the text stream.

buffer

The character array to write to the text stream.

index

The starting index in the buffer.

count

The number of characters to write.

b_value

The boolean value to write.

i_value

The integer to write.

l_value

The long to write.

f_value

The float to write.

d_value

The double to write.

s_value

The string to write.

o_value

The object to write.


MemoryStream Class

Implements an in-memory data stream.

DataStream
  |
  +--MemoryStream

package com.ms.wfc.io

public class MemoryStream
extends DataStream


 MemoryStream Methods

MemoryStream Methods

Constructors | Description
MemoryStream | Creates a MemoryStream object.

Methods | Description
getCapacity | Retrieves the current size of the stream.
getLength | Retrieves the length of the stream in bytes.
getPosition | Retrieves the position of this stream.
read | Reads the next byte of data from this stream.
readByte | Reads a byte from this stream.
readChar | Reads a character from this stream.
readCore | Implements the core array read method.
readInt | Reads an integer from this stream.
readShort | Reads a short value from this stream.
readStringCharsAnsi | Reads an American National Standards Institute (ANSI) string from this stream.
readStringNull | Reads a null-terminated Unicode string from this stream.
readStringNullAnsi | Reads a null-terminated ANSI string from this stream.
reset | Flushes the stream buffer.
setLength | Sets the length of this stream.
setPosition | Sets the position of this stream.
toByteArray | Converts a SafeArray data structure to a Java array. The location is considered to be index zero.
write | Writes a single byte of data to this stream.
writeByte | Writes a byte to this stream.
writeChar | Writes a character to this stream.
writeCore | Implements the core array write method.
writeInt | Writes an integer to this stream.
writeShort | Writes a short value to this stream.
writeTo | Writes the contents of this stream to the specified output stream argument.


 MemoryStream.getCapacity

MemoryStream.getCapacity

Retrieves the current size of the stream.

Syntax

public int getCapacity()

Return Value

Returns the current size of the stream.


 MemoryStream.getLength

MemoryStream.getLength

Retrieves the length of the stream in bytes.

Syntax

public long getLength()

Return Value

Returns the current length of the stream.


 MemoryStream.getPosition

MemoryStream.getPosition

Retrieves the position of this stream.

Syntax

public long getPosition()

Return Value

Returns the current position of the stream.


 MemoryStream.MemoryStream

MemoryStream.MemoryStream

Creates a MemoryStream object.

Syntax

public MemoryStream()

public MemoryStream( int capacity )

public MemoryStream( byte[] buffer )

public MemoryStream( byte[] buffer, int offset, int length )

public MemoryStream( IByteStream stream, int length )

public MemoryStream( IStream stream, int length )

public MemoryStream( java.io.InputStream stream )

Parameters

capacity

The size of the stream.

buffer

An array of a primitive type.

offset

The byte offset into the buffer.

length

The length of the buffer in bytes.

stream

The data stream to act on.


 MemoryStream.read

MemoryStream.read

Reads the next byte of data from this stream.

Syntax

public int read()

Return Value

Returns a byte of data from the stream.


 MemoryStream.readByte

MemoryStream.readByte

Reads a byte from this stream.

Syntax

public byte readByte()

Return Value

Returns a byte of data from the stream.


 MemoryStream.readChar

MemoryStream.readChar

Reads a character from this stream.

Syntax

public char readChar()

Return Value

Returns a character of data from this stream.


 MemoryStream.readCore

MemoryStream.readCore

Implements the core array read method.

Syntax

protected int readCore( Object array, int offset, int count )

Parameters

array

The array of primitive types to be read.

offset

The byte offset into array.

count

The number of bytes in array to read.

Return Value

Returns an array of data from this stream.

Overrides DataStream.readCore


 MemoryStream.readInt

MemoryStream.readInt

Reads an integer from this stream.

Syntax

public int readInt()

Return Value

Returns an integer from this stream.


 MemoryStream.readShort

MemoryStream.readShort

Reads a short value from this stream.

Syntax

public short readShort()

Return Value

Returns the short value that was read.


 MemoryStream.readStringCharsAnsi

MemoryStream.readStringCharsAnsi

Reads an American National Standards Institute (ANSI) string from this stream.

Syntax

public String readStringCharsAnsi( int length )

Parameters

length

The length of the buffer in bytes.

Return Value

Returns the string value that was read.


 MemoryStream.readStringNull

MemoryStream.readStringNull

Reads a null-terminated Unicode string from this stream.

Syntax

public String readStringNull()

Return Value

Returns the string value that was read.


 MemoryStream.readStringNullAnsi

MemoryStream.readStringNullAnsi

Reads a null-terminated ANSI string from this stream.

Syntax

public String readStringNullAnsi()

Return Value

Returns the string value that was read.


 MemoryStream.reset

MemoryStream.reset

Flushes the stream buffer.

Syntax

public void reset()


 MemoryStream.setLength

MemoryStream.setLength

Sets the length of this stream.

Syntax

public void setLength( long length )

Parameters

length

The new length of the stream.


 MemoryStream.setPosition

MemoryStream.setPosition

Sets the position of this stream.

Syntax

public void setPosition( long value )

Parameters

value

The new position of the stream.


 MemoryStream.toByteArray

MemoryStream.toByteArray

Converts a SafeArray data structure to a Java array. The location is considered to be index zero.

Syntax

public byte[] toByteArray()

Return Value

Returns the flattened contents of the array.


 MemoryStream.write

MemoryStream.write

Writes a single byte of data to this stream.

Syntax

public void write( int value )

Parameters

value

The value to write.


 MemoryStream.writeByte

MemoryStream.writeByte

Writes a byte to this stream.

Syntax

public void writeByte( byte value )

Parameters

value

The value to write.


 MemoryStream.writeChar

MemoryStream.writeChar

Writes a character to this stream.

Syntax

public void writeChar( char value )

Parameters

value

The value to write.


 MemoryStream.writeCore

MemoryStream.writeCore

Implements the core array write method.

Syntax

protected void writeCore( Object array, int offset, int count )

Parameters

array

An array of primitive types to write.

index

The byte offset into array.

count

The number of bytes in array to write.

Overrides DataStream.writeCore


 MemoryStream.writeInt

MemoryStream.writeInt

Writes an integer to this stream.

Syntax

public void writeInt( int value )

Parameters

value

The value to write.


 MemoryStream.writeShort

MemoryStream.writeShort

Writes a short value to this stream.

Syntax

public void writeShort( short value )

Parameters

value

The value to write.


 MemoryStream.writeTo

MemoryStream.writeTo

Writes the contents of this stream to the specified output stream argument.

Syntax

public void writeTo( IByteStream stream )

public void writeTo( IStream stream )

Parameters

stream

The stream to write to.


Reader Class

Represents a reader that can read a sequential stream of characters.

package com.ms.wfc.io

public abstract class Reader
implements IReader

Remarks

The Reader class is an abstract base class. A subclass must minimally implement the peek and read methods.

See Also StringReader, Text, TextReader, Writer


 Reader Methods

Reader Methods

Methods | Description
close | Closes this Reader object and releases any system resources associated with the reader.
peek | Retrieves the next available character from the input stream without actually reading it.
read | Reads the next character from the input stream.
readLine | Reads a line.


 Reader.close

Reader.close

Closes this Reader object and releases any system resources associated with the reader.

Syntax

public void close()

Remarks

Following a call to close, any operations on the Reader object can raise exceptions. The default method is empty, but a subclass can override this method to provide the appropriate functionality.


 Reader.peek

Reader.peek

Retrieves the next available character from the input stream without actually reading it.

Syntax

public int peek()

Return Value

Returns the next character to be read, or returns -1 if no additional characters are available.

Remarks

This operation does not change the current position of the Reader object. This default method returns -1.


 Reader.read

Reader.read

Reads the next character from the input stream.

Syntax

public int read()

public int read( char[] buffer, int index, int count )

Parameters

buffer

The character array to read data into.

index

The starting index in the buffer.

count

The number of characters to read.

Return Value

Returns the next character from the input stream, or returns -1 if no additional characters are available. The second syntax returns the total number of characters read into the buffer. This can be fewer than the number of characters requested if that many characters aren't currently available, or this can be zero if the end of the stream is reached.

Exceptions

IOException thrown if an I/O error occurs or if the stream does not support reading.

WFCInvalidArgumentException thrown if the buffer is null, the index is out of bounds, or the count is out of bounds.

Remarks

The second syntax for this method reads up to count characters from this Reader object into the buffer array starting at position index.


 Reader.readLine

Reader.readLine

Reads a line.

Syntax

public String readLine()

Return Value

Returns the next line from the input stream, or returns null if the end of the input stream is reached.

Remarks

A line is defined as a sequence of characters followed by a carriage return (\r), a line feed (\n), or a carriage return immediately followed by a line feed. The resulting string does not contain the terminating carriage return and/or line feed.


StringReader Class

Implements a reader that reads from a string.

Reader
  |
  +--StringReader

package com.ms.wfc.io

public class StringReader
extends Reader

See Also Reader, StringWriter


 StringReader Methods

StringReader Methods

Constructors | Description
StringReader | Creates a StringReader object.

Methods | Description
close | Closes this StringReader object.
peek | Retrieves the next available character without actually reading it from the underlying string.
read | Reads the next character from the underlying string.
readLine | Reads a line.


 StringReader.close

StringReader.close

Closes this StringReader object.

Syntax

public void close()

Remarks

Following a call to this method, the string reader appears to have no further characters.

Overrides Reader.close


 StringReader.peek

StringReader.peek

Retrieves the next available character without actually reading it from the underlying string.

Syntax

public int peek()

Return Value

Returns the next character to be read, or returns -1 if no further characters are available.

Remarks

The current position of the TextReader is not changed by this operation.

Overrides Reader.peek


 StringReader.read

StringReader.read

Reads the next character from the underlying string.

Syntax

public int read()

public int read( char[] buffer, int index, int count )

Parameters

buffer

The character array to read data into.

index

The starting index in the buffer.

count

The number of characters to read.

Return Value

Returns the next character from the underlying string, or returns -1 if no further characters are available. The second syntax returns the total number of characters read into the buffer. This may be less than the number of characters requested if that many characters aren't currently available, or zero if the end of the underlying string is reached.

Exceptions

WFCInvalidArgumentException thrown if the buffer is null, the index is out of bounds, or the count is out of bounds.

Remarks

This method reads up to count characters from this TextReader into the buffer character array starting at position index. Returns the actual number of characters read.

Overrides Reader.read


 StringReader.readLine

StringReader.readLine

Reads a line.

Syntax

public String readLine()

Return Value

Returns the next line from the underlying string, or returns null if the end of the underlying string is reached.

Remarks

A line is defined as a sequence of characters followed by a carriage return (\r), a line feed (\n), or a carriage return immediately followed by a line feed. The resulting string does not contain the terminating carriage return and/or line feed.

Overrides Reader.readLine


 StringReader.StringReader

StringReader.StringReader

Creates a StringReader object.

Syntax

public StringReader( String s )

Parameters

s

The string to read.


StringWriter Class

Implements a writer that writes to a string buffer and allows the resulting sequence of characters to be presented as a string.

Writer
  |
  +--StringWriter

package com.ms.wfc.io

public class StringWriter
extends Writer

See Also StringReader, Writer


 StringWriter Methods

StringWriter Methods

Constructors | Description
StringWriter | Creates a StringWriter object.

Methods | Description
getStringBuffer | Retrieves the underlying StringBuffer object.
toString | Retrieves a string containing the characters written to this StringWriter object.
write | Writes a character to the underlying string buffer.


 StringWriter.getStringBuffer

StringWriter.getStringBuffer

Retrieves the underlying StringBuffer object.

Syntax

public StringBuffer getStringBuffer()

Return Value

Returns the underlying string buffer. This is either the StringBuffer object that was passed to the constructor or the StringBuffer object that was automatically created.


 StringWriter.StringWriter

StringWriter.StringWriter

Creates a StringWriter object.

Syntax

public StringWriter()

public StringWriter( StringBuffer sb )

Parameters

sb

The java.lang.StringBuffer object to associate with the string writer. If no string buffer is specified, a new StringBuffer object is automatically created and associated with this string writer.


 StringWriter.toString

StringWriter.toString

Retrieves a string containing the characters written to this StringWriter object.

Syntax

public String toString()

Return Value

Returns a string containing the characters written to the StringWriter object.


 StringWriter.write

StringWriter.write

Writes a character to the underlying string buffer.

Syntax

public void write( char value )

public void write( char[] buffer, int index, int count )

public void write( String value )

Parameters

value

The character or string to write. If null, nothing is written.

buffer

The character array to write data from.

index

The starting index in the buffer.

count

The number of characters to write.

Exceptions

WFCInvalidArgumentException thrown if the buffer is null, the index is out of bounds, or the count is out of bounds.

Remarks

The second method syntax writes count characters of data into this StringWriter from the buffer character array starting at position index.

Overrides Writer.write


Text Class

Provides fields that represent the standard input, output, and error files of a process. This class cannot be instantiated.

package com.ms.wfc.io

public final class Text

Remarks

This class is used for low-level system input and output. For example:

Text.out.writeLine("debug")

is the same as

System.out.println("debug")

See Also TextReader, TextWriter


 Text Fields

Text Fields

Fields | Description
err | Specifies the standard error.
in | Specifies the standard input.
out | Specifies the standard output.


 Text.err

Text.err

Specifies the standard error.

Syntax

public static final TextWriter err;


 Text.in

Text.in

Specifies the standard input.

Syntax

public static final TextReader in;


 Text.out

Text.out

Specifies the standard output.

Syntax

public static final TextWriter out;


TextReader Class

Implements a reader that can read a sequential stream of characters from an IByteStream object or from a named file.

Reader
  |
  +--TextReader

package com.ms.wfc.io

public class TextReader
extends Reader

Remarks

This class performs buffering of the input and conversions from the underlying single-byte or double-byte character set to Unicode.

See Also StringReader, Text, TextWriter


 TextReader Methods

TextReader Methods

Constructors | Description
TextReader | Creates a TextReader object.

Methods | Description
close | Closes this TextReader object and the underlying IByteStream object.
getStream | Retrieves the stream that underlies this TextReader object.
peek | Retrieves the next available character without actually reading it from the input stream.
read | Reads the next character from the input stream.
readLine | Reads a line.


 TextReader.close

TextReader.close

Closes this TextReader object and the underlying IByteStream object.

Syntax

public void close()

Remarks

Following a call to close, any operations on the TextReader object will raise exceptions.

Overrides Reader.close


 TextReader.getStream

TextReader.getStream

Retrieves the stream that underlies this TextReader object.

Syntax

public IByteStream getStream()

Return Value

Returns either the stream that was passed to the constructor or the File object that was automatically created as part of constructing this TextReader object.


 TextReader.peek

TextReader.peek

Retrieves the next available character without actually reading it from the input stream.

Syntax

public int peek()

Return Value

Returns the next character to be read, or returns -1 if no further characters are available.

Remarks

The current position of the TextReader is not changed by this operation.

Overrides Reader.peek


 TextReader.read

TextReader.read

Reads the next character from the input stream.

Syntax

public int read()

public int read( char[] buffer, int index, int count )

Parameters

buffer

The character array to read data into.

index

The starting index in the buffer.

count

The number of characters to read.

Return Value

Returns the next character from the input stream, or returns -1 if no further characters are available. The second syntax returns the total number of characters read into the buffer. This can be fewer than the number of characters requested if that many characters aren't currently available, or this can be zero if the end of the stream is reached.

Remarks

The second method syntax reads up to count characters from this TextReader into the buffer character array starting at position index. Returns the actual number of characters read.

Overrides Reader.read


 TextReader.readLine

TextReader.readLine

Reads a line.

Syntax

public String readLine()

Return Value

Returns the next line from the input stream, or returns null if the end of the input stream is reached.

Remarks

A line is defined as a sequence of characters followed by a carriage return (\r), a line feed (\n), or a carriage return immediately followed by a line feed. The resulting string does not contain the terminating carriage return and/or line feed.

Overrides Reader.readLine


 TextReader.TextReader

TextReader.TextReader

Creates a TextReader object.

Syntax

public TextReader( IByteStream stream )

public TextReader( IByteStream stream, int codePage )

public TextReader( IByteStream stream, int codePage, int bufferSize )

public TextReader( String path )

public TextReader( String path, int codePage )

public TextReader( String path, int codePage, int bufferSize )

Parameters

stream

The IByteStream object to read from.

codePage

The code page to use when converting input characters to Unicode. This parameter must be a value from the CodePage enumeration or the identifier of a code page that is supported by the system. If no code page is specified, the American National Standards Institute (ANSI) code page is used.

bufferSize

The input buffer size in characters. If no value is specified for this parameter, the buffer size is set to 1024 characters.

path

The name of an existing file to open.


TextWriter Class

Implements a writer that can write a sequential stream of characters to an IByteStream object or to a named file.

Writer
  |
  +--TextWriter

package com.ms.wfc.io

public class TextWriter
extends Writer

Remarks

This class performs buffering of the output and conversions from Unicode to the underlying single-byte or double-byte character set.

See Also StringWriter, Text, TextReader


 TextWriter Methods

TextWriter Methods

Constructors | Description
TextWriter | Creates a TextWriter object.

Methods | Description
close | Closes this TextWriter object and the underlying IByteStream object.
flush | Clears the output buffer for this TextWriter object and causes any buffered data to be written to the underlying IByteStream object.
getAutoFlush | Retrieves a boolean value indicating whether write operations are automatically flushed to the underlying IByteStream object.
getStream | Retrieves the stream that underlies this TextWriter object.
setAutoFlush | Sets a boolean value indicating whether to enable the automatic flushing of output characters.
write | Writes a character to the text stream.


 TextWriter.close

TextWriter.close

Closes this TextWriter object and the underlying IByteStream object.

Syntax

public void close()

Remarks

Following a call to close, any operations on the TextWriter object will raise exceptions.

Overrides Writer.close


 TextWriter.flush

TextWriter.flush

Clears the output buffer for this TextWriter object and causes any buffered data to be written to the underlying IByteStream object.

Syntax

public void flush()

Remarks

If the autoFlush property for the TextWriter object is set to true, flush is automatically called after every write operation.

Overrides Writer.flush

See Also setAutoFlush


 TextWriter.getAutoFlush

TextWriter.getAutoFlush

Retrieves a boolean value indicating whether write operations are automatically flushed to the underlying IByteStream object.

Syntax

public boolean getAutoFlush()

Return Value

Returns true if write operations are flushed to the underlying IByteStream object; otherwise, returns false.

See Also setAutoFlush


 TextWriter.getStream

TextWriter.getStream

Retrieves the stream that underlies this TextWriter object.

Syntax

public IByteStream getStream()

Return Value

Returns the stream that underlies this TextWriter object.

Remarks

Retrieves either the stream that was passed to the constructor or the File object that was automatically created as part of constructing this TextWriter object.


 TextWriter.setAutoFlush

TextWriter.setAutoFlush

Sets a boolean value indicating whether to enable the automatic flushing of output characters.

Syntax

public void setAutoFlush( boolean value )

Parameters

value

Set to true to enable automatic flushing; set to false to disable automatic flushing.

Remarks

When automatic flushing is enabled, output is automatically written to the underlying stream at the end of each write operation.

See Also flush, getAutoFlush


 TextWriter.TextWriter

TextWriter.TextWriter

Creates a TextWriter object.

Syntax

public TextWriter( IByteStream stream )

public TextWriter( IByteStream stream, int codePage )

public TextWriter( IByteStream stream, int codePage, int bufferSize )

public TextWriter( String path )

public TextWriter( String path, int codePage )

public TextWriter( String path, int codePage, int bufferSize )

Parameters

stream

The IByteStream object to write to.

codePage

The code page to use when converting Unicode characters to output characters. This parameter must be a value from the CodePage enumeration or the identifier of a code page that is supported by the system.

bufferSize

Output buffer size in characters. If no value is specified for this parameter, the buffer size is set to 1024 characters.

path

The name of the file to create.


 TextWriter.write

TextWriter.write

Writes a character to the text stream.

Syntax

public void write( char c_value )

public void write( char[] buffer, int index, int count )

public void write( String s_value )

Parameters

c_value

The character to write to the text stream.

buffer

The character array to write data from.

index

The starting index in the buffer.

count

The number of characters to write.

s_value

The string to write.

Exceptions

WFCInvalidArgumentException thrown if the buffer is null, the index is out of bounds, or the count is out of bounds.

Remarks

Use the second syntax to write count characters of data into this TextWriter object from the buffer character array starting at position index. If the specified string is null, nothing is written to the text stream.

Overrides Writer.write


WinIOException Class

Creates a Windows input/output (I/O) error exception class.

IOException
  |
  +--WinIOException

package com.ms.wfc.io

public class WinIOException
extends IOException

Remarks

This class is used to report I/O errors that originate from the operating system.


 WinIOException Methods

WinIOException Methods

Constructors | Description
WinIOException | Creates a WinIOException object based on the last operating system error.

Methods | Description
getErrorCode | Retrieves the error code associated with this exception.


 WinIOException.getErrorCode

WinIOException.getErrorCode

Retrieves the error code associated with this exception.

Syntax

public int getErrorCode()

Return Value

Returns the operating system error code for the exception.


 WinIOException.WinIOException

WinIOException.WinIOException

Creates a WinIOException object based on the last operating system error.

Syntax

public WinIOException()

public WinIOException( int errorCode )

public WinIOException( int errorCode, String s )

Parameters

errorcode

The error code number.

s

The text to be displayed when this error occurs.

Remarks

The first constructor calls the com.ms.dll.DllLib.getLastWin32Error method to get the last operating system error code and constructs an error message based on that error code. If you are using J/Direct to call a Windows API function, and the function reports an error, you can turn that error into a WinIOException using this constructor.

The second syntax calls the Utils.getSystemErrorMessage method to construct an error message based on the specified error code.


Writer Class

Represents a writer that can write a sequential stream of characters.

package com.ms.wfc.io

public abstract class Writer
implements IWriter

Remarks

The Writer class is an abstract base class. A subclass must minimally implement the write method.


 Writer Methods

Writer Methods

Methods | Description
close | Closes this Writer object and releases any system resources associated with the writer.
flush | Clears all buffers for this Writer object and causes any buffered data to be written to the underlying device.
getNewLine | Retrieves the line terminator string used by this Writer object.
setNewLine | Sets the line terminator string for this Writer object.
write | Writes the specified item to the text stream.
writeLine | Writes the specified item followed by a line terminator to the text stream.


 Writer.close

Writer.close

Closes this Writer object and releases any system resources associated with the writer.

Syntax

public void close()

Remarks

Following a call to close, any operations on the Writer object can raise exceptions. The default method is empty, but a subclass can override this method to provide the appropriate functionality.


 Writer.flush

Writer.flush

Clears all buffers for this Writer object and causes any buffered data to be written to the underlying device.

Syntax

public void flush()

Remarks

The default method is empty, but a subclass can override this method to provide the appropriate functionality.


 Writer.getNewLine

Writer.getNewLine

Retrieves the line terminator string used by this Writer object.

Syntax

public String getNewLine()

Return Value

Returns the line terminator string.

Remarks

The default line terminator string is a carriage return followed by a line feed (\r\n).

See Also setNewLine


 Writer.setNewLine

Writer.setNewLine

Sets the line terminator string for this Writer object.

Syntax

public void setNewLine( String value )

Parameters

value

The line terminator string.

Remarks

The line terminator string is written to the text stream whenever one of the writeLine methods are called. For text written by the Writer object to be readable by a Reader object, only one of the following line terminator strings should be used: \r, \n, or \r\n.

See Also getNewLine


 Writer.write

Writer.write

Writes the specified item to the text stream.

Syntax

public void write( char value )

public void write( char[] buffer )

public void write( char[] buffer, int index, int count )

public void write( boolean b_value )

public void write( int i_value )

public void write( long l_value )

public void write( float f_value )

public void write( double d_value )

public void write( String s_value )

public void write( Object o_value )

Parameters

value

The character to write to the text stream.

buffer

The character array to write to the text stream.

index

The starting index in the buffer.

count

The number of characters to write.

b_value

The boolean value to write.

i_value

The integer to write. The text of i_value is produced by calling the Integer.toString(int) method.

l_value

The long to write. The text of l_value is produced by calling the Long.toString(long) method.

f_value

The float to write. The text of f_value is produced by calling the Float.toString(float) method.

d_value

The double to write. The text of d_value is produced by calling the Double.toString(double) method.

s_value

The string to write. If the specified string is null, nothing is written to the text stream.

o_value

The object to write.

Remarks

The default method is empty, but a subclass can override this method to provide the appropriate functionality. The second method syntax calls write(char) for each of the characters in the character array. If the character array is null, nothing is written. The third method syntax writes count characters of data into this Writer object from the buffer character array starting at position index. The fourth method syntax outputs either the string "true" or the string "false".

If the o_value is null, the string "null" is written to the text stream. Otherwise, the object's toString method is called to produce the string representation, and the resulting string is then written to the output stream.


 Writer.writeLine

Writer.writeLine

Writes the specified item followed by a line terminator to the text stream.

Syntax

public void writeLine()

public void writeLine( char value )

public void writeLine( char[] buffer )

public void writeLine( char[] buffer, int index, int count )

public void writeLine( boolean b_value )

public void writeLine( int i_value )

public void writeLine( long l_value )

public void writeLine( float f_value )

public void writeLine( double d_value )

public void writeLine( String s_value )

public void writeLine( Object o_value )

Parameters

value

The character to write to the text stream.

buffer

The character array to write to the text stream.

index

The starting index in the buffer.

count

The number of characters to write.

b_value

The boolean value to write.

i_value

The integer to write.

l_value

The long to write.

f_value

The float to write.

d_value

The double to write.

s_value

The string to write.

o_value

The object to write.

Exceptions

WFCInvalidArgumentException thrown if the buffer is null, the index is out of bounds, or the count is out of bounds.

Remarks

The default line terminator is a carriage return followed by a line feed (\r\n), but this value can be changed using the setNewLine method.


Package com.ms.wfc.ui

Provides user interface component classes.

Classes

Animation

Encapsulates a Windows animation control, a rectangular control that plays an Audio-Video Interleaved (AVI) animation file.

Appearance

Defines constants that specify the appearance of a component.

AutoSizeEvent

Provides data for the autoSize event of the Rebar object.

AxHost

Wraps an ActiveX control and exposes the control as a WFC control.

AxHost.AxPropertyInfo

Extends the ProperyInfo object for an ActiveX control to provide access to the underlying ActiveX object.

AxHost.Flags

Defines the flags that can be passed to the AxHost object constructor.

AxHost.State

Encapsulates the persisted state of an ActiveX control.

Bitmap

Encapsulates a Windows bitmap.

Border3DSide

Defines constants that specify which sides of a rectangle to apply a three-dimensional border to.

Border3DStyle

Defines constants that specify the kind of three-dimensional border to apply to a rectangle.

BorderStyle

Defines constants that specify basic border styles for a window.

Brush

Encapsulates a Windows brush, a tool that Win32-based applications use to paint the interior of polygons and ellipses.

BrushStyle

Defines the brush style constants on which you can base Brush objects.

Button

Encapsulates a Windows button control.

ButtonState

Defines constants that specify the appearance of a button.

CaptionButton

Defines constants that specify the kind of caption button to draw.

CharacterCasing

Defines constants that specify the case of characters.

CheckBox

Encapsulates a Windows check box control, which is a labeled box that is checked or unchecked to turn an option on or off.

CheckedListBox

Represents a checked list box control, which is a list box containing items accompanied by check boxes that can be checked or unchecked.

CheckState

Defines constants that specify the appearance of a control that can be checked and unchecked.

Color

Describes the color of a screen element, using a red-green-blue (RGB) or hue-saturation-brightness (HSB) triplet, a cyan-yellow-magenta-black (CYMK) quadruplet, or a system color constant (the color of a command button, for example).

ColorDialog

Represents a common dialog box that displays available colors along with controls that let the user define custom colors.

ColumnClickEvent

Provides data for the columnClick event of the ListView object.

ColumnHeader

Encapsulates a column header in a ListView control.

ColumnHeaderStyle

Defines constants that specify the column header style.

ComboBox

Encapsulates the Windows combo box control.

ComboBoxStyle

Defines constants that specify the appearance of a combo box.

CommonDialog

Defines the base class used for displaying dialog boxes on the screen.

ContentAlignment

Defines horizontal and vertical alignments.

ContextMenu

Encapsulates the ContextMenu control.

Control

Defines the base class used for controls, which are standardized child windows that the user can manipulate to perform an action or display information.

ControlAnchor

Defines constants that specify how a control is anchored to the edges of its container.

ControlDock

Defines constants that specify how a control is docked to the edges of its container.

CoordinateSystem

Defines the constants that identify the coordinate systems that you can associate with a Graphics object.

CreateParams

Encapsulates the information used when creating a control.

Cursor

Encapsulates a mouse pointer and the operations that you can perform on a cursor.

DateRangeEvent

Provides data for the dateChanged event and the dateSelected event of a MonthCalendar control.

DateTimeFormatEvent

Provides data for the format event of the DateTimePicker control.

DateTimeFormatQueryEvent

Provides data for the formatQuery event of the DateTimePicker control.

DateTimePicker

Encapsulates a Windows date and time picker control, which allows users to specify date and time information.

DateTimePickerFormat

Defines constants that specify how the date and time picker control displays date and time information.

DateTimeUserStringEvent

Provides data for the userString event of the DateTimePicker control.

DateTimeWmKeyDownEvent

Provides data for the wmKeyDown event of the DateTimePicker control.

Days

Defines constants that represent the days of the week.

DialogResult

Defines constants that represent common results returned from dialog boxes.

Dimensions

Encapsulates a two-dimensional array.

DocumentReadyEvent

Provides data for the documentReady event of the HTMLControl object.

DragAction

Defines constants that specify how and if a drag-and-drop operation should continue.

DragDropEffect

Defines constants that specify the the effects of a drag-and-drop operation.

DragEvent

Provides data for the the dragDrop, dragEnter, dragLeave, or dragOver event of a Control object.

DrawItemEvent

Provides data for the drawItem event of a ComboBox, ListBox, StatusBar, TabStrip, or TabControl control.

DrawItemState

Defines constants that specify state information for a drawing operation.

DrawMode

Defines a group of constants that specify how the elements of a list box or combo box are drawn.

Edit

Encapsulates a Windows edit control, which is a rectangular control that the user can enter text into.

EraseBackgroundEvent

Provides data for the eraseBackground event of the Control object.

FileDialog

Defines the base class for the OpenFileDialog and SaveFileDialog classes.

FloodFillType

Defines the filling modes used by the Graphics object to fill an area.

Font

Encapsulates a Win32 font, which is used to draw text on video displays and other output devices.

FontDescriptor

The FontDescriptor object, like the FontMetrics object that it extends, provides information about the font that underlies a Font object.

FontDevice

Defines a group of constants that determine what types of fonts will be listed in a font dialog box.

FontDialog

Represents a common dialog box that displays a list of fonts that are currently installed on the system.

FontFamily

Defines a group of constants that represent the families to which a font may belong.

FontMetrics

Defines the physical characteristics of a font as it is mapped into a Graphics object.

FontPitch

Encapsulates a font's pitch.

FontSize

Defines a group of constants that represent the units in which font sizes can be specified.

FontType

Encapsulates a font type.

FontWeight

Defines constants that represent the different weights that you can associate with a font.

Form

Represents the basic top-level window.

FormBorderStyle

Defines enumeration constants that represent the border styles of a form.

FormPaletteMode

Defines the palette modes supported by a WFC form on 256-color systems.

FormStartPosition

Defines constant values that describe the initial position of a form.

FormWindowState

Defines a group of constants that specify the state of a window.

GiveFeedbackEvent

Provides data for the giveFeedBack event of the Control object.

Graphics

Encapsulates a Win32 device context (DC) and the drawing operations that are typically performed on a DC.

GroupBox

Encapsulates a group box control, which is a rectangle that contains other controls.

Help

Encapsulates the Win32 help engine.

HelpEvent

Provides data for the help event of the Control object.

HelpProvider

Defines methods that provide online help support for WFC controls.

HitArea

Defines constants that represent areas in a MonthCalendar control.

HitTestInfo

Contains information specific to hit-testing points for a month calendar control.

HorizontalAlignment

Defines constants that specify how an object or text in a control is horizontally aligned relative to an element of the control.

HScrollBar

Encapsulates a scroll bar that is always oriented horizontally.

HTMLControl

Encapsulates an HTML control.

Icon

Encapsulates a Windows icon, which is a small, transparent bitmap used to visually represent an object, such as a Windows application.

IconArrange

Defines a group of constants that specify how icons are arranged within a window.

Image

Represents the base class for image classes, such as Bitmap, Cursor, Metafile, and Icon.

ImageList

Contains a collection of images that can be used by other controls, such as the ListView, TreeView, Toolbar, TabStrip, and TabControl controls.

ImageListStreamer

Allows an ImageList object to be persisted to a stream and depersisted from a stream.

InputLangChangeEvent

Provides data for the inputLangChange event of the Form control.

InputLangChangeRequestEvent

Provides data for the inputLangChangeRequest event of the Form control.

ItemActivation

Defines the constants that specify the user action that is required to activate items in a the list view control and the feedback that is given as the user moves the mouse pointer over an item.

ItemBoundsPortion

Defines the constants that specify a portion of the list view item for which to retrieve the bounding rectangle.

ItemCheckEvent

Provides data for the itemCheck event of a CheckedListBox control.

ItemDragEvent

Provides data for the itemDrag event of a ListView or a TreeView control.

Key

Defines constants to use for processing keyboard input.

KeyEvent

Provides data for the keyDown or keyUp event of a Control object.

KeyPressEvent

Provides data for the keyPress event of a Control object.

Label

Encapsulates the Windows label control, which displays a string of text that the user cannot edit.

LabelEditEvent

Provides data for the afterLabelEdit event and the beforeLabelEdit event of a ListView control.

LayoutEvent

Provides data for the layout event of the Control object.

LeftRightAlignment

Defines constants that specify whether an object or text is aligned to the left or to the right of a reference point.

ListBox

Encapsulates the Windows list box control, which displays a list from which the user can select one or more items.

ListItem

Represents an item in a list view control.

ListView

Encapsulates the Windows list view control, which displays a collection of items, each consisting of an icon (from an image list) and a label.

ListViewAlignment

Defines the constants that specify how items are aligned in a list view control.

MainMenu

Encapsulates the MainMenu control.

MDIClient

Represents a window that contains MDI child windows.

MDILayout

Defines constants that specify the layout MDI child windows.

MeasureItemEvent

Provides data for the measureItem event of a ComboBox or ListBox control.

Menu

Encapsulates a WFC menu.

MenuGlyph

Defines a group of constants that determine how a menu glyph should be drawn.

MenuItem

Encapsulates a menu item.

MenuMerge

Defines constants that specify how menus behave when they are merged together.

MessageBox

Allows the user to display a message box that can contain various buttons and icons.

Metafile

Encapsulates a Windows metafile.

MonthCalendar

Encapsulates a Windows month calendar control, which provides a simple calendar interface from which the user can select a date.

MouseButton

Defines constants that specify which mouse button was pressed.

MouseEvent

Provides data for the the mouseDown, mouseEnter, mouseLeave, mouseMove, or mouseUp event of a Control object.

NodeLabelEditEvent

Provides data for the afterLabelEdit event and the beforeLabelEdit event of a TreeView control.

OpenFileDialog

Encapsulates the Save As common dialog box control that allows the user to open a file.

Orientation

Defines a group of constants that represent the orientation of a control or of an element of the control.

PaintEvent

Provides data for the paint event of the Control object.

Palette

Encapsulates a Windows logical palette.

Panel

Represents a container you can use to parent other controls visually.

Pen

Encapsulates a Windows pen that applications use to draw lines, curves, and shapes.

PenStyle

Defines constants for the seven built-in pen styles supported by the Windows operating system.

PictureBox

Encapsulates a PictureBox control.

PictureBoxSizeMode

Defines the constants that determine the sizing mode of the PictureBox control.

Point

Encapsulates a single (x,y) coordinate and the operations that you can perform on such a coordinate.

PolyFillMode

Defines a group of constants that describe the approaches to filling areas in a polygon.

ProgressBar

Encapsulates the ProgressBar control.

QueryContinueDragEvent

Provides data for the queryContinueDrag event of the Control object.

RadioButton

Encapsulates a radio button (or option button) control, which displays an option that can be turned on or off.

Radix

Defines constants that specify the supported base values for the up-down control.

RasterOp

Encapsulates a Win32 raster operation.

ReadyStateEvent

Provides data for the readyState event of the DhTable, DhImage, DhDocument, DhInlineFrame, or DhObjectFactory object.

Rebar

Encapsulates a rebar control, which contains other controls within moveable, resizable bands.

RebarBand

Encapsulates a band on a Rebar control.

Rectangle

Encapsulates a rectangular area defined by its top-left (x, y) coordinate and its width and height.

Region

Encapsulates a Windows region and the logical operations that you can perform on regions.

RequestResizeEvent

Provides data for the requestResize event of the RichEdit control.

RichEdit

Encapsulates a Win32 RichEdit control.

RichEditFind

Defines constants that determine how a text search is carried out in a RichEdit control.

RichEditIMEColor

Defines constants that indicate the IME color and weight of text displayed a RichEdit control.

RichEditIMEOptions

Defines constants that represent the options you can set on a RichEdit control.

RichEditScrollBars

Defines constants that identify the type of scroll bars that should be used in a RichEdit control.

RichEditSelType

Defines constants that indicate the type of selection in a RichEdit control.

RichEditStreamType

Defines constants that identify the types of input and output streams used by the RichEdit control's saveFile and loadFile methods.

RichEditWordPunctuation

Defines the types of punctuation tables that can be used with the RichEdit control's word-wrapping and word-breaking features.

SaveFileDialog

Encapsulates the Save As common dialog box control that allows the user to specify options for saving a file.

Screen

Encapsulates the physical display device.

ScrollBar

Represents the base class for scroll bar controls.

ScrollBars

Defines constants that specify which scroll bars appear with a control.

ScrollButton

Defines the constants that specify which scroll bar button is drawn.

ScrollEvent

Provides information about the scroll event of a scroll bar.

ScrollEventType

Defines the constants that specify the type of scroll event that occurred.

SelectionMode

Defines constants that specify how many items in a list a user can select at one time and how the user can make multiple selections.

SelectionRange

Represents a date selection range in a MonthCalendar control.

SelectionStyle

Defines constants that specify the borders a component can have when selected in the Forms Designer.

Shortcut

Defines constants that specify shortcut keys that can be associated with menu items.

SortOrder

Defines constants that specify how items in a list are sorted.

Splitter

Encapsulates the splitter control, which allows the user to resize docked controls at run time.

SplitterEvent

Provides data for the splitterMoved and splitterMoving events of a Splitter control.

StatusBar

Encapsulates the Windows status bar control.

StatusBarDrawItemEvent

Provides data for the drawItem event of the StatusBar object.

StatusBarPanel

Represents a panel in a StatusBar control.

StatusBarPanelAutoSize

Defines constants that specify how a panel on a status bar autosizes when the status bar resizes.

StatusBarPanelBorderStyle

Defines constants that specify the appearance of the border for a panel on a status bar.

StatusBarPanelClickEvent

Provides data for the panelClick event of the StatusBar control.

StatusBarPanelStyle

Defines constants that specify whether a panel on a status bar is owner-drawn (to support displaying images or a different font from the rest of the status bar) or system-drawn (the standard setting for displaying text).

TabAlignment

Defines constants that specify where the tabs in a tab control are located.

TabAppearance

Defines constants that specify the appearance of the tabs in a tab control or tab strip.

TabBase

Defines the base class that contains common functionality for the TabStrip and TabControl classes.

TabControl

Encapsulates the tab control.

TabDrawMode

Defines constants that specify whether the tabs in a TabStrip or TabControl control are system-drawn or owner-drawn (drawn by the parent window).

TabItem

Encapsulates a tab in a tab strip.

TabPage

Encapsulates a tab page in a tab control.

TabSizeMode

Defines constants that specify how tabs in a TabStrip or TabControl control are sized.

TabStrip

Encapsulates a tab strip control.

TextFormat

Defines a group of constants that indicate how text should be formatted.

TickStyle

Defines constants that specify where tick marks appear in a trackbar control.

ToolBar

Encapsulates the ToolBar custom control.

ToolBarAppearance

Defines the enumeration constants that specify the appearance of a Toolbar control.

ToolBarButton

Encapsulates a button on a toolbar.

ToolBarButtonClickEvent

Provides data for the buttonClick and buttonDropDown events of the ToolBar control.

ToolBarButtonStyle

Encapsulates the styles that you can assign to toolbar buttons.

ToolBarTextAlign

Defines the constants that determine how text is positioned on a toolbar button.

ToolTip

Encapsulates the ToolTip control which provides a tooltip for the controls on a form.

TrackBar

Encapsulates a trackbar control (also known as a slider control), which contains a slider for selecting a value in a range.

TreeNode

Represents a node in a TreeView control.

TreeNodesEditDialog

Represents the TreeNode Editor dialog box that is used for editing tree view nodes from the Properties window.

TreeView

Encapsulates a Windows tree view control.

TreeViewCancelEvent

Provides data for the beforeCollapse, the beforeExpand, and the beforeSelect events of a TreeView control.

TreeViewEvent

Provides data for the afterCollapse, the afterExpand, and the afterSelect events of a TreeView control.

UpDown

Encapsulates the up-down control.

UpDownAcceleration

Contains the amount that the up-down control's value changes when the user clicks an arrow button and the amount of time that elapses before the change takes effect.

UpDownAlignment

Defines constants that specify how the up-down control is positioned relative to its buddy control.

UpDownChangedEvent

Provides data for the upDownChanged event of the UpDown object.

UserControl

Represents an empty control that can be used in the Forms Designer to create other controls.

ViewEnum

Defines constants that specify how list items are displayed in a list view control.

VScrollBar

Encapsulates a scroll bar that is always oriented vertically.

Interfaces

IButtonControl

Defines the button interface.

IHandleHook

Defines the interface that provides information about when components create and destroy their handles.

ISelectionService

Defines the interface for selecting components in the Forms Designer.

ITopLevelWindow

Defines the interface for a top-level window.

Delegates

AutoSizeEventHandler

Identifies the method that will handle the autoSize event of a Rebar control.

ColumnClickEventHandler

Identifies the method that will handle the columnClick event of a ListView control.

DateRangeEventHandler

Identifies the method that will handle the dateChanged event and the dateSelected event of a MonthCalendar control.

DateTimeFormatEventHandler

Identifies the method that will handle the format event of a DateTimePicker control.

DateTimeFormatQueryEventHandler

Identifies the method handling the formatQuery event of a DateTimePicker control.

DateTimeUserStringEventHandler

Identifies the method that will handle the userString event of a DateTimePicker control.

DateTimeWmKeyDownEventHandler

Identifies the method that will handle the wmKeyDown event of a DateTimePicker control.

DocumentReadyEventHandler

Identifies the method that will handle the documentReady event of an HTML control.

DragEventHandler

Identifies the method handling the dragDrop, dragEnter, dragLeave, or dragOver event of a Control control.

DrawItemEventHandler

Identifies the method that will handle the drawItem event of a ComboBox, ListBox, StatusBar, TabStrip, or TabControl control.

GiveFeedbackEventHandler

Identifies the method handling the giveFeedback event of a Control control.

HelpEventHandler

Identifies the method handling the help event of a Control control.

InputLangChangeEventHandler

Identifies the method that will handle the inputLangChange event of a Form control.

InputLangChangeRequestEventHandler

Identifies the method that will handle the inputLangChangeRequest event of a Form control.

ItemCheckEventHandler

Identifies the method that will handle the itemCheck event of a CheckedListBox control.

ItemDragEventHandler

Identifies the method that will handle the itemDrag event of a ListView or a TreeView control.

KeyEventHandler

Identifies the method handling the keyDown or keyUp event of a Control control.

KeyPressEventHandler

Identifies the method that will handle the keyPress event of a Control control.

LabelEditEventHandler

Identifies the method that will handle the afterLabelEdit event and the beforeLabelEdit event of a ListView control.

LayoutEventHandler

Identifies the method handling the layout event of a Control control.

MeasureItemEventHandler

Identifies the method that will handle the measureItem event of a ComboBox or a ListBox control.

MouseEventHandler

Identifies the method handling the mouseDown, mouseEnter, mouseLeave, mouseMove, or mouseUp event of a Control control.

NodeLabelEditEventHandler

Identifies the method that will handle the afterLabelEdit event and the beforeLabelEdit event of a TreeView control.

PaintEventHandler

Identifies the method handling the paint event of a Control control.

QueryContinueDragEventHandler

Identifies the method handling the queryContinueDrag event of a Control control.

ReadyStateEventHandler

Identifies the method that will handle the readyState event of the DhTable, DhImage, DhDocument, DhInlineFrame, or DhObjectFactory object.

RequestResizeEventHandler

Identifies the method that will handle the requestResize event of a RichEdit control.

ScrollEventHandler

Identifies the method that will handle the scroll event of a scroll bar control.

SplitterEventHandler

Identifies the method that will handle the splitterMoved and splitterMoving events of a Splitter control.

StatusBarDrawItemEventHandler

Identifies the method that will handle the drawItem event of a StatusBar control.

StatusBarPanelClickEventHandler

Identifies the method that will handle the panelClick event of a StatusBar control.

ToolBarButtonClickEventHandler

Identifies the method that will handle the buttonClick and buttonDropDown events of a ToolBar control.

TreeViewCancelEventHandler

Identifies the method that will handle the beforeCollapse, the beforeExpand, and the beforeSelect events of a TreeView control.

TreeViewEventHandler

Identifies the method that will handle the afterCollapse, the afterExpand, and the afterSelect events of a TreeView control.

UpDownChangedEventHandler

Identifies the method that will handle the upDownChanged event of the UpDown control.

Value Editors

The com.ms.wfc.ui package also provides the following value editor classes:

  • AnchorEditor
  • DockEditor
  • FileNameEditor
  • ImageIndexEditor
  • IntegerEditor
  • ReferenceEditor
  • SameParentReferenceEditor
  • StringEditor
  • TreeNodesEditor

For more information about these editors, see Value Editor Classes.


Value Editor Classes (com.ms.wfc.ui)

Provide editors for property values of a specified type. Value editors are used within a property browser to modify property values at design time.

ValueEditor
  |
  +--AnchorEditor
  |
  +--DockEditor
  |
  +--IntegerEditor
  |    |
  |    +--ImageIndexEditor
  |
  +--ReferenceEditor
  |    |
  |    +--SameParentReferenceEditor
  |
  +--StringEditor
  |    |
  |    +--FileNameEditor
  |
  +--TreeNodesEditor

package com.ms.wfc.ui

AnchorEditor

Supports property values that determine which sides of the container a control is bound to. This class provides a drop-down graphical control that allows the user to specify which sides to anchor the control to.

DockEditor

Supports property values that determine which side of the container a control is docked to. This class provides a drop-down graphical control that allows the user to specify which side to dock the control to.

FileNameEditor

Supports property values that are file names, providing a dialog box to select an existing file. This class extends StringEditor.

ImageIndexEditor

Supports property values that are arrays of images, providing a dialog box to visually add, remove, and sort images. This class extends IntegerEditor.

IntegerEditor

Supports property values of type int. This class can translate to and from textual representations.

ReferenceEditor

Supports property values that refer to other components. This class enumerates possible values by querying the container of the hosting component for all components that implement the property type.

SameParentReferenceEditor

Supports property values that refer to other components that have the same parent as this control. This class extends ReferenceEditor.

StringEditor

Supports property values that are strings.

TreeNodesEditor

Supports property values that are arrays of tree nodes, providing a dialog box to visually add, remove, and sort nodes and to associate images with nodes.


Animation Class

Encapsulates a Windows animation control, a rectangular control that plays an Audio-Video Interleaved (AVI) animation file.

Component
  |
  +--Control
    |
    +--Animation

package com.ms.wfc.ui

public class Animation
extends Control

Remarks

To specify which animation file to play in an Animation control, use the setFileName method. Use the start method to start the animation, and use the stop method to end it. Use the setAutoPlay method to set the autoPlay property to true if you want the animation to begin automatically when the Animation control loads the animation file. The Animation control can play only uncompressed AVI files or AVI files that have been compressed using Run-Length Encoding (RLE). If sound information is included in the AVI file, the Animation control ignores it. One common use for an Animation control is to indicate system activity during a lengthy operation. For example, the Find dialog box in Windows Explorer displays a moving magnifying glass as the system searches for a file.

The following example plays the animation file Clock.avi three times from frame four to the end:

private void btnAnimate_click(Object source, Event e)
{
    animation1.setFileName("D:\\WINNT\\clock.avi"); //sets the file to play
    animation1.start(3,4,-1); //plays from frame 4 to the end of the movie 3 times
}


 Animation Methods

Animation Methods

Constructors | Description
Animation | Creates an Animation object.

Methods | Description
addOnStart | Assigns a delegate to the start event.
addOnStop | Assigns a delegate to the stop event.
getAutoPlay | Retrieves a boolean value indicating whether the Animation control will start to play an animation file as soon as the animation file is loaded.
getCentered | Retrieves a boolean value indicating whether the animation will appear in the center of the Animation control.
getFileName | Retrieves the file name of the animation to be played.
getTransparent | Retrieves a boolean value indicating whether Windows will draw the animation using a transparent background or the background color specified in the animation clip.
getUseTimer | Retrieves a boolean value indicating whether a Win32 timer is used instead of a separate thread to synchronize animation playback.
onStart | Triggers the start event.
onStop | Triggers the stop event.
removeOnStart | Removes the delegate that is assigned to the start event.
removeOnStop | Removes the delegate that is assigned to the stop event.
setAutoPlay | Sets a boolean value indicating whether the Animation control will start to play an animation file as soon as the animation file is loaded.
setCentered | Sets a boolean value indicating whether the animation will appear in the center of the Animation control.
setFileName | Sets the file name of the animation to be played.
setTransparent | Sets a boolean value indicating whether Windows will draw the animation using a transparent background or the background color specified in the animation clip.
setUseTimer | Sets a boolean value indicating whether a Win32 timer is used instead of a separate thread to synchronize animation playback.
start | Plays the animation clip one time from beginning to end, or plays the animation the specified number of times from the specified start frame to the specified end frame.
stop | Stops playing the animation.


 Animation.addOnStart

Animation.addOnStart

Assigns a delegate to the start event.

Syntax

public final void addOnStart( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the start event to that method in the Properties window. The start event occurs when an animation file starts playing in the Animation control.

See Also removeOnStart


 Animation.addOnStop

Animation.addOnStop

Assigns a delegate to the stop event.

Syntax

public final void addOnStop( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the stop event to that method in the Properties window. The stop event occurs when an animation file stops playing in the Animation control.

See Also removeOnStop


 Animation.Animation

Animation.Animation

Creates an Animation object.

Syntax

public Animation()

Remarks

After you have created the Animation object, use the setFileName method to specify which animation file you want the control to play. Use the start method to start the animation, and use the stop method to end it.


 Animation.getAutoPlay

Animation.getAutoPlay

Retrieves a boolean value indicating whether the Animation control will start to play an animation file as soon as the animation file is loaded.

Syntax

public final boolean getAutoPlay()

Return Value

Returns true if the control automatically starts playing an animation file as soon as the file is opened; otherwise, returns false. If getAutoPlay returns false, the Animation control does not start playing the animation file until the start method is called.

Remarks

To set the value of the autoPlay property, use the setAutoPlay method.

See Also setAutoPlay


 Animation.getCentered

Animation.getCentered

Retrieves a boolean value indicating whether the animation will appear in the center of the Animation control.

Syntax

public final boolean getCentered()

Return Value

Returns true if the animation will be centered within the Animation control; otherwise, returns false. If getCentered returns false, the animation will be placed in the upper-left corner of the Animation control.

Remarks

To set the value of the centered property, use the setCentered method.

See Also setCentered


 Animation.getFileName

Animation.getFileName

Retrieves the file name of the animation to be played.

Syntax

public final String getFileName()

Return Value

Returns the file name of the animation to be played.

Remarks

The name will be returned as a fully qualified path. To set the value of the fileName property, use the setFileName method.

See Also setFileName


 Animation.getTransparent

Animation.getTransparent

Retrieves a boolean value indicating whether Windows will draw the animation using a transparent background or the background color specified in the animation clip.

Syntax

public final boolean getTransparent()

Return Value

Returns true if Windows will draw the animation with a transparent background; returns false if the color specified in the animation clip will be used.

Remarks

To set the value of the transparent property, use the setTransparent method.

See Also setTransparent


 Animation.getUseTimer

Animation.getUseTimer

Retrieves a boolean value indicating whether a Win32 timer is used instead of a separate thread to synchronize animation playback.

Syntax

public final boolean getUseTimer()

Return Value

Returns true if a timer will be used; returns false if a thread will be used. Threads are used by default.

Remarks

To set the value of the useTimer property, use the setUseTimer method.

See Also setUseTimer


 Animation.onStart

Animation.onStart

Triggers the start event.

Syntax

protected void onStart( Event e )

Parameters

e

An Event object that provides information about the start event.

Remarks

When overriding this method, call super.onStart

See Also addOnStart


 Animation.onStop

Animation.onStop

Triggers the stop event.

Syntax

protected void onStop( Event e )

Parameters

e

An Event object that provides information about the start event.

Remarks

When overriding this method, call super.onStop.

See Also addOnStop


 Animation.removeOnStart

Animation.removeOnStart

Removes the delegate that is assigned to the start event.

Syntax

public final void removeOnStart( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnStart


 Animation.removeOnStop

Animation.removeOnStop

Removes the delegate that is assigned to the stop event.

Syntax

public final void removeOnStop( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnStop


 Animation.setAutoPlay

Animation.setAutoPlay

Sets a boolean value indicating whether the Animation control will start to play an animation file as soon as the animation file is loaded.

Syntax

public final void setAutoPlay( boolean value )

Parameters

value

Set to true if the control automatically starts playing an animation file as soon as the file is opened; otherwise, set to false. If getAutoPlay returns false, the Animation control does not start playing the animation file until the start method is called. The default value is false.

Remarks

To get the value of the autoPlay property, use the getAutoPlay method.

See Also getAutoPlay


 Animation.setCentered

Animation.setCentered

Sets a boolean value indicating whether the animation will appear in the center of the Animation control.

Syntax

public final void setCentered( boolean value )

Parameters

value

Set to true if the animation will be centered within the Animation control; set to false if the animation will be placed in the upper-left corner of the Animation control. The default value is false.

Remarks

If the animation is not centered, it will appear in the upper-left corner of the control. To get the value of the centered property, use the getCentered method.

See Also getCentered


 Animation.setFileName

Animation.setFileName

Sets the file name of the animation to be played.

Syntax

public final void setFileName( String value )

Parameters

value

The file name of the animation to be played. Set to null to clear the control.

Remarks

To get the value of the fileName property, use the getFileName method. For a code example using this method, see the Animation control topic.

See Also getFileName


 Animation.setTransparent

Animation.setTransparent

Sets a boolean value indicating whether Windows will draw the animation using a transparent background or the background color specified in the animation clip.

Syntax

public final void setTransparent( boolean value )

Parameters

value

Set to true if Windows will draw the animation with a transparent background; set to false if the background color specified in the animation clip will be used. The default value is false.

Remarks

To get the value of the transparent property, use the getTransparent method.

See Also getTransparent


 Animation.setUseTimer

Animation.setUseTimer

Sets a boolean value indicating whether a Win32 timer is used instead of a separate thread to synchronize animation playback.

Syntax

public final void setUseTimer( boolean value )

Parameters

value

Set to true if a timer will be used; set to false if a thread will be used. The default value is false.

Remarks

To get the value of the useTimer property, use the getUseTimer method.

See Also getUseTimer


 Animation.start

Animation.start

Plays the animation clip one time from beginning to end, or plays the animation the specified number of times from the specified start frame to the specified end frame.

Syntax

public final boolean start()

public final boolean start( int repeat, int start, int end )

Parameters

repeat

The number of times to play the animation.

start

The frame on which to start playing.

end

The frame on which to stop playing. A value of -1 indicates that the clip should be played to the end.

Return Value

Returns true if the start operation succeeded; otherwise, returns false.

Remarks

To get the value of the useTimer property, use the getUseTimer method. For a code example using the start method, see the Animation control topic.


 Animation.stop

Animation.stop

Stops playing the animation.

Syntax

public final boolean stop()

Return Value

Returns true if the start operation succeeded; otherwise, returns false.


Appearance Class

Defines constants that specify the appearance of a component.

Enum
  |
  +--Appearance

package com.ms.wfc.ui

public class Appearance
extends Enum


 Appearance Methods

Appearance Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 Appearance.valid

Appearance.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 Appearance Fields

Appearance Fields

Fields | Description
BUTTON | Specifies that the component should have the appearance of a Windows command button (also known as a push button).
NORMAL | Specifies that the component should have its default appearance.


 Appearance.BUTTON

Appearance.BUTTON

Specifies that the component should have the appearance of a Windows command button (also known as a push button).

Syntax

public static final int BUTTON;


 Appearance.NORMAL

Appearance.NORMAL

Specifies that the component should have its default appearance.

Syntax

public static final int NORMAL;


AutoSizeEvent Class

Provides data for the autoSize event of the Rebar object.

Event
  |
  +--AutoSizeEvent

package com.ms.wfc.ui

public class AutoSizeEvent
extends Event

Remarks

The autoSize event occurs when the rebar automatically resizes itself in response to a change in the size or position of the bands it contains. An AutoSizeEvent object specifies the bounding rectangle for the resized rebar.

For information about the WFC event model, see Handling Events in WFC.


 AutoSizeEvent Methods

AutoSizeEvent Methods

Constructors | Description
AutoSizeEvent | Creates a AutoSizeEvent object.


 AutoSizeEvent.AutoSizeEvent

AutoSizeEvent.AutoSizeEvent

Creates a AutoSizeEvent object.

Syntax

public AutoSizeEvent( Rectangle rect )

Parameters

rect

The Rectangle object that represents the bounding rectangle for the resized control.


 AutoSizeEvent Fields

AutoSizeEvent Fields

Fields | Description
newRectangle | Specifies the Rectangle object that represents the bounding rectangle for the resized control.


 AutoSizeEvent.newRectangle

AutoSizeEvent.newRectangle

Specifies the Rectangle object that represents the bounding rectangle for the resized control.

Syntax

public final Rectangle newRectangle;


AutoSizeEventHandler Delegate

Identifies the method that will handle the autoSize event of a Rebar control.

package com.ms.wfc.ui

public multicast delegate
void AutoSizeEventHandler( Object sender, AutoSizeEvent e );

Remarks

The syntax of the AutoSizeEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is an AutoSizeEvent object that provides the event data.

When you create a AutoSizeEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered. For more information about delegates, see Handling Events in WFC.


AxHost Class

Wraps an ActiveX control and exposes the control as a WFC control.

Control
  |
  +--AxHost

package com.ms.wfc.ui

public class AxHost
extends Control
implements IRequireBegin

Remarks

The AxHost class is not used directly, but is extended by you. You can use the JActiveX tool to generate the wrappers that extend AxHost.


 AxHost Methods

AxHost Methods

Constructors | Description
AxHost | Creates an AxHost object.

Methods | Description
attachInterfaces | Called when the AxHost object is ready to create the underlying ActiveX object.
begin | Signals that loading of all peer components and property sets is complete.
destroyHandle | Destroys the handle associated with this control.
getContainingForm | Retrieves the form that contains this control.
getOcx | Retrieves the IUnknown object for the ActiveX control that this class wraps.
getOcxState | Retrieves the persisted state of the ActiveX control that underlies this object.
preProcessMessage | Preprocesses messages directed to this control before the messages are sent to the control's window procedure.
propertyChanged | Called by the control when a property changes.
setAboutBoxDelegate | Sets the delegate that will be called when the user clicks the About item on the control's context menu.
setBoundsCore | Sets the bounds of the control.
setComponentSite | Sets the control's site.
setContainingForm | Sets the control's container.
setOcxState | Sets the persisted state of the control.
setTopLevel | Sets a boolean value that determines whether this control should be a top-level window.
setVisible | Sets a boolean value that determines whether the control is visible.
shouldPersistContainingForm | Sets a boolean value that specifies whether this control should persist the property that identifies its containing form.
wndProc | Represents the window procedure for this control.


 AxHost.attachInterfaces

AxHost.attachInterfaces

Called when the AxHost object is ready to create the underlying ActiveX object.

Syntax

protected void attachInterfaces()

Remarks

Classes that extend AxHost should override this method. Within an overridden version of this method, the extending class should call getOcx to retrieve its own interface. The getOcx method should generally not be called before this method is called.

Additionally, a call to the begin method results in the invocation of attachInterfaces.


 AxHost.AxHost

AxHost.AxHost

Creates an AxHost object.

Syntax

protected AxHost( String clsid )

protected AxHost( String clsid, int flags )

Parameters

clsid

The class identifier (CLSID) of the underlying ActiveX control.

flags

One or more of the internal Flags class members, combined with the bitwise OR operator.


 AxHost.begin

AxHost.begin

Signals that loading of all peer components and property sets is complete.

Syntax

public void begin()

Remarks

It should be possible for the user of your control to invoke any property on your control after calling this method.

A side-effect of this method is the creation of the parent control's handle. Consequently, this control must have a parent before the begin method is called.


 AxHost.destroyHandle

AxHost.destroyHandle

Destroys the handle associated with this control.

Syntax

protected void destroyHandle()

Remarks

Generally, the application developer should not directly call this method; it is called by the object when the object is ready to destroy its underlying handle.


 AxHost.getContainingForm

AxHost.getContainingForm

Retrieves the form that contains this control.

Syntax

public Form getContainingForm()

Return Value

Returns a Form object that specifies this control's containing form.


 AxHost.getOcx

AxHost.getOcx

Retrieves the IUnknown object for the ActiveX control that this class wraps.

Syntax

public IUnknown getOcx()

Return Value

Returns the IUnknown object for this ActiveX control.


 AxHost.getOcxState

AxHost.getOcxState

Retrieves the persisted state of the ActiveX control that underlies this object.

Syntax

public State getOcxState()

Return Value

Returns a State object that specifies the persisted state of the ActiveX control that underlies this object.


 AxHost.preProcessMessage

AxHost.preProcessMessage

Preprocesses messages directed to this control before the messages are sent to the control's window procedure.

Syntax

public boolean preProcessMessage( MSG msg )

Parameters

msg

An MSG structure that specifies the message to preprocess. Possible values for this parameter include WM_KEYDOWN, WM_SYSKEYDOWN, WM_CHAR, and WM_SYSCHAR.

Return Value

Returns true if this method processes the message; otherwise, returns false.

Remarks

This method is called by the application message loop to pre-process input messages before the messages are dispatched to the application's window procedure.

If this method preprocesses the method and returns true, the message is not passed to the application's window procedure.

This method should not be called directly by the application developer.

See Also wndProc


 AxHost.propertyChanged

AxHost.propertyChanged

Called by the control when a property changes.

Syntax

protected void propertyChanged( int property )

Parameters

property

The property that changed.

Remarks

Classes that extend this one can override this method to get property change notification.


 AxHost.setAboutBoxDelegate

AxHost.setAboutBoxDelegate

Sets the delegate that will be called when the user clicks the About item on the control's context menu.

Syntax

protected void setAboutBoxDelegate( AboutBoxDelegate d )

Parameters

d

An AboutBoxDelegate object that specifies the delegate to be notified when the user clicks the About menu item.


 AxHost.setBoundsCore

AxHost.setBoundsCore

Sets the bounds of the control.

Syntax

protected void setBoundsCore( int x, int y, int width, int height )

Parameters

x

The x-coordinate of the control's bounds.

y

The y-coordinate of the control's bounds.

width

The width of the control's bounds.

height

The height of the control's bounds.


 AxHost.setComponentSite

AxHost.setComponentSite

Sets the control's site.

Syntax

public void setComponentSite( IComponentSite site )

Parameters

site

An IComponentSite object that specifies the container to which the control has been added. If this control is being removed from a container, this value should be null.


 AxHost.setContainingForm

AxHost.setContainingForm

Sets the control's container.

Syntax

public void setContainingForm( Form f )

Parameters

f

A Form object that specifies the control's container.

See Also getContainingForm


 AxHost.setOcxState

AxHost.setOcxState

Sets the persisted state of the control.

Syntax

public void setOcxState( State ocxState )

Parameters

ocxState

A State object that specifies the control's state.

Remarks

The value to which you initialize this method's ocxState parameter should be null, obtained by calling getOcxState, or read from a resource. The value of this parameter is used after the control is created, but before it is displayed.

Exceptions

WFCException thrown if the control has already been activated.


 AxHost.setTopLevel

AxHost.setTopLevel

Sets a boolean value that determines whether this control should be a top-level window.

Syntax

public void setTopLevel( boolean value )

Parameters

value

Set to true to make this control a top-level window; otherwise, set to false.

Remarks

Because an ActiveX control can never be a top-level window, the value of the value parameter should always be false.

Exceptions

WFCException thrown if the value parameter is set to true.


 AxHost.setVisible

AxHost.setVisible

Sets a boolean value that determines whether the control is visible.

Syntax

public void setVisible( boolean value )

Parameters

value

Set to true to make the control visible; otherwise, set to false.

Remarks

Calling this method on a control that is designed to be invisible at runtime has no effect.


 AxHost.shouldPersistContainingForm

AxHost.shouldPersistContainingForm

Sets a boolean value that specifies whether this control should persist the property that identifies its containing form.

Syntax

public boolean shouldPersistContainingForm()

Return Value

Returns true if the containing form should be persisted; otherwise, returns false.


 AxHost.wndProc

AxHost.wndProc

Represents the window procedure for this control.

Syntax

protected void wndProc( Message m )

Parameters

m

A Message object that specifies the message to process.

Remarks

This method is passed messages that have not been processed by the object's preProcessMessage method.


AxHost.AxPropertyInfo Class

Extends the ProperyInfo object for an ActiveX control to provide access to the underlying ActiveX object.

PropertyInfo
  |
  +--AxHost.AxPropertyInfo

package com.ms.wfc.ui

public static class AxHost.AxPropertyInfo
extends PropertyInfo


 AxHost.AxPropertyInfo Methods

AxHost.AxPropertyInfo Methods

Constructors | Description
AxPropertyInfo | Creates an AxPropertyInfo object.

Methods | Description
getValueEditor | Retrieves the value editor for this property based on a specified IEditorSite object.
setValue | Sets the value of this property to a specified value.


 AxHost.AxPropertyInfo.AxPropertyInfo

AxHost.AxPropertyInfo.AxPropertyInfo

Creates an AxPropertyInfo object.

Syntax

public AxPropertyInfo( Class componentClass, String name, Class type, MemberAttribute[] attributes )

Parameters

componentClass

The class from which the control's get and set methods will come. This should be the class which extends AxHost

name

The name of the property.

type

The type of the property.

attributes

An array of MemberAttribute objects that specify the attributes of this property.


 AxHost.AxPropertyInfo.getValueEditor

AxHost.AxPropertyInfo.getValueEditor

Retrieves the value editor for this property based on a specified IEditorSite object.

Syntax

public IValueEditor getValueEditor( IEditorSite site )

Parameters

site

An IEditorSite object that specifies the editor site to use.

Return Value

Returns an IValueEditor object that specifies the value editor for this property.

Remarks

If the attributes of this property specify a value editor, or if the type of this property is Image, Color, or Font, then calling this method is equivalent to calling the PropertyInfo object's getValueEditor method. Otherwise, a special value editor is returned, and the behavior of this editor depends on the underlying ActiveX control.


 AxHost.AxPropertyInfo.setValue

AxHost.AxPropertyInfo.setValue

Sets the value of this property to a specified value.

Syntax

public void setValue( Object component, Object value )

Parameters

component

The object to modify.

value

An object that specifies the new property value.

Remarks

The object type of the value parameter should correspond to the object type of this property or should be a special value returned by the value editor's getValues method.


AxHost.Flags Class

Defines the flags that can be passed to the AxHost object constructor.

package com.ms.wfc.ui

public static class AxHost.Flags


 AxHost.Flags Fields

AxHost.Flags Fields

Fields | Description
INCLUDE_PROPERTIES_VERB | Specifies that the context menu for the control should not contain an Edit verb unless the ActiveX control offers this verb.
PREVENT_EDIT_MODE | Specifies that the context menu for the control should contain a Properties verb which can be used to display the property pages for the control.


 AxHost.Flags.INCLUDE_PROPERTIES_VERB

AxHost.Flags.INCLUDE_PROPERTIES_VERB

Specifies that the context menu for the control should not contain an Edit verb unless the ActiveX control offers this verb.

Syntax

public static final int INCLUDE_PROPERTIES_VERB;

Remarks

By default, all wrapped ActiveX controls contain an Edit verb.


 AxHost.Flags.PREVENT_EDIT_MODE

AxHost.Flags.PREVENT_EDIT_MODE

Specifies that the context menu for the control should contain a Properties verb which can be used to display the property pages for the control.

Syntax

public static final int PREVENT_EDIT_MODE;

Remarks

Even if this flag is specified at control creation, the verb does not appear unless the control supports a set of property pages. Because most ActiveX controls already have a properties verb on the context menu, this flag is not used by default.


AxHost.State Class

Encapsulates the persisted state of an ActiveX control.

package com.ms.wfc.ui

public static class AxHost.State
implements IPersistable

Remarks

The State object can be created by calling getOcxState on an AxHost object, or by reading the control's state from a data stream.


 AxHost.State Methods

AxHost.State Methods

Constructors | Description
State | Creates a new State object.

Methods | Description
getExtension | Retrieves the file extension that should be used to save objects of this type.
save | Saves the object's state to a data stream.


 AxHost.State.getExtension

AxHost.State.getExtension

Retrieves the file extension that should be used to save objects of this type.

Syntax

public String getExtension()

Return Value

Returns the recommended file extension. This method always returns "ocd".

See Also save


 AxHost.State.save

AxHost.State.save

Saves the object's state to a data stream.

Syntax

public void save( IDataStream ids )

Parameters

ids

The data stream (IDataStream) to which to save the object's state.


 AxHost.State.State

AxHost.State.State

Creates a new State object.

Syntax

public State( IDataStream ids )

Parameters

ids

The data stream (IDataStream) from which to read the object's state.

Remarks

The AxHost object creates the State object by reading it from a specified data stream. The seek pointer in this stream should be positioned at the place that it was located immediately before the save method was called on the stream.

See Also IPersistable


Bitmap Class

Encapsulates a Windows bitmap.

Image
  |
  +--Bitmap

package com.ms.wfc.ui

public class Bitmap
extends Image
implements IPersistable

Remarks

You can use the methods supported by the Bitmap class to load bitmap images from disk files or to create bitmaps in memory. This object also supports methods that enable you to specify certain colors in a bitmap as transparent so that they are not rendered when the bitmap is drawn.


 Bitmap Methods

Bitmap Methods

Constructors | Description
Bitmap | Creates a new Bitmap object.

Methods | Description
clone | Clones the Bitmap object and returns a duplicate.
copyHandle | Retrieves a copy of the Win32 handle for the bitmap on which this object is based.
destroyHandle | Called when this object is going to destroy its Win32 handle.
dispose | Frees all the resources allocated by this object.
drawStretchTo | Renders the bitmap image to a Graphics object, stretching the image to fill the specified dimensions.
drawTo | Renders the bitmap image (or part of it) to a Graphics object, cropping the image to fit the specified dimensions.
finalize | Frees the resources allocated by the Bitmap object.
getColorMask | Retrieves the transparency mask for a transparent bitmap.
getExtension | Retrieves the recommended file extension for files that persist this object.
getGraphics | Retrieves a Graphics object that you can use to paint to this image.
getHandle | Retrieves the Win32 handle to this bitmap.
getMonochromeMask | Retrieves the monochrome mask for a transparent bitmap.
getPalette | Retrieves this Bitmap object's palette.
getPICTDESC | Retrieves a PICTDESC (Picture Descriptor) for this bitmap.
getSize | Retrieves the size of this Bitmap object's image.
getTransparent | Retrieves a boolean value that specifies whether this object is configured to be drawn transparently.
getTransparentColor | Retrieves the transparent color for the Bitmap object.
setTransparent | Specifies whether the bitmap will be drawn transparently.
setTransparentColor | Specifies the transparent color for this Bitmap's image.
toString | Retrieves a human-readable string representation of this object.


 Bitmap.Bitmap

Bitmap.Bitmap

Creates a new Bitmap object.

Syntax

public Bitmap( int handle )

public Bitmap( int handle, Palette palette )

public Bitmap( Bitmap maskBitmap, Bitmap colorBitmap )

public Bitmap( int width, int height )

public Bitmap( int width, int height, Graphics gr )

public Bitmap( int width, int height, int planes, int bitsPerPixel, short bits[] )

public Bitmap( String filename )

public Bitmap( Class type, String resource )

public Bitmap( IDataStream stream )

public Bitmap( IStream stream )

public Bitmap( IPicture picture )

Parameters

handle

A Win32 handle to the bitmap on which to base this object. This handle is not owned by the Bitmap object; you are responsible for freeing it.

palette

A Palette object to use with the bitmap.

maskBitmap

A black and white bitmap mask.

colorBitmap

A Bitmap object that contains a color mask.

width

The width of the bitmap.

height

The height of the bitmap.

gr

A Graphics object with which the bitmap is compatible. For example, a Graphics object based on a printer device context rather than the screen device context.

planes

The number of planes in the bitmap.

bitsPerPixel

The number of bits used to describe each pixel in the bitmap. For example, a 256-color bitmap uses eight bits to describe the color of each pixel, while a true color bitmap generally uses 24 or 32 bits.

bits

An array that contains the bits that make up the bitmap. If you want the Bitmap object to remain uninitialized, this value should be null.

filename

The name of the file that contains the bitmap image.

type

The class used to load the bitmap resource.

resource

The resource to load.

stream

A data stream (IDataStream or com.ms.wfc.ole32.IStream) from which to load the bitmap.

picture

The com.ms.wfc.ole32.IPicture object to get the bitmap from.

Remarks

The Bitmap object defines a large variety of ways in which to create a bitmap. You can create bitmaps in memory or load them from a file, a data stream, or a resource. You can create a bitmap based on a pre-existing Win32 handle or you can create bitmaps that represent a combination of two bitmasks.

When you create a bitmap based on a Win32 handle that you have previously allocated, the Bitmap object does not assume ownership of that handle. Once the Bitmap object has been disposed of you must manually free the bitmap handle.

When you create a bitmap based on two Bitmap objects that specify transparency masks, you can use the new bitmap to draw transparently to the screen. The mask bitmap should be a black and white bitmap. Each part of the mask bitmap to be drawn transparently should be white. Each part of the color bitmap to be drawn transparently should be black.


 Bitmap.clone

Bitmap.clone

Clones the Bitmap object and returns a duplicate.

Syntax

public Object clone()

Return Value

Returns an Object that can be cast to a Bitmap object.


 Bitmap.copyHandle

Bitmap.copyHandle

Retrieves a copy of the Win32 handle for the bitmap on which this object is based.

Syntax

public final int copyHandle()

Return Value

Returns a copy of the Win32 handle to the bitmap that underlies this object.

Remarks

When you copy a bitmap handle, you own the handle and are responsible for freeing it.


 Bitmap.destroyHandle

Bitmap.destroyHandle

Called when this object is going to destroy its Win32 handle.

Syntax

protected void destroyHandle( int handle )

Parameters

handle

The Win32 handle to the bitmap on which this object is based.

Remarks

The Bitmap class' implementation of destroyHandle frees only handles owned by the Bitmap object. If you have created this object based on a previously allocated bitmap handle, this method does nothing; you must free this handle. Similarly, if you have used the object to retrieve a handle to this bitmap (using the copyHandle method), this handle is not freed by the object's call to destroyHandle; you must free it.

However, you can override this method in your Bitmap-derived class to define your own custom semantics for handle creation and destruction.


 Bitmap.dispose

Bitmap.dispose

Frees all the resources allocated by this object.

Syntax

public void dispose()

Remarks

The dispose method frees only those resources allocated by the object. Such resources do not include handle copies that you retrieve using the object's methods; you must free these manually.

Once the dispose method is called, the Bitmap object is no longer useful.


 Bitmap.drawStretchTo

Bitmap.drawStretchTo

Renders the bitmap image to a Graphics object, stretching the image to fill the specified dimensions.

Syntax

protected void drawStretchTo( Graphics g, Rectangle imageRect, Rectangle targetRect, int rop )

Parameters

g

The Graphics object to which to draw the image.

imageRect

A Rectangle object that specifies the bitmap region to draw.

targetRect

A Rectangle object that specifies the area to which to draw the image.

rop

A numerical raster operation (ROP) code that describes how to draw the source image to the target.

Remarks

The drawStretchTo and drawTo methods are used by the Graphics object for all image rendering. For more information on how the Graphics object uses these methods, see the Graphics object's drawImage method.

If the area specified in imageRect is smaller than the area specified in targetRect, the source image is stretched to fill the specified area. If the area specified in imageRect is larger than that specified in targetRect, the image is shrunk.


 Bitmap.drawTo

Bitmap.drawTo

Renders the bitmap image (or part of it) to a Graphics object, cropping the image to fit the specified dimensions.

Syntax

protected void drawTo( Graphics g, Rectangle imageRect, Rectangle targetRect, int rop )

Parameters

g

The Graphics object to which to draw the image.

imageRect

A Rectangle object that specifies the source rectangle in the image.

targetRect

A Rectangle object that specifies the rectangle to which to draw the image. If this area is smaller than imageRect, the source rectangle is cropped to fit in the target rectangle.

rop

A numerical raster operation (ROP) code that specifies how to draw the image.

Remarks

The drawStretchTo and drawTo methods are used by the Graphics object for all image rendering. For more information on how the Graphics object uses these methods, see the Graphics object's drawImage method.

See Also drawStretchTo


 Bitmap.finalize

Bitmap.finalize

Frees the resources allocated by the Bitmap object.

Syntax

protected void finalize()


 Bitmap.getColorMask

Bitmap.getColorMask

Retrieves the transparency mask for a transparent bitmap.

Syntax

public Bitmap getColorMask()

Return Value

A Bitmap object that contains the transparency color mask.

Remarks

This functionality is useful in cases in which you need to render bitmap transparency yourself, or to pass transparent masks to another method.


 Bitmap.getExtension

Bitmap.getExtension

Retrieves the recommended file extension for files that persist this object.

Syntax

public String getExtension()

Return Value

Returns the recommended file extension for this object, minus the prefixing period. The default implementation of this method always returns "bmp".


 Bitmap.getGraphics

Bitmap.getGraphics

Retrieves a Graphics object that you can use to paint to this image.

Syntax

public final Graphics getGraphics()

Return Value

Returns a Graphics object for the Bitmap object. If a Graphics object does not already exist for this object, one is created. If you have created a Graphics object through a previous call to getGraphics, the existing Graphics object is returned.

Remarks

When you create a Graphics object instance using the Bitmap object's getGraphics method, the Graphics object's drawing methods draw to the surface of the Bitmap object itself.


 Bitmap.getHandle

Bitmap.getHandle

Retrieves the Win32 handle to this bitmap.

Syntax

public int getHandle()

Return Value

Returns the handle to this bitmap.

Exceptions

WFCException thrown if the Bitmap object has been disposed through a call to its dispose method.

Remarks

The handle returned by this method is not a copy of the bitmap handle. Therefore, this handle should not be freed by the caller.

See Also copyHandle


 Bitmap.getMonochromeMask

Bitmap.getMonochromeMask

Retrieves the monochrome mask for a transparent bitmap.

Syntax

public Bitmap getMonochromeMask()

Return Value

Returns a Bitmap object that contains the monochrome mask.

Remarks

Generally, you use this method when you need to draw a bitmap transparency yourself, or to pass the transparent mask to another method.


 Bitmap.getPalette

Bitmap.getPalette

Retrieves this Bitmap object's palette.

Syntax

public final Palette getPalette()

Return Value

Returns a Palette object for this bitmap, if there is one; otherwise, returns null.


 Bitmap.getPICTDESC

Bitmap.getPICTDESC

Retrieves a PICTDESC (Picture Descriptor) for this bitmap.

Syntax

public final PICTDESC getPICTDESC()

Return Value

Returns a PICTDESC structure that describes this object's image.

Remarks

The PICTDESC structure is used by OLE functions to create picture objects.


 Bitmap.getSize

Bitmap.getSize

Retrieves the size of this Bitmap object's image.

Syntax

public final Point getSize()

Return Value

A Point object that specifies the height and width of the image.


 Bitmap.getTransparent

Bitmap.getTransparent

Retrieves a boolean value that specifies whether this object is configured to be drawn transparently.

Syntax

public final boolean getTransparent()

Return Value

Returns true if the bitmap is to be drawn transparently; otherwise, returns false.

Remarks

Because Windows does not natively support bitmap transparency, the Bitmap object simulates transparency. Setting the Bitmap object's transparency value (using setTransparent) specifies whether the bitmap's transparent color will be drawn when the image is rendered.

If you specify that a bitmap's transparency color will not be drawn, you should also use the setTransparentColor method to specify which color is transparent for the Bitmap object. If you call the setTransparent method specifying that the bitmap's transparent color should not be drawn, but do not call setTransparentColor to identify the transparent color, the Bitmap object uses the color of the pixel in the lower-left corner of the bitmap.


 Bitmap.getTransparentColor

Bitmap.getTransparentColor

Retrieves the transparent color for the Bitmap object.

Syntax

public final Color getTransparentColor()

Return Value

Returns a Color object that specifies the bitmap's transparent color.

Remarks

If you have not previously used the setTransparentColor method to specify a transparent color for this object, the color of the image's lower-left pixel is the default transparent color.


 Bitmap.setTransparent

Bitmap.setTransparent

Specifies whether the bitmap will be drawn transparently.

Syntax

public final void setTransparent( boolean transparent )

Parameters

transparent

If set to true, the object's specified transparent color is not rendered when the image is drawn; otherwise, the transparent color is drawn.

See Also getTransparent, setTransparentColor


 Bitmap.setTransparentColor

Bitmap.setTransparentColor

Specifies the transparent color for this Bitmap's image.

Syntax

public final void setTransparentColor( Color color )

Parameters

color

A Color object that describes the transparent color.

Remarks

Because Windows does not provide native support for transparency, the transparency information that you specify is not persisted with the Bitmap's image.


 Bitmap.toString

Bitmap.toString

Retrieves a human-readable string representation of this object.

Syntax

public String toString()

Return Value

A string that describes this Bitmap object.


Border3DSide Class

Defines constants that specify which sides of a rectangle to apply a three-dimensional border to.

package com.ms.wfc.ui

public final class Border3DSide

Remarks

You pass a Border3DSide constant as a parameter to the drawBorder3D method of the Graphics object.


 Border3DSide Methods

Border3DSide Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 Border3DSide.valid

Border3DSide.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 Border3DSide Fields

Border3DSide Fields

Fields | Description
BOTTOM | Draws a three-dimensional border on the lower side of a rectangle.
LEFT | Draws a three-dimensional border on the left side of a rectangle.
MIDDLE | Fills in the interior of the rectangle with the color defined for three-dimensional controls instead of with the background color for the form.
RIGHT | Draws a three-dimensional border on the right side of a rectangle.
TOP | Draws a three-dimensional border on the upper side of a rectangle.


 Border3DSide.BOTTOM

Border3DSide.BOTTOM

Draws a three-dimensional border on the lower side of a rectangle.

Syntax

public static final int BOTTOM;


 Border3DSide.LEFT

Border3DSide.LEFT

Draws a three-dimensional border on the left side of a rectangle.

Syntax

public static final int LEFT;


 Border3DSide.MIDDLE

Border3DSide.MIDDLE

Fills in the interior of the rectangle with the color defined for three-dimensional controls instead of with the background color for the form.

Syntax

public static final int MIDDLE;


 Border3DSide.RIGHT

Border3DSide.RIGHT

Draws a three-dimensional border on the right side of a rectangle.

Syntax

public static final int RIGHT;


 Border3DSide.TOP

Border3DSide.TOP

Draws a three-dimensional border on the upper side of a rectangle.

Syntax

public static final int TOP;


Border3DStyle Class

Defines constants that specify the kind of three-dimensional border to apply to a rectangle.

Enum
  |
  +--Border3DStyle

package com.ms.wfc.ui

public final class Border3DStyle
extends Enum

Remarks

You pass a Border3DStyle constant as a parameter to the drawBorder3D method of the Graphics object.


 Border3DStyle Methods

Border3DStyle Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 Border3DStyle.valid

Border3DStyle.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 Border3DStyle Fields

Border3DStyle Fields

Fields | Description
ADJUST | Specifies that the border should be drawn outside the specified rectangle, preserving the dimensions of the rectangle for drawing.
BUMP | Specifies a raised outer edge and a sunken inner edge.
ETCHED | Specifies a sunken inner edge and a raised outer edge.
FLAT | Specifies a border with no three-dimensional effects.
RAISED | Specifies raised inner and outer edges.
RAISEDINNER | Specifies a raised inner edge and no outer edge.
RAISEDOUTER | Specifies a raised outer edge and no inner edge.
SUNKEN | Specifies sunken inner and outer edges.
SUNKENINNER | Specifies a sunken inner edge and no outer edge.
SUNKENOUTER | Specifies a sunken outer edge and no inner edge.


 Border3DStyle.ADJUST

Border3DStyle.ADJUST

Specifies that the border should be drawn outside the specified rectangle, preserving the dimensions of the rectangle for drawing.

Syntax

public static final int ADJUST;


 Border3DStyle.BUMP

Border3DStyle.BUMP

Specifies a raised outer edge and a sunken inner edge.

Syntax

public static final int BUMP;


 Border3DStyle.ETCHED

Border3DStyle.ETCHED

Specifies a sunken inner edge and a raised outer edge.

Syntax

public static final int ETCHED;


 Border3DStyle.FLAT

Border3DStyle.FLAT

Specifies a border with no three-dimensional effects.

Syntax

public static final int FLAT;


 Border3DStyle.RAISED

Border3DStyle.RAISED

Specifies raised inner and outer edges.

Syntax

public static final int RAISED;


 Border3DStyle.RAISEDINNER

Border3DStyle.RAISEDINNER

Specifies a raised inner edge and no outer edge.

Syntax

public static final int RAISEDINNER;


 Border3DStyle.RAISEDOUTER

Border3DStyle.RAISEDOUTER

Specifies a raised outer edge and no inner edge.

Syntax

public static final int RAISEDOUTER;


 Border3DStyle.SUNKEN

Border3DStyle.SUNKEN

Specifies sunken inner and outer edges.

Syntax

public static final int SUNKEN;


 Border3DStyle.SUNKENINNER

Border3DStyle.SUNKENINNER

Specifies a sunken inner edge and no outer edge.

Syntax

public static final int SUNKENINNER;


 Border3DStyle.SUNKENOUTER

Border3DStyle.SUNKENOUTER

Specifies a sunken outer edge and no inner edge.

Syntax

public static final int SUNKENOUTER;


BorderStyle Class

Defines constants that specify basic border styles for a window.

Enum
  |
  +--BorderStyle

package com.ms.wfc.ui

public class BorderStyle
extends Enum


 BorderStyle Methods

BorderStyle Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 BorderStyle.valid

BorderStyle.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 BorderStyle Fields

BorderStyle Fields

Fields | Description
FIXED_3D | Specifies a three-dimensional line border.
FIXED_SINGLE | Specifies a single-line border.
NONE | Specifies no border for the window.


 BorderStyle.FIXED_3D

BorderStyle.FIXED_3D

Specifies a three-dimensional line border.

Syntax

public static final int FIXED_3D;


 BorderStyle.FIXED_SINGLE

BorderStyle.FIXED_SINGLE

Specifies a single-line border.

Syntax

public static final int FIXED_SINGLE;


 BorderStyle.NONE

BorderStyle.NONE

Specifies no border for the window.

Syntax

public static final int NONE;


Brush Class

Encapsulates a Windows brush, a tool that Win32-based applications use to paint the interior of polygons and ellipses.

package com.ms.wfc.ui

public class Brush

Remarks

A brush is used to fill areas of a window or a Graphics region. You can use the constants defined in the Brush and BrushStyle classes to create a Brush object that represents the pattern or color (or both) with which you want to paint enclosed areas. Optionally, you can create a Brush object based on a bitmap that you read from a disk file or create in memory.

Brushes come in three varieties: solid, pattern, and hatched.

A solid brush can consist of any color, and can consist additionally of a color or pattern specifically defined by some element of the Windows user interface.

A hatched brush consists of a combination of a color and of one of the six patterns defined by Windows.

A pattern brush consists of a bitmap that is used as the basis for a pattern that fills a shape. Where the area to be filled is larger than the bitmap, the bitmap is tiled horizontally and vertically across the display. Pattern brushes enable you to create custom brushes that consist of any pattern that you define.


 Brush Methods

Brush Methods

Constructors | Description
Brush | Creates a Brush object.

Methods | Description
copyHandle | Retrieves a copy of the Win32 handle for the brush on which this object is based.
destroyHandle | Called when this object is going to destroy its Win32 handle.
dispose | Frees all the resources allocated by this object.
equals | Retrieves a boolean value that indicates whether the specified object is equivalent to this Brush object.
finalize | Frees the Win32 resources associated with this Brush object.
getColor | Retrieves the color of this brush.
getHandle | Retrieves the Win32 handle of the brush.
getStyle | Retrieves the style of the brush.
hashCode | Computes and returns the hash code for this Brush object.


 Brush.Brush

Brush.Brush

Creates a Brush object.

Syntax

public Brush( Color color )

public Brush( Color color, int style )

public Brush( Bitmap bmp )

public Brush( int handle )

Parameters

color

The Color object that specifies the color of the brush.

style

One of the enumeration constants defined by the BrushStyle class.

bmp

A Bitmap object on which to base the brush.

handle

The handle to a Win32 brush (HBRUSH).

Remarks

The constructors supported by the Brush object enable you to create solid, hatched, pattern, and handle-based brushes.

A brush that you create based on a Win32 handle does not own the handle. Consequently, after using a handle-based brush, you must call the Win32 DeleteObject function to dispose of it.


 Brush.copyHandle

Brush.copyHandle

Retrieves a copy of the Win32 handle for the brush on which this object is based.

Syntax

public final int copyHandle()

Return Value

Returns a copy of the Win32 handle to the brush that underlies this object.

Remarks

When you copy a brush handle, you own the handle and are responsible for freeing it.


 Brush.destroyHandle

Brush.destroyHandle

Called when this object is going to destroy its Win32 handle.

Syntax

protected void destroyHandle( int handle )

Parameters

handle

The Win32 handle to the brush (HBRUSH) on which this object is based.

Remarks

The Brush class' implementation of destroyHandle frees only handles owned by the Brush object. If you have used the object to retrieve a handle to this brush (using the copyHandle method), or if you have created a Brush object based on a previously allocated handle, this handle is not freed by the object's call to destroyHandle; you are responsible for freeing these handles.

However, you can override this method in your Brush-derived class to define your own custom semantics for handle creation and destruction.


 Brush.dispose

Brush.dispose

Frees all the resources allocated by this object.

Syntax

public void dispose()

Remarks

The dispose method frees only those resources allocated by the object. Such resources do not include handle copies that you retrieve using the object's methods; you must free these manually.

Once the dispose method is called, the Bitmap object is no longer useful.


 Brush.equals

Brush.equals

Retrieves a boolean value that indicates whether the specified object is equivalent to this Brush object.

Syntax

public boolean equals( Object obj )

Parameters

obj

The object to which to compare this brush.

Return Value

Returns true if the specified object is a Brush object and is equivalent to this brush; otherwise, returns false.


 Brush.finalize

Brush.finalize

Frees the Win32 resources associated with this Brush object.

Syntax

protected void finalize() throws Throwable

Exceptions

Throwable thrown if resources associated with this brush cannot be freed.

Remarks

The resources freed by a call to finalize include only those allocated by the Brush object. For example, if you construct a Brush object based on a Win32 brush handle, a call to finalize does not free that handle. Instead, you must free this handle manually (usually by calling the Win32 DestroyObject function).


 Brush.getColor

Brush.getColor

Retrieves the color of this brush.

Syntax

public final Color getColor()

Return Value

Returns the brush color.

Remarks

A pattern brush does not return a color.


 Brush.getHandle

Brush.getHandle

Retrieves the Win32 handle of the brush.

Syntax

public final int getHandle()

Return Value

Returns a Win32 handle value.

Remarks

Every brush has a handle, an integer that uniquely identifies the brush to the operating system. After you retrieve the handle to a Brush object, you can pass that handle to any Win32 function that takes a brush handle as a parameter.


 Brush.getStyle

Brush.getStyle

Retrieves the style of the brush.

Syntax

public final int getStyle()

Return Value

Returns one of the constants defined in the BrushStyle class.


 Brush.hashCode

Brush.hashCode

Computes and returns the hash code for this Brush object.

Syntax

public int hashCode()

Return Value

Returns an integer hash code value.


 Brush Fields

Brush Fields

Fields | Description
ACTIVEBORDER | Represents a Brush object that is the color of the active window border.
ACTIVECAPTION | Represents a Brush object that is the color of the active caption bar.
APPWORKSPACE | Represents a Brush object that is the color of the application workspace window.
CONTROL | Represents a Brush object that is the color of controls.
CONTROLDARK | Represents a Brush object that is the color of the shadow portion of a 3D element.
CONTROLDARKDARK | Represents a Brush object that is the color of the darkest portion of a 3D element.
CONTROLLIGHT | Represents a Brush object that is the color of the highlighted portion of a 3D element.
CONTROLLIGHTLIGHT | Represents a Brush object that is the color of the lightest part of a 3D element.
DESKTOP | Represents a Brush object that is the current color of the desktop.
HALFTONE | Represents a Brush object that is the color of a standard halftone brush.
HIGHLIGHT | Represents a Brush object that is the color of the background of highlighted elements.
HOLLOW | Represents a hollow brush.
HOTTRACK | Represents a Brush object that is the color used to indicate hot tracking.
INACTIVEBORDER | Represents a Brush object that is the color of an inactive window border.
INACTIVECAPTION | Represents a Brush object that is the color of an inactive caption bar.
INFO | Represents a Brush object that is the color of the background of an information ToolTip.
MENU | Represents a Brush object that is the color of the menu background.
NULL | Represents a null brush.
SCROLLBAR | Represents a Brush object that is the color of a scrollbar background.
WINDOW | Represents a Brush object that is the color of the window background.


 Brush.ACTIVEBORDER

Brush.ACTIVEBORDER

Represents a Brush object that is the color of the active window border.

Syntax

public static final Brush ACTIVEBORDER;

Remarks

The color represented by this setting is based on the current system settings. If the system setting for this user interface element is modified, this object automatically reflects the new setting.


 Brush.ACTIVECAPTION

Brush.ACTIVECAPTION

Represents a Brush object that is the color of the active caption bar.

Syntax

public static final Brush ACTIVECAPTION;

Remarks

The color represented by this setting is based on the current system settings. If the system setting for this user interface element is modified, this object automatically reflects the new setting.


 Brush.APPWORKSPACE

Brush.APPWORKSPACE

Represents a Brush object that is the color of the application workspace window.

Syntax

public static final Brush APPWORKSPACE;

Remarks

The color represented by this setting is based on the current system settings. If the system setting for this user interface element is modified, this object automatically reflects the new setting.


 Brush.CONTROL

Brush.CONTROL

Represents a Brush object that is the color of controls.

Syntax

public static final Brush CONTROL;

Remarks

The control color is the surface color for 3D elements.

The color represented by this setting is based on the current system settings. If the system setting for controls is modified, this object automatically reflects the new setting.


 Brush.CONTROLDARK

Brush.CONTROLDARK

Represents a Brush object that is the color of the shadow portion of a 3D element.

Syntax

public static final Brush CONTROLDARK;

Remarks

The color represented by this setting is based on the current system settings. If the system setting for this user interface element is modified, this object automatically reflects the new setting.


 Brush.CONTROLDARKDARK

Brush.CONTROLDARKDARK

Represents a Brush object that is the color of the darkest portion of a 3D element.

Syntax

public static final Brush CONTROLDARKDARK;

Remarks

The color represented by this setting is based on the current system settings. If the system setting for this user interface element is modified, this object automatically reflects the new setting.


 Brush.CONTROLLIGHT

Brush.CONTROLLIGHT

Represents a Brush object that is the color of the highlighted portion of a 3D element.

Syntax

public static final Brush CONTROLLIGHT;

Remarks

The color represented by this setting is based on the current system settings. If the system setting for this user interface element is modified, this object automatically reflects the new setting.


 Brush.CONTROLLIGHTLIGHT

Brush.CONTROLLIGHTLIGHT

Represents a Brush object that is the color of the lightest part of a 3D element.

Syntax

public static final Brush CONTROLLIGHTLIGHT;

Remarks

The color represented by this setting is based on the current system settings. If the system setting for this user interface element is modified, this object automatically reflects the new setting.


 Brush.DESKTOP

Brush.DESKTOP

Represents a Brush object that is the current color of the desktop.

Syntax

public static final Brush DESKTOP;

Remarks

The color represented by this setting is based on the current system settings. If the system setting for this user interface element is modified, this object automatically reflects the new setting.


 Brush.HALFTONE

Brush.HALFTONE

Represents a Brush object that is the color of a standard halftone brush.

Syntax

public static final Brush HALFTONE;


 Brush.HIGHLIGHT

Brush.HIGHLIGHT

Represents a Brush object that is the color of the background of highlighted elements.

Syntax

public static final Brush HIGHLIGHT;

Remarks

The color represented by this setting is based on the current system settings. If the system setting for this user interface element is modified, this object automatically reflects the new setting.


 Brush.HOLLOW

Brush.HOLLOW

Represents a hollow brush.

Syntax

public static final Brush HOLLOW;

Remarks

A hollow brush paints nothing.


 Brush.HOTTRACK

Brush.HOTTRACK

Represents a Brush object that is the color used to indicate hot tracking.

Syntax

public static final Brush HOTTRACK;

Remarks

The color represented by this setting is based on the current system settings. If the system setting for this user interface element is modified, this object automatically reflects the new setting.


 Brush.INACTIVEBORDER

Brush.INACTIVEBORDER

Represents a Brush object that is the color of an inactive window border.

Syntax

public static final Brush INACTIVEBORDER;

Remarks

The color represented by this setting is based on the current system settings. If the system setting for this user interface element is modified, this object automatically reflects the new setting.


 Brush.INACTIVECAPTION

Brush.INACTIVECAPTION

Represents a Brush object that is the color of an inactive caption bar.

Syntax

public static final Brush INACTIVECAPTION;

Remarks

The color represented by this setting is based on the current system settings. If the system setting for this user interface element is modified, this object automatically reflects the new setting.


 Brush.INFO

Brush.INFO

Represents a Brush object that is the color of the background of an information ToolTip.

Syntax

public static final Brush INFO;

Remarks

The color represented by this setting is based on the current system settings. If the system setting for this user interface element is modified, this object automatically reflects the new setting.


 Brush.MENU

Brush.MENU

Represents a Brush object that is the color of the menu background.

Syntax

public static final Brush MENU;

Remarks

The color represented by this setting is based on the current system settings. If the system setting for this user interface element is modified, this object automatically reflects the new setting.


 Brush.NULL

Brush.NULL

Represents a null brush.

Syntax

public static final Brush NULL;

Remarks

The behavior of a null brush is identical to that of a hollow brush.


 Brush.SCROLLBAR

Brush.SCROLLBAR

Represents a Brush object that is the color of a scrollbar background.

Syntax

public static final Brush SCROLLBAR;

Remarks

The color represented by this setting is based on the current system settings. If the system setting for this user interface element is modified, this object automatically reflects the new setting.


 Brush.WINDOW

Brush.WINDOW

Represents a Brush object that is the color of the window background.

Syntax

public static final Brush WINDOW;

Remarks

The color represented by this setting is based on the current system settings. If the system setting for this user interface element is modified, this object automatically reflects the new setting.


BrushStyle Class

Defines the brush style constants on which you can base Brush objects.

Enum
  |
  +--BrushStyle

package com.ms.wfc.ui

public class BrushStyle
extends Enum


 BrushStyle Methods

BrushStyle Methods

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value is a valid member of this class.


 BrushStyle.valid

BrushStyle.valid

Retrieves a boolean value that indicates whether a specified value is a valid member of this class.

Syntax

public static boolean valid( int value )

Parameters

value

A value to compare to the constants defined in this class.

Return Value

Returns true if value is a valid member of this class; otherwise, returns false.


 BrushStyle Fields

BrushStyle Fields

Fields | Description
BACKWARDDIAGONAL | Specifies a hatched brush consisting of backward diagonal lines.
CROSS | Specifies a hatched brush consisting of horizontal and vertical crossing lines.
DIAGONALCROSS | Specifies a hatched brush consisting of diagonal crossing lines.
FORWARDDIAGONAL | Specifies a hatched brush consisting of forward diagonal lines.
HOLLOW | Specifies a "hollow" brush. A hollow brush does not paint.
HORIZONTAL | Specifies a hatched brush consisting of horizontal lines.
PATTERN | Specifies a pattern brush. A pattern brush is one in which the pattern is based on a bitmap.
SOLID | Specifies a solid-colored brush.
VERTICAL | Specifies a hatched brush consisting of vertical lines.


 BrushStyle.BACKWARDDIAGONAL

BrushStyle.BACKWARDDIAGONAL

Specifies a hatched brush consisting of backward diagonal lines.

Syntax

public static final int BACKWARDDIAGONAL;


 BrushStyle.CROSS

BrushStyle.CROSS

Specifies a hatched brush consisting of horizontal and vertical crossing lines.

Syntax

public static final int CROSS;


 BrushStyle.DIAGONALCROSS

BrushStyle.DIAGONALCROSS

Specifies a hatched brush consisting of diagonal crossing lines.

Syntax

public static final int DIAGONALCROSS;


 BrushStyle.FORWARDDIAGONAL

BrushStyle.FORWARDDIAGONAL

Specifies a hatched brush consisting of forward diagonal lines.

Syntax

public static final int FORWARDDIAGONAL;


 BrushStyle.HOLLOW

BrushStyle.HOLLOW

Specifies a "hollow" brush. A hollow brush does not paint.

Syntax

public static final int HOLLOW;


 BrushStyle.HORIZONTAL

BrushStyle.HORIZONTAL

Specifies a hatched brush consisting of horizontal lines.

Syntax

public static final int HORIZONTAL;


 BrushStyle.PATTERN

BrushStyle.PATTERN

Specifies a pattern brush. A pattern brush is one in which the pattern is based on a bitmap.

Syntax

public static final int PATTERN;


 BrushStyle.SOLID

BrushStyle.SOLID

Specifies a solid-colored brush.

Syntax

public static final int SOLID;


 BrushStyle.VERTICAL

BrushStyle.VERTICAL

Specifies a hatched brush consisting of vertical lines.

Syntax

public static final int VERTICAL;


Button Class

Encapsulates a Windows button control.

Component
  |
  +--Control
    |
    +--Button

package com.ms.wfc.ui

public class Button
extends Control
implements IButtonControl

Remarks

To set the text on a button, use the setText method. To allow the user to choose the button by pressing ENTER, pass the name of the button to the setAcceptButton method of the form that contains the button. To allow the user to choose the button by pressing ESC, pass the button name to the setCancelButton method of the form that contains the button. To specify the value that the form that containing the button will return, use the setDialogResult method.


 Button Methods

Button Methods

Constructors | Description
Button | Creates a Button control.

Methods | Description
getBackColor | Retrieves the button's current background color.
getBrush | Retrieves the brush used to display this control.
getDialogResult | Retrieves the dialog box result generated by clicking the button.
getForeColor | Retrieves the button's current foreground color.
notifyDefault | Notifies the button whether it is the default button so that it can adjust its appearance accordingly.
performClick | Generates a click event for the button, simulating a click by a user.
setDialogResult | Sets the dialog box result generated by clicking the button.


 Button.Button

Button.Button

Creates a Button control.

Syntax

public Button()

Remarks

By default, the button has no caption. If you create a button using the Forms Designer, the button caption is set to the button name by default. To set the text on a button programmatically, use the setText method.


 Button.getBackColor

Button.getBackColor

Retrieves the button's current background color.

Syntax

public final Color getBackColor()

Return Value

Returns a Color object that represents the button's current background color.

Remarks

Because the button color is read-only, this method always returns the value of the CONTROL constant, which specifies the system backcolor for buttons.


 Button.getBrush

Button.getBrush

Retrieves the brush used to display this control.

Syntax

public final Brush getBrush()

Return Value

Returns a Brush object that represents the default system brush.

Remarks

Because a control's background color is read-only, this method always returns the default system brush.


 Button.getDialogResult

Button.getDialogResult

Retrieves the dialog box result generated by clicking the button.

Syntax

public final int getDialogResult()

Return Value

Returns an integer that specifies the current dialog box result. Possible return values include constants defined in the DialogResult class.

See Also setDialogResult


 Button.getForeColor

Button.getForeColor

Retrieves the button's current foreground color.

Syntax

public final Color getForeColor()

Return Value

Returns the button's current foreground color.

Remarks

Because the button's foreground color is read-only, this method always returns the value of the WINDOWTEXT constant, which specifies the system forecolor.


 Button.notifyDefault

Button.notifyDefault

Notifies the button whether it is the default button so that it can adjust its appearance accordingly.

Syntax

public void notifyDefault( boolean value )

Parameters

value

Set to true if the button has the appearance of the default button (if it has a thicker border than usual); otherwise, set to false.

Remarks

From the parent form, call the setAcceptButton to set the default button, and then call the notifyDefault method to allow the button to adjust its appearance.


 Button.performClick

Button.performClick

Generates a click event for the button, simulating a click by a user.

Syntax

public final void performClick()


 Button.setDialogResult

Button.setDialogResult

Sets the dialog box result generated by clicking the button.

Syntax

public final void setDialogResult( int value )

Parameters

value

A constant indicating the dialog box result that should be set when the button is clicked. If value is anything other than DialogResult.NONE, and if the parent form was displayed using the showDialog method, clicking the button closes the parent form and sets its dialogResult property to value. Values that represent common results are included in the DialogResult class. The default value is DialogResult.NONE.

See Also getDialogResult


ButtonState Class

Defines constants that specify the appearance of a button.

package com.ms.wfc.ui

public final class ButtonState


 ButtonState Methods

ButtonState Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 ButtonState.valid

ButtonState.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 ButtonState Fields

ButtonState Fields

Fields | Description
CHECKED | Specifies that the button has a shaded background.
FLAT | Specifies that the button is flat.
INACTIVE | Specifies that the button is disabled.
NORMAL | Specifies that the button is three-dimensional and not pressed.
PUSHED | Specifies that the button is pressed.


 ButtonState.CHECKED

ButtonState.CHECKED

Specifies that the button has a shaded background.

Syntax

public static final int CHECKED;

Remarks

This appearance is often used to show that a toggle button has been pressed.


 ButtonState.FLAT

ButtonState.FLAT

Specifies that the button is flat.

Syntax

public static final int FLAT;


 ButtonState.INACTIVE

ButtonState.INACTIVE

Specifies that the button is disabled.

Syntax

public static final int INACTIVE;


 ButtonState.NORMAL

ButtonState.NORMAL

Specifies that the button is three-dimensional and not pressed.

Syntax

public static final int NORMAL;


 ButtonState.PUSHED

ButtonState.PUSHED

Specifies that the button is pressed.

Syntax

public static final int PUSHED;

Remarks

This appearance is often used to when the mouse pointer is over a toggle button that has been pressed.


CaptionButton Class

Defines constants that specify the kind of caption button to draw.

Enum
  |
  +--CaptionButton

package com.ms.wfc.ui

public final class CaptionButton
extends Enum

Remarks

Caption buttons are the system buttons usually found on the right side of a form's title bar.


 CaptionButton Methods

CaptionButton Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 CaptionButton.valid

CaptionButton.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 CaptionButton Fields

CaptionButton Fields

Fields | Description
CLOSE | Specifies a Close button.
HELP | Specifies a Help button.
MAXIMIZE | Specifies a Maximize button.
MINIMIZE | Specifies a Minimize button.
RESTORE | Specifies a Restore button.


 CaptionButton.CLOSE

CaptionButton.CLOSE

Specifies a Close button.

Syntax

public static final int CLOSE;


 CaptionButton.HELP

CaptionButton.HELP

Specifies a Help button.

Syntax

public static final int HELP;


 CaptionButton.MAXIMIZE

CaptionButton.MAXIMIZE

Specifies a Maximize button.

Syntax

public static final int MAXIMIZE;


 CaptionButton.MINIMIZE

CaptionButton.MINIMIZE

Specifies a Minimize button.

Syntax

public static final int MINIMIZE;


 CaptionButton.RESTORE

CaptionButton.RESTORE

Specifies a Restore button.

Syntax

public static final int RESTORE;


CharacterCasing Class

Defines constants that specify the case of characters.

Enum
  |
  +--CharacterCasing

package com.ms.wfc.ui

public class CharacterCasing
extends Enum


 CharacterCasing Methods

CharacterCasing Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 CharacterCasing.valid

CharacterCasing.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 CharacterCasing Fields

CharacterCasing Fields

Fields | Description
LOWER | Specifies that all characters should be converted to lowercase.
NORMAL | Specifies that the case of characters should be left unchanged.
UPPER | Specifies that all characters should be converted to uppercase.


 CharacterCasing.LOWER

CharacterCasing.LOWER

Specifies that all characters should be converted to lowercase.

Syntax

public static final int LOWER;


 CharacterCasing.NORMAL

CharacterCasing.NORMAL

Specifies that the case of characters should be left unchanged.

Syntax

public static final int NORMAL;


 CharacterCasing.UPPER

CharacterCasing.UPPER

Specifies that all characters should be converted to uppercase.

Syntax

public static final int UPPER;


CheckBox Class

Encapsulates a Windows check box control, which is a labeled box that is checked or unchecked to turn an option on or off.

Component
  |
  +--Control
    |
    +--CheckBox

package com.ms.wfc.ui

public class CheckBox
extends Control

Remarks

Use the getChecked or getCheckState method to determine whether a check box is currently checked. Use the setChecked or setCheckState method to check or uncheck the check box.


 CheckBox Methods

CheckBox Methods

Constructors | Description
CheckBox | Creates a CheckBox control.

Methods | Description
addOnCheckedChanged | Assigns a delegate to the checkedChanged event.
addOnCheckStateChanged | Assigns a delegate to the checkStateChanged event.
getAppearance | Retrieves a value that indicates whether the check box will have the appearance of a command button rather than the usual appearance of a check box.
getAutoCheck | Retrieves a boolean value that indicates whether the user can change the value of the check box by clicking it or whether the value can only be changed programmatically.
getChecked | Retrieves a boolean value that indicates whether the check box is checked.
getCheckState | Retrieves a value that indicates whether a check box is checked, unchecked, or indeterminate.
getGroupValue | Retrieves a value that indicates which check boxes in a check box group are checked.
getTextAlign | Retrieves a value that indicates where the text for the CheckBox control is positioned relative to the checkable box.
getThreeState | Retrieves a boolean value that indicates whether the check box supports a third, indeterminate state in addition to the checked and unchecked states.
onCheckedChanged | Triggers the checkedChanged event.
onCheckStateChanged | Triggers the checkStateChanged event.
onClick | Triggers the click event.
removeOnCheckedChanged | Removes the delegate that is assigned to the checkedChanged event.
removeOnCheckStateChanged | Removes the delegate that is assigned to the checkStateChanged event.
setAppearance | Sets a value that indicates whether the check box will have the appearance of a command button rather than the usual appearance of a check box.
setAutoCheck | Sets a boolean value that indicates whether the user can change the value of the check box by clicking it or whether the value can only be changed programmatically.
setChecked | Sets a boolean value that indicates whether the check box is checked.
setCheckState | Sets a value that indicates whether a check box is checked, unchecked, or indeterminate.
setGroupValue | Sets a value that indicates which check boxes in a check box group are checked.
setTextAlign | Sets a value that indicates where the text for the CheckBox control is positioned relative to the checkable box.
setThreeState | Sets a boolean value that indicates whether the check box supports a third, indeterminate state in addition to the checked and unchecked states.


 CheckBox.addOnCheckedChanged

CheckBox.addOnCheckedChanged

Assigns a delegate to the checkedChanged event.

Syntax

public final void addOnCheckedChanged( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the checkedChanged event to that method in the Properties window. The checkedChanged event occurs when the value of the CheckBox control changes. For check boxes that support an indeterminate state in addition to a checked and a unchecked state, use the addOnCheckStateChanged method instead of the addOnCheckedChanged method.

See Also removeOnCheckedChanged


 CheckBox.addOnCheckStateChanged

CheckBox.addOnCheckStateChanged

Assigns a delegate to the checkStateChanged event.

Syntax

public final void addOnCheckStateChanged( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the checkStateChanged event to that method in the Properties window. The checkStateChanged event occurs when the value for the CheckBox control changes. For check boxes that support an indeterminate state in addition to a checked and a unchecked state, use this method instead of the addOnCheckedChanged method.

See Also removeOnCheckStateChanged


 CheckBox.CheckBox

CheckBox.CheckBox

Creates a CheckBox control.

Syntax

public CheckBox()

Remarks

By default, a check box is unchecked.


 CheckBox.getAppearance

CheckBox.getAppearance

Retrieves a value that indicates whether the check box will have the appearance of a command button rather than the usual appearance of a check box.

Syntax

public final int getAppearance()

Return Value

Returns an integer that specifies the current appearance of the check box. Possible return values are constants defined in the Appearance class. If the value is Appearance.NORMAL, the check box has the usual appearance of a check box. If the value is Appearance.BUTTON, the check box has the usual appearance of a command button.

Remarks

For a check box that looks like a command button, a pushed-in appearance is equivalent to being checked, a popped-up appearance is equivalent to being unchecked, and a shaded and pushed appearance is equivalent to being indeterminate.

See Also setAppearance


 CheckBox.getAutoCheck

CheckBox.getAutoCheck

Retrieves a boolean value that indicates whether the user can change the value of the check box by clicking it or whether the value can only be changed programmatically.

Syntax

public final boolean getAutoCheck()

Return Value

Returns true if the user can change the value of the check box by clicking it; returns false if the value of the control can only be changed programmatically.

See Also setAutoCheck


 CheckBox.getChecked

CheckBox.getChecked

Retrieves a boolean value that indicates whether the check box is checked.

Syntax

public final boolean getChecked()

Return Value

Returns true if the check box is checked or indeterminate; returns false if the check box is unchecked.

Remarks

If the threeState property of a check box is set to true, this method returns true for either checked or indeterminate states. If you want to distinguish between a checked and indeterminate state, use the getCheckState method to return the check box state.

See Also setChecked


 CheckBox.getCheckState

CheckBox.getCheckState

Retrieves a value that indicates whether a check box is checked, unchecked, or indeterminate.

Syntax

public final int getCheckState()

Return Value

Returns a value that indicates the current state of the check box. Possible return values are constants defined in the CheckState class. This method can return the CheckState.INDETERMINATE value only if the threeState property of the check box is set to true.

See Also setCheckState


 CheckBox.getGroupValue

CheckBox.getGroupValue

Retrieves a value that indicates which check boxes in a check box group are checked.

Syntax

public static int getGroupValue( Control group )

Parameters

group

The check box group you want to find the value for.

Return Value

Returns an integer that indicates which check boxes in the specified check box group are checked. This value contains bit flags that specify the checked state of each check box, with the value in the lowest bit indicating the state of the first check box in the tab order (one for checked or indeterminate states, zero for the unchecked state), the value in the second-lowest bit indicating the state of the second check box in the tab order, and so on. For example, if the second and fifth check boxes in a group are checked (or indeterminate), this method returns 18 (2 + 16).

See Also setGroupValue


 CheckBox.getTextAlign

CheckBox.getTextAlign

Retrieves a value that indicates where the text for the CheckBox control is positioned relative to the checkable box.

Syntax

public final int getTextAlign()

Return Value

Returns an integer that specifies the current position of the text relative to the box. Possible return values are constants defined in the LeftRightAlignment class. If the value is LeftRightAlignment.RIGHT (default), the text appears to the right of the box. If the value is LeftRightAlignment.LEFT, the text appears to the left of the box.

See Also setTextAlign


 CheckBox.getThreeState

CheckBox.getThreeState

Retrieves a boolean value that indicates whether the check box supports a third, indeterminate state in addition to the checked and unchecked states.

Syntax

public final boolean getThreeState()

Return Value

Returns true if the check box supports an indeterminate state (indicated by a shaded appearance); returns false if the check box supports only the checked and unchecked states.

Remarks

The indeterminate state, which is visually represented by a shaded appearance, has a value equal to the CheckState.INDETERMINATE constant.

See Also setThreeState


 CheckBox.onCheckedChanged

CheckBox.onCheckedChanged

Triggers the checkedChanged event.

Syntax

protected void onCheckedChanged( Event e )

Parameters

e

An Event object that provides information about the checkedChanged event.

Remarks

When overriding this method, call super.onCheckedChanged.

See Also addOnCheckedChanged


 CheckBox.onCheckStateChanged

CheckBox.onCheckStateChanged

Triggers the checkStateChanged event.

Syntax

protected void onCheckStateChanged( Event e )

Parameters

e

An Event object that provides information about the checkStateChanged event.

Remarks

When overriding this method, call super.onCheckStateChanged.

See Also addOnCheckStateChanged


 CheckBox.onClick

CheckBox.onClick

Triggers the click event.

Syntax

protected void onClick( Event e )

Parameters

e

An Event object that provides information about the click event.

Remarks

When overriding this method, call super.onClick.


 CheckBox.removeOnCheckedChanged

CheckBox.removeOnCheckedChanged

Removes the delegate that is assigned to the checkedChanged event.

Syntax

public final void removeOnCheckedChanged( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnCheckedChanged


 CheckBox.removeOnCheckStateChanged

CheckBox.removeOnCheckStateChanged

Removes the delegate that is assigned to the checkStateChanged event.

Syntax

public final void removeOnCheckStateChanged( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnCheckStateChanged


 CheckBox.setAppearance

CheckBox.setAppearance

Sets a value that indicates whether the check box will have the appearance of a command button rather than the usual appearance of a check box.

Syntax

public final void setAppearance( int value )

Parameters

value

An integer that specifies the current appearance of the check box. Possible values are constants defined in the Appearance class. If the value is set to Appearance.NORMAL, the check box has the usual appearance of a check box. If the value is set to Appearance.BUTTON, the check box has the usual appearance of a command button. The default value is Appearance.NORMAL.

Remarks

For a check box that looks like a command button, a pushed-in appearance is equivalent to being checked, a popped-up appearance is equivalent to being unchecked, and a shaded and pushed appearance is equivalent to being indeterminate.

See Also getAppearance


 CheckBox.setAutoCheck

CheckBox.setAutoCheck

Sets a boolean value that indicates whether the user can change the value of the check box by clicking it or whether the value can only be changed programmatically.

Syntax

public final void setAutoCheck( boolean value )

Parameters

value

Set to true if the user can change the value of the check box by clicking it; set to false if the value of the control can only be changed programmatically. The default value is true.

See Also getAutoCheck


 CheckBox.setChecked

CheckBox.setChecked

Sets a boolean value that indicates whether the check box is checked.

Syntax

public final void setChecked( boolean value )

Parameters

value

Set to true to check the check box; set to false to uncheck the check box. The default value is false.

Remarks

You cannot use this method to set the check box to an indeterminate state. To set the check box to an indeterminate state, use the setCheckState method.

See Also getChecked


 CheckBox.setCheckState

CheckBox.setCheckState

Sets a value that indicates whether a check box is checked, unchecked, or indeterminate.

Syntax

public final void setCheckState( int value )

Parameters

value

A value that indicates the state of the check box. Possible values are constants defined in the CheckState class. To use this method to set the check box to an indeterminate state, set the threeState property of the check box to true. The default value is CheckState.UNCHECKED.

Exceptions

WFCInvalidEnumException thrown if the specified value is not a valid CheckState constant.

See Also getCheckState


 CheckBox.setGroupValue

CheckBox.setGroupValue

Sets a value that indicates which check boxes in a check box group are checked.

Syntax

public static void setGroupValue( Control group, int value )

Parameters

group

The check box group control that contains the check boxes you want to set the state for.

value

An integer that indicates which check boxes in the specified check box group are checked. This value contains bit flags that specify the checked state of each check box, with the value in the lowest bit indicating the state of the first check box in the tab order (one for checked or indeterminate states, zero for the unchecked state), the value in the second-lowest bit indicating the state of the second check box in the tab order, and so on. For example, to check the second and fifth check boxes in a group, pass a value of 18 (2 + 16) as the value parameter to this method. You cannot use this method to set check boxes to the indeterminate state.

See Also getGroupValue


 CheckBox.setTextAlign

CheckBox.setTextAlign

Sets a value that indicates where the text for the CheckBox control is positioned relative to the checkable box.

Syntax

public final void setTextAlign( int value )

Parameters

value

An integer that specifies the current position of the text relative to the box. Possible values are constants defined in the LeftRightAlignment class. If the value is LeftRightAlignment.RIGHT (default), the text appears to the right of the box. If the value is LeftRightAlignment.LEFT, the text appears to the left of the box. The default value is LeftRightAlignment.RIGHT.

Exceptions

WFCInvalidEnumException thrown if the specified value is not a valid LeftRightAlignment constant.

See Also getTextAlign


 CheckBox.setThreeState

CheckBox.setThreeState

Sets a boolean value that indicates whether the check box supports a third, indeterminate state in addition to the checked and unchecked states.

Syntax

public final void setThreeState( boolean value )

Parameters

value

Set to true to allow the check box to support an indeterminate state (indicated by a shaded appearance); set to false to allow the check box to support only the checked and unchecked states. The default value is false.

Remarks

The third state, which represents an indeterminate state, has a value equal to the CheckState.INDETERMINATE constant.

See Also getThreeState


CheckedListBox Class

Represents a checked list box control, which is a list box containing items accompanied by check boxes that can be checked or unchecked.

Component
  |
  +--Control
    |
    +--ListBox
      |
      +--CheckedListBox

package com.ms.wfc.ui

public class CheckedListBox
extends ListBox


 CheckedListBox Methods

CheckedListBox Methods

Constructors | Description
CheckedListBox | Creates a CheckedListBox control.

Methods | Description
addItem | Adds an item to the checked list box.
addOnItemCheck | Assigns a delegate to the itemCheck event.
getCheckedIndices | Retrieves an array that contains the zero-based indices of all items with checked check boxes.
getCheckOnClick | Retrieves a boolean value indicating whether clicking an item in the list both selects the item and toggles the state of its check box or whether one click selects the item and a second click toggles the check box state.
getItemCheck | Retrieves a value indicating whether a check box for the specified item is checked, unchecked, or indeterminate.
getItemChecked | Retrieves a boolean value indicating whether the check box for the specified item is checked.
getThreeDCheckBoxes | Retrieves a boolean value indicating whether the check boxes for the list items have a three-dimensional appearance.
removeAll | Removes all items from the list box.
removeOnItemCheck | Removes the delegate that is assigned to the itemCheck event.
setCheckOnClick | Sets a boolean value indicating whether clicking an item in the list both selects the item and toggles the state of its check box or whether one click selects the item and a second click toggles the check box state.
setItemCheck | Sets a value indicating the check state of the a check box for the specified item.
setSelectionMode | Sets a value indicating whether the user can select items in the list box.
setThreeDCheckBoxes | Sets a boolean value indicating whether the check boxes for the list items have a three-dimensional appearance.


 CheckedListBox.addItem

CheckedListBox.addItem

Adds an item to the checked list box.

Syntax

public final int addItem( Object item, int check )

public final int addItem( Object item, boolean checked )

Parameters

item

An object (generally a String object) whose toString method returns the string you want to display in the checked list box.

check

An integer indicating whether the check box for the item is initially checked, unchecked, or indeterminate. Possible values are constants defined in the CheckState class.

checked

Set to true to add an item whose check box is initially checked; set to false to add an item whose check box is initially unchecked. To specify that a check box is initially indeterminate (shaded), use the syntax that takes the check parameter instead of the checked parameter.

Return Value

Returns the zero-based index of the added item.


 CheckedListBox.addOnItemCheck

CheckedListBox.addOnItemCheck

Assigns a delegate to the itemCheck event.

Syntax

public final void addOnItemCheck( ItemCheckEventHandler value )

Parameters

value

The ItemCheckEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the itemCheck event to that method in the Properties window. The itemCheck event occurs when the check state of an item changes.

See Also removeOnItemCheck


 CheckedListBox.CheckedListBox

CheckedListBox.CheckedListBox

Creates a CheckedListBox control.

Syntax

public CheckedListBox()


 CheckedListBox.getCheckedIndices

CheckedListBox.getCheckedIndices

Retrieves an array that contains the zero-based indices of all items with checked check boxes.

Syntax

public final int [] getCheckedIndices()

Return Value

Returns an array that contains the zero-based indices of all items with checked check boxes. Items with indeterminate (shaded) check boxes are included in the returned array. If there are no items in the checked list box that have checked check boxes, this method returns an empty array.


 CheckedListBox.getCheckOnClick

CheckedListBox.getCheckOnClick

Retrieves a boolean value indicating whether clicking an item in the list both selects the item and toggles the state of its check box or whether one click selects the item and a second click toggles the check box state.

Syntax

public final boolean getCheckOnClick()

Return Value

Returns true if a single click both selects the item and toggles its check box; returns false if one click is required to select the item and a second click is required to toggle its check box.

See Also setCheckOnClick


 CheckedListBox.getItemCheck

CheckedListBox.getItemCheck

Retrieves a value indicating whether a check box for the specified item is checked, unchecked, or indeterminate.

Syntax

public final int getItemCheck( int index )

Parameters

index

The zero-based index of the item whose check box state you want to examine.

Return Value

Returns a value that indicates the current state of the check box. Possible return values are constants defined in the CheckState class.

Exceptions

WFCInvalidArgumentException thrown if the specified index is not valid.

See Also setItemCheck


 CheckedListBox.getItemChecked

CheckedListBox.getItemChecked

Retrieves a boolean value indicating whether the check box for the specified item is checked.

Syntax

public final boolean getItemChecked( int index )

Parameters

index

The zero-based index of the item whose check box state you want to check.

Return Value

Returns true if the check box for the specified item is checked or indeterminate; otherwise, returns false.


 CheckedListBox.getThreeDCheckBoxes

CheckedListBox.getThreeDCheckBoxes

Retrieves a boolean value indicating whether the check boxes for the list items have a three-dimensional appearance.

Syntax

public final boolean getThreeDCheckBoxes()

Return Value

Returns true if the check boxes for the list items have a three-dimensional appearance; returns false if the check boxes have a flat appearance.

See Also setThreeDCheckBoxes


 CheckedListBox.removeAll

CheckedListBox.removeAll

Removes all items from the list box.

Syntax

public final void removeAll()

Remarks

When you remove items from the list box, all information about the deleted items is lost.


 CheckedListBox.removeOnItemCheck

CheckedListBox.removeOnItemCheck

Removes the delegate that is assigned to the itemCheck event.

Syntax

public final void removeOnItemCheck( ItemCheckEventHandler value )

Parameters

value

The ItemCheckEventHandler delegate to be removed.

See Also addOnItemCheck


 CheckedListBox.setCheckOnClick

CheckedListBox.setCheckOnClick

Sets a boolean value indicating whether clicking an item in the list both selects the item and toggles the state of its check box or whether one click selects the item and a second click toggles the check box state.

Syntax

public final void setCheckOnClick( boolean value )

Parameters

value

Set to true if a single click both selects the item and toggles its check box; set to false if one click is required to select the item and a second click is required to toggle its check box. The default value is false.

See Also getCheckOnClick


 CheckedListBox.setItemCheck

CheckedListBox.setItemCheck

Sets a value indicating the check state of the a check box for the specified item.

Syntax

public final void setItemCheck( int index, int value )

public final void setItemCheck( int index, boolean value )

Parameters

index

The zero-based index of the item whose check box state you want to set.

value

A value that indicates the current state of the check box. You can pass either a constant defined in the CheckState class or a boolean value. If you pass a boolean value, specify true to check the check box, and specify false to uncheck it.

Exceptions

WFCInvalidArgumentException thrown if the specified index is not valid or if the specified value is not a valid CheckState constant.

See Also getItemCheck


 CheckedListBox.setSelectionMode

CheckedListBox.setSelectionMode

Sets a value indicating whether the user can select items in the list box.

Syntax

public final void setSelectionMode( int value )

Parameters

value

A value indicating whether the user can select items in the list box. Possible values are SelectionMode.ONE and SelectionMode.NONE. The default value is SelectionMode.ONE .

Exceptions

WFCInvalidEnumException thrown if the specified value is not either SelectionMode.ONE or SelectionMode.NONE.


 CheckedListBox.setThreeDCheckBoxes

CheckedListBox.setThreeDCheckBoxes

Sets a boolean value indicating whether the check boxes for the list items have a three-dimensional appearance.

Syntax

public final void setThreeDCheckBoxes( boolean threed )

Parameters

threed

Set to true if the check boxes for the list items have a three-dimensional appearance; set to false if the check boxes have a flat appearance. The default value is true.

See Also getThreeDCheckBoxes


CheckState Class

Defines constants that specify the appearance of a control that can be checked and unchecked.

Enum
  |
  +--CheckState

package com.ms.wfc.ui

public class CheckState
extends Enum


 CheckState Methods

CheckState Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 CheckState.valid

CheckState.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 CheckState Fields

CheckState Fields

Fields | Description
CHECKED | Specifies that the control is checked.
INDETERMINATE | Specifies that the control is indeterminate (not checked or unchecked). An indeterminate control generally has a shaded appearance.
UNCHECKED | Specifies that the control is unchecked.


 CheckState.CHECKED

CheckState.CHECKED

Specifies that the control is checked.

Syntax

public static final int CHECKED;


 CheckState.INDETERMINATE

CheckState.INDETERMINATE

Specifies that the control is indeterminate (not checked or unchecked). An indeterminate control generally has a shaded appearance.

Syntax

public static final int INDETERMINATE;


 CheckState.UNCHECKED

CheckState.UNCHECKED

Specifies that the control is unchecked.

Syntax

public static final int UNCHECKED;


Color Class

Describes the color of a screen element, using a red-green-blue (RGB) or hue-saturation-brightness (HSB) triplet, a cyan-yellow-magenta-black (CYMK) quadruplet, or a system color constant (the color of a command button, for example).

package com.ms.wfc.ui

public class Color
implements IConstructable

Remarks

To determine the appearance of Color constants with which you are unfamiliar (for example, Color.CONTROLDARKDARK), you can display a form and select the color as the background color of the form.


 Color Methods

Color Methods

Constructors | Description
Color | Creates a Color object.

Methods | Description
equals | Retrieves a boolean value that indicates whether the specified object is equivalent to this Color object.
fromCMYK | Creates a new Color object based on the specified color values.
fromHSB | Creates a new Color object based on the specified hue, saturation, and brightness values.
getBlack | Returns the level of black in this color, using a CMYK color system.
getBlue | Retrieves the blue component of the color.
getBrightness | Retrieves the HSB brightness for this color.
getConstructorArgs | Retrieves an array of ConstructorArg objects that describe the data types and values needed to persist this object.
getCyan | Retrieves the level of cyan in this color, using a CMYK color system.
getGreen | Retrieves the green component of the color.
getHue | Retrieves the HSB hue value for this color.
getMagenta | Retrieves the level of magenta in this color, using a CMYK color system.
getRed | Retrieves the red component of the color.
getRGB | Retrieves the entire RGB triplet for the color.
getSaturation | Retrieves the HSB saturation for this color.
getValue | Retrieves the current value of this Color object.
getYellow | Retrieves the level of yellow in this color, using a CMYK color system.
hashCode | Retrieves a hash code for this object for use with various sorting and hash table objects.
toString | Retrieves a string description of the Color object.


 Color.Color

Color.Color

Creates a Color object.

Syntax

public Color( int value )

public Color( int red, int green, int blue )

Parameters

value

A system color value.

red

The red component of the color.

green

The green component of the color.

blue

The blue component of the color.


 Color.equals

Color.equals

Retrieves a boolean value that indicates whether the specified object is equivalent to this Color object.

Syntax

public boolean equals( Object obj )

Parameters

obj

The object to compare to this one.

Return Value

Returns true if the objects are equivalent; otherwise, returns false.

Remarks

If the object you specify is not a Color object, or the colors do not match, this method returns false.


 Color.fromCMYK

Color.fromCMYK

Creates a new Color object based on the specified color values.

Syntax

public static final Color fromCMYK( int cyan, int magenta, int yellow, int black )

Parameters

cyan

The level of cyan in the color.

magenta

The level of magenta in the color.

yellow

The level of yellow in the color.

black

The level of black in the color.

Return Value

Returns the new Color object.

Remarks

If any of the color levels specified exceed 255, the color is reduced to 255.

See Also fromHSB


 Color.fromHSB

Color.fromHSB

Creates a new Color object based on the specified hue, saturation, and brightness values.

Syntax

public static final Color fromHSB( float hue, float saturation, float brightness )

Parameters

hue

The hue of the color. This value is represented as an angle that extends from 0 to 360, where red is at 0. As the angle increases, the hue flows from red to yellow, green, cyan, blue, and magenta, and back to red.

saturation

The saturation level of the given hue. Zero represents the least saturated hue (gray), while one is the most saturated.

brightness

The overall brightness of the color value. Zero represents black and one represents white.

Return Value

Returns the new Color object.

See Also fromCMYK


 Color.getBlack

Color.getBlack

Returns the level of black in this color, using a CMYK color system.

Syntax

public int getBlack()

Return Value

Returns an integer that indicates the level of black in the color.

See Also getCyan, getMagenta, getYellow


 Color.getBlue

Color.getBlue

Retrieves the blue component of the color.

Syntax

public int getBlue()

Return Value

Returns the blue component of the color.

Remarks

This method works identically for Color objects based on system colors or on RGB triplets.

See Also getGreen, getRed


 Color.getBrightness

Color.getBrightness

Retrieves the HSB brightness for this color.

Syntax

public float getBrightness()

Return Value

Returns the color's brightness, where 0 represents black and 1 represents white.

See Also getHue, getSaturation


 Color.getConstructorArgs

Color.getConstructorArgs

Retrieves an array of ConstructorArg objects that describe the data types and values needed to persist this object.

Syntax

public ConstructorArg[] getConstructorArgs()

Return Value

Returns an array of ConstructorArg objects.


 Color.getCyan

Color.getCyan

Retrieves the level of cyan in this color, using a CMYK color system.

Syntax

public int getCyan()

Return Value

Returns the level of cyan in this color.

See Also getBlack, getMagenta, getYellow


 Color.getGreen

Color.getGreen

Retrieves the green component of the color.

Syntax

public int getGreen()

Return Value

Returns the green component of the color.

Remarks

This method works identically for Color objects based on system colors or on RGB triplets.

See Also getBlue, getRed


 Color.getHue

Color.getHue

Retrieves the HSB hue value for this color.

Syntax

public float getHue()

Return Value

Returns the hue, in degrees.

See Also getBrightness, getSaturation


 Color.getMagenta

Color.getMagenta

Retrieves the level of magenta in this color, using a CMYK color system.

Syntax

public int getMagenta()

Return Value

Returns the level of magenta in this color.

See Also getBlack, getCyan, getYellow


 Color.getRed

Color.getRed

Retrieves the red component of the color.

Syntax

public int getRed()

Return Value

Returns the red component of the color.

Remarks

This method works identically for Color objects based on system colors or on RGB triplets.

See Also getBlue, getGreen


 Color.getRGB

Color.getRGB

Retrieves the entire RGB triplet for the color.

Syntax

public int getRGB()

Return Value

Returns the RGB triplet value.

Remarks

This method works identically for Color objects based on system colors or on RGB triplets.


 Color.getSaturation

Color.getSaturation

Retrieves the HSB saturation for this color.

Syntax

public float getSaturation()

Return Value

Returns the saturation for this color, where 0 is gray, and 1 is the most saturated.

See Also getBrightness, getHue


 Color.getValue

Color.getValue

Retrieves the current value of this Color object.

Syntax

public int getValue()

Return Value

Returns the value of the Color object.

Remarks

If this Color object is a system color, the high byte of the returned value is non-zero and the value returned is generally usable only by OLE functions.


 Color.getYellow

Color.getYellow

Retrieves the level of yellow in this color, using a CMYK color system.

Syntax

public int getYellow()

Return Value

Returns the level of yellow in this color.

See Also getBlack, getCyan, getMagenta


 Color.hashCode

Color.hashCode

Retrieves a hash code for this object for use with various sorting and hash table objects.

Syntax

public int hashCode()

Return Value

Returns a hash code for this object.


 Color.toString

Color.toString

Retrieves a string description of the Color object.

Syntax

public String toString()

Return Value

Returns a string describing the Color object.


 Color Fields

Color Fields

Fields | Description
ACTIVEBORDER | Represents the color of an active window border.
ACTIVECAPTION | Represents the color of the background of an active title bar caption.
ACTIVECAPTIONTEXT | Represents the text color of an active title bar caption.
APPWORKSPACE | Represents the color of the application workspace.
AQUA | Represents the color aqua.
BLACK | Represents the color black.
BLUE | Represents the color blue.
BROWN | Represents the color brown.
CONTROL | Represents the color for controls.
CONTROLDARK | Represents the shadow part of a 3D element.
CONTROLDARKDARK | Represents the darkest part of a 3D element.
CONTROLLIGHT | Represents the highlight part of a 3D element.
CONTROLLIGHTLIGHT | Represents the lightest part of a 3D element.
CONTROLTEXT | Represents the color of control text.
CYAN | Represents the color cyan.
DARKGRAY | Represents the color dark gray.
DESKTOP | Represents the current desktop color.
GRAY | Represents the color gray.
GRAYTEXT | Represents the color of gray disabled text.
GREEN | Represents the color green.
HIGHLIGHT | Represents the color of highlighted objects.
HIGHLIGHTTEXT | Represents the color of highlighted text.
HOTTRACK | Represents the hottrack color.
INACTIVEBORDER | Represents the color of an inactive window's border.
INACTIVECAPTION | Represents the color of the background of an inactive title bar caption.
INACTIVECAPTIONTEXT | Represents the color of caption text displayed in the title bar of an inactive window.
INFO | Represents the background color of an information ToolTip.
INFOTEXT | Represents the color of information ToolTip text.
LIGHTGRAY | Represents the color light gray.
MAGENTA | Represents the color magenta.
MENU | The color for menus.
MENUTEXT | The color for menu text.
ORANGE | Represents the color orange.
PURPLE | Represents the color purple.
RED | Represents the color red.
SCROLLBAR | Represents the color of the area of a scroll bar not covered by the thumb button.
WHITE | Represents the color white.
WINDOW | Represents the color of a window.
WINDOWFRAME | Represents the color of a window frame.
WINDOWTEXT | Represents the color of window text.
YELLOW | Represents the color yellow.


 Color.ACTIVEBORDER

Color.ACTIVEBORDER

Represents the color of an active window border.

Syntax

public static final Color ACTIVEBORDER;


 Color.ACTIVECAPTION

Color.ACTIVECAPTION

Represents the color of the background of an active title bar caption.

Syntax

public static final Color ACTIVECAPTION;


 Color.ACTIVECAPTIONTEXT

Color.ACTIVECAPTIONTEXT

Represents the text color of an active title bar caption.

Syntax

public static final Color ACTIVECAPTIONTEXT;


 Color.APPWORKSPACE

Color.APPWORKSPACE

Represents the color of the application workspace.

Syntax

public static final Color APPWORKSPACE;

Remarks

The application workspace is the area in a multiple-document view that is not occupied by documents.


 Color.AQUA

Color.AQUA

Represents the color aqua.

Syntax

public static final Color AQUA;


 Color.BLACK

Color.BLACK

Represents the color black.

Syntax

public static final Color BLACK;


 Color.BLUE

Color.BLUE

Represents the color blue.

Syntax

public static final Color BLUE;


 Color.BROWN

Color.BROWN

Represents the color brown.

Syntax

public static final Color BROWN;


 Color.CONTROL

Color.CONTROL

Represents the color for controls.

Syntax

public static final Color CONTROL;


 Color.CONTROLDARK

Color.CONTROLDARK

Represents the shadow part of a 3D element.

Syntax

public static final Color CONTROLDARK;


 Color.CONTROLDARKDARK

Color.CONTROLDARKDARK

Represents the darkest part of a 3D element.

Syntax

public static final Color CONTROLDARKDARK;


 Color.CONTROLLIGHT

Color.CONTROLLIGHT

Represents the highlight part of a 3D element.

Syntax

public static final Color CONTROLLIGHT;


 Color.CONTROLLIGHTLIGHT

Color.CONTROLLIGHTLIGHT

Represents the lightest part of a 3D element.

Syntax

public static final Color CONTROLLIGHTLIGHT;


 Color.CONTROLTEXT

Color.CONTROLTEXT

Represents the color of control text.

Syntax

public static final Color CONTROLTEXT;


 Color.CYAN

Color.CYAN

Represents the color cyan.

Syntax

public static final Color CYAN;


 Color.DARKGRAY

Color.DARKGRAY

Represents the color dark gray.

Syntax

public static final Color DARKGRAY;


 Color.DESKTOP

Color.DESKTOP

Represents the current desktop color.

Syntax

public static final Color DESKTOP;


 Color.GRAY

Color.GRAY

Represents the color gray.

Syntax

public static final Color GRAY;


 Color.GRAYTEXT

Color.GRAYTEXT

Represents the color of gray disabled text.

Syntax

public static final Color GRAYTEXT;


 Color.GREEN

Color.GREEN

Represents the color green.

Syntax

public static final Color GREEN;


 Color.HIGHLIGHT

Color.HIGHLIGHT

Represents the color of highlighted objects.

Syntax

public static final Color HIGHLIGHT;


 Color.HIGHLIGHTTEXT

Color.HIGHLIGHTTEXT

Represents the color of highlighted text.

Syntax

public static final Color HIGHLIGHTTEXT;


 Color.HOTTRACK

Color.HOTTRACK

Represents the hottrack color.

Syntax

public static final Color HOTTRACK;


 Color.INACTIVEBORDER

Color.INACTIVEBORDER

Represents the color of an inactive window's border.

Syntax

public static final Color INACTIVEBORDER;


 Color.INACTIVECAPTION

Color.INACTIVECAPTION

Represents the color of the background of an inactive title bar caption.

Syntax

public static final Color INACTIVECAPTION;


 Color.INACTIVECAPTIONTEXT

Color.INACTIVECAPTIONTEXT

Represents the color of caption text displayed in the title bar of an inactive window.

Syntax

public static final Color INACTIVECAPTIONTEXT;


 Color.INFO

Color.INFO

Represents the background color of an information ToolTip.

Syntax

public static final Color INFO;


 Color.INFOTEXT

Color.INFOTEXT

Represents the color of information ToolTip text.

Syntax

public static final Color INFOTEXT;


 Color.LIGHTGRAY

Color.LIGHTGRAY

Represents the color light gray.

Syntax

public static final Color LIGHTGRAY;


 Color.MAGENTA

Color.MAGENTA

Represents the color magenta.

Syntax

public static final Color MAGENTA;


 Color.MENU

Color.MENU

The color for menus.

Syntax

public static final Color MENU;


 Color.MENUTEXT

Color.MENUTEXT

The color for menu text.

Syntax

public static final Color MENUTEXT;


 Color.ORANGE

Color.ORANGE

Represents the color orange.

Syntax

public static final Color ORANGE;


 Color.PURPLE

Color.PURPLE

Represents the color purple.

Syntax

public static final Color PURPLE;


 Color.RED

Color.RED

Represents the color red.

Syntax

public static final Color RED;


 Color.SCROLLBAR

Color.SCROLLBAR

Represents the color of the area of a scroll bar not covered by the thumb button.

Syntax

public static final Color SCROLLBAR;


 Color.WHITE

Color.WHITE

Represents the color white.

Syntax

public static final Color WHITE;


 Color.WINDOW

Color.WINDOW

Represents the color of a window.

Syntax

public static final Color WINDOW;


 Color.WINDOWFRAME

Color.WINDOWFRAME

Represents the color of a window frame.

Syntax

public static final Color WINDOWFRAME;


 Color.WINDOWTEXT

Color.WINDOWTEXT

Represents the color of window text.

Syntax

public static final Color WINDOWTEXT;


 Color.YELLOW

Color.YELLOW

Represents the color yellow.

Syntax

public static final Color YELLOW;


ColorDialog Class

Represents a common dialog box that displays available colors along with controls that let the user define custom colors.

Component
  |
  +--CommonDialog
    |
    +--ColorDialog

package com.ms.wfc.ui

public class ColorDialog
extends CommonDialog

Remarks

Use the showDialog method to show the dialog box. Use the getColor method to get the color the user selected.

The following example opens a Color dialog box and sets the background color for the form to color the user selects:

private void btnColor_click(Object source, Event e)
{
    ColorDialog cd = new ColorDialog();
    cd.setAllowFullOpen(true); //enables the Define Custom Colors button
    cd.setColor(Color.RED);  //sets the color initially chosen in the dialog box to red
    int dlgResult = cd.showDialog();
    if (dlgResult == DialogResult.OK) {
        Color objColor = cd.getColor(); //gets the color the user chose
        this.setBackColor(objColor);  //sets the form background color to the chosen color
    }
}


 ColorDialog Methods

ColorDialog Methods

Constructors | Description
ColorDialog | Creates a ColorDialog control.

Methods | Description
getAllowFullOpen | Retrieves a boolean value indicating whether the user can use the dialog box to define custom colors.
getAnyColor | Retrieves a boolean value indicating whether the dialog box displays all available colors in the set of basic colors.
getColor | Retrieves a value indicating the color the user selected in the dialog box.
getCustomColors | Retrieves an array that represents the set of custom colors defined in the dialog box.
getFullOpen | Retrieves a boolean value indicating whether the controls used to create custom colors are visible when the dialog box is opened or if the user has to click the Define Custom Colors button to display these controls.
getShowHelp | Retrieves a boolean value indicating whether the dialog box contains a Help button.
getSolidColorOnly | Retrieves a boolean value indicating whether the dialog box displays only solid colors in the set of basic colors or whether it also offers colors that are composites of other colors.
reset | Resets all dialog box options, the last selected color, and the custom colors to their default values.
setAllowFullOpen | Sets a boolean value indicating whether the user can use the dialog box to define custom colors.
setAnyColor | Sets a boolean value indicating whether the dialog box displays all available colors in the set of basic colors.
setColor | Sets a value that indicates which color is selected by default when the dialog box is opened.
setCustomColors | Sets an array that represents the set of custom colors that are defined in the dialog box.
setFullOpen | Sets a boolean value indicating whether the controls used to create custom colors are visible when the dialog box is opened or if the user has to click the Define Custom Colors button to display these controls.
setShowHelp | Sets a boolean value indicating whether the dialog box contains a Help button.
setSolidColorOnly | Sets a boolean value indicating whether the dialog box displays only solid colors in the set of basic colors or whether it also offers colors that are composites of other colors.


 ColorDialog.ColorDialog

ColorDialog.ColorDialog

Creates a ColorDialog control.

Syntax

public ColorDialog()


 ColorDialog.getAllowFullOpen

ColorDialog.getAllowFullOpen

Retrieves a boolean value indicating whether the user can use the dialog box to define custom colors.

Syntax

public final boolean getAllowFullOpen()

Return Value

Returns true if the user can define custom colors; otherwise, returns false. If the user cannot define custom colors, the Define Custom Colors button in the dialog box is disabled, and the user cannot access the custom colors controls in the dialog box.

See Also setAllowFullOpen


 ColorDialog.getAnyColor

ColorDialog.getAnyColor

Retrieves a boolean value indicating whether the dialog box displays all available colors in the set of basic colors.

Syntax

public final boolean getAnyColor()

Return Value

Returns true if the dialog box displays all available colors in the set of basic colors; otherwise, returns false.

See Also setAnyColor


 ColorDialog.getColor

ColorDialog.getColor

Retrieves a value indicating the color the user selected in the dialog box.

Syntax

public final Color getColor()

Return Value

Returns a Color object that represents the color the user selected.

Remarks

If the user didn't select a color, this method returns zero (0), which is represents the color black. To distinguish between the case of the user choosing the color black and not choosing a color at all, be sure to check the return value of the showDialog method before checking the return value of the getColor method. For a code example using this method, see the ColorDialog control topic.

See Also setColor


 ColorDialog.getCustomColors

ColorDialog.getCustomColors

Retrieves an array that represents the set of custom colors defined in the dialog box.

Syntax

public final int[] getCustomColors()

Return Value

Returns an array of integers that represent the RGB values for colors that will appear in the custom colors area of the dialog box.

Remarks

Each integer in the color array contains three values in the range 0-255 that represent the red, green, and blue components of the color. The red value is stored in the high-order byte, the green value in the middle byte, and the blue value in the low-order byte.

See Also setCustomColors


 ColorDialog.getFullOpen

ColorDialog.getFullOpen

Retrieves a boolean value indicating whether the controls used to create custom colors are visible when the dialog box is opened or if the user has to click the Define Custom Colors button to display these controls.

Syntax

public final boolean getFullOpen()

Return Value

Returns true if the custom color controls are visible when the dialog box is first opened; returns false if the custom color controls are hidden until the user clicks Define Custom Colors.

Remarks

By default, the custom color controls are not visible when the dialog box is first opened.

See Also setFullOpen


 ColorDialog.getShowHelp

ColorDialog.getShowHelp

Retrieves a boolean value indicating whether the dialog box contains a Help button.

Syntax

public final boolean getShowHelp()

Return Value

Returns true if the dialog box includes a Help button; otherwise, returns false.

See Also setShowHelp


 ColorDialog.getSolidColorOnly

ColorDialog.getSolidColorOnly

Retrieves a boolean value indicating whether the dialog box displays only solid colors in the set of basic colors or whether it also offers colors that are composites of other colors.

Syntax

public final boolean getSolidColorOnly()

Return Value

Returns true if users can select only solid colors; returns false if the user can select composite colors in addition to solid colors.

See Also setSolidColorOnly


 ColorDialog.reset

ColorDialog.reset

Resets all dialog box options, the last selected color, and the custom colors to their default values.

Syntax

public final void reset()


 ColorDialog.setAllowFullOpen

ColorDialog.setAllowFullOpen

Sets a boolean value indicating whether the user can use the dialog box to define custom colors.

Syntax

public final void setAllowFullOpen( boolean value )

Parameters

value

Set to true if the user can define custom colors; otherwise, set to false. If the user cannot define custom colors, the Define Custom Colors button in the dialog box is disabled, and the user cannot access the custom colors controls in the dialog box. The default value is true.

Remarks

For a code example using this method, see the ColorDialog control topic.

See Also getAllowFullOpen


 ColorDialog.setAnyColor

ColorDialog.setAnyColor

Sets a boolean value indicating whether the dialog box displays all available colors in the set of basic colors.

Syntax

public final void setAnyColor( boolean value )

Parameters

value

Set to true if the dialog box displays all available colors in the set of basic colors; otherwise, set to false. The default value is false.

See Also getAnyColor


 ColorDialog.setColor

ColorDialog.setColor

Sets a value that indicates which color is selected by default when the dialog box is opened.

Syntax

public final void setColor( Color value )

Parameters

value

A Color object that represents the color that is selected by default when the dialog box is opened. The default value is black.

Remarks

For a code example using this method, see the ColorDialog control topic.

See Also getColor


 ColorDialog.setCustomColors

ColorDialog.setCustomColors

Sets an array that represents the set of custom colors that are defined in the dialog box.

Syntax

public final void setCustomColors( int[] value )

Parameters

value

An array of integers that represent the RGB values for colors that will appear on the custom colors area of the dialog box.

Remarks

Each integer in the color array contains three values in the range 0-255 that represent the red, green, and blue components of the color. The red value is stored in the high-order byte, the green value in the middle byte, and the blue value in the low-order byte. Use the Color.getRGB method to convert a Color object to an RGB integer.

See Also getCustomColors


 ColorDialog.setFullOpen

ColorDialog.setFullOpen

Sets a boolean value indicating whether the controls used to create custom colors are visible when the dialog box is opened or if the user has to click the Define Custom Colors button to display these controls.

Syntax

public final void setFullOpen( boolean value )

Parameters

value

Set to true if the custom color controls are visible when the dialog box is first opened; set to false if the custom color controls are hidden until the user clicks Define Custom Colors. The default value is false.

See Also getFullOpen


 ColorDialog.setShowHelp

ColorDialog.setShowHelp

Sets a boolean value indicating whether the dialog box contains a Help button.

Syntax

public final void setShowHelp( boolean value )

Parameters

value

Set to true if the dialog box includes a Help button; otherwise, set to false. The default value is false.

See Also getShowHelp


 ColorDialog.setSolidColorOnly

ColorDialog.setSolidColorOnly

Sets a boolean value indicating whether the dialog box displays only solid colors in the set of basic colors or whether it also offers colors that are composites of other colors.

Syntax

public final void setSolidColorOnly( boolean value )

Parameters

value

Set to true if users can select only solid colors; set to false if the user can select composite colors in addition to solid colors. The default value is false.

See Also getSolidColorOnly


ColumnClickEvent Class

Provides data for the columnClick event of the ListView object.

Event
  |
  +--ColumnClickEvent

package com.ms.wfc.ui

public class ColumnClickEvent
extends Event

Remarks

The columnClick event occurs when the user clicks one of the column headers that are visible in Report view. A ColumnClickEvent object specifies which column header was clicked.

For information about the WFC event model, see Handling Events in WFC.


 ColumnClickEvent Methods

ColumnClickEvent Methods

Constructors | Description
ColumnClickEvent | Creates a ColumnClickEvent object.


 ColumnClickEvent.ColumnClickEvent

ColumnClickEvent.ColumnClickEvent

Creates a ColumnClickEvent object.

Syntax

public ColumnClickEvent( int column )

Parameters

column

The zero-based index of the column header that was clicked.


 ColumnClickEvent Fields

ColumnClickEvent Fields

Fields | Description
column | Specifies the zero-based index of the column header that was clicked.


 ColumnClickEvent.column

ColumnClickEvent.column

Specifies the zero-based index of the column header that was clicked.

Syntax

public final int column;


ColumnClickEventHandler Delegate

Identifies the method that will handle the columnClick event of a ListView control.

package com.ms.wfc.ui

public multicast delegate
void ColumnClickEventHandler( Object sender, ColumnClickEvent e );

Remarks

The syntax of the ColumnClickEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a ColumnClickEvent object that provides the event data.

When you create a ColumnClickEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered. For more information about delegates, see Handling Events in WFC.


ColumnHeader Class

Encapsulates a column header in a ListView control.

Component
  |
  +--ColumnHeader

package com.ms.wfc.ui

public class ColumnHeader
extends Component
implements Cloneable

Remarks

A column header is an item in a list view control that contains heading text. Column headers can be added to a list view control using the addColumn, insertColumn, or setColumns method of the ListView control.


 ColumnHeader Methods

ColumnHeader Methods

Constructors | Description
ColumnHeader | Creates a ColumnHeader object.

Methods | Description
clone | Creates an identical copy of this ColumnHeader object that is not attached to any list view control.
dispose | Frees all resources allocated for this control.
getIndex | Retrieves the zero-based index of the column header.
getListView | Retrieves the ListView object associated with this column header.
getText | Retrieves the text associated with this column header.
getTextAlign | Retrieves a value that indicates the current text alignment setting for the column header.
getWidth | Retrieves the width of the column header.
setText | Sets the text associated with this column header.
setTextAlign | Sets a value that indicates the current text alignment setting for the column header.
setWidth | Sets the width of the column header.


 ColumnHeader.clone

ColumnHeader.clone

Creates an identical copy of this ColumnHeader object that is not attached to any list view control.

Syntax

public Object clone()

Return Value

Returns a copy of this ColumnHeader object.


 ColumnHeader.ColumnHeader

ColumnHeader.ColumnHeader

Creates a ColumnHeader object.

Syntax

public ColumnHeader()


 ColumnHeader.dispose

ColumnHeader.dispose

Frees all resources allocated for this control.

Syntax

public void dispose()

Remarks

You cannot call this method at run time. Any resources used by the control should be set up to be released when the control is disposed of through the garbage collection. When overriding this method, call super.dispose.


 ColumnHeader.getIndex

ColumnHeader.getIndex

Retrieves the zero-based index of the column header.

Syntax

public int getIndex()

Return Value

Returns the zero-based index of the column header. Returns -1 if the column header is not contained in a list view control.


 ColumnHeader.getListView

ColumnHeader.getListView

Retrieves the ListView object associated with this column header.

Syntax

public ListView getListView()

Return Value

Returns the ListView object associated with this column header.


 ColumnHeader.getText

ColumnHeader.getText

Retrieves the text associated with this column header.

Syntax

public String getText()

Return Value

Returns a String object that contains the text associated with this column header.

See Also setText


 ColumnHeader.getTextAlign

ColumnHeader.getTextAlign

Retrieves a value that indicates the current text alignment setting for the column header.

Syntax

public int getTextAlign()

Return Value

Returns a constant that specifies the text alignment setting for this column header. Possible return values are constants defined in the HorizontalAlignment class.

See Also setTextAlign


 ColumnHeader.getWidth

ColumnHeader.getWidth

Retrieves the width of the column header.

Syntax

public int getWidth()

Return Value

Returns the width, in pixels, of the column header.

See Also setWidth


 ColumnHeader.setText

ColumnHeader.setText

Sets the text associated with this column header.

Syntax

public void setText( String str )

Parameters

str

A String object that contains the text associated with this column header.

See Also getText


 ColumnHeader.setTextAlign

ColumnHeader.setTextAlign

Sets a value that indicates the current text alignment setting for the column header.

Syntax

public void setTextAlign( int value )

Parameters

value

A constant that specifies the text alignment setting for this column header. Possible return values are constants defined in the HorizontalAlignment class. The default value is HorizontalAlignment.LEFT.

Exceptions

WFCInvalidArgumentException thrown if the specified value is not a valid HorizontalAlignment constant.

See Also getTextAlign


 ColumnHeader.setWidth

ColumnHeader.setWidth

Sets the width of the column header.

Syntax

public void setWidth( int width )

Parameters

width

The width, in pixels, of the column header. Set to -1 if you want the width of the column header to adjust to the width of the text of the items in the column. Set to -2 if you want the width of the column header to adjust to the width of the text of the column header. The default value is 60.

See Also getWidth


ColumnHeaderStyle Class

Defines constants that specify the column header style.

Enum
  |
  +--ColumnHeaderStyle

package com.ms.wfc.ui

public class ColumnHeaderStyle
extends Enum


 ColumnHeaderStyle Methods

ColumnHeaderStyle Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 ColumnHeaderStyle.valid

ColumnHeaderStyle.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 ColumnHeaderStyle Fields

ColumnHeaderStyle Fields

Fields | Description
CLICKABLE | Specifies that the column headers work like buttons and can carry out an action, such as sorting, when clicked.
NONCLICKABLE | Specifies that the column headers do not work like buttons.
NONE | Specifies that the column header is not displayed in report view.


 ColumnHeaderStyle.CLICKABLE

ColumnHeaderStyle.CLICKABLE

Specifies that the column headers work like buttons and can carry out an action, such as sorting, when clicked.

Syntax

public static final int CLICKABLE;


 ColumnHeaderStyle.NONCLICKABLE

ColumnHeaderStyle.NONCLICKABLE

Specifies that the column headers do not work like buttons.

Syntax

public static final int NONCLICKABLE;


 ColumnHeaderStyle.NONE

ColumnHeaderStyle.NONE

Specifies that the column header is not displayed in report view.

Syntax

public static final int NONE;

Remarks

By default, columns have headers in report view.


ComboBox Class

Encapsulates the Windows combo box control.

Component
  |
  +--Control
    |
    +--ComboBox

package com.ms.wfc.ui

public class ComboBox
extends Control

Remarks

A combo box consists of a list box combined with a static text control or an edit control. The list box portion of the control can be displayed at all times or can drop down when the user clicks the drop-down arrow. You can add a set of items to a combo box at one time using the setItems method. Use the getSelectedIndex, getSelectedItem and getSelectedText methods to get information about the current selection in the combo box.


 ComboBox Methods

ComboBox Methods

Constructors | Description
ComboBox | Creates a ComboBox control.

Methods | Description
addItem | Adds an item to the combo box and returns the index of the new item.
addOnDrawItem | Assigns a delegate to the drawItem event.
addOnDropDown | Assigns a delegate to the dropDown event.
addOnMeasureItem | Assigns a delegate to the measureItem event.
addOnSelectedIndexChanged | Assigns a delegate to the selectedIndexChanged event.
addOnTextChanged | Assigns a delegate to the textChanged event.
beginUpdate | Maintains performance while items are added to the combo box one at a time by preventing the control from painting until the endUpdate method is called.
endUpdate | Resumes painting the ListBox control after painting is suspended by the beginUpdate method.
findString | Finds the first item in the combo box that starts with the specified string.
findStringExact | Finds the first item in the list that exactly matches the string specified in the s parameter.
getDrawMode | Retrieves a value indicating whether the system draws the combo box, whether the combo box owner draws the combo box with all items of equal height, or whether the combo box owner draws the combo box with items of variable height.
getDroppedDown | Retrieves a boolean value indicating whether the list box of a combo box is currently dropped down.
getFocused | Retrieves a boolean value indicating whether the control has the focus.
getIntegralHeight | Retrieves a boolean value indicating whether the combo box should resize to avoid showing partial items.
getItem | Retrieves the item at the specified zero-based index.
getItemCount | Retrieves the number of items in the combo box.
getItemHeight | Retrieves the height, in pixels, of an item in the combo box.
getItems | Retrieves an Object array containing all the items in the combo box.
getMaxDropDownItems | Retrieves the maximum number of items that can be displayed in the drop-down list box of the combo box.
getMaxLength | Retrieves the maximum number of characters the user can type into the edit control of a combo box.
getSelectedIndex | Retrieves the zero-based index of the currently selected item in the combo box.
getSelectedItem | Retrieves the currently selected item in the the combo box.
getSelectedText | Retrieves the text that is selected in the edit control of the combo box.
getSelectionEnd | Retrieves the zero-based index of the first character after the end of the current text selection in the edit control of the combo box.
getSelectionStart | Retrieves the zero-based index of the first character in the current text selection in the edit control of the combo box.
getSorted | Retrieves a boolean value indicating whether the items in the combo box are sorted alphabetically.
getStyle | Retrieves a value indicating the style of the combo box (whether the combo box has an edit control or a static text control and whether the list for the combo box is always visible or visible only when dropped down by the user).
insertItem | Adds an item to the combo box at the specified position.
onDrawItem | Triggers the drawItem event.
onDropDown | Triggers the dropDown event.
onMeasureItem | Triggers the measureItem event.
onSelectedIndexChanged | Triggers the selectedIndexChanged event.
onTextChanged | Triggers the textChanged event.
removeAll | Removes all items from the list box.
removeItem | Removes the specified item from the list box.
removeOnDrawItem | Removes the delegate that is assigned to the drawItem event.
removeOnDropDown | Removes the delegate that is assigned to the dropDown event.
removeOnMeasureItem | Removes the delegate that is assigned to the measureItem event.
removeOnSelectedIndexChanged | Removes the delegate that is assigned to the selectedIndexChanged event.
removeOnTextChanged | Removes the delegate that is assigned to the textChanged event.
select | Selects a range of text in the edit control of the combo box.
selectAll | Selects all the text in the edit control of the combo box.
setDrawMode | Sets a value indicating whether the system draws the combo box, whether the combo box owner draws the combo box with all items of equal height, or whether the combo box owner draws the combo box with items of variable height.
setDroppedDown | Sets a boolean value indicating whether the list box of the combo box is currently dropped down.
setIntegralHeight | Sets a boolean value indicating whether the combo box should resize to avoid showing partial items.
setItem | Allows you to replace the item at the specified position in the combo box.
setItemHeight | Sets the height, in pixels, of an item in the combo box.
setItems | Adds a set of items to the combo box.
setMaxDropDownItems | Sets the maximum number of items that can be displayed in the drop-down list box of the combo box.
setMaxLength | Sets the maximum number of characters the user can type into the edit control of a combo box.
setSelectedIndex | Selects an item in a combo box.
setSelectedItem | Selects the first occurrence of the specified item in a single-selection combo box, and returns the zero-based index of the item.
setSelectedText | Replaces the currently selected text in the edit control of the combo box with the specified text.
setSelectionEnd | Sets the end position of the text selection in the edit control of the combo box.
setSelectionStart | Sets the starting position of the text selection in the edit control of the combo box.
setSorted | Sets a boolean value indicating whether the items in the combo box are sorted alphabetically.
setStyle | Sets a value indicating the style of the combo box (whether the combo box has an edit control or a static text control, and whether the list for the combo box is always visible or visible only when dropped down by the user).


 ComboBox.addItem

ComboBox.addItem

Adds an item to the combo box and returns the index of the new item.

Syntax

public final int addItem( Object item )

Parameters

item

An object (generally a String object) whose toString method returns the string you want to display in the combo box.

Return Value

Returns the zero-based index of where the item was inserted.

Remarks

If the sorted property of the combo box is set to true, the item is inserted into the list alphabetically. Otherwise, the item is inserted at the end of the list. To insert an item into the combo box at a specific position, use the insertItem method. To add a set of items to the combo box at one time, use the setItems method.

See Also removeItem


 ComboBox.addOnDrawItem

ComboBox.addOnDrawItem

Assigns a delegate to the drawItem event.

Syntax

public final void addOnDrawItem( DrawItemEventHandler value )

Parameters

value

The DrawItemEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the drawItem event to that method in the Properties window. The drawItem event occurs when an item in an owner-drawn combo box needs to be repainted. The DrawItemEventHandler object passed to this event handler contains a Graphics object that is used to paint the item and a Rectangle object that represents the rectangle in which to paint the item.

See Also removeOnDrawItem


 ComboBox.addOnDropDown

ComboBox.addOnDropDown

Assigns a delegate to the dropDown event.

Syntax

public final void addOnDropDown( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the dropDown event to that method in the Properties window. The dropDown event occurs when the list box of a combo box is about to drop down. This event can occur only for combo boxes with drop-down lists.

See Also removeOnDropDown


 ComboBox.addOnMeasureItem

ComboBox.addOnMeasureItem

Assigns a delegate to the measureItem event.

Syntax

public final void addOnMeasureItem( MeasureItemEventHandler value )

Parameters

value

The MeasureItemEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the measureItem event to that method in the Properties window. The measureItem event occurs when an owner-drawn combo box with items of variable size is created and the sizes of the list items are queried. This event occurs only once for owner-drawn list boxes with items of fixed size. Use the setItemHeight method to set the item size for this type of list box.

See Also removeOnMeasureItem


 ComboBox.addOnSelectedIndexChanged

ComboBox.addOnSelectedIndexChanged

Assigns a delegate to the selectedIndexChanged event.

Syntax

public final void addOnSelectedIndexChanged( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the selectedIndexChanged event to that method in the Properties window. The selectedIndexChanged event occurs when the selection in the combo box changes. The selection can be changed by the user or programmatically.

See Also removeOnSelectedIndexChanged


 ComboBox.addOnTextChanged

ComboBox.addOnTextChanged

Assigns a delegate to the textChanged event.

Syntax

public final void addOnTextChanged( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the textChanged event to that method in the Properties window. The textChanged event occurs when the user takes an action that may have altered the text in the edit control of the combo box.

See Also removeOnTextChanged


 ComboBox.beginUpdate

ComboBox.beginUpdate

Maintains performance while items are added to the combo box one at a time by preventing the control from painting until the endUpdate method is called.

Syntax

public final void beginUpdate()

Remarks

The preferred way to insert items is to use the setItems method to add an array of items to a combo box at once. However, if you want to add items one at a time, use this method to prevent the control from painting during these operations. Call the endUpdate method when all the items have been added to the combo box so that the control can resume painting.


 ComboBox.ComboBox

ComboBox.ComboBox

Creates a ComboBox control.

Syntax

public ComboBox()

Remarks

By default, the combo box consists of an edit control and a drop-down list. To change the style of the combo box, use the setStyle method with one of the constants defined in the ComboBoxStyle class.


 ComboBox.endUpdate

ComboBox.endUpdate

Resumes painting the ListBox control after painting is suspended by the beginUpdate method.

Syntax

public final void endUpdate()


 ComboBox.findString

ComboBox.findString

Finds the first item in the combo box that starts with the specified string.

Syntax

public final int findString( String s )

public final int findString( String s, int startIndex )

Parameters

s

The string to match. Any string that begins with the specified characters is considered a match.

startIndex

The zero-based index of the item before the first item to be searched. Set to -1 to search from the beginning of the combo box.

Return Value

Returns the zero-based index of the item found; returns ListBox.NOMATCHES if no match is found.

Remarks

The search is not case sensitive.


 ComboBox.findStringExact

ComboBox.findStringExact

Finds the first item in the list that exactly matches the string specified in the s parameter.

Syntax

public final int findStringExact( String s )

public final int findStringExact( String s, int startIndex )

Parameters

s

The string to match exactly. Only strings that match this string in its entirety are considered matches.

startIndex

The zero-based index of the item before the first item to be searched. Set to -1 to search from the beginning of the combo box.

Return Value

Returns the zero-based index of the item found; returns ListBox.NOMATCHES if no match is found.

Remarks

The search is not case sensitive.


 ComboBox.getDrawMode

ComboBox.getDrawMode

Retrieves a value indicating whether the system draws the combo box, whether the combo box owner draws the combo box with all items of equal height, or whether the combo box owner draws the combo box with items of variable height.

Syntax

public final int getDrawMode()

Return Value

Returns an integer that specifies the how the current combo box is drawn. Possible return values are constants defined in the DrawMode class.

See Also setDrawMode


 ComboBox.getDroppedDown

ComboBox.getDroppedDown

Retrieves a boolean value indicating whether the list box of a combo box is currently dropped down.

Syntax

public final boolean getDroppedDown()

Return Value

Returns true if the list box of a combo box is dropped down; otherwise, returns false.

See Also setDroppedDown


 ComboBox.getFocused

ComboBox.getFocused

Retrieves a boolean value indicating whether the control has the focus.

Syntax

public boolean getFocused()

Return Value

Returns true if this control has the focus; otherwise, returns false.


 ComboBox.getIntegralHeight

ComboBox.getIntegralHeight

Retrieves a boolean value indicating whether the combo box should resize to avoid showing partial items.

Syntax

public final boolean getIntegralHeight()

Return Value

Returns true if Windows resizes the combo box so that it does not display partial items; returns false if the size of the combo box remains exactly the size specified by the application when it creates the combo box, allowing partial items to be shown.

See Also setIntegralHeight


 ComboBox.getItem

ComboBox.getItem

Retrieves the item at the specified zero-based index.

Syntax

public final Object getItem( int index )

Parameters

index

The index of the item to retrieve.

Return Value

Returns an object that represents the retrieved list-box item.

Exceptions

WFCInvalidArgumentException thrown if the specified index is not valid.

See Also setItem


 ComboBox.getItemCount

ComboBox.getItemCount

Retrieves the number of items in the combo box.

Syntax

public final int getItemCount()

Return Value

Returns the number of items in the combo box.

Remarks

Because the index for a list box is zero-based, the returned count is one greater than the index value of the last item in the list.


 ComboBox.getItemHeight

ComboBox.getItemHeight

Retrieves the height, in pixels, of an item in the combo box.

Syntax

public final int getItemHeight()

public final int getItemHeight( int index )

Parameters

index

The zero-based index of the item to return the height for.

Return Value

Returns the height, in pixels, of an item in the list.

Remarks

For combo boxes with items of variable height (combo boxes whose drawMode property is set to DrawMode.OWNERDRAWVARIABLE), use the index parameter to indicate which item you want a height returned for. If you call this method on a combo box with items of variable height without supplying the index parameter, this method returns the height of the first item in the combo box.

See Also setItemHeight


 ComboBox.getItems

ComboBox.getItems

Retrieves an Object array containing all the items in the combo box.

Syntax

public final Object[] getItems()

Return Value

Returns a zero-based array of objects. Items are placed in this array in the same positions as they appear in the combo box.

See Also setItems


 ComboBox.getMaxDropDownItems

ComboBox.getMaxDropDownItems

Retrieves the maximum number of items that can be displayed in the drop-down list box of the combo box.

Syntax

public final int getMaxDropDownItems()

Return Value

Returns the maximum number of items that can be displayed in the drop-down list box.

Remarks

Valid values are between 1 and 100.

See Also setMaxDropDownItems


 ComboBox.getMaxLength

ComboBox.getMaxLength

Retrieves the maximum number of characters the user can type into the edit control of a combo box.

Syntax

public final int getMaxLength()

Return Value

Returns the maximum number of characters that the user can type into the edit control of the combo box.

See Also setMaxLength


 ComboBox.getSelectedIndex

ComboBox.getSelectedIndex

Retrieves the zero-based index of the currently selected item in the combo box.

Syntax

public final int getSelectedIndex()

Return Value

Returns the zero-based index of the currently selected item in a combo box. If no item is currently selected, the return value is -1.

See Also setSelectedIndex


 ComboBox.getSelectedItem

ComboBox.getSelectedItem

Retrieves the currently selected item in the the combo box.

Syntax

public final Object getSelectedItem()

Return Value

Returns an object that represents the current selection in a combo box. Returns null if no item is currently selected or if the combo box style property is ComboBoxStyle.SIMPLE.

See Also setSelectedItem


 ComboBox.getSelectedText

ComboBox.getSelectedText

Retrieves the text that is selected in the edit control of the combo box.

Syntax

public final String getSelectedText()

Return Value

Returns the text that is selected in the edit control of the combo box. If the combo box has a static text control instead of an edit control, or if no text is selected in the edit control, this method returns an empty string.

See Also setSelectedText


 ComboBox.getSelectionEnd

ComboBox.getSelectionEnd

Retrieves the zero-based index of the first character after the end of the current text selection in the edit control of the combo box.

Syntax

public final int getSelectionEnd()

Return Value

Returns the zero-based index of the first character after the end of the current text selection in the edit control of the combo box. For example, if the third through fifth characters are selected in the edit control (with zero-based indexes 2 through 4), the getSelectionEnd method returns 5. If the cursor is in the edit control but no text is selected, both the getSelectionStart method and the getSelectionEnd method return the same value. For example, if the cursor is between the third and fourth characters, both methods return 3. If the edit control does not have the focus, this method returns zero (0). If the combo box has a static text control instead of an edit control, this method returns -1.

See Also setSelectionEnd


 ComboBox.getSelectionStart

ComboBox.getSelectionStart

Retrieves the zero-based index of the first character in the current text selection in the edit control of the combo box.

Syntax

public final int getSelectionStart()

Return Value

Returns the zero-based index of the first character in the current text selection in the edit control of the combo box. For example, if the third through fifth characters are selected in the edit control (with zero-based indexes 2 through 4), the getSelectionStart method returns 2. If the cursor is in the edit control but no text is selected, both the getSelectionStart method and the getSelectionEnd method return the same value. For example, if the cursor is between the third and fourth characters, both methods return 3. If the edit control does not have the focus, this method returns zero (0). If the combo box has a static text control instead of an edit control, this method returns -1.

See Also setSelectionStart


 ComboBox.getSorted

ComboBox.getSorted

Retrieves a boolean value indicating whether the items in the combo box are sorted alphabetically.

Syntax

public final boolean getSorted()

Return Value

Returns true if the list is sorted alphabetically; otherwise, returns false.

See Also setSorted


 ComboBox.getStyle

ComboBox.getStyle

Retrieves a value indicating the style of the combo box (whether the combo box has an edit control or a static text control and whether the list for the combo box is always visible or visible only when dropped down by the user).

Syntax

public final int getStyle()

Return Value

Returns an integer that specifies the style of the combo box. Possible return values are constants defined in the ComboBoxStyle class.

See Also setStyle


 ComboBox.insertItem

ComboBox.insertItem

Adds an item to the combo box at the specified position.

Syntax

public final void insertItem( int index, Object item )

Parameters

index

The zero-based position where you want to insert the item into the combo box.

item

The object (generally a String object) whose corresponding string you want to insert into the list. The string returned by the toString property of this object is inserted into the combo box.

Exceptions

WFCInvalidArgumentException thrown if the specified index is not valid.

Remarks

Items inserted into a combo box using this method are not sorted, even if the sorted property is set to true. To add an item that is inserted into the list alphabetically when the sorted property is set to true, use the addItem method.


 ComboBox.onDrawItem

ComboBox.onDrawItem

Triggers the drawItem event.

Syntax

protected void onDrawItem( DrawItemEvent e )

Parameters

e

A DrawItemEvent object that provides notification for the event.

Remarks

When overriding this method, call super.onDrawItem.

See Also addOnDrawItem


 ComboBox.onDropDown

ComboBox.onDropDown

Triggers the dropDown event.

Syntax

protected void onDropDown( Event e )

Parameters

e

An Event object that provides notification for the event.

Remarks

When overriding this method, call super.onDropDown.

See Also addOnDropDown


 ComboBox.onMeasureItem

ComboBox.onMeasureItem

Triggers the measureItem event.

Syntax

protected void onMeasureItem( MeasureItemEvent e )

Parameters

e

A MeasureItemEvent object that provides notification for the event.

Remarks

When overriding this method, call super.onMeasureItem.

See Also addOnMeasureItem


 ComboBox.onSelectedIndexChanged

ComboBox.onSelectedIndexChanged

Triggers the selectedIndexChanged event.

Syntax

protected void onSelectedIndexChanged( Event e )

Parameters

e

An Event object that provides notification for the event.

Remarks

When overriding this method, call super.onSelectedIndexChanged.

See Also addOnSelectedIndexChanged


 ComboBox.onTextChanged

ComboBox.onTextChanged

Triggers the textChanged event.

Syntax

protected void onTextChanged( Event e )

Parameters

e

An Event object that provides notification for the event.

Remarks

When overriding this method, call super.onTextChanged.

See Also addOnTextChanged


 ComboBox.removeAll

ComboBox.removeAll

Removes all items from the list box.

Syntax

public final void removeAll()

Remarks

When you remove items from the list, all information about the deleted items is lost.


 ComboBox.removeItem

ComboBox.removeItem

Removes the specified item from the list box.

Syntax

public final void removeItem( int index )

public final int removeItem( Object value )

Parameters

index

The zero-based index of the item to remove.

value

The item to remove.

Return Value

The second syntax returns the zero-based index of the removed item; returns -1 if the item is not found in the list.

Exceptions

WFCInvalidArgumentException thrown if the specified index is not valid.

Remarks

When you remove an item from the list, the indices change for subsequent items in the list. All information about the deleted item is lost.

See Also addItem


 ComboBox.removeOnDrawItem

ComboBox.removeOnDrawItem

Removes the delegate that is assigned to the drawItem event.

Syntax

public final void removeOnDrawItem( DrawItemEventHandler value )

Parameters

value

The DrawItemEventHandler delegate to be removed.

See Also addOnDrawItem


 ComboBox.removeOnDropDown

ComboBox.removeOnDropDown

Removes the delegate that is assigned to the dropDown event.

Syntax

public final void removeOnDropDown( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnDropDown


 ComboBox.removeOnMeasureItem

ComboBox.removeOnMeasureItem

Removes the delegate that is assigned to the measureItem event.

Syntax

public final void removeOnMeasureItem( MeasureItemEventHandler value )

Parameters

value

The MeasureItemEventHandler delegate to be removed.

See Also addOnMeasureItem


 ComboBox.removeOnSelectedIndexChanged

ComboBox.removeOnSelectedIndexChanged

Removes the delegate that is assigned to the selectedIndexChanged event.

Syntax

public final void removeOnSelectedIndexChanged( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnSelectedIndexChanged


 ComboBox.removeOnTextChanged

ComboBox.removeOnTextChanged

Removes the delegate that is assigned to the textChanged event.

Syntax

public final void removeOnTextChanged( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnTextChanged


 ComboBox.select

ComboBox.select

Selects a range of text in the edit control of the combo box.

Syntax

public final void select( int start, int end )

Parameters

start

The position of the last character before the beginning of the current text selection in the edit control.

end

The position of the last character before the end of the current text selection in the edit control.

Remarks

If the combo box has a static text control instead of an edit control, calling this method has no effect.


 ComboBox.selectAll

ComboBox.selectAll

Selects all the text in the edit control of the combo box.

Syntax

public final void selectAll()

Remarks

If the combo box has a static text control instead of an edit control, calling this method has no effect.


 ComboBox.setDrawMode

ComboBox.setDrawMode

Sets a value indicating whether the system draws the combo box, whether the combo box owner draws the combo box with all items of equal height, or whether the combo box owner draws the combo box with items of variable height.

Syntax

public final void setDrawMode( int value )

Parameters

value

An integer that specifies how the current combo box is drawn. Possible return values are constants defined in the DrawMode class. The default value is DrawMode.NORMAL.

Exceptions

WFCInvalidEnumException thrown if the specified value is not a valid DrawMode constant.

See Also getDrawMode, addOnDrawItem


 ComboBox.setDroppedDown

ComboBox.setDroppedDown

Sets a boolean value indicating whether the list box of the combo box is currently dropped down.

Syntax

public final void setDroppedDown( boolean value )

Parameters

value

Set to true if the list box of the combo box is dropped down; otherwise, set to false. The default value is false.

See Also getDroppedDown


 ComboBox.setIntegralHeight

ComboBox.setIntegralHeight

Sets a boolean value indicating whether the combo box should resize to avoid showing partial items.

Syntax

public final void setIntegralHeight( boolean value )

Parameters

value

Set to true if Windows resizes the combo box so that it does not display partial items; set to false if the size of the combo box remains the exact size specified by the application when it creates the combo box, allowing partial items to be shown. The default value is true.

See Also getIntegralHeight


 ComboBox.setItem

ComboBox.setItem

Allows you to replace the item at the specified position in the combo box.

Syntax

public final void setItem( int index, Object item )

Parameters

index

The zero-based index of the item you want to replace.

item

The new item that you want insert in the place of the item currently at the specified position.

Exceptions

WFCInvalidArgumentException thrown if the specified index is not valid.

See Also getItem


 ComboBox.setItemHeight

ComboBox.setItemHeight

Sets the height, in pixels, of an item in the combo box.

Syntax

public final void setItemHeight( int value )

Parameters

value

The height, in pixels, of an item in the list. The default value is 15.

Exceptions

WFCInvalidArgumentException thrown if the specified value is less than one (1).

Remarks

Use this method to set the height of items in an owner-drawn combo box with items of fixed height. To set the height of items in an owner-drawn combo box with items of variable height, use the measureItem event. For combo boxes that are drawn by the system, calls to this method are ignored.

See Also getItemHeight


 ComboBox.setItems

ComboBox.setItems

Adds a set of items to the combo box.

Syntax

public final void setItems( Object[] value )

Parameters

value

A zero-based array of objects (generally String objects) that you want to add to the combo box. If the sorted property of the combo box is set to true, the items are inserted into the list alphabetically. Otherwise, the items are inserted in the order they occur the array.

Remarks

This method removes all existing items from the combo box before inserting the new items.

See Also getItems


 ComboBox.setMaxDropDownItems

ComboBox.setMaxDropDownItems

Sets the maximum number of items that can be displayed in the drop-down list box of the combo box.

Syntax

public final void setMaxDropDownItems( int value )

Parameters

value

The maximum number of items that can be displayed in the drop-down list box. Valid values are between 1 and 100. The default value is 8.

Exceptions

WFCInvalidArgumentException thrown if the specified value is less than zero (0) or more than 100.

See Also getMaxDropDownItems


 ComboBox.setMaxLength

ComboBox.setMaxLength

Sets the maximum number of characters the user can type into the edit control of a combo box.

Syntax

public final void setMaxLength( int value )

Parameters

value

The maximum number of characters that the user can type into the edit control of the combo box. Set to a value less than or equal to zero (0) to indicate that the maximum capacity of the edit control is limited only to available memory. The default value is zero (0).

See Also getMaxLength


 ComboBox.setSelectedIndex

ComboBox.setSelectedIndex

Selects an item in a combo box.

Syntax

public final void setSelectedIndex( int index )

Parameters

index

The zero-based index of the item you want to select. Set to -1 if you do not want any items to be selected.

See Also getSelectedIndex


 ComboBox.setSelectedItem

ComboBox.setSelectedItem

Selects the first occurrence of the specified item in a single-selection combo box, and returns the zero-based index of the item.

Syntax

public final int setSelectedItem( Object value )

Parameters

value

The object (generally a String object) to select.

Return Value

Returns the zero-based index of the selected item if it exists in the combo box; returns -1 if the item is not in the combo box.

Remarks

If the specified item is not contained in the combo box, this method returns -1.

See Also getSelectedItem


 ComboBox.setSelectedText

ComboBox.setSelectedText

Replaces the currently selected text in the edit control of the combo box with the specified text.

Syntax

public final void setSelectedText( String value )

Parameters

value

The text with which to replace the currently selected text.

See Also getSelectedText


 ComboBox.setSelectionEnd

ComboBox.setSelectionEnd

Sets the end position of the text selection in the edit control of the combo box.

Syntax

public final void setSelectionEnd( int value )

Parameters

value

The zero-based index of the first character after the end of the text to select in the edit control of the combo box. For example, to select the third through fifth characters are selected in the edit control (with zero-based indexes 2 through 4), set this value to 5, and set the value parameter of the setSelectionStart method to 2. To place the cursor in the edit control without selecting text, specify the same value for both the getSelectionStart method and the getSelectionEnd method. For example, to place the cursor between the third and fourth characters, pass the value 3 to both methods. If the combo box has a static text control instead of an edit control, calling this method has no effect.

See Also getSelectionEnd


 ComboBox.setSelectionStart

ComboBox.setSelectionStart

Sets the starting position of the text selection in the edit control of the combo box.

Syntax

public final void setSelectionStart( int value )

Parameters

value

The zero-based index of the first character to include in the text selection in the edit control of the combo box. For example, to select the third through fifth characters in the edit control (with zero-based indexes 2 through 4), set this value to 2, and set the value parameter of the setSelectionEnd method to 5. To place the cursor in the edit control without selecting text, specify the same value for both the getSelectionStart method and the getSelectionEnd method. For example, to place the cursor between the third and fourth characters, pass the value 3 to both methods. If the combo box has a static text control instead of an edit control, calling this method has no effect.

See Also getSelectionStart


 ComboBox.setSorted

ComboBox.setSorted

Sets a boolean value indicating whether the items in the combo box are sorted alphabetically.

Syntax

public final void setSorted( boolean value )

Parameters

value

Set to true if the list is sorted alphabetically; otherwise, set to false. The default value is false.

See Also getSorted


 ComboBox.setStyle

ComboBox.setStyle

Sets a value indicating the style of the combo box (whether the combo box has an edit control or a static text control, and whether the list for the combo box is always visible or visible only when dropped down by the user).

Syntax

public final void setStyle( int value )

Parameters

value

An integer that specifies the style of the combo box. Possible return values are constants defined in the ComboBoxStyle class. The default value is ComboBoxStyle.DROPDOWN.

Exceptions

WFCInvalidEnumException thrown if the specified value is not a valid ComboBoxStyle constant.

See Also getStyle


ComboBoxStyle Class

Defines constants that specify the appearance of a combo box.

Enum
  |
  +--ComboBoxStyle

package com.ms.wfc.ui

public class ComboBoxStyle
extends Enum


 ComboBoxStyle Methods

ComboBoxStyle Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 ComboBoxStyle.valid

ComboBoxStyle.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 ComboBoxStyle Fields

ComboBoxStyle Fields

Fields | Description
DROPDOWN | Specifies a drop-down combo box, which is an edit control with an attached list box that is displayed only when the user clicks the drop-down arrow to the right of the edit control.
DROPDOWNLIST | Specifies a drop-down list box, which is a selection field that cannot be edited by the user with an attached list box that is displayed only when the user clicks the drop-down arrow to the right of the selection field.
SIMPLE | Specifies a simple combo box, which is an edit control with an attached list box that is always displayed.


 ComboBoxStyle.DROPDOWN

ComboBoxStyle.DROPDOWN

Specifies a drop-down combo box, which is an edit control with an attached list box that is displayed only when the user clicks the drop-down arrow to the right of the edit control.

Syntax

public static final int DROPDOWN;


 ComboBoxStyle.DROPDOWNLIST

ComboBoxStyle.DROPDOWNLIST

Specifies a drop-down list box, which is a selection field that cannot be edited by the user with an attached list box that is displayed only when the user clicks the drop-down arrow to the right of the selection field.

Syntax

public static final int DROPDOWNLIST;


 ComboBoxStyle.SIMPLE

ComboBoxStyle.SIMPLE

Specifies a simple combo box, which is an edit control with an attached list box that is always displayed.

Syntax

public static final int SIMPLE;


CommonDialog Class

Defines the base class used for displaying dialog boxes on the screen.

Component
  |
  +--CommonDialog

package com.ms.wfc.ui

public abstract class CommonDialog
extends Component

Remarks

Subclasses of CommonDialog are required to implement the runDialog method to create a specific common dialog box. Subclasses can optionally override the hookProc method to implement specific dialog box hook functionality.


 CommonDialog Methods

CommonDialog Methods

Constructors | Description
CommonDialog | Creates a CommonDialog control.

Methods | Description
addOnHelp | Assigns a delegate to the help event.
hookProc | Defines the common dialog box hook procedure that is overridden to add specific functionality to a common dialog box.
onHelp | Triggers the help event.
ownerWndProc | Defines the owner window procedure that is overridden to add specific functionality to a common dialog box.
removeOnHelp | Removes the delegate that is assigned to the help event.
reset | Resets the properties of a common dialog box to the default values.
runDialog | Called by the showDialog method to implement a specific common dialog box.
showDialog | Displays a common dialog box and returns a value indicating whether the user clicked OK in the dialog box.


 CommonDialog.addOnHelp

CommonDialog.addOnHelp

Assigns a delegate to the help event.

Syntax

public final void addOnHelp( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the help event to that method in the Properties window. The help event occurs when the user clicks Help in the dialog box.


 CommonDialog.CommonDialog

CommonDialog.CommonDialog

Creates a CommonDialog control.

Syntax

public CommonDialog()


 CommonDialog.hookProc

CommonDialog.hookProc

Defines the common dialog box hook procedure that is overridden to add specific functionality to a common dialog box.

Syntax

protected int hookProc( int hWnd, int msg, int wParam, int lParam )

Parameters

hWnd

The handle to the dialog box window.

msg

The message being received.

wParam

Additional information about the message.

lParam

Additional information about the message.

Return Value

Returns zero if the default dialog box procedure processes the message; returns a nonzero value if the default dialog box procedure ignores the message.

Remarks

When overriding this method, call super.hookProc.


 CommonDialog.onHelp

CommonDialog.onHelp

Triggers the help event.

Syntax

protected void onHelp( Event e )

Parameters

e

An Eventobject that provides the event data.

Remarks

When overriding this method, call super.onHelp.


 CommonDialog.ownerWndProc

CommonDialog.ownerWndProc

Defines the owner window procedure that is overridden to add specific functionality to a common dialog box.

Syntax

protected int ownerWndProc( int hWnd, int msg, int wParam, int lParam )

Parameters

hWnd

The window handle of the message to send.

msg

The Win32 message to send.

wParam

The wParam to send with the message.

lParam

The lParam to send with the message.

Remarks

When overriding this method, call super.ownerWndProc.


 CommonDialog.removeOnHelp

CommonDialog.removeOnHelp

Removes the delegate that is assigned to the help event.

Syntax

public final void removeOnHelp( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.


 CommonDialog.reset

CommonDialog.reset

Resets the properties of a common dialog box to the default values.

Syntax

public void reset()

Remarks

Subclasses must override this method to reset their own properties.


 CommonDialog.runDialog

CommonDialog.runDialog

Called by the showDialog method to implement a specific common dialog box.

Syntax

protected abstract boolean runDialog( int hwndOwner, int hookProcPtr )

Parameters

hwndOwner

An integer that represents the window handle of the owner window for the common dialog box.

hookProcPtr

An integer that represents the address of a common dialog box hook that will invoke the hookProc method.

Remarks

This method is invoked when the user of a common dialog box calls the showDialog method. When overriding this method, call super.getCreateParams. An implementation of the runDialog method should store the hwndOwner and hookProcPtr parameters in the common dialog box structure's hwndOwner and lpfnHook fields.


 CommonDialog.showDialog

CommonDialog.showDialog

Displays a common dialog box and returns a value indicating whether the user clicked OK in the dialog box.

Syntax

public final int showDialog()

Return Value

Returns DialogResult.OK if the user clicked OK in the dialog box; otherwise, returns DialogResult.CANCEL.


ContentAlignment Class

Defines horizontal and vertical alignments.

Enum
  |
  +--ContentAlignment

package com.ms.wfc.ui

public class ContentAlignment
extends Enum

Remarks

The constants defined in this class are used to set the alignment property of a DataGrid control's column.


 ContentAlignment Methods

ContentAlignment Methods

Methods | Description
toTextFormat | Converts a ContentAlignment constant to a corresponding TextFormat constant.
valid | Determines whether the specified value is one of the constants defined in this class.


 ContentAlignment.toTextFormat

ContentAlignment.toTextFormat

Converts a ContentAlignment constant to a corresponding TextFormat constant.

Syntax

public static final int toTextFormat( int align )

Parameters

align

One of the constants defined in this class.

Return Value

Returns one of the constants defined by the TextFormat class.


 ContentAlignment.valid

ContentAlignment.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 ContentAlignment Fields

ContentAlignment Fields

Fields | Description
BOTTOM | Specifies that the item is vertically aligned to the bottom.
BOTTOMCENTER | Specifies that the item is vertically aligned to the bottom and horizontally centered.
BOTTOMLEFT | Specifies that the item is vertically aligned to the bottom and horizontally aligned to the left.
BOTTOMRIGHT | Specifies that the item is vertically aligned to the bottom and horizontally aligned to the right.
CENTER | Specifies that the item is horizontally centered.
LEFT | Specifies that the item is horizontally aligned to the left.
MIDDLE | Specifies that the item is vertically centered.
MIDDLECENTER | Specifies that the item is vertically and horizontally centered.
MIDDLELEFT | Specifies that the item is vertically centered and horizontally aligned to the left.
MIDDLERIGHT | Specifies that the item is vertically centered and horizontally aligned to the right.
RIGHT | Specifies that the item is horizontally aligned to the right.
TOP | Specifies that the item is vertically aligned to the top.
TOPCENTER | Specifies that the item is vertically aligned to the top and horizontally centered.
TOPLEFT | Specifies that the item is vertically aligned to the top and horizontally aligned to the left.
TOPRIGHT | Specifies that the item is vertically aligned to the top and horizontally aligned to the right.


 ContentAlignment.BOTTOM

ContentAlignment.BOTTOM

Specifies that the item is vertically aligned to the bottom.

Syntax

public static final int BOTTOM;


 ContentAlignment.BOTTOMCENTER

ContentAlignment.BOTTOMCENTER

Specifies that the item is vertically aligned to the bottom and horizontally centered.

Syntax

public static final int BOTTOMCENTER;


 ContentAlignment.BOTTOMLEFT

ContentAlignment.BOTTOMLEFT

Specifies that the item is vertically aligned to the bottom and horizontally aligned to the left.

Syntax

public static final int BOTTOMLEFT;


 ContentAlignment.BOTTOMRIGHT

ContentAlignment.BOTTOMRIGHT

Specifies that the item is vertically aligned to the bottom and horizontally aligned to the right.

Syntax

public static final int BOTTOMRIGHT;


 ContentAlignment.CENTER

ContentAlignment.CENTER

Specifies that the item is horizontally centered.

Syntax

public static final int CENTER;


 ContentAlignment.LEFT

ContentAlignment.LEFT

Specifies that the item is horizontally aligned to the left.

Syntax

public static final int LEFT;


 ContentAlignment.MIDDLE

ContentAlignment.MIDDLE

Specifies that the item is vertically centered.

Syntax

public static final int MIDDLE;


 ContentAlignment.MIDDLECENTER

ContentAlignment.MIDDLECENTER

Specifies that the item is vertically and horizontally centered.

Syntax

public static final int MIDDLECENTER;


 ContentAlignment.MIDDLELEFT

ContentAlignment.MIDDLELEFT

Specifies that the item is vertically centered and horizontally aligned to the left.

Syntax

public static final int MIDDLELEFT;


 ContentAlignment.MIDDLERIGHT

ContentAlignment.MIDDLERIGHT

Specifies that the item is vertically centered and horizontally aligned to the right.

Syntax

public static final int MIDDLERIGHT;


 ContentAlignment.RIGHT

ContentAlignment.RIGHT

Specifies that the item is horizontally aligned to the right.

Syntax

public static final int RIGHT;


 ContentAlignment.TOP

ContentAlignment.TOP

Specifies that the item is vertically aligned to the top.

Syntax

public static final int TOP;


 ContentAlignment.TOPCENTER

ContentAlignment.TOPCENTER

Specifies that the item is vertically aligned to the top and horizontally centered.

Syntax

public static final int TOPCENTER;


 ContentAlignment.TOPLEFT

ContentAlignment.TOPLEFT

Specifies that the item is vertically aligned to the top and horizontally aligned to the left.

Syntax

public static final int TOPLEFT;


 ContentAlignment.TOPRIGHT

ContentAlignment.TOPRIGHT

Specifies that the item is vertically aligned to the top and horizontally aligned to the right.

Syntax

public static final int TOPRIGHT;


ContextMenu Class

Encapsulates the ContextMenu control.

Menu
  |
  +--ContextMenu

package com.ms.wfc.ui

public class ContextMenu
extends Menu

Remarks

A context menu is a pop-up menu that is associated with a particular window and that is typically displayed when the user clicks the right mouse button with the mouse positioned over the control or window.


 ContextMenu Methods

ContextMenu Methods

Constructors | Description
ContextMenu | Creates a ContextMenu object.

Methods | Description
addOnPopup | Assigns a delegate to the popup event.
onPopup | Triggers the popup event.
removeOnPopup | Removes the delegate that is assigned to the popup event.
show | Displays the context menu over the specified control and at the specified position.


 ContextMenu.addOnPopup

ContextMenu.addOnPopup

Assigns a delegate to the popup event.

Syntax

public void addOnPopup( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

The popup event occurs when the context menu is about to be displayed. Typically, you use this event handler to add, remove, enable, or disable items contained in the menu, as appropriate.

See Also onPopup, removeOnPopup


 ContextMenu.ContextMenu

ContextMenu.ContextMenu

Creates a ContextMenu object.

Syntax

public ContextMenu()

public ContextMenu( MenuItem[] menuItems )

Parameters

menuItems

An array of MenuItem objects that specifies the initial items on the context menu.


 ContextMenu.onPopup

ContextMenu.onPopup

Triggers the popup event.

Syntax

protected void onPopup( Event e )

Parameters

e

An Event object that provides the event data.

Remarks

The popup event occurs when the context menu is about to be displayed. Typically, you use this event handler to add, remove, enable, or disable items contained in the menu, as appropriate.

See Also addOnPopup, removeOnPopup


 ContextMenu.removeOnPopup

ContextMenu.removeOnPopup

Removes the delegate that is assigned to the popup event.

Syntax

public void removeOnPopup( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

Remarks

The popup event occurs when the context menu is about to be displayed. Typically, you use this event handler to add, remove, enable, or disable items contained in the menu, as appropriate.

See Also addOnPopup, onPopup


 ContextMenu.show

ContextMenu.show

Displays the context menu over the specified control and at the specified position.

Syntax

public void show( Control control, Point pos )

Parameters

control

A Control object that specifies the control with which this context menu is associated.

pos

A Point object that specifies the coordinates at which to display the menu. These coordinates are specified relative to the client coordinates of the control specified in the control parameter.

Remarks

This method does not return until the user dismisses the context menu.


Control Class

Defines the base class used for controls, which are standardized child windows that the user can manipulate to perform an action or display information.

Component
  |
  +--Control

package com.ms.wfc.ui

public class Control
extends Component

Remarks

The Control class encapsulates a window handle (HWND).


 Control Methods

Control Methods

Constructors | Description
Control | Creates a Control object.

Methods | Description
add | Adds a child control to this control.
addOnClick | Assigns a delegate to the click event.
addOnCreateHandle | Assigns a delegate to the createHandle event.
addOnDestroyHandle | Assigns a delegate to the destroyHandle event.
addOnDoubleClick | Assigns a delegate to the doubleClick event.
addOnDragDrop | Assigns a delegate to the dragDrop event.
addOnDragEnter | Assigns a delegate to the dragEnter event.
addOnDragLeave | Assigns a delegate to the dragLeave event.
addOnDragOver | Assigns a delegate to the dragOver event.
addOnEnter | Assigns a delegate to the enter event.
addOnGiveFeedback | Assigns a delegate to the giveFeedback event.
addOnGotFocus | Assigns a delegate to the gotFocus event.
addOnHelp | Assigns a delegate to the help event.
addOnKeyDown | Assigns a delegate to the keyDown event.
addOnKeyPress | Assigns a delegate to the keyPress event.
addOnKeyUp | Assigns a delegate to the keyUp event.
addOnLayout | Assigns a delegate to the layout event.
addOnLeave | Assigns a delegate to the leave event.
addOnLostFocus | Assigns a delegate to the lostFocus event.
addOnMouseDown | Assigns a delegate to the mouseDown event.
addOnMouseEnter | Assigns a delegate to the mouseEnter event.
addOnMouseLeave | Assigns a delegate to the mouseLeave event.
addOnMouseMove | Assigns a delegate to the mouseMove event.
addOnMouseUp | Assigns a delegate to the mouseUp event.
addOnMouseWheel | Assigns a delegate to the mouseWheel event.
addOnMove | Assigns a delegate to the move event.
addOnPaint | Assigns a delegate to the paint event.
addOnQueryContinueDrag | Assigns a delegate to the queryContinueDrag event.
addOnResize | Assigns a delegate to the resize event.
assignParent | Assigns a new parent control.
bringToFront | Brings this control to the front of the z-order.
canFocus | Retrieves a boolean value indicating whether this control can receive the focus.
canSelect | Retrieves a boolean value indicating whether this control can be selected.
contains | Retrieves a value indicating whether the specified control is a child of this control.
createControl | Forces the creation of the control, including the creation of the control handle and any child controls.
createGraphics | Creates a Graphics object that can be used to draw in the client area of the control.
createHandle | Creates a handle for this control.
createWindowGraphics | Creates a Graphics object that can be used to draw in the entire window of the control rather than just the client area of the control.
destroyHandle | This method should be called only by the framework. Destroys the handle associated with this control.
dispose | Frees all resources allocated for this control.
doDragDrop | Begins a drag-and-drop operation.
finalize | Terminates the control window and releases the window handle.
fireDragEvent | Triggers a drag event.
fireKeyEvent | Triggers a key event.
fireMouseEvent | Triggers a mouse event.
focus | Attempts to set the focus to this control and activate the form that contains this control, and returns a boolean value indicating whether the attempt succeeded.
fromChildHandle | Returns the control that contains the specified handle.
fromHandle | Returns the control that is currently associated with the specified handle.
getAcceptsChildren | Retrieves a boolean value indicating whether this control can contain child controls.
getAllowDrop | Retrieves a boolean value indicating whether this control can accept data that the user drags and drops into it.
getAnchor | Retrieves a value indicating which edges of the control are anchored to the edges of its container.
getBackColor | Retrieves the background color for this control.
getBottom | Retrieves the distance between the bottom edge of the control and the top edge of its container's client area.
getBounds | Retrieves the bounding rectangle for the control.
getBrush | Retrieves the brush for this control.
getCapture | Retrieves a boolean value indicating whether this control has captured the mouse.
getChildAtPoint | Retrieves the child control that is located at the specified coordinates.
getClientRect | Retrieves the rectangle that represents the client area of the control.
getClientSize | Retrieves the height and width of the client area of the control.
getContextMenu | Retrieves the shortcut menu (also known as a context menu) associated with this control.
getControl | Retrieves the child control with the specified zero-based index within the parent's control array.
getControlCount | Retrieves the number of child controls this control contains.
getControlIndex | Retrieves the zero-based index of this control within the parent control array.
getControls | Retrieves an array of the child controls contained in this control.
getCreated | Retrieves a boolean value indicating whether the control has been created.
getCreateParams | Retrieves the information used to create the handle for this control.
getCursor | Retrieves the cursor that is displayed when the user moves the mouse pointer over this control.
getDisplayRect | Retrieves the rectangle that represents the display area of the control.
getDock | Retrieves a value indicating which edge of its container this control is docked to.
getEnabled | Retrieves a boolean value indicating whether this control is enabled.
getFocused | Retrieves a boolean value indicating whether the control has the focus.
getFont | Retrieves the current font for this control, which is the font the control uses to draw its text.
getForeColor | Retrieves the current foreground color for this control, which is the color the control uses to draw its text.
getForm | Retrieves the form that this control is on.
getHandle | Retrieves the window handle (HWND) that this control is bound to.
getHandleCreated | Retrieves a boolean value indicating whether this control has a handle associated with it.
getHeight | Retrieves the height of this control.
getInputChar | Retrieves a boolean value indicating whether the control processes the specified character itself.
getInputKey | Retrieves a boolean value indicating whether the control processes the specified keyboard input.
getInvokeRequired | Determines whether the caller must call invoke when making method calls to this control.
getLeft | Retrieves the distance between the left edge of the control and the left edge of its container's client area.
getLocation | Retrieves coordinates of the upper-left corner of the control relative to the upper-left corner of its container's client area.
getMnemonic | Retrieves a boolean value indicating whether the specified character is the mnemonic character in the specified string.
getModifierKeys | Retrieves a value indicating the current state of the SHIFT, CTRL, and ALT keys.
getMouseButtons | Retrieves a value indicating the current state of the left, right, and middle mouse buttons.
getMousePosition | Retrieves the current position of the mouse in screen coordinates.
getNextControl | Retrieves the control that follows or precedes the specified control in the tab order.
getPalette | Retrieves the palette associated with this control.
getParent | Retrieves the parent of this control.
getRecreatingHandle | Retrieves a boolean value indicating whether the control is currently re-creating its handle.
getRegion | Retrieves the region (the elliptical or polygonal area within a window) associated with this control.
getRight | Retrieves the distance between the right edge of the control and the left edge of its container's client area.
getSize | Retrieves the height and width of the control.
getStyle | Retrieves the current value of the specified bit field in the control's style property.
getTabIndex | Retrieves the tab order of this control within the parent form.
getTabList | Retrieves all the child controls included in the tab order.
getTabStop | Retrieves a boolean value indicating whether the user can give the focus to this control using the TAB key.
getText | Retrieves the text associated with this control.
getTop | Retrieves the distance between the top edge of the control and the top edge of its container's client area.
getTopLevel | Retrieves a boolean value indicating whether this control is a top-level window (a window that has no parent window).
getTopLevelControl | Retrieves the top-level control that contains this control.
getVisible | Retrieves a boolean value indicating whether this control is visible.
getWidth | Retrieves the width of this control.
hide | Hides the control by setting the visible property to false.
invalidate | Invalidates the specified part of the control (adds it to the control's update region, which is the area that will be repainted at the next paint operation), and causes a paint message to be sent to the control.
invoke | Executes the specified delegate on the thread that created the control's handle and returns when the delegate has completed execution.
invokeAsync | Executes the specified delegate on the thread that created the control's handle and returns immediately (because the delegate is invoked asynchronously).
onClick | Triggers the click event.
onCreateHandle | Triggers the createHandle event.
onDestroyHandle | Triggers the destroyHandle event.
onDoubleClick | Triggers the doubleClick event.
onDragDrop | Triggers the dragDrop event.
onDragEnter | Triggers the dragEnter event.
onDragLeave | Triggers the dragLeave event.
onDragOver | Triggers the dragOver event.
onEnter | Triggers the enter event.
onEraseBackground | Triggers the eraseBackground event.
onGiveFeedback | Triggers the giveFeedback event.
onGotFocus | Triggers the gotFocus event.
onHelp | Triggers the help event.
onKeyDown | Triggers the keyDown event.
onKeyPress | Triggers the keyPress event.
onKeyUp | Triggers the keyUp event.
onLayout | Triggers the layout event.
onLeave | Triggers the leave event.
onLostFocus | Triggers the lostFocus event.
onMouseDown | Triggers the mouseDown event.
onMouseEnter | Triggers the mouseEnter event.
onMouseLeave | Triggers the mouseLeave event.
onMouseMove | Triggers the mouseMove event.
onMouseUp | Triggers the mouseUp event.
onMouseWheel | Triggers the mouseWheel event.
onMove | Triggers the move event.
onPaint | Triggers the paint event.
onQueryContinueDrag | Triggers the queryContinueDrag event.
onResize | Triggers the resize event.
performLayout | Forces the control to apply layout logic to all its child controls.
pointToClient | Converts the coordinates of a point from screen coordinates to client coordinates.
pointToScreen | Converts the coordinates of a point from client coordinates to screen coordinates.
preProcessMessage | This method is called by the application's message loop to preprocess input messages before they are dispatched.
processCmdKey | Processes a command key.
processDialogChar | Processes a dialog character, checking for mnemonics, and forwards the appropriate messages.
processDialogKey | Processes a dialog key, checking for mnemonics, tabs, and arrows, and forwards the appropriate messages.
processKeyEvent | Processes a key message and generates the appropriate control events.
processKeyMessage | Processes a key message.
processKeyPreview | Processes key preview messages.
processMnemonic | Processes a mnemonic character.
propertyChanged | This method is called by the control when any property changes.
recreateHandle | Forces the re-creation of the handle for this control.
rectToClient | Converts the coordinates of a rectangle from screen coordinates to client coordinates.
rectToScreen | Converts the coordinates of a rectangle from client coordinates to screen coordinates.
reflectMessage | Reflects the specified message to the control that is bound to the specified handle.
remove | Removes the specified child control from this control.
removeOnClick | Removes the delegate that is assigned to the click event.
removeOnCreateHandle | Removes the delegate that is assigned to the createHandle event.
removeOnDestroyHandle | Removes the delegate that is assigned to the destroyHandle event.
removeOnDoubleClick | Removes the delegate that is assigned to the doubleClick event.
removeOnDragDrop | Removes the delegate that is assigned to the dragDrop event.
removeOnDragEnter | Removes the delegate that is assigned to the dragEnter event.
removeOnDragLeave | Removes the delegate that is assigned to the dragLeave event.
removeOnDragOver | Removes the delegate that is assigned to the dragOver event.
removeOnEnter | Removes the delegate that is assigned to the enter event.
removeOnGiveFeedback | Removes the delegate that is assigned to the giveFeedback event.
removeOnGotFocus | Removes the delegate that is assigned to the gotFocus event.
removeOnHelp | Removes the delegate that is assigned to the help event.
removeOnKeyDown | Removes the delegate that is assigned to the keyDown event.
removeOnKeyPress | Removes the delegate that is assigned to the keyPress event.
removeOnKeyUp | Removes the delegate that is assigned to the keyUp event.
removeOnLayout | Removes the delegate that is assigned to the layout event.
removeOnLeave | Removes the delegate that is assigned to the leave event.
removeOnLostFocus | Removes the delegate that is assigned to the lostFocus event.
removeOnMouseDown | Removes the delegate that is assigned to the mouseDown event.
removeOnMouseEnter | Removes the delegate that is assigned to the mouseEnter event.
removeOnMouseLeave | Removes the delegate that is assigned to the mouseLeave event.
removeOnMouseMove | Removes the delegate that is assigned to the mouseMove event.
removeOnMouseUp | Removes the delegate that is assigned to the mouseUp event.
removeOnMouseWheel | Removes the delegate that is assigned to the mouseWheel event.
removeOnMove | Removes the delegate that is assigned to the move event.
removeOnPaint | Removes the delegate that is assigned to the paint event.
removeOnQueryContinueDrag | Removes the delegate that is assigned to the queryContinueDrag event.
removeOnResize | Removes the delegate that is assigned to the resize event.
resetBackColor | Resets the background color of the control to the parent's background color.
resetFont | Resets the font for the control to the parent's font.
resetForeColor | Resets the foreground color of the control to the parent's foreground color.
resumeLayout | Resumes normal layout logic.
scale | Scales the entire control and any child controls.
scaleCore | Performs the work of scaling the entire control and any child controls.
select | Activates this control.
selectNextControl | Selects the control that follows or precedes the specified control in the tab order.
sendMessage | Sends the specified Win32 message to this control.
sendToBack | Sends this control to the back of the z-order.
setAllowDrop | Sets a boolean value indicating whether this control can accept data that the user drags and drops into it.
setAnchor | Sets a value indicating which edges of the control are anchored to the edges of its container.
setBackColor | Sets the background color for this control.
setBounds | Sets the bounding rectangle for the control.
setBoundsCore | Performs the work of setting the bounds of this control.
setBrush | Sets the brush for this control.
setCapture | Sets a boolean value indicating whether this control has captured the mouse.
setClientSize | Sets the height and width of the client area of the control.
setClientSizeCore | Performs the work of setting the size of the client area of the control.
setContextMenu | Sets the shortcut menu (also known as a context menu) associated with this control.
setControlIndex | Sets the zero-based index of the specified child control within the parent's control array.
setControls | Sets the array of the child controls contained in this control.
setCursor | Sets the cursor that is displayed when the user moves the mouse pointer over this control.
setDock | Sets a value indicating which edge of its container this control is docked to.
setEnabled | Sets a boolean value indicating whether this control is enabled.
setFont | Sets the font for this control, which is the font the control uses to draw its text.
setForeColor | Sets the current foreground color for this control, which is the color the control uses to draw its text.
setHeight | Sets the height of this control.
setLeft | Sets the distance between the left edge of the control and the left edge of its container's client area.
setLocation | Sets coordinates of the upper-left corner of the control relative to the upper-left corner of its container's client area.
setNewControls | Performs the work of setting the array of the child controls contained in this control.
setParent | Sets the parent for this control.
setRegion | Sets the region (the elliptical or polygonal area within a window) associated with this control.
setSize | Sets the height and width of the control.
setStyle | Sets the value of the specified bit field in the control's style property.
setTabIndex | Sets the tab order of this control within the parent form.
setTabStop | Sets a boolean value indicating whether the user can give the focus to this control using the TAB key.
setText | Sets the text associated with this control.
setTop | Sets the distance between the top edge of the control and the top edge of its container's client area.
setTopLevel | Sets a boolean value indicating whether this control is a top-level window (a window that has no parent window).
setVisible | Sets a boolean value indicating whether this control is visible.
setWidth | Sets the width of this control.
shouldPersistBackColor | Retrieves a boolean value indicating whether the background color for the control has been explicitly set.
shouldPersistFont | Retrieves a boolean value indicating whether the background color for the control has been explicitly set.
shouldPersistForeColor | Retrieves a boolean value indicating whether the background color for the control has been explicitly set.
show | Displays the control by setting the visible property to true.
suspendLayout | Suspends the layout logic for the control.
update | Forces the control to paint its update region (regions that have been marked as needing repainting).
updateBounds | Updates the bounding rectangle of the control based on the handle the control is bound to.
updateStyles | Forces styles to be reapplied to the handle without recreating the handle.
updateZOrder | Updates this control's position within its parent's z-order.


 Control.add

Control.add

Adds a child control to this control.

Syntax

public void add( Control control )

Parameters

control

A Control object that represents the child control to be added.

Exceptions

WFCException thrown if the specified control is a top-level control or if adding the new control as a child would result in a circular control reference.

Remarks

The new child control becomes the last control in the child control list. If the added child control is already a child of another control, it is removed as a child of the first control before being added as a child of this control.

See Also remove, setParent


 Control.addOnClick

Control.addOnClick

Assigns a delegate to the click event.

Syntax

public final void addOnClick( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the click event to that method in the Properties window. The click event occurs when the user clicks the control. The click event can also occur when the value of a control changes.

See Also removeOnClick


 Control.addOnCreateHandle

Control.addOnCreateHandle

Assigns a delegate to the createHandle event.

Syntax

public final void addOnCreateHandle( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

The createHandle event occurs immediately after the control's handle is created.

See Also removeOnCreateHandle


 Control.addOnDestroyHandle

Control.addOnDestroyHandle

Assigns a delegate to the destroyHandle event.

Syntax

public final void addOnDestroyHandle( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

The destroyHandle event occurs immediately before the control's handle is destroyed.

See Also removeOnDestroyHandle


 Control.addOnDoubleClick

Control.addOnDoubleClick

Assigns a delegate to the doubleClick event.

Syntax

public final void addOnDoubleClick( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the doubleClick event to that method in the Properties window. The doubleClick event occurs when the user double-clicks the control.

See Also removeOnDoubleClick


 Control.addOnDragDrop

Control.addOnDragDrop

Assigns a delegate to the dragDrop event.

Syntax

public final void addOnDragDrop( DragEventHandler value )

Parameters

value

The DragEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the dragDrop event to that method in the Properties window. The dragDrop event occurs when the user completes a drag-and-drop operation by dragging an object over the control and then dropping the object onto the control by releasing the mouse button.

See Also removeOnDragDrop


 Control.addOnDragEnter

Control.addOnDragEnter

Assigns a delegate to the dragEnter event.

Syntax

public final void addOnDragEnter( DragEventHandler value )

Parameters

value

The DragEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the dragEnter event to that method in the Properties window. The dragEnter event occurs when the user moves the mouse pointer into the control while dragging an object with the mouse.

See Also removeOnDragEnter


 Control.addOnDragLeave

Control.addOnDragLeave

Assigns a delegate to the dragLeave event.

Syntax

public final void addOnDragLeave( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the dragLeave event to that method in the Properties window. The dragLeave event occurs when the user moves the mouse pointer out of the control while dragging an object with the mouse.

See Also removeOnDragLeave


 Control.addOnDragOver

Control.addOnDragOver

Assigns a delegate to the dragOver event.

Syntax

public final void addOnDragOver( DragEventHandler value )

Parameters

value

The DragEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the dragOver event to that method in the Properties window. The dragOver event occurs when the user moves the mouse pointer over the control while dragging an object with the mouse.

See Also removeOnDragOver


 Control.addOnEnter

Control.addOnEnter

Assigns a delegate to the enter event.

Syntax

public final void addOnEnter( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the enter event to that method in the Properties window.

The enter event occurs when this control or a child of this control becomes the active control of the form: that is, when the focus moves to this control or to a child control of this control from another control on the same form. If this control is the active control for a deactivated form, this event is not triggered when the form is activated. A control becomes the form's active control when the user sets the focus to the control or when the control is set to the active control using the form's setActiveControl method.

See Also removeOnEnter


 Control.addOnGiveFeedback

Control.addOnGiveFeedback

Assigns a delegate to the giveFeedback event.

Syntax

public final void addOnGiveFeedback( GiveFeedbackEventHandler value )

Parameters

value

The GiveFeedbackEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the giveFeedback event to that method in the Properties window. The giveFeedback event occurs during a drag operation and allows the source of a drag event to modify the mouse pointer to give the user visual feedback during a drag-and-drop operation.

See Also removeOnGiveFeedback


 Control.addOnGotFocus

Control.addOnGotFocus

Assigns a delegate to the gotFocus event.

Syntax

public final void addOnGotFocus( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

The gotFocus event occurs when this control gets the focus.

See Also removeOnGotFocus


 Control.addOnHelp

Control.addOnHelp

Assigns a delegate to the help event.

Syntax

public final void addOnHelp( HelpEventHandler value )

Parameters

value

The HelpEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the help event to that method in the Properties window. The help event occurs when the user requests Help for this control.

See Also removeOnHelp


 Control.addOnKeyDown

Control.addOnKeyDown

Assigns a delegate to the keyDown event.

Syntax

public final void addOnKeyDown( KeyEventHandler value )

Parameters

value

The KeyEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the keyDown event to that method in the Properties window. The keyDown event occurs when the user presses a key while this control has the focus. You can retrieve the virtual key code for the key that was pressed using the getKeyCode method of the KeyEvent object that is sent with this event. The Key class contains constants that represent possible virtual key codes.

See Also removeOnKeyDown


 Control.addOnKeyPress

Control.addOnKeyPress

Assigns a delegate to the keyPress event.

Syntax

public final void addOnKeyPress( KeyPressEventHandler value )

Parameters

value

The KeyPressEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the keyPress event to that method in the Properties window. The keyPress event occurs when the the user composes a character by pressing keys on the keyboard. You can use the getKeyChar method of the KeyPressEvent object that is sent with this event to retrieve the character that was composed.

See Also removeOnKeyPress


 Control.addOnKeyUp

Control.addOnKeyUp

Assigns a delegate to the keyUp event.

Syntax

public final void addOnKeyUp( KeyEventHandler value )

Parameters

value

The KeyEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the keyUp event to that method in the Properties window. The keyUp event occurs when the user releases a key while this control has the focus. You can retrieve the virtual key code for the key that was pressed using the getKeyCode method of the KeyEvent object that is sent with this event. The Key class contains constants that represent possible virtual key codes.

See Also removeOnKeyUp


 Control.addOnLayout

Control.addOnLayout

Assigns a delegate to the layout event.

Syntax

public final void addOnLayout( LayoutEventHandler value )

Parameters

value

The LayoutEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the layout event to that method in the Properties window. The layout event occurs when the control has to lay out its child controls. Actions that make it necessary for a control to lay out its child controls include resizng, showing or hiding child controls, and adding or removing child controls. Use this event to perform any custom layout logic.

See Also removeOnLayout


 Control.addOnLeave

Control.addOnLeave

Assigns a delegate to the leave event.

Syntax

public final void addOnLeave( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the leave event to that method in the Properties window. The leave event occurs when the active control for the form changes from this control or a child of this control to a control on the form other than this control or a child of this control. If the form is active when this event occurs, the focus moves to the new active control on the form. If this control is the active control for an active form, this event is not triggered when the form is deactivated.

Data validation for a control should take place in the handler for the leave event of the control or one of its containers. Use the setActiveControl method in your event handler to prevent the user from leaving a control without entering valid data.

See Also removeOnLeave


 Control.addOnLostFocus

Control.addOnLostFocus

Assigns a delegate to the lostFocus event.

Syntax

public final void addOnLostFocus( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

The lostFocus event occurs when this control loses focus.

See Also removeOnLostFocus


 Control.addOnMouseDown

Control.addOnMouseDown

Assigns a delegate to the mouseDown event.

Syntax

public final void addOnMouseDown( MouseEventHandler value )

Parameters

value

The MouseEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the mouseDown event to that method in the Properties window. The mouseDown event occurs when the user presses down the mouse button over this control.

See Also removeOnMouseDown


 Control.addOnMouseEnter

Control.addOnMouseEnter

Assigns a delegate to the mouseEnter event.

Syntax

public final void addOnMouseEnter( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the mouseEnter event to that method in the Properties window. The mouseEnter event occurs when the mouse first moves over this control.

See Also removeOnMouseEnter


 Control.addOnMouseLeave

Control.addOnMouseLeave

Assigns a delegate to the mouseLeave event.

Syntax

public final void addOnMouseLeave( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the mouseLeave event to that method in the Properties window. The mouseLeave event occurs when the mouse first moves away from this control.

See Also removeOnMouseLeave


 Control.addOnMouseMove

Control.addOnMouseMove

Assigns a delegate to the mouseMove event.

Syntax

public final void addOnMouseMove( MouseEventHandler value )

Parameters

value

The MouseEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the mouseMove event to that method in the Properties window. The mouseMove event occurs when the user moves the mouse over this control.

See Also removeOnMouseMove


 Control.addOnMouseUp

Control.addOnMouseUp

Assigns a delegate to the mouseUp event.

Syntax

public final void addOnMouseUp( MouseEventHandler value )

Parameters

value

The MouseEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the mouseUp event to that method in the Properties window. The mouseUp event occurs when the user releases a mouse button inside the control.

See Also removeOnMouseUp


 Control.addOnMouseWheel

Control.addOnMouseWheel

Assigns a delegate to the mouseWheel event.

Syntax

public final void addOnMouseWheel( MouseEventHandler value )

Parameters

value

The MouseEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the mouseWheel event to that method in the Properties window. The mouseWheel event occurs when the user rotates the mouse wheel while this control has the focus. Pressing the mouse wheel generates a mouseDown event with the middle button pressed.

See Also removeOnMouseWheel


 Control.addOnMove

Control.addOnMove

Assigns a delegate to the move event.

Syntax

public final void addOnMove( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the move event to that method in the Properties window. The move event occurs when the position of the control has changed.

See Also removeOnMove


 Control.addOnPaint

Control.addOnPaint

Assigns a delegate to the paint event.

Syntax

public final void addOnPaint( PaintEventHandler value )

Parameters

value

The PaintEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the paint event to that method in the Properties window. The paint event occurs when the control makes a request to repaint a portion of its client area.

See Also removeOnPaint


 Control.addOnQueryContinueDrag

Control.addOnQueryContinueDrag

Assigns a delegate to the queryContinueDrag event.

Syntax

public final void addOnQueryContinueDrag( QueryContinueDragEventHandler value )

Parameters

value

The QueryContinueDragEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the queryContinueDrag event to that method in the Properties window. The queryContinueDrag event occurs during a drag-and-drop operation and allows the drag source to determine whether the drag-and-drop operation should be canceled.

See Also removeOnQueryContinueDrag


 Control.addOnResize

Control.addOnResize

Assigns a delegate to the resize event.

Syntax

public final void addOnResize( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the resize event to that method in the Properties window. The resize event occurs when the control is resized. This event can be triggered from the base control constructor.

See Also removeOnResize


 Control.assignParent

Control.assignParent

Assigns a new parent control.

Syntax

protected final void assignParent( Control value )

Parameters

value

A Control object that represents the new parent control.

Remarks

This method sends out the appropriate property change notifications for properties that are affected by the change of parent.


 Control.bringToFront

Control.bringToFront

Brings this control to the front of the z-order.

Syntax

public final void bringToFront()


 Control.canFocus

Control.canFocus

Retrieves a boolean value indicating whether this control can receive the focus.

Syntax

public final boolean canFocus()

Return Value

Returns true if the control can receive the focus; otherwise, returns false. In order for a control to receive the focus, the control must have a handle, and the control and all its parent controls must be both visible and enabled.


 Control.canSelect

Control.canSelect

Retrieves a boolean value indicating whether this control can be selected.

Syntax

public final boolean canSelect()

Return Value

Returns true if the control can be selected; otherwise, returns false. For a control to be selected, the control must be contained in a form, and the control and all its parent controls must be both visible and enabled.

See Also select


 Control.contains

Control.contains

Retrieves a value indicating whether the specified control is a child of this control.

Syntax

public final boolean contains( Control ctl )

Parameters

ctl

A Control object that represents the control to check.

Return Value

Returns true if the specified control is a child of this control; otherwise, returns false.


 Control.Control

Control.Control

Creates a Control object.

Syntax

public Control()

Remarks

This constructor is typically called from a constructor of a derived class.


 Control.createControl

Control.createControl

Forces the creation of the control, including the creation of the control handle and any child controls.

Syntax

public final void createControl()


 Control.createGraphics

Control.createGraphics

Creates a Graphics object that can be used to draw in the client area of the control.

Syntax

public final Graphics createGraphics()

public final Graphics createGraphics( int dc )

Parameters

dc

An integer that represents a handle to a device context (HDC) to wrap in the Graphics object. The Graphics object does not claim ownership of the device context; you are responsible for freeing the device context.

Return Value

Returns a Graphics object that can be used to draw in the client area of the control.

Remarks

The brush, font, foreground color, and background color of the control determine the default values for the Graphics object. Use the dispose method of the returned Graphics object to free resources allocated by the Graphics object when the object is no longer needed. The Graphics object is valid only for the duration of the current window's message. To create a Graphics object that allows you to draw in the entire window for the control instead of just in the client area, use the createWindowGraphics method.

Creates a Graphics object that can be used to draw in the client area of the control.


 Control.createHandle

Control.createHandle

Creates a handle for this control.

Syntax

protected void createHandle()

Remarks

This method should be called only by the framework. When overriding this method, be sure to call super.createHandle.


 Control.createWindowGraphics

Control.createWindowGraphics

Creates a Graphics object that can be used to draw in the entire window of the control rather than just the client area of the control.

Syntax

public final Graphics createWindowGraphics()

Return Value

Returns a Graphics object that can be used to draw in the entire window for the control.

Remarks

The foreground color and background color of the control determine the default values for the Graphics object. Use the dispose method of the returned Graphics object to free resources allocated by the Graphics object when the object is no longer needed. The Graphics object is valid only for the duration of the current window's message.


 Control.destroyHandle

Control.destroyHandle

This method should be called only by the framework. Destroys the handle associated with this control.

Syntax

protected void destroyHandle()

Remarks

When overriding this method, call super.destroyHandle.


 Control.dispose

Control.dispose

Frees all resources allocated for this control.

Syntax

public void dispose()

Remarks

Any resources used by the control should be set up to be released in this method. This method is called when the control is garbage collected or when its container is disposed. You can call this method to force its resources to be released. Because this method can be called multiple times, make sure it is re-entrant. When overriding this method, call super.dispose.


 Control.doDragDrop

Control.doDragDrop

Begins a drag-and-drop operation.

Syntax

public final int doDragDrop( Object data, int allowedEffects )

Parameters

data

An object that represents contains the data to drag and drop. If the drag-and-drop operation involves moving data between applications in different processes, the data parameter should be either an object that implements com.ms.wfc.core.Ipersistable or an object that implements com.ms.wfc.app.IDataObject.

allowedEffects

An integer specifying which drag-and-drop operations are allowed. Possible values are obtained by applying the bitwise OR operation (|) to the constants defined in the DragDropEffect class.

Return Value

Returns an integer that indicates the final effect of the drag operation. Possible return values are values obtained by applying the bitwise OR operation (|) to the constants defined in the DragDropEffect class.


 Control.finalize

Control.finalize

Terminates the control window and releases the window handle.

Syntax

protected void finalize() throws Throwable

Exceptions

Throwable thrown if there was a problem cleaning up the font.


 Control.fireDragEvent

Control.fireDragEvent

Triggers a drag event.

Syntax

protected final void fireDragEvent( Object key, DragEvent e )

Parameters

key

An object that represents the drag event to trigger.

e

An DragEvent object that provides the event data.


 Control.fireKeyEvent

Control.fireKeyEvent

Triggers a key event.

Syntax

protected final void fireKeyEvent( Object key, KeyEvent e )

Parameters

key

An object that represents the key event to trigger.

e

An KeyEvent object that provides the event data.


 Control.fireMouseEvent

Control.fireMouseEvent

Triggers a mouse event.

Syntax

protected final void fireMouseEvent( Object key, MouseEvent e )

Parameters

key

An object that represents the mouse event to trigger.

e

An MouseEvent object that provides the event data.


 Control.focus

Control.focus

Attempts to set the focus to this control and activate the form that contains this control, and returns a boolean value indicating whether the attempt succeeded.

Syntax

public final boolean focus()

Return Value

Returns true if the focus is successfully set to this control; otherwise, returns false.

Remarks

Use the canFocus method to determine whether a control can receive the focus. Using the setActiveControl method is a more robust way than using the focus method to set the active control on a form because it does not activate inactive forms.


 Control.fromChildHandle

Control.fromChildHandle

Returns the control that contains the specified handle.

Syntax

public static final Control fromChildHandle( int handle )

Parameters

handle

The window handle (HWND) to search for.

Return Value

Returns a Control object that represents the control associated with the specified handle; returns null if no control with the specified handle is found.

Remarks

This method searches up the window handle (HWND) parent chain until it finds a handle that is associated with a control. This method is more robust than the fromHandle method because it correctly returns controls that own more than one handle.


 Control.fromHandle

Control.fromHandle

Returns the control that is currently associated with the specified handle.

Syntax

public static final Control fromHandle( int handle )

Parameters

handle

The window handle (HWND) to search for.

Return Value

Returns a Control object that represents the control associated with the specified handle; returns null if no control with the specified handle is found.

Remarks

Use the fromChildHandle method if you need to correctly return controls that own more than one handle.

See Also fromChildHandle


 Control.getAcceptsChildren

Control.getAcceptsChildren

Retrieves a boolean value indicating whether this control can contain child controls.

Syntax

public final boolean getAcceptsChildren()

Return Value

Returns true if this control can contain children; otherwise, returns false.

Remarks

Derived control classes can specify whether they accept children by passing STYLE_ACCEPTSCHILDREN as the flag parameter to the setStyle method as shown in the following line of code.

setStyle(STYLE_ACCEPTSCHILDREN, true);


 Control.getAllowDrop

Control.getAllowDrop

Retrieves a boolean value indicating whether this control can accept data that the user drags and drops into it.

Syntax

public final boolean getAllowDrop()

Return Value

Returns true if the control is a valid drop target; otherwise, returns false.

See Also setAllowDrop


 Control.getAnchor

Control.getAnchor

Retrieves a value indicating which edges of the control are anchored to the edges of its container.

Syntax

public final int getAnchor()

Return Value

Returns an integer that represents how a control is anchored to the edges of its container. Possible return values are constants defined in the ControlAnchor class.

See Also setAnchor


 Control.getBackColor

Control.getBackColor

Retrieves the background color for this control.

Syntax

public Color getBackColor()

Return Value

Returns a Color object that represents the background color for this control. Returns the background color for the control's parent if no background color has been explicitly set for this control. Returns the default system brush if no background color has been explicitly set for this control or for this control's parent.

Remarks

This is an ambient property and will always return a non-null value.

See Also setBackColor


 Control.getBottom

Control.getBottom

Retrieves the distance between the bottom edge of the control and the top edge of its container's client area.

Syntax

public final int getBottom()

Return Value

Returns an integer that represents the distance, in pixels, between the bottom edge of the control and the top edge of its container's client area. This value is equal to the value returned by the getTop method plus the value returned by the getHeight method.

See Also getBounds


 Control.getBounds

Control.getBounds

Retrieves the bounding rectangle for the control.

Syntax

public final Rectangle getBounds()

Return Value

Returns a Rectangle object that represents the bounding rectangle for the control.

See Also setBounds


 Control.getBrush

Control.getBrush

Retrieves the brush for this control.

Syntax

public Brush getBrush()

Return Value

Returns a Brush object that represents the brush for this control.

Remarks

This is an ambient property and always returns a non-null value.

See Also setBrush


 Control.getCapture

Control.getCapture

Retrieves a boolean value indicating whether this control has captured the mouse.

Syntax

public final boolean getCapture()

Return Value

Returns true if this control has captured the mouse; otherwise, returns false.

Remarks

When a control has captured the mouse, it receives mouse input whether or not the cursor is within its borders.

See Also setCapture


 Control.getChildAtPoint

Control.getChildAtPoint

Retrieves the child control that is located at the specified coordinates.

Syntax

public final Control getChildAtPoint( Point pt )

Parameters

pt

A Point object that contains the coordinates where you want to look for a control. Coordinates are expressed relative to the upper-left corner of the control's client area.

Return Value

Returns a Control object that represents the control that contains the specified point. If there is no control at the specified point other than this control, returns null.


 Control.getClientRect

Control.getClientRect

Retrieves the rectangle that represents the client area of the control.

Syntax

public final Rectangle getClientRect()

Return Value

Returns a Rectangle object that represents the client area of the control. Because client coordinates are relative to the upper-left corner of the client area of the control, the coordinates of the upper-left corner of the returned rectangle are (0,0).


 Control.getClientSize

Control.getClientSize

Retrieves the height and width of the client area of the control.

Syntax

public final Point getClientSize()

Return Value

Returns a Point object that contains the dimensions of the client area of the control. The Point.x field holds the client area width; the Point.y field holds the height.

See Also setClientSize


 Control.getContextMenu

Control.getContextMenu

Retrieves the shortcut menu (also known as a context menu) associated with this control.

Syntax

public final ContextMenu getContextMenu()

Return Value

Returns The ContextMenu object that represents the shortcut menu that appears when the user right-clicks this control.

Remarks

The shortcut menu is the menu that appears when the user right-clicks the control.

See Also setContextMenu


 Control.getControl

Control.getControl

Retrieves the child control with the specified zero-based index within the parent's control array.

Syntax

public Control getControl( int index )

Parameters

index

The zero-based index of the child control to return.

Return Value

Returns a Control object that represents the child control with the specified index.

Remarks

The controls are arranged in parent's control array according to their z-order.


 Control.getControlCount

Control.getControlCount

Retrieves the number of child controls this control contains.

Syntax

public int getControlCount()

Return Value

Returns an integer that represents the number of of child controls this control contains.

Remarks

Because the indices for child controls within the parent control array are zero-based, the index numbers for the child controls start at zero (0) and end at controlCount - 1.


 Control.getControlIndex

Control.getControlIndex

Retrieves the zero-based index of this control within the parent control array.

Syntax

public final int getControlIndex()

Return Value

Returns an integer that represents the zero-based index of this control within the parent control array. Returns -1 if this control is not a child of another control.

See Also setControlIndex


 Control.getControls

Control.getControls

Retrieves an array of the child controls contained in this control.

Syntax

public Control[] getControls()

Return Value

Returns an array of Control objects that represents the child controls contained in this control. Returns an empty array if this control contains no child controls.

Remarks

The controls are placed in the array according to their z-order.

See Also setControls


 Control.getCreated

Control.getCreated

Retrieves a boolean value indicating whether the control has been created.

Syntax

public final boolean getCreated()

Return Value

Returns true if the control has been created; otherwise, returns false.


 Control.getCreateParams

Control.getCreateParams

Retrieves the information used to create the handle for this control.

Syntax

protected CreateParams getCreateParams()

Return Value

Returns a CreateParams object that supplied information about the initial state of a control when the control handle was created. Derived classes can override this method to include additional information in the CreateParams object. When overriding this method, call super.getCreateParams. The following example shows how a derived class might override the getCreateParams method:

protected CreateParams getCreateParams() {
    CreateParams cp = super.getCreateParams();
    // modify cp here...
    cp.style |= win.WS_BORDER;
    return cp;
}


 Control.getCursor

Control.getCursor

Retrieves the cursor that is displayed when the user moves the mouse pointer over this control.

Syntax

public final Cursor getCursor()

Return Value

Returns a Cursor that represents the current control cursor.

See Also setCursor


 Control.getDisplayRect

Control.getDisplayRect

Retrieves the rectangle that represents the display area of the control.

Syntax

public Rectangle getDisplayRect()

Return Value

Returns a Rectangle object that represents the display area of the control. For the Control class, getDisplayRect and getClientRect return identical rectangles because the client area and display area are identical. You can override this method in a derived control if the client area and display area are different for that control.


 Control.getDock

Control.getDock

Retrieves a value indicating which edge of its container this control is docked to.

Syntax

public final int getDock()

Return Value

Returns an integer that represents which edge of its container this control is docked to. Possible return values are constants defined in the ControlDock class.

See Also setDock


 Control.getEnabled

Control.getEnabled

Retrieves a boolean value indicating whether this control is enabled.

Syntax

public boolean getEnabled()

Return Value

Returns true if the control is enabled; otherwise, returns false.

See Also setEnabled


 Control.getFocused

Control.getFocused

Retrieves a boolean value indicating whether the control has the focus.

Syntax

public boolean getFocused()

Return Value

Returns true if this control has the focus; otherwise, returns false.

See Also focus


 Control.getFont

Control.getFont

Retrieves the current font for this control, which is the font the control uses to draw its text.

Syntax

public Font getFont()

Return Value

Returns a Font object that represents the font used to draw text in this control. Returns the font for the control's parent if no font has been explicitly set for this control. Returns the default graphical user interface (GUI) font if no font has been explicitly set for this control or for this control's parent.

Remarks

This is an ambient property and will always return a non-null value.

See Also setFont


 Control.getForeColor

Control.getForeColor

Retrieves the current foreground color for this control, which is the color the control uses to draw its text.

Syntax

public Color getForeColor()

Return Value

Returns a Color object that represents the color used to draw text in this control. Returns the foreground color for the control's parent if no foreground color has been explicitly set for this control. Returns the default window text color if no foreground color has been explicitly set for this control or for this control's parent.

Remarks

This is an ambient property and will always return a non-null value.

See Also setForeColor


 Control.getForm

Control.getForm

Retrieves the form that this control is on.

Syntax

public Form getForm()

Return Value

Returns a Form object that represents the form that contains this control.

Remarks

The parent for a control is not necessarily the form. For example, the parent for a radio button in a group box is the group box, not the form that contains the radio button.


 Control.getHandle

Control.getHandle

Retrieves the window handle (HWND) that this control is bound to.

Syntax

public final int getHandle()

Return Value

Returns the HWND of the control.

Remarks

If the handle has not yet been created, this will force handle creation.


 Control.getHandleCreated

Control.getHandleCreated

Retrieves a boolean value indicating whether this control has a handle associated with it.

Syntax

public final boolean getHandleCreated()

Return Value

Returns true if this control has a handle associated with it; otherwise, returns false.


 Control.getHeight

Control.getHeight

Retrieves the height of this control.

Syntax

public final int getHeight()

Return Value

Returns an integer that represents the height, in pixels, of this control.

See Also getBounds, setHeight


 Control.getInputChar

Control.getInputChar

Retrieves a boolean value indicating whether the control processes the specified character itself.

Syntax

protected boolean getInputChar( char charCode )

Parameters

charCode

The character to test. You can specify a constant defined in the Key class for this parameter.

Return Value

Returns true if the control will process the character specified by charCode; returns false if the system will process the character.


 Control.getInputKey

Control.getInputKey

Retrieves a boolean value indicating whether the control processes the specified keyboard input.

Syntax

protected boolean getInputKey( int keyData )

Parameters

keyData

An integer that represents the keyboard input to test. You can specify a constant defined in the Key class for this parameter.

Return Value

Returns true if the control will process the keyboard input specified by keyData; returns false if the system will process the keyboard input.


 Control.getInvokeRequired

Control.getInvokeRequired

Determines whether the caller must call invoke when making method calls to this control.

Syntax

public final synchronized boolean getInvokeRequired()

Return Value

Returns true if the control's Win32 window handle is on a different thread from the calling thread, indicating that you should make calls to the control through the invoke method.

Remarks

Controls in WFC are bound to a specific thread and are not thread safe. Therefore, if you are calling a control's method from a different thread, you must use the control's invoke method to marshal the call to the proper thread. This function can be used to determine if you must call invoke, which can be useful if you don't know what thread owns a control.

There are four functions on a control that are safe to call from any thread: getInvokeRequired, invoke, invokeAsync, and createGraphics. For all other method calls, you should use one of the invokeXXX methods.

See Also Control.invoke, Control.invokeAsync


 Control.getLeft

Control.getLeft

Retrieves the distance between the left edge of the control and the left edge of its container's client area.

Syntax

public final int getLeft()

Return Value

Returns an integer that represents the distance, in pixels, between the left edge of the control and the left edge of its container's client area.

See Also getBounds , setLeft


 Control.getLocation

Control.getLocation

Retrieves coordinates of the upper-left corner of the control relative to the upper-left corner of its container's client area.

Syntax

public final Point getLocation()

Return Value

Returns a Point object that contains the coordinates of the upper-left corner of the control relative to the upper-left corner of its container's client area.

See Also getBounds , setLocation


 Control.getMnemonic

Control.getMnemonic

Retrieves a boolean value indicating whether the specified character is the mnemonic character in the specified string.

Syntax

public static final boolean getMnemonic( char charCode, String text )

Parameters

charCode

The character to test.

text

The string to search.

Return Value

Returns true if the character specified by charCode is the mnemonic character in the string specified by text.

Remarks

The mnemonic character is the character imediately following the first instance of the ampersand (&) in a string. The mnemonic character (also known as an access key), is the letter that appears underlined in the control. The user can press ALT+ the mnemonic character to activate the control.


 Control.getModifierKeys

Control.getModifierKeys

Retrieves a value indicating the current state of the SHIFT, CTRL, and ALT keys.

Syntax

public static final int getModifierKeys()

Return Value

Returns an integer that represents the status of the SHIFT, CTRL, and ALT keys. Possible return values are obtained by applying the bitwise OR operation (|) to the Key.SHIFT, Key.CONTROL, and Key.ALT constants defined in the Key class.


 Control.getMouseButtons

Control.getMouseButtons

Retrieves a value indicating the current state of the left, right, and middle mouse buttons.

Syntax

public static final int getMouseButtons()

Return Value

Returns an integer that represents the status of the left, right, and middle mouse buttons. Possible return values are obtained by applying the bitwise OR operation (|) to the MouseButton.LEFT, MouseButton.RIGHT, and MouseButton.MIDDLE constants defined in the MouseButton class.


 Control.getMousePosition

Control.getMousePosition

Retrieves the current position of the mouse in screen coordinates.

Syntax

public static final Point getMousePosition()

Return Value

Returns a Point object that contains the coordinates of the mouse pointer relative to the upper-left corner of the screen.


 Control.getNextControl

Control.getNextControl

Retrieves the control that follows or precedes the specified control in the tab order.

Syntax

public final Control getNextControl( Control ctl, boolean forward )

Parameters

ctl

A Control object that represents the control to start the search from.

forward

Set to true to search forward through the tab order from the specified control; set to false to search backward through the tab order.

Return Value

Returns a Control object that represents control immediately before or after the specified control in the tab order.


 Control.getPalette

Control.getPalette

Retrieves the palette associated with this control.

Syntax

public Palette getPalette()

Return Value

Returns a Palette object that represents the palette used to render this control.


 Control.getParent

Control.getParent

Retrieves the parent of this control.

Syntax

public final Control getParent()

Return Value

Returns a Control object that represents the parent control that contains this control. The parent for a control is not necessarily the form that contains it. To retrieve the form that contains a control, use the getForm method.

See Also setParent


 Control.getRecreatingHandle

Control.getRecreatingHandle

Retrieves a boolean value indicating whether the control is currently re-creating its handle.

Syntax

public final boolean getRecreatingHandle()

Return Value

Returns true if the control is currently re-creating its handle.


 Control.getRegion

Control.getRegion

Retrieves the region (the elliptical or polygonal area within a window) associated with this control.

Syntax

public final Region getRegion()

Return Value

Returns a Region object corresponding to the current shape of the control.

See Also setRegion


 Control.getRight

Control.getRight

Retrieves the distance between the right edge of the control and the left edge of its container's client area.

Syntax

public final int getRight()

Return Value

Returns an integer that represents the distance, in pixels, between the right edge of the control and the left edge of its container's client area. This value is equal to the value returned by the getLeft method plus the value returned by the getWidth method.

See Also getBounds


 Control.getSize

Control.getSize

Retrieves the height and width of the control.

Syntax

public final Point getSize()

Return Value

Returns a Point object that contains the dimensions of the the control. The Point.x field holds the control width; the Point.y field holds the height.

See Also setSize


 Control.getStyle

Control.getStyle

Retrieves the current value of the specified bit field in the control's style property.

Syntax

protected final boolean getStyle( int flag )

Parameters

flag

The bit field within the style property value that you want to check.

Return Value

Returns true if the bit field specified by the flag parameter is set in the control's style property; otherwise, returns false.

Remarks

This method retrieves values from the control's style property; it does not retrieve information from the windows styles or extended styles associated with the control's window handle.

See Also setStyle


 Control.getTabIndex

Control.getTabIndex

Retrieves the tab order of this control within the parent form.

Syntax

public final int getTabIndex()

Return Value

Returns the zero-based index of this control within the set of controls on the form that are included in the tab order. For a control to be included in the tab order, its tabStop property must be set to true.

See Also setTabIndex


 Control.getTabList

Control.getTabList

Retrieves all the child controls included in the tab order.

Syntax

public final Control[] getTabList()

Return Value

Returns a zero-based array of Control objects that represent all the child controls on the form that the user can give the focus to using the TAB key.


 Control.getTabStop

Control.getTabStop

Retrieves a boolean value indicating whether the user can give the focus to this control using the TAB key.

Syntax

public final boolean getTabStop()

Return Value

Returns true if the user can give the focus to this control using the TAB key; otherwise, returns false.

See Also setTabStop


 Control.getText

Control.getText

Retrieves the text associated with this control.

Syntax

public String getText()

Return Value

Returns a String object that represents the text associated with this control.

See Also setText


 Control.getTop

Control.getTop

Retrieves the distance between the top edge of the control and the top edge of its container's client area.

Syntax

public final int getTop()

Return Value

Returns an integer that represents the distance, in pixels, between the top edge of the control and the top edge of its container's client area.

See Also getBounds, setTop


 Control.getTopLevel

Control.getTopLevel

Retrieves a boolean value indicating whether this control is a top-level window (a window that has no parent window).

Syntax

public final boolean getTopLevel()

Return Value

Returns true if this control is a top-level window; otherwise, returns false.

See Also setTopLevel


 Control.getTopLevelControl

Control.getTopLevelControl

Retrieves the top-level control that contains this control.

Syntax

public final Control getTopLevelControl()

Return Value

Returns the top-level control that contains this control.

Remarks

This method does not necessarily return the same value as the getForm method because forms can have other controls as parents.


 Control.getVisible

Control.getVisible

Retrieves a boolean value indicating whether this control is visible.

Syntax

public final boolean getVisible()

Return Value

Returns true if the control is visible; otherwise, returns false.

See Also setVisible


 Control.getWidth

Control.getWidth

Retrieves the width of this control.

Syntax

public final int getWidth()

Return Value

Returns an integer that represents the width, in pixels, of this control.

See Also getBounds , setWidth


 Control.hide

Control.hide

Hides the control by setting the visible property to false.

Syntax

public final void hide()


 Control.invalidate

Control.invalidate

Invalidates the specified part of the control (adds it to the control's update region, which is the area that will be repainted at the next paint operation), and causes a paint message to be sent to the control.

Syntax

public final void invalidate()

public final void invalidate( Rectangle rc )

public final void invalidate( Region region )

Parameters

rc

A Rectangle object that represents the area to add to the update region.

region

A Region object that represents the area.

Remarks

Calling this method does not force a synchronous paint; to force a synchronous paint, call the update method after calling the invalidate method. If this method is called with no parameters, the entire client area is added to the update region.


 Control.invoke

Control.invoke

Executes the specified delegate on the thread that created the control's handle and returns when the delegate has completed execution.

Syntax

public final Object invoke( Delegate method )

public final Object invoke( Delegate method, Object args[] )

Parameters

method

A delegate to a method that takes parameters of the same number and type that are contained in args. The delegate can be an EventHandler object, in which case the sender parameter will contain this control, and the event parameter will contain Event.EMPTY. The delegate can also be a MethodInvoker object or any other delegate that takes a void parameter list. A call to an EventHandler or MethodInvoker delegate is faster than a call to another type of delegate.

args

An array of objects to pass as arguments to the specified method. This can be null if no arguments are needed.

Return Value

Returns the return value of the invoked delegate; returns null if the delegate has no return value.

Exceptions

WFCSystemException thrown if the control's thread is blocked.

Remarks

This method cannot be called if the control's handle hasn't been created yet or if the handle was created on the current thread. There are four functions on a control that are safe to call from any thread: getInvokeRequired, invoke, invokeAsync, and createGraphics. For all other method calls, you should use one of the invokeXXX methods to marshal the call to the control's thread.


 Control.invokeAsync

Control.invokeAsync

Executes the specified delegate on the thread that created the control's handle and returns immediately (because the delegate is invoked asynchronously).

Syntax

public final void invokeAsync( Delegate method )

public final void invokeAsync( Delegate method, Object args[] )

Parameters

method

A delegate to a method that takes no parameters.

method

A delegate to a method that takes parameters of the same number and type that are contained in args.

args

An array of objects to pass as arguments to the specified method. This can be null if no arguments are needed.

Exceptions

WFCSystemException thrown if the control's thread is blocked.

Remarks

This method cannot be called if the control's handle hasn't been created yet. There are four functions on a control that are safe to call from any thread: getInvokeRequired, invoke, invokeAsync, and createGraphics. For all other method calls, you should use one of the invokeXXX methods to marshal the call to the control's thread.


 Control.onClick

Control.onClick

Triggers the click event.

Syntax

protected void onClick( Event e )

Parameters

e

An Event object that provides the event data.

Remarks

When overriding this method, call super.onClick.

See Also addOnClick


 Control.onCreateHandle

Control.onCreateHandle

Triggers the createHandle event.

Syntax

protected void onCreateHandle( Event e )

Parameters

e

An Event object that provides the event data.

Remarks

Inheriting classes should override this method to determine when the handle has been created. When overriding this method, call super.onCreateHandle.

See Also addOnCreateHandle


 Control.onDestroyHandle

Control.onDestroyHandle

Triggers the destroyHandle event.

Syntax

protected void onDestroyHandle( Event e )

Parameters

e

An Event object that provides the event data.

Remarks

Inheriting classes should override this method to determine when the handle is about to be destroyed. When overriding this method, call super.onDestroyHandle.

See Also addOnDestroyHandle


 Control.onDoubleClick

Control.onDoubleClick

Triggers the doubleClick event.

Syntax

protected void onDoubleClick( Event e )

Parameters

e

An Event object that provides the event data.

Remarks

When overriding this method, call super.onDoubleClick.

See Also addOnDoubleClick


 Control.onDragDrop

Control.onDragDrop

Triggers the dragDrop event.

Syntax

protected void onDragDrop( DragEvent event )

Parameters

event

A DragEvent object that provides the event data.

Remarks

When overriding this method, call super.onDragDrop.

See Also addOnDragDrop


 Control.onDragEnter

Control.onDragEnter

Triggers the dragEnter event.

Syntax

protected void onDragEnter( DragEvent event )

Parameters

event

A DragEvent object that provides the event data.

Remarks

When overriding this method, call super.onDragEnter.

See Also addOnDragEnter


 Control.onDragLeave

Control.onDragLeave

Triggers the dragLeave event.

Syntax

protected void onDragLeave( Event event )

Parameters

event

An Event object that provides the event data.

Remarks

When overriding this method, call super.onDragLeave.

See Also addOnDragLeave


 Control.onDragOver

Control.onDragOver

Triggers the dragOver event.

Syntax

protected void onDragOver( DragEvent event )

Parameters

event

A DragEvent object that provides the event data.

Remarks

When overriding this method, call super.onDragOver.

See Also addOnDragOver


 Control.onEnter

Control.onEnter

Triggers the enter event.

Syntax

protected void onEnter( Event event )

Parameters

event

An Event object that provides the event data.

Remarks

When overriding this method, call super.onEnter.

See Also addOnEnter


 Control.onEraseBackground

Control.onEraseBackground

Triggers the eraseBackground event.

Syntax

protected void onEraseBackground( EraseBackgroundEvent event )

Parameters

event

An EraseBackgroundEvent object that provides the event data.

Remarks

When overriding this method, call super.onEraseBackground.


 Control.onGiveFeedback

Control.onGiveFeedback

Triggers the giveFeedback event.

Syntax

protected void onGiveFeedback( GiveFeedbackEvent event )

Parameters

event

A GiveFeedbackEvent object that provides the event data.

Remarks

When overriding this method, call super.onGiveFeedback.

See Also addOnGiveFeedback


 Control.onGotFocus

Control.onGotFocus

Triggers the gotFocus event.

Syntax

protected void onGotFocus( Event e )

Parameters

e

An Event object that provides the event data.

Remarks

When overriding this method, call super.onGotFocus.

See Also addOnGotFocus


 Control.onHelp

Control.onHelp

Triggers the help event.

Syntax

protected void onHelp( HelpEvent event )

Parameters

event

A HelpEvent object that provides the event data.

Remarks

When overriding this method, call super.onHelp.

See Also addOnHelp


 Control.onKeyDown

Control.onKeyDown

Triggers the keyDown event.

Syntax

protected void onKeyDown( KeyEvent e )

Parameters

e

A KeyEvent object that provides the event data.

Remarks

When overriding this method, call super.onKeyDown.

See Also addOnKeyDown


 Control.onKeyPress

Control.onKeyPress

Triggers the keyPress event.

Syntax

protected void onKeyPress( KeyPressEvent e )

Parameters

e

A KeyPressEvent object that provides the event data.

Remarks

When overriding this method, call super.onKeyPress.

See Also addOnKeyPress


 Control.onKeyUp

Control.onKeyUp

Triggers the keyUp event.

Syntax

protected void onKeyUp( KeyEvent e )

Parameters

e

A KeyEvent object that provides the event data.

Remarks

When overriding this method, call super.onKeyUp.

See Also addOnKeyUp


 Control.onLayout

Control.onLayout

Triggers the layout event.

Syntax

protected void onLayout( LayoutEvent event )

Parameters

event

A LayoutEvent object that provides the event data.

Remarks

Inheriting controls should override this function to do any custom layout logic. It is not neccessary to call super.onLayout. However, for normal docking and anchoring functions to work, you must call super.onLayout.

See Also addOnLayout


 Control.onLeave

Control.onLeave

Triggers the leave event.

Syntax

protected void onLeave( Event e )

Parameters

e

An Event object that provides the event data.

Remarks

When overriding this method, call super.onLeave.

See Also addOnLeave


 Control.onLostFocus

Control.onLostFocus

Triggers the lostFocus event.

Syntax

protected void onLostFocus( Event e )

Parameters

e

An Event object that provides the event data.

Remarks

When overriding this method, call super.onLostFocus.

See Also addOnLostFocus


 Control.onMouseDown

Control.onMouseDown

Triggers the mouseDown event.

Syntax

protected void onMouseDown( MouseEvent e )

Parameters

e

A MouseEvent object that provides the event data.

Remarks

When overriding this method, call super.onMouseDown.

See Also addOnMouseDown


 Control.onMouseEnter

Control.onMouseEnter

Triggers the mouseEnter event.

Syntax

protected void onMouseEnter( Event e )

Parameters

e

An Event object that provides the event data.

Remarks

When overriding this method, call super.onMouseEnter.

See Also addOnMouseEnter


 Control.onMouseLeave

Control.onMouseLeave

Triggers the mouseLeave event.

Syntax

protected void onMouseLeave( Event e )

Parameters

e

An Event object that provides the event data.

Remarks

When overriding this method, call super.onMouseLeave.

See Also addOnMouseLeave


 Control.onMouseMove

Control.onMouseMove

Triggers the mouseMove event.

Syntax

protected void onMouseMove( MouseEvent e )

Parameters

e

A MouseEvent object that provides the event data.

Remarks

When overriding this method, call super.onMouseMove.

See Also addOnMouseMove


 Control.onMouseUp

Control.onMouseUp

Triggers the mouseUp event.

Syntax

protected void onMouseUp( MouseEvent e )

Parameters

e

A MouseEvent object that provides the event data.

Remarks

When overriding this method, call super.onMouseUp.

See Also addOnMouseUp


 Control.onMouseWheel

Control.onMouseWheel

Triggers the mouseWheel event.

Syntax

protected void onMouseWheel( MouseEvent e )

Parameters

e

A MouseEvent object that provides the event data.

Remarks

When overriding this method, call super.onMouseWheel.

See Also addOnMouseWheel


 Control.onMove

Control.onMove

Triggers the move event.

Syntax

protected void onMove( Event e )

Parameters

e

An Event object that provides the event data.

Remarks

When overriding this method, call super.onMove.

See Also addOnMove


 Control.onPaint

Control.onPaint

Triggers the paint event.

Syntax

protected void onPaint( PaintEvent e )

Parameters

e

A PaintEvent object that provides the event data.

Remarks

When overriding this method, call super.onPaint.

See Also addOnPaint


 Control.onQueryContinueDrag

Control.onQueryContinueDrag

Triggers the queryContinueDrag event.

Syntax

protected void onQueryContinueDrag( QueryContinueDragEvent event )

Parameters

event

A QueryContinueDragEvent object that provides the event data.

Remarks

When overriding this method, call super.onQueryContinueDrag.

See Also addOnQueryContinueDrag


 Control.onResize

Control.onResize

Triggers the resize event.

Syntax

protected void onResize( Event e )

Parameters

e

An Event object that provides the event data.

Remarks

When overriding this method, call super.onResize.

See Also addOnResize


 Control.performLayout

Control.performLayout

Forces the control to apply layout logic to all its child controls.

Syntax

public final void performLayout()

public final void performLayout( Control affectedControl )

Parameters

affectedControl

A Control object that represents the most recently changed control.


 Control.pointToClient

Control.pointToClient

Converts the coordinates of a point from screen coordinates to client coordinates.

Syntax

public Point pointToClient( Point p )

Parameters

p

The Point object containing screen coordinates that you want to convert to client coordinates.

Return Value

Returns a Point object containing the client coordinates that correspond to the screen coordinates contained in p.


 Control.pointToScreen

Control.pointToScreen

Converts the coordinates of a point from client coordinates to screen coordinates.

Syntax

public Point pointToScreen( Point p )

Parameters

p

The Point object containing client coordinates that you want to convert to screen coordinates.

Return Value

Returns a Point object containing the screen coordinates that correspond to the client coordinates contained in p.


 Control.preProcessMessage

Control.preProcessMessage

This method is called by the application's message loop to preprocess input messages before they are dispatched.

Syntax

public boolean preProcessMessage( MSG msg )

Parameters

msg

The message to process. Possible values for the message field of the msg parameter are WM_KEYDOWN, WM_SYSKEYDOWN, WM_CHAR, and WM_SYSCHAR.

Return Value

Returns true if the method processes the message; otherwise, returns false. If the method processes the message, the message loop will not dispatch the message.

Remarks

For WM_KEYDOWN and WM_SYSKEYDOWN messages, the preProcessMessage method first calls the processCmdKey method to check for command keys such as accelerator keys. If the processCmdKey method doesn't process the message, the isInputKey method is called to check whether the key message represents an input key for the control. Finally, if the isInputKey method indicates that the control isn't interested in the key message, the processDialogKey method is called to check for dialog box keys such as the TAB key, arrow keys, and mnemonic characters.

For WM_CHAR messages, the preProcessMessage method first calls the isInputChar method to check whether the character message represents an input character for the control. If the isInputChar method indicates that the control isn't interested in the character message, the processDialogChar method is called to check for dialog box keys such as mnemonic characters. For WM_SYSCHAR messages, the preProcessMessage method calls the processDialogChar method to check dialog box keys such as mnemonic characters.

When overriding the preProcessMessage method, a control should return true to indicate that it has processed the message. For messages that aren't processed by the control, the control should return the result of the super.preProcessMessage method. Controls will typically override one of the more specialized methods (such as isInputChar, isInputKey, processCmdKey, processDialogChar, or processDialogKey) instead of overriding the preProcessMessage method.


 Control.processCmdKey

Control.processCmdKey

Processes a command key.

Syntax

protected boolean processCmdKey( MSG msg, int keyData )

Parameters

msg

The message to process. Possible values for the message field of the msg parameter are WM_KEYDOWN, WM_SYSKEYDOWN, WM_CHAR, and WM_SYSCHAR.

keyData

An integer that specifies the key code for the key the user pressed and indicates which, if any, of the CTRL, SHIFT, and ALT keys were pressed at the time.

Return Value

Returns true if the method processes the command key; returns false if the key that was pressed is not a command key.

Remarks

Command keys are keys that take precedence over regular input keys. Examples of command keys are shortcut keys and access keys. If this control has a shortcut menu (also known as a context menu), this method calls the processCmdKey method of the ContextMenu object that represents the shortcut menu to check for menu shortcuts. Finally, if the control has a parent, the key is passed to the parent's processCmdKey method. In this way, command keys are "bubbled" up the control hierarchy.

When overriding the processCmdKey method, a control should return true to indicate that it has processed the key. For keys that aren't processed by the control, the control should return the result of the super.processCmdKey method.


 Control.processDialogChar

Control.processDialogChar

Processes a dialog character, checking for mnemonics, and forwards the appropriate messages.

Syntax

protected boolean processDialogChar( char charCode )

Parameters

charCode

The character to process.

Return Value

Returns true if the character was used; otherwise, returns false.


 Control.processDialogKey

Control.processDialogKey

Processes a dialog key, checking for mnemonics, tabs, and arrows, and forwards the appropriate messages.

Syntax

protected boolean processDialogKey( int keyData )

Parameters

keyData

The key to process.

Return Value

Returns true if the key was used; otherwise, returns false.


 Control.processKeyEvent

Control.processKeyEvent

Processes a key message and generates the appropriate control events.

Syntax

protected boolean processKeyEvent( Message m )

Parameters

m

The Win32 message to process.

Return Value

Returns true if the message was handled.

Remarks

This handles double-byte character set (DBCS)/Unicode conversions.


 Control.processKeyMessage

Control.processKeyMessage

Processes a key message.

Syntax

protected boolean processKeyMessage( Message m )

Parameters

m

The Win32 message to process.

Return Value

Returns true if the message was handled; otherwise, returns false.

Remarks

When overriding the processKeyMessage method, a control should return true to indicate that it has processed the message. For messages that aren't processed by the control, the control should return the result of the super.processKeyMessage method.


 Control.processKeyPreview

Control.processKeyPreview

Processes key preview messages.

Syntax

protected boolean processKeyPreview( Message m )

Parameters

m

The Win32 message to process.

Return Value

Returns true if the message was handled.

Remarks

When overriding the processKeyPreview method, a control should return true to indicate that it has processed the message. For messages that aren't processed by the control, the control should return the result of the super.processKeyPreview method.


 Control.processMnemonic

Control.processMnemonic

Processes a mnemonic character.

Syntax

protected boolean processMnemonic( char charCode )

Parameters

charCode

The character to test.

Return Value

Returns true if the control used charCode as a mnemonic; otherwise, returns false.

Remarks

When overriding the processMnemonic method, a control should return true to indicate that it has used the specified character as a mnemonic. For characters that aren't used as mnemonics, the control should return the result of the super.processMnemonic method.


 Control.propertyChanged

Control.propertyChanged

This method is called by the control when any property changes.

Syntax

protected void propertyChanged( int property )

Parameters

property

The property that changed.

Remarks

Derived controls can override this method to get property change notification on basic properties. When overriding this method, call super.propertyChanged.


 Control.recreateHandle

Control.recreateHandle

Forces the re-creation of the handle for this control.

Syntax

protected synchronized void recreateHandle()

Remarks

When overriding this method, call super.recreateHandle.


 Control.rectToClient

Control.rectToClient

Converts the coordinates of a rectangle from screen coordinates to client coordinates.

Syntax

public Rectangle rectToClient( Rectangle r )

Parameters

r

The Rectangle object containing screen coordinates that you want to convert to client coordinates.

Return Value

Returns a Rectangle object containing the client coordinates that correspond to the screen coordinates contained in r.


 Control.rectToScreen

Control.rectToScreen

Converts the coordinates of a rectangle from client coordinates to screen coordinates.

Syntax

public Rectangle rectToScreen( Rectangle r )

Parameters

r

The Rectangle object containing client coordinates that you want to convert to screen coordinates.

Return Value

Returns a Rectangle object containing the screen coordinates that correspond to the client coordinates contained in r.


 Control.reflectMessage

Control.reflectMessage

Reflects the specified message to the control that is bound to the specified handle.

Syntax

protected final static boolean reflectMessage( int hWnd, Message m )

Parameters

hWnd

The handle to reflect the message to.

m

The Win32 message to reflect.

Return Value

Returns true if the message was reflected; otherwise, returns false.


 Control.remove

Control.remove

Removes the specified child control from this control.

Syntax

public void remove( Control control )

Parameters

control

Control to remove from this control.

Remarks

When overriding this method, call super.remove.

See Also add


 Control.removeOnClick

Control.removeOnClick

Removes the delegate that is assigned to the click event.

Syntax

public void removeOnClick( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnClick


 Control.removeOnCreateHandle

Control.removeOnCreateHandle

Removes the delegate that is assigned to the createHandle event.

Syntax

public final void removeOnCreateHandle( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnCreateHandle


 Control.removeOnDestroyHandle

Control.removeOnDestroyHandle

Removes the delegate that is assigned to the destroyHandle event.

Syntax

public final void removeOnDestroyHandle( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnDestroyHandle


 Control.removeOnDoubleClick

Control.removeOnDoubleClick

Removes the delegate that is assigned to the doubleClick event.

Syntax

public final void removeOnDoubleClick( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnDoubleClick


 Control.removeOnDragDrop

Control.removeOnDragDrop

Removes the delegate that is assigned to the dragDrop event.

Syntax

public final void removeOnDragDrop( DragEventHandler value )

Parameters

value

The DragEventHandler delegate to be removed.

See Also addOnDragDrop


 Control.removeOnDragEnter

Control.removeOnDragEnter

Removes the delegate that is assigned to the dragEnter event.

Syntax

public final void removeOnDragEnter( DragEventHandler value )

Parameters

value

The DragEventHandler delegate to be removed.

See Also addOnDragEnter


 Control.removeOnDragLeave

Control.removeOnDragLeave

Removes the delegate that is assigned to the dragLeave event.

Syntax

public final void removeOnDragLeave( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnDragLeave


 Control.removeOnDragOver

Control.removeOnDragOver

Removes the delegate that is assigned to the dragOver event.

Syntax

public final void removeOnDragOver( DragEventHandler value )

Parameters

value

The DragEventHandler delegate to be removed.

See Also addOnDragOver


 Control.removeOnEnter

Control.removeOnEnter

Removes the delegate that is assigned to the enter event.

Syntax

public final void removeOnEnter( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnEnter


 Control.removeOnGiveFeedback

Control.removeOnGiveFeedback

Removes the delegate that is assigned to the giveFeedback event.

Syntax

public final void removeOnGiveFeedback( GiveFeedbackEventHandler value )

Parameters

value

The GiveFeedbackEventHandler delegate to be removed.

See Also addOnGiveFeedback


 Control.removeOnGotFocus

Control.removeOnGotFocus

Removes the delegate that is assigned to the gotFocus event.

Syntax

public final void removeOnGotFocus( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnGotFocus


 Control.removeOnHelp

Control.removeOnHelp

Removes the delegate that is assigned to the help event.

Syntax

public final void removeOnHelp( HelpEventHandler value )

Parameters

value

The HelpEventHandler delegate to be removed.

See Also addOnHelp


 Control.removeOnKeyDown

Control.removeOnKeyDown

Removes the delegate that is assigned to the keyDown event.

Syntax

public final void removeOnKeyDown( KeyEventHandler value )

Parameters

value

The KeyEventHandler delegate to be removed.

See Also addOnKeyDown


 Control.removeOnKeyPress

Control.removeOnKeyPress

Removes the delegate that is assigned to the keyPress event.

Syntax

public final void removeOnKeyPress( KeyPressEventHandler value )

Parameters

value

The KeyPressEventHandler delegate to be removed.

See Also addOnKeyPress


 Control.removeOnKeyUp

Control.removeOnKeyUp

Removes the delegate that is assigned to the keyUp event.

Syntax

public final void removeOnKeyUp( KeyEventHandler value )

Parameters

value

The KeyEventHandler delegate to be removed.

See Also addOnKeyUp


 Control.removeOnLayout

Control.removeOnLayout

Removes the delegate that is assigned to the layout event.

Syntax

public final void removeOnLayout( LayoutEventHandler value )

Parameters

value

The LayoutEventHandler delegate to be removed.

See Also addOnLayout


 Control.removeOnLeave

Control.removeOnLeave

Removes the delegate that is assigned to the leave event.

Syntax

public final void removeOnLeave( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnLeave


 Control.removeOnLostFocus

Control.removeOnLostFocus

Removes the delegate that is assigned to the lostFocus event.

Syntax

public final void removeOnLostFocus( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnLostFocus


 Control.removeOnMouseDown

Control.removeOnMouseDown

Removes the delegate that is assigned to the mouseDown event.

Syntax

public final void removeOnMouseDown( MouseEventHandler value )

Parameters

value

The MouseEventHandler delegate to be removed.

See Also addOnMouseDown


 Control.removeOnMouseEnter

Control.removeOnMouseEnter

Removes the delegate that is assigned to the mouseEnter event.

Syntax

public final void removeOnMouseEnter( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnMouseEnter


 Control.removeOnMouseLeave

Control.removeOnMouseLeave

Removes the delegate that is assigned to the mouseLeave event.

Syntax

public final void removeOnMouseLeave( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnMouseLeave


 Control.removeOnMouseMove

Control.removeOnMouseMove

Removes the delegate that is assigned to the mouseMove event.

Syntax

public final void removeOnMouseMove( MouseEventHandler value )

Parameters

value

The MouseEventHandler delegate to be removed.

See Also addOnMouseMove


 Control.removeOnMouseUp

Control.removeOnMouseUp

Removes the delegate that is assigned to the mouseUp event.

Syntax

public final void removeOnMouseUp( MouseEventHandler value )

Parameters

value

The MouseEventHandler delegate to be removed.

See Also addOnMouseUp


 Control.removeOnMouseWheel

Control.removeOnMouseWheel

Removes the delegate that is assigned to the mouseWheel event.

Syntax

public final void removeOnMouseWheel( MouseEventHandler value )

Parameters

value

The MouseEventHandler delegate to be removed.

See Also addOnMouseWheel


 Control.removeOnMove

Control.removeOnMove

Removes the delegate that is assigned to the move event.

Syntax

public final void removeOnMove( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnMove


 Control.removeOnPaint

Control.removeOnPaint

Removes the delegate that is assigned to the paint event.

Syntax

public final void removeOnPaint( PaintEventHandler value )

Parameters

value

The PaintEventHandler delegate to be removed.

See Also addOnPaint


 Control.removeOnQueryContinueDrag

Control.removeOnQueryContinueDrag

Removes the delegate that is assigned to the queryContinueDrag event.

Syntax

public final void removeOnQueryContinueDrag( QueryContinueDragEventHandler value )

Parameters

value

The QueryContinueDragEventHandler delegate to be removed.

See Also addOnQueryContinueDrag


 Control.removeOnResize

Control.removeOnResize

Removes the delegate that is assigned to the resize event.

Syntax

public final void removeOnResize( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnResize


 Control.resetBackColor

Control.resetBackColor

Resets the background color of the control to the parent's background color.

Syntax

public void resetBackColor()

See Also getBackColor


 Control.resetFont

Control.resetFont

Resets the font for the control to the parent's font.

Syntax

public void resetFont()

See Also getFont


 Control.resetForeColor

Control.resetForeColor

Resets the foreground color of the control to the parent's foreground color.

Syntax

public void resetForeColor()

See Also getForeColor


 Control.resumeLayout

Control.resumeLayout

Resumes normal layout logic.

Syntax

public final void resumeLayout()

protected final void resumeLayout( boolean performLayout )

Parameters

performLayout

Set to true if pending layout requests are immediately executed; set to false if pending layout requests are ignored.

Remarks

Calling this method forces an immediate layout if there are any pending layout requests. Also, calling this method with the performLayout parameter set to true forces an immediate layout if there are any pending layout requests.


 Control.scale

Control.scale

Scales the entire control and any child controls.

Syntax

public final void scale( float ratio )

public final void scale( float dx, float dy )

Parameters

dx

The ratio by which to scale the control horizontally.

dy

The ratio by which to scale the control vertically.

ratio

The ratio by which to scale the control horizontally and vertically.


 Control.scaleCore

Control.scaleCore

Performs the work of scaling the entire control and any child controls.

Syntax

protected void scaleCore( float dx, float dy )

Parameters

dx

The ratio by which to scale the control horizontally.

dy

The ratio by which to scale the control vertically.


 Control.select

Control.select

Activates this control.

Syntax

public final void select()


 Control.selectNextControl

Control.selectNextControl

Selects the control that follows or precedes the specified control in the tab order.

Syntax

public final boolean selectNextControl( Control ctl, boolean forward, boolean tabStopOnly, boolean nested, boolean wrap )

Parameters

ctl

A Control object that represents the control to start the search from.

forward

Set to true to search forward through the tab order from the specified control; set to false to search backward through the tab order.

tabStopOnly

Set to true to include only controls whose tabStop property is set to true; set to false to include all controls in the search.

nested

Set to true if nested children of this control are included in the search; set to false if only direct children of this control are included.

wrap

Set to true to start searching at the beginning of the tab order when the end of the tab order is reached; set to false to stop searching at the end of the tab order.

Return Value

Returns true if a control was selected; otherwise, returns false.


 Control.sendMessage

Control.sendMessage

Sends the specified Win32 message to this control.

Syntax

public final int sendMessage( int msg, int wParam, int lParam )

protected final int sendMessage( int msg, int wParam, Object lParam )

protected final int sendMessage( int msg, Object wParam, Object lParam )

Parameters

msg

The Win32 message to send.

wParam

The wParam to send with the message.

lParam

The lParam to send with the message.

Return Value

Returns an integer that represents the result of the message processing.


 Control.sendToBack

Control.sendToBack

Sends this control to the back of the z-order.

Syntax

public final void sendToBack()


 Control.setAllowDrop

Control.setAllowDrop

Sets a boolean value indicating whether this control can accept data that the user drags and drops into it.

Syntax

public final void setAllowDrop( boolean allowDrop )

Parameters

allowDrop

Set to true if the control is a valid drop target; otherwise, set to false.

See Also getAllowDrop


 Control.setAnchor

Control.setAnchor

Sets a value indicating which edges of the control are anchored to the edges of its container.

Syntax

public final void setAnchor( int value )

Parameters

value

An integer that represents how a control is anchored to the edges of its container. Possible values are constants defined in the ControlAnchor class.

Exceptions

WFCInvalidEnumException thrown if the specified value is not a valid ControlAnchor constant.

See Also getAnchor


 Control.setBackColor

Control.setBackColor

Sets the background color for this control.

Syntax

public void setBackColor( Color value )

Parameters

value

A Color object that represents the background color for this control. Specifying null for this parameter sets the control's background color to its parent's background color.

See Also getBackColor


 Control.setBounds

Control.setBounds

Sets the bounding rectangle for the control.

Syntax

public final void setBounds( Rectangle value )

public final void setBounds( int x, int y, int width, int height )

Parameters

x

An integer that represents the distance, in pixels, between the left edge of the control and the left edge of its container's client area.

y

An integer that represents the distance, in pixels, between the right edge of the control and the left edge of its container's client area.

value

A Rectangle object that represents the bounding rectangle for the control.

width

An integer that represents the width, in pixels, of this control.

height

An integer that represents the height, in pixels, of this control.

See Also getBounds


 Control.setBoundsCore

Control.setBoundsCore

Performs the work of setting the bounds of this control.

Syntax

protected void setBoundsCore( int x, int y, int width, int height )

Parameters

x

An integer that represents the distance, in pixels, between the left edge of the control and the left edge of its container's client area.

y

An integer that represents the distance, in pixels, between the right edge of the control and the left edge of its container's client area.

width

An integer that represents the width, in pixels, of this control.

height

An integer that represents the height, in pixels, of this control.

Remarks

Derived classes can override this function to add size restrictions. Derived classes must call super.setBoundsCore to actually cause the bounds of the control to change.


 Control.setBrush

Control.setBrush

Sets the brush for this control.

Syntax

public void setBrush( Brush br )

Parameters

br

A Brush object that represents the brush for this control.

See Also getBrush


 Control.setCapture

Control.setCapture

Sets a boolean value indicating whether this control has captured the mouse.

Syntax

public final void setCapture( boolean value )

Parameters

value

Set to true if this control has captured the mouse; otherwise, set to false.

Remarks

When a control has captured the mouse, it receives mouse input whether or not the cursor is within its borders.

See Also getCapture


 Control.setClientSize

Control.setClientSize

Sets the height and width of the client area of the control.

Syntax

public final void setClientSize( Point size )

public final void setClientSize( int x, int y )

Parameters

size

A Point object that contains the dimensions of the client area of the control. The Point.x field holds the client area width; the Point.y field holds the height.

x

An integer that represents the client area width.

y

An integer that represents the client area height.

See Also getClientSize


 Control.setClientSizeCore

Control.setClientSizeCore

Performs the work of setting the size of the client area of the control.

Syntax

protected void setClientSizeCore( int x, int y )

Parameters

x

An integer that represents the client area width.

y

An integer that represents the client area height.


 Control.setContextMenu

Control.setContextMenu

Sets the shortcut menu (also known as a context menu) associated with this control.

Syntax

public final void setContextMenu( ContextMenu contextMenu )

Parameters

contextMenu

The ContextMenu object that represents the shortcut menu that appears when the user right-clicks this control.

Remarks

The shortcut menu is the menu that appears when the user right-clicks the control.

See Also getContextMenu


 Control.setControlIndex

Control.setControlIndex

Sets the zero-based index of the specified child control within the parent's control array.

Syntax

public final void setControlIndex( int value )

Parameters

value

The zero-based index that you want this control to have.

See Also getControlIndex


 Control.setControls

Control.setControls

Sets the array of the child controls contained in this control.

Syntax

public final void setControls( Control[] value )

Parameters

value

An array of Control objects that represents the child controls contained in this control.

See Also getControls


 Control.setCursor

Control.setCursor

Sets the cursor that is displayed when the user moves the mouse pointer over this control.

Syntax

public final void setCursor( Cursor value )

Parameters

value

A Cursor that represents the control cursor.

See Also getCursor


 Control.setDock

Control.setDock

Sets a value indicating which edge of its container this control is docked to.

Syntax

public void setDock( int value )

Parameters

value

An integer that represents which edge of its container this control is docked to. Possible values are constants defined in the ControlDock class.

Exceptions

WFCInvalidEnumException thrown if the specified value is not a valid ControlDock constant.

See Also getDock


 Control.setEnabled

Control.setEnabled

Sets a boolean value indicating whether this control is enabled.

Syntax

public void setEnabled( boolean enabled )

Parameters

enabled

Set to true to enable the control; otherwise, set to false.

See Also getEnabled


 Control.setFont

Control.setFont

Sets the font for this control, which is the font the control uses to draw its text.

Syntax

public void setFont( Font value )

Parameters

value

A Font object that represents the font used to draw text in this control.

See Also getFont


 Control.setForeColor

Control.setForeColor

Sets the current foreground color for this control, which is the color the control uses to draw its text.

Syntax

public void setForeColor( Color value )

Parameters

value

A Color object that represents the color used to draw text in this control.

See Also getForeColor


 Control.setHeight

Control.setHeight

Sets the height of this control.

Syntax

public final void setHeight( int value )

Parameters

value

An integer that represents the height, in pixels, of this control.

See Also getBounds , getHeight


 Control.setLeft

Control.setLeft

Sets the distance between the left edge of the control and the left edge of its container's client area.

Syntax

public final void setLeft( int value )

Parameters

value

An integer that represents the distance, in pixels, between the left edge of the control and the left edge of its container's client area.

See Also getBounds , getLeft


 Control.setLocation

Control.setLocation

Sets coordinates of the upper-left corner of the control relative to the upper-left corner of its container's client area.

Syntax

public final void setLocation( int x, int y )

public final void setLocation( Point value )

Parameters

x

An integer that represents the distance, in pixels, between the left edge of the control and the left edge of its container's client area.

y

An integer that represents the distance, in pixels, between the right edge of the control and the left edge of its container's client area.

value

A Point object that contains the coordinates of the upper-left corner of the control. The Point.x field holds the x-coordinate; the Point.y field holds the y-coordinate.

See Also getBounds , getLocation


 Control.setNewControls

Control.setNewControls

Performs the work of setting the array of the child controls contained in this control.

Syntax

public void setNewControls( Control[] value )

Parameters

value

An array of Control objects that represents the child controls contained in this control.


 Control.setParent

Control.setParent

Sets the parent for this control.

Syntax

public final void setParent( Control value )

Parameters

value

A Control object that represents the control you want to be the parent of this control. Setting this parameter to null removes this control from the child list of its current parent.

See Also getParent


 Control.setRegion

Control.setRegion

Sets the region (the elliptical or polygonal area within a window) associated with this control.

Syntax

public final void setRegion( Region region )

Parameters

region

A Region object corresponding to the shape of the control.

See Also getRegion


 Control.setSize

Control.setSize

Sets the height and width of the control.

Syntax

public final void setSize( int width, int height )

public final void setSize( Point value )

Parameters

width

The control width.

height

The control height.

value

A Point object that contains the dimensions of the the control. The Point.x field holds the control width; the Point.y field holds the height.

See Also getSize


 Control.setStyle

Control.setStyle

Sets the value of the specified bit field in the control's style property.

Syntax

protected final void setStyle( int flag, boolean value )

Parameters

flag

The bit field within the style property value that you want to set.

value

Set to true to turn on the specified bit field in the style property; set to false to turn off the specified bit field.

See Also getStyle


 Control.setTabIndex

Control.setTabIndex

Sets the tab order of this control within the parent form.

Syntax

public final void setTabIndex( int value )

Parameters

value

The zero-based index of this control within the set of controls on the form that are included in the tab order. If you specify a negative number for this parameter, the control will be the first control in the tab order. If you specify a number greater than the number of controls in the container - 1, the control will be the last control in the tab order. For a control to be included in the tab order, its tabStop property must be set to true.

See Also getTabIndex


 Control.setTabStop

Control.setTabStop

Sets a boolean value indicating whether the user can give the focus to this control using the TAB key.

Syntax

public final void setTabStop( boolean value )

Parameters

value

Set to true if the user can give the focus to this control using the TAB key; otherwise, set to false.

See Also getTabStop


 Control.setText

Control.setText

Sets the text associated with this control.

Syntax

public void setText( String value )

Parameters

value

A String object that represents the text associated with this control.

See Also getText


 Control.setTop

Control.setTop

Sets the distance between the top edge of the control and the top edge of its container's client area.

Syntax

public final void setTop( int value )

Parameters

value

An integer that represents the distance, in pixels, between the top edge of the control and the top edge of its container's client area.

See Also getBounds, getTop


 Control.setTopLevel

Control.setTopLevel

Sets a boolean value indicating whether this control is a top-level window (a window that has no parent window).

Syntax

public void setTopLevel( boolean value )

Parameters

value

Set to true if this control is a top-level window; otherwise, set to false.

Exceptions

WFCException thrown if this control has a parent.

See Also getTopLevel


 Control.setVisible

Control.setVisible

Sets a boolean value indicating whether this control is visible.

Syntax

public void setVisible( boolean value )

Parameters

value

Set to true if the control is visible; otherwise, set to false.

See Also getVisible


 Control.setWidth

Control.setWidth

Sets the width of this control.

Syntax

public final void setWidth( int value )

Parameters

value

An integer that represents the width, in pixels, of this control.

See Also getBounds, getWidth


 Control.shouldPersistBackColor

Control.shouldPersistBackColor

Retrieves a boolean value indicating whether the background color for the control has been explicitly set.

Syntax

public boolean shouldPersistBackColor()

Return Value

Returns true if the background color for the control has been explicitly set; returns false if the control is using a default background color (either the background color set for its parent or the default system brush).


 Control.shouldPersistFont

Control.shouldPersistFont

Retrieves a boolean value indicating whether the background color for the control has been explicitly set.

Syntax

public boolean shouldPersistFont()

Return Value

Returns true if the font for the control has been explicitly set; returns false if the control is using a default font (either the font set for its parent or the default GUI font).


 Control.shouldPersistForeColor

Control.shouldPersistForeColor

Retrieves a boolean value indicating whether the background color for the control has been explicitly set.

Syntax

public boolean shouldPersistForeColor()

Return Value

Returns true if the foreground color for the control has been explicitly set; returns false if the control is using a default foreground color (either the foreground color set for its parent or the default window text color).


 Control.show

Control.show

Displays the control by setting the visible property to true.

Syntax

public final void show()


 Control.suspendLayout

Control.suspendLayout

Suspends the layout logic for the control.

Syntax

public final void suspendLayout()


 Control.update

Control.update

Forces the control to paint its update region (regions that have been marked as needing repainting).

Syntax

public final void update()

See Also invalidate


 Control.updateBounds

Control.updateBounds

Updates the bounding rectangle of the control based on the handle the control is bound to.

Syntax

protected final void updateBounds()

protected final void updateBounds( int x, int y, int width, int height )

protected final void updateBounds( int x, int y, int width, int height, int clientWidth, int clientHeight )

Parameters

x

An integer that represents the distance, in pixels, between the left edge of the control and the left edge of its container's client area.

y

An integer that represents the distance, in pixels, between the right edge of the control and the left edge of its container's client area.

width

An integer that represents the width, in pixels, of this control.

height

An integer that represents the height, in pixels, of this control.

clientWidth

An integer that represents the width, in pixels, of the client area of this control.

clientHeight

An integer that represents the height, in pixels, of the client area of this control.


 Control.updateStyles

Control.updateStyles

Forces styles to be reapplied to the handle without recreating the handle.

Syntax

protected final void updateStyles()

Remarks

This method calls the getCreateParams method to determine which styles to apply.


 Control.updateZOrder

Control.updateZOrder

Updates this control's position within its parent's z-order.

Syntax

protected final void updateZOrder()


 Control Fields

Control Fields

Fields | Description
defaultBrush | Specifies that the default brush for the control is the brush defined in Brush.CONTROL.
PROP_BACKCOLOR | Specifies that the value of the backColor property has changed.
PROP_CURSOR | Specifies that the value of the cursor property has changed.
PROP_ENABLED | Specifies that the value of the enabled property has changed.
PROP_FONT | Specifies that the value of the font property has changed.
PROP_FORECOLOR | Specifies that the value of the foreColor property has changed.
PROP_LOCATION | Specifies that the value of the location property has changed.
PROP_PARENTBACKCOLOR | Specifies that the value of the parent's backColor property has changed.
PROP_PARENTFONT | Specifies that the value of the parent's font property has changed.
PROP_PARENTFORECOLOR | Specifies that the value of the parent's foreColor property has changed.
PROP_SIZE | Specifies that the value of the size property has changed.
PROP_TABSTOP | Specifies that the value of the tabStop property has changed.
PROP_TEXT | Specifies that the value of the text property has changed.
PROP_VISIBLE | Specifies that the value of the visible property has changed.
STYLE_ACCEPTSCHILDREN | Specifies that the control accepts children.
STYLE_FIXED_HEIGHT | Specifies that the control has a fixed height.
STYLE_FIXED_WIDTH | Specifies that the control has a fixed width.
STYLE_FORM | Specifies that the control is a container for other controls.
STYLE_OPAQUE | Specifies that the background will be erased when the control is repainted.
STYLE_OPTIMIZE_SIZEPAINT | Specifies that the background will be erased when the control is repainted after being resized.
STYLE_RESIZE_REDRAW | Specifies that the control redraws when it is resized.
STYLE_STDCLICK | Specifies that the control receives standard click events.
STYLE_USERPAINT | Specifies that the control does its own painting.


 Control.defaultBrush

Control.defaultBrush

Specifies that the default brush for the control is the brush defined in Brush.CONTROL.

Syntax

protected static final Brush defaultBrush;


 Control.PROP_BACKCOLOR

Control.PROP_BACKCOLOR

Specifies that the value of the backColor property has changed.

Syntax

protected static final int PROP_BACKCOLOR;


 Control.PROP_CURSOR

Control.PROP_CURSOR

Specifies that the value of the cursor property has changed.

Syntax

protected static final int PROP_CURSOR;


 Control.PROP_ENABLED

Control.PROP_ENABLED

Specifies that the value of the enabled property has changed.

Syntax

protected static final int PROP_ENABLED;


 Control.PROP_FONT

Control.PROP_FONT

Specifies that the value of the font property has changed.

Syntax

protected static final int PROP_FONT;


 Control.PROP_FORECOLOR

Control.PROP_FORECOLOR

Specifies that the value of the foreColor property has changed.

Syntax

protected static final int PROP_FORECOLOR;


 Control.PROP_LOCATION

Control.PROP_LOCATION

Specifies that the value of the location property has changed.

Syntax

protected static final int PROP_LOCATION;


 Control.PROP_PARENTBACKCOLOR

Control.PROP_PARENTBACKCOLOR

Specifies that the value of the parent's backColor property has changed.

Syntax

protected static final int PROP_PARENTBACKCOLOR;


 Control.PROP_PARENTFONT

Control.PROP_PARENTFONT

Specifies that the value of the parent's font property has changed.

Syntax

protected static final int PROP_PARENTFONT;


 Control.PROP_PARENTFORECOLOR

Control.PROP_PARENTFORECOLOR

Specifies that the value of the parent's foreColor property has changed.

Syntax

protected static final int PROP_PARENTFORECOLOR;


 Control.PROP_SIZE

Control.PROP_SIZE

Specifies that the value of the size property has changed.

Syntax

protected static final int PROP_SIZE;


 Control.PROP_TABSTOP

Control.PROP_TABSTOP

Specifies that the value of the tabStop property has changed.

Syntax

protected static final int PROP_TABSTOP;


 Control.PROP_TEXT

Control.PROP_TEXT

Specifies that the value of the text property has changed.

Syntax

protected static final int PROP_TEXT;


 Control.PROP_VISIBLE

Control.PROP_VISIBLE

Specifies that the value of the visible property has changed.

Syntax

protected static final int PROP_VISIBLE;


 Control.STYLE_ACCEPTSCHILDREN

Control.STYLE_ACCEPTSCHILDREN

Specifies that the control accepts children.

Syntax

protected static final int STYLE_ACCEPTSCHILDREN;


 Control.STYLE_FIXED_HEIGHT

Control.STYLE_FIXED_HEIGHT

Specifies that the control has a fixed height.

Syntax

protected static final int STYLE_FIXED_HEIGHT;


 Control.STYLE_FIXED_WIDTH

Control.STYLE_FIXED_WIDTH

Specifies that the control has a fixed width.

Syntax

protected static final int STYLE_FIXED_WIDTH;


 Control.STYLE_FORM

Control.STYLE_FORM

Specifies that the control is a container for other controls.

Syntax

protected static final int STYLE_FORM;


 Control.STYLE_OPAQUE

Control.STYLE_OPAQUE

Specifies that the background will be erased when the control is repainted.

Syntax

protected static final int STYLE_OPAQUE;


 Control.STYLE_OPTIMIZE_SIZEPAINT

Control.STYLE_OPTIMIZE_SIZEPAINT

Specifies that the background will be erased when the control is repainted after being resized.

Syntax

protected static final int STYLE_OPTIMIZE_SIZEPAINT;


 Control.STYLE_RESIZE_REDRAW

Control.STYLE_RESIZE_REDRAW

Specifies that the control redraws when it is resized.

Syntax

protected static final int STYLE_RESIZE_REDRAW;


 Control.STYLE_STDCLICK

Control.STYLE_STDCLICK

Specifies that the control receives standard click events.

Syntax

protected static final int STYLE_STDCLICK;


 Control.STYLE_USERPAINT

Control.STYLE_USERPAINT

Specifies that the control does its own painting.

Syntax

protected static final int STYLE_USERPAINT;


ControlAnchor Class

Defines constants that specify how a control is anchored to the edges of its container.

Enum
  |
  +--ControlAnchor

package com.ms.wfc.ui

public class ControlAnchor
extends Enum

Remarks

When a control is anchored to an edge of its container, the distance between the control and the specified edge remains constant when the container resizes. For example, if a control is anchored to the right edge of its container, the distance between the right edge of the control and the right edge of the container remains constant when the container resizes. A control can be anchored to any combination of the edges of a control. If the control is anchored to opposite edges of its container (for example, to the top and bottom), it resizes when the container resizes.


 ControlAnchor Methods

ControlAnchor Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 ControlAnchor.valid

ControlAnchor.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int anchor )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 ControlAnchor Fields

ControlAnchor Fields

Fields | Description
ALL | Specifies that the control is anchored to all edges of its container.
BOTTOM | Specifies that the control is anchored to the bottom edge of its container.
BOTTOMLEFT | Specifies that the control is anchored to the bottom and left edges of its container.
BOTTOMLEFTRIGHT | Specifies that the control is anchored to the left, bottom, and right edges of its container.
BOTTOMRIGHT | Specifies that the control is anchored to the bottom and right edges of its container.
LEFT | Specifies that the control is anchored to the left edge of its container.
LEFTRIGHT | Specifies that the control is anchored to the left and right edges of its container.
NONE | Specifies that the control not anchored to any of the edges of its container.
RIGHT | Specifies that the control is anchored to the right edge of its container.
TOP | Specifies that the control is anchored to the top edge of its container.
TOPBOTTOM | Specifies that the control is anchored to the top and bottom edges of its container.
TOPBOTTOMLEFT | Specifies that the control is anchored to the top, left, and bottom edges of its container.
TOPBOTTOMRIGHT | Specifies that the control is anchored to the top, right, and bottom edges of its container.
TOPLEFT | Specifies that the control is anchored to the top and left edges of its container.
TOPLEFTRIGHT | Specifies that the control is anchored to the top, left, and right edges of its container.
TOPRIGHT | Specifies that the control is anchored to the top and right edges of its container.


 ControlAnchor.ALL

ControlAnchor.ALL

Specifies that the control is anchored to all edges of its container.

Syntax

public static final int ALL;


 ControlAnchor.BOTTOM

ControlAnchor.BOTTOM

Specifies that the control is anchored to the bottom edge of its container.

Syntax

public static final int BOTTOM;


 ControlAnchor.BOTTOMLEFT

ControlAnchor.BOTTOMLEFT

Specifies that the control is anchored to the bottom and left edges of its container.

Syntax

public static final int BOTTOMLEFT;


 ControlAnchor.BOTTOMLEFTRIGHT

ControlAnchor.BOTTOMLEFTRIGHT

Specifies that the control is anchored to the left, bottom, and right edges of its container.

Syntax

public static final int BOTTOMLEFTRIGHT;


 ControlAnchor.BOTTOMRIGHT

ControlAnchor.BOTTOMRIGHT

Specifies that the control is anchored to the bottom and right edges of its container.

Syntax

public static final int BOTTOMRIGHT;


 ControlAnchor.LEFT

ControlAnchor.LEFT

Specifies that the control is anchored to the left edge of its container.

Syntax

public static final int LEFT;


 ControlAnchor.LEFTRIGHT

ControlAnchor.LEFTRIGHT

Specifies that the control is anchored to the left and right edges of its container.

Syntax

public static final int LEFTRIGHT;


 ControlAnchor.NONE

ControlAnchor.NONE

Specifies that the control not anchored to any of the edges of its container.

Syntax

public static final int NONE;


 ControlAnchor.RIGHT

ControlAnchor.RIGHT

Specifies that the control is anchored to the right edge of its container.

Syntax

public static final int RIGHT;


 ControlAnchor.TOP

ControlAnchor.TOP

Specifies that the control is anchored to the top edge of its container.

Syntax

public static final int TOP;


 ControlAnchor.TOPBOTTOM

ControlAnchor.TOPBOTTOM

Specifies that the control is anchored to the top and bottom edges of its container.

Syntax

public static final int TOPBOTTOM;


 ControlAnchor.TOPBOTTOMLEFT

ControlAnchor.TOPBOTTOMLEFT

Specifies that the control is anchored to the top, left, and bottom edges of its container.

Syntax

public static final int TOPBOTTOMLEFT;


 ControlAnchor.TOPBOTTOMRIGHT

ControlAnchor.TOPBOTTOMRIGHT

Specifies that the control is anchored to the top, right, and bottom edges of its container.

Syntax

public static final int TOPBOTTOMRIGHT;


 ControlAnchor.TOPLEFT

ControlAnchor.TOPLEFT

Specifies that the control is anchored to the top and left edges of its container.

Syntax

public static final int TOPLEFT;


 ControlAnchor.TOPLEFTRIGHT

ControlAnchor.TOPLEFTRIGHT

Specifies that the control is anchored to the top, left, and right edges of its container.

Syntax

public static final int TOPLEFTRIGHT;


 ControlAnchor.TOPRIGHT

ControlAnchor.TOPRIGHT

Specifies that the control is anchored to the top and right edges of its container.

Syntax

public static final int TOPRIGHT;


ControlDock Class

Defines constants that specify how a control is docked to the edges of its container.

Enum
  |
  +--ControlDock

package com.ms.wfc.ui

public class ControlDock
extends Enum

Remarks

When a control is docked to the edge of its container, it remains in contact with that edge when the container resizes. If multiple controls are docked to the some edge, one is docked to the edge of the container, and the others are docked as close as possible to the edge without covering each other.


 ControlDock Methods

ControlDock Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 ControlDock.valid

ControlDock.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int dock )

Parameters

dock

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 ControlDock Fields

ControlDock Fields

Fields | Description
BOTTOM | Specifies that the control is docked to the bottom edge of its container.
FILL | Specifies that the control is docked to the center of its container.
LEFT | Specifies that the control is docked to the left edge of its container.
NONE | Specifies that the control is not docked.
RIGHT | Specifies that the control is docked to the right edge of its container.
TOP | Specifies that the control is docked to the top edge of its container.


 ControlDock.BOTTOM

ControlDock.BOTTOM

Specifies that the control is docked to the bottom edge of its container.

Syntax

public static final int BOTTOM;

Remarks

The width of the control is adjusted to match the width of the container.


 ControlDock.FILL

ControlDock.FILL

Specifies that the control is docked to the center of its container.

Syntax

public static final int FILL;

Remarks

The height and width of the control are adjusted to fill any space in the container not taken up by controls docked to the edges of the container.


 ControlDock.LEFT

ControlDock.LEFT

Specifies that the control is docked to the left edge of its container.

Syntax

public static final int LEFT;

Remarks

The height of the control is adjusted to match the height of the container minus any space taken up by controls docked to the bottom or top of the container.


 ControlDock.NONE

ControlDock.NONE

Specifies that the control is not docked.

Syntax

public static final int NONE;


 ControlDock.RIGHT

ControlDock.RIGHT

Specifies that the control is docked to the right edge of its container.

Syntax

public static final int RIGHT;

Remarks

The height of the control is adjusted to match the height of the container minus any space taken up by controls docked to the bottom or top of the container.


 ControlDock.TOP

ControlDock.TOP

Specifies that the control is docked to the top edge of its container.

Syntax

public static final int TOP;

Remarks

The width of the control is adjusted to match the width of the container.


CoordinateSystem Class

Defines the constants that identify the coordinate systems that you can associate with a Graphics object.

Enum
  |
  +--CoordinateSystem

package com.ms.wfc.ui

public class CoordinateSystem
extends Enum

Remarks

The term coordinate system identifies how the coordinates that you pass to a Graphics object's drawing methods map to the display or a device.

Suppose, for example, that you call the Graphics object's drawString method to draw text at coordinates 100,100:

Graphics g = this.createGraphics();

g.drawString("Hello, WFC", new Point(100, 100));

The Point object in this example specifies the x and y coordinates at which to draw the string. However, the actual result of this operation depends on the coordinate system with which the Graphics object is associated.

The coordinate systems with which you can associate a Graphics object are defined in the CoordinateSystem class. The default coordinate system for a Graphics object is CoordinateSystem.TEXT, which means that as the x and y values in a Point increase, the text (or bitmap or control) proceeds to the right horizontally and down vertically.

To associate a coordinate system with a Graphics object, use the Graphics object's setCoordinateSystem method.


 CoordinateSystem Methods

CoordinateSystem Methods

Methods | Description
valid | Retrieves a boolean value that indicates whether the specified value is a valid member of this class.


 CoordinateSystem.valid

CoordinateSystem.valid

Retrieves a boolean value that indicates whether the specified value is a valid member of this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check against the values defined in this class.

Return Value

Returns true if the value is valid; otherwise, returns false.


 CoordinateSystem Fields

CoordinateSystem Fields

Fields | Description
ANISOTROPIC | Specifies that logical units are converted to arbitrary units with arbitrarily scaled axes.
HIENGLISH | Specifies that each logical unit is converted to 0.001 inch.
HIMETRIC | Specifies that each logical unit is converted to 0.01 millimeter.
ISOTROPIC | Specifies that logical units are converted to arbitrary units with equally scaled axes; that is, one unit along the x-axis is equal to one unit along the y-axis.
LOENGLISH | Specifies that each logical unit is converted to 0.01 inch.
LOMETRIC | Specifies that each logical unit is converted to 0.1 millimeter.
TEXT | Specifies that each logical unit is converted to one device pixel.
TWIP | Specifies that each logical unit is converted to one twentieth of a point (called a twip).


 CoordinateSystem.ANISOTROPIC

CoordinateSystem.ANISOTROPIC

Specifies that logical units are converted to arbitrary units with arbitrarily scaled axes.

Syntax

public static final int ANISOTROPIC;


 CoordinateSystem.HIENGLISH

CoordinateSystem.HIENGLISH

Specifies that each logical unit is converted to 0.001 inch.

Syntax

public static final int HIENGLISH;

Remarks

As the positive x value increases, the x-coordinate moves to the right. As the positive y value increases, the y-coordinate moves up.


 CoordinateSystem.HIMETRIC

CoordinateSystem.HIMETRIC

Specifies that each logical unit is converted to 0.01 millimeter.

Syntax

public static final int HIMETRIC;

Remarks

As the positive x value increases, the x-coordinate moves to the right. As the positive y value increases, the y-coordinate moves up.


 CoordinateSystem.ISOTROPIC

CoordinateSystem.ISOTROPIC

Specifies that logical units are converted to arbitrary units with equally scaled axes; that is, one unit along the x-axis is equal to one unit along the y-axis.

Syntax

public static final int ISOTROPIC;

Remarks

As the positive x value increases, the x-coordinate moves to the right. As the positive y value increases, the y-coordinate moves up.


 CoordinateSystem.LOENGLISH

CoordinateSystem.LOENGLISH

Specifies that each logical unit is converted to 0.01 inch.

Syntax

public static final int LOENGLISH;

Remarks

As the positive x value increases, the x-coordinate moves to the right. As the positive y value increases, the y-coordinate moves up.


 CoordinateSystem.LOMETRIC

CoordinateSystem.LOMETRIC

Specifies that each logical unit is converted to 0.1 millimeter.

Syntax

public static final int LOMETRIC;

Remarks

As the positive x value increases, the x-coordinate moves to the right. As the positive y value increases, the y-coordinate moves up.


 CoordinateSystem.TEXT

CoordinateSystem.TEXT

Specifies that each logical unit is converted to one device pixel.

Syntax

public static final int TEXT;

Remarks

As the positive x value increases, the x-coordinate moves to the right. As the positive y value increases, the y-coordinate moves down.

Because of the left-to-right, top-to-bottom orientation of this coordinate system, this option is named TEXT. This is the default coordinate system of a Graphics object.


 CoordinateSystem.TWIP

CoordinateSystem.TWIP

Specifies that each logical unit is converted to one twentieth of a point (called a twip).

Syntax

public static final int TWIP;

Remarks

Because a point is 1/72 of an inch, a twip is 1/1440 of an inch.

As the positive x value increases, the x-coordinate moves to the right. As the positive y value increases, the y-coordinate moves up.


CreateParams Class

Encapsulates the information used when creating a control.

package com.ms.wfc.ui

public class CreateParams

Remarks

The information in a CreateParams object can be used to pass information about the initial state of a control. The CreateParams object is sent to controls through the getCreateParams method, which individual controls override to include additional information in this object.


 CreateParams Fields

CreateParams Fields

Fields | Description
caption | Specifies the initial caption for the control.
className | Specifies the name of the window class to subclass.
classStyle | Contains class style bits.
exStyle | Contains extended window style bits.
height | Specifies the proposed initial height.
param | Specifies additional information to provide to the underlying handle.
parent | Specifies the handle to the parent of the control.
style | Contains window style bits.
width | Specifies the proposed initial width.
x | Specifies the x-coordinate of the initial proposed location.
y | Specifies the y-coordinate of the initial proposed location.


 CreateParams.caption

CreateParams.caption

Specifies the initial caption for the control.

Syntax

public String caption;


 CreateParams.className

CreateParams.className

Specifies the name of the window class to subclass.

Syntax

public String className;

Remarks

The default value for this field is null, which indicates that the window is not a subclass of an existing window class. To subclass an existing window class, store the window class name in this field. For example, to subclass the standard edit control, set this field to "EDIT".


 CreateParams.classStyle

CreateParams.classStyle

Contains class style bits.

Syntax

public int classStyle;

Remarks

This value must be a combination of CS_XXX style flags. This field is ignored if the value of the className field is not null.


 CreateParams.exStyle

CreateParams.exStyle

Contains extended window style bits.

Syntax

public int exStyle;

Remarks

This value must be a combination of WS_EX_XXX style flags.


 CreateParams.height

CreateParams.height

Specifies the proposed initial height.

Syntax

public int height;


 CreateParams.param

CreateParams.param

Specifies additional information to provide to the underlying handle.

Syntax

public Object param;


 CreateParams.parent

CreateParams.parent

Specifies the handle to the parent of the control.

Syntax

public int parent;


 CreateParams.style

CreateParams.style

Contains window style bits.

Syntax

public int style;

Remarks

This value must be a combination of WS_XXX style flags and other control-specific style flags.


 CreateParams.width

CreateParams.width

Specifies the proposed initial width.

Syntax

public int width;


 CreateParams.x

CreateParams.x

Specifies the x-coordinate of the initial proposed location.

Syntax

public int x;


 CreateParams.y

CreateParams.y

Specifies the y-coordinate of the initial proposed location.

Syntax

public int y;


Cursor Class

Encapsulates a mouse pointer and the operations that you can perform on a cursor.

Image
  |
  +--Cursor

package com.ms.wfc.ui

public final class Cursor
extends Image


 Cursor Methods

Cursor Methods

Constructors | Description
Cursor | Creates a Cursor object.

Methods | Description
clone | Clones the Cursor object and returns a duplicate.
copyHandle | Retrieves a copy of the Win32 handle for the cursor on which this object is based. When you copy a cursor handle, you own the handle and are responsible for freeing it.
destroyHandle | Called when this object is going to destroy its Win32 handle.
dispose | Frees all the resources allocated by this object.
drawStretchTo | Renders the cursor to a Graphics object, stretching the cursor to fill specified dimensions.
drawTo | Renders the bitmap image (or part of it) to a Graphics object, cropping the image to fit specified dimensions.
finalize | Frees the resources allocated by the Cursor object.
getClip | Retrieves the current cursor's clipping rectangle in screen coordinates.
getExtension | Retrieves the recommended file extension for this object.
getHandle | Retrieves the Win32 handle to this cursor.
getPICTDESC | Retrieves a PICTDESC (Picture Descriptor) for this cursor. The PICTDESC structure is used by OLE functions to create picture objects.
getPosition | Retrieves the screen coordinates for the cursor's current position.
getSize | Retrieves the size of the cursor, in pixels.
hide | Hides the cursor.
setClip | Specifies the cursor's clipping rectangle.
setCurrent | Sets the current system cursor as the cursor for this object.
setPosition | Moves the cursor to the specified position (in screen coordinates).
show | Displays the cursor.
toString | Retrieves a string representation of this Cursor object.


 Cursor.clone

Cursor.clone

Clones the Cursor object and returns a duplicate.

Syntax

public Object clone()

Return Value

Returns an object that can be cast to a Cursor object.


 Cursor.copyHandle

Cursor.copyHandle

Retrieves a copy of the Win32 handle for the cursor on which this object is based. When you copy a cursor handle, you own the handle and are responsible for freeing it.

Syntax

public final int copyHandle()

Return Value

A copy of the Win32 handle to the cursor that underlies this object.

Remarks

Because the handle returned by copyHandle is a copy of the cursor's underlying Win32 handle, you are responsible for freeing this handle when you are finished using it.

See Also getHandle


 Cursor.Cursor

Cursor.Cursor

Creates a Cursor object.

Syntax

public Cursor( int handle )

public Cursor( String filename )

public Cursor( Class type, String resource )

public Cursor( IDataStream stream )

public Cursor( IStream stream )

public Cursor( IPicture picture )

Parameters

handle

A Win-32 cursor handle. This handle is not owned by the Cursor object; you are responsible for freeing it.

filename

The name of a file from which to load the cursor.

type

The class used to load the cursor resource.

resource

The resource to load.

stream

A data stream (IDataStream or com.ms.wfc.ole32.IStream) from which to load the cursor.

picture

An OLE com.ms.wfc.ole32.IPicture object on which to base the cursor.


 Cursor.destroyHandle

Cursor.destroyHandle

Called when this object is going to destroy its Win32 handle.

Syntax

protected void destroyHandle()

Remarks

The Cursor class' implementation of destroyHandle frees only handles owned by the Cursor object. If you create a Cursor object based on a previously allocated handle, this method does nothing. Similarly, if you have used the Cursor object's copyHandle method to duplicate the cursor handle, this handle is not freed by the object's call to destroyHandle; you are responsible for freeing these handles.

However, you can override this method in your Cursor-derived class to define your own custom semantics for handle creation and destruction.


 Cursor.dispose

Cursor.dispose

Frees all the resources allocated by this object.

Syntax

public void dispose()

Remarks

The dispose method frees only those resources allocated by the object. Such resources do not include handle copies that you retrieve using the object's methods; you must free these manually.

Once the dispose method is called, the Cursor object is no longer useful.


 Cursor.drawStretchTo

Cursor.drawStretchTo

Renders the cursor to a Graphics object, stretching the cursor to fill specified dimensions.

Syntax

protected void drawStretchTo( Graphics g, Rectangle imageRect, Rectangle targetRect, int rop )

Parameters

g

The Graphics object to which to draw the cursor.

imageRect

A Rectangle object that specifies the cursor region to draw.

targetRect

A Rectangle object that specifies the area to which to draw the cursor.

rop

A numerical ROP code that describes how to draw the source cursor to the target.

Remarks

The drawStretchTo and drawTo methods are used by the Graphics object for all image rendering. For more information on how the Graphics object uses these methods, see the Graphics object's drawImage method.

If the area specified in imageRect is smaller than the area specified in targetRect, the source cursor is stretched to fill the specified area. If the area specified in imageRect is larger than that specified in targetRect, the image is shrunk.


 Cursor.drawTo

Cursor.drawTo

Renders the bitmap image (or part of it) to a Graphics object, cropping the image to fit specified dimensions.

Syntax

protected void drawTo( Graphics g, Rectangle imageRect, Rectangle targetRect, int rop )

Parameters

g

The Graphics object to which to draw the cursor.

imageRect

A Rectangle object that specifies the source rectangle in the cursor.

targetRect

A Rectangle object that specifies the rectangle to which to draw the cursor. If this area is smaller than imageRect, the source rectangle is cropped to fit in the target rectangle.

rop

A numerical ROP code that specifies how to draw the cursor.

Remarks

The drawStretchTo and drawTo methods are used by the Graphics object for all image rendering. For more information on how the Graphics object uses these methods, see the Graphics object's drawImage method.


 Cursor.finalize

Cursor.finalize

Frees the resources allocated by the Cursor object.

Syntax

protected void finalize()


 <b>Cursor.getClip</b>

Cursor.getClip

Retrieves the current cursor's clipping rectangle in screen coordinates.

Syntax

public final static Rectangle getClip()

Return Value

Returns a Rectangle object that specifies the cursor's clipping rectangle.

Remarks

If the cursor is not currently clipped, the resulting rectangle contains the dimensions of the entire screen.

A clipped cursor is allowed to move only within its clipping rectangle.


 Cursor.getExtension

Cursor.getExtension

Retrieves the recommended file extension for this object.

Syntax

public String getExtension()

Return Value

Returns the recommended file extension for this object, minus the prefixing period.

Remarks

Currently, this method always returns "cur".


 Cursor.getHandle

Cursor.getHandle

Retrieves the Win32 handle to this cursor.

Syntax

public int getHandle()

Return Value

Returns the handle to this cursor.

Exceptions

WFCException thrown if the Cursor object has been disposed through a call to its dispose method.

Remarks

The handle returned by this method is not a copy of the cursor handle. Therefore, this handle should not be freed by the caller.

See Also copyHandle


 Cursor.getPICTDESC

Cursor.getPICTDESC

Retrieves a PICTDESC (Picture Descriptor) for this cursor. The PICTDESC structure is used by OLE functions to create picture objects.

Syntax

public final PICTDESC getPICTDESC()

Return Value

Returns a PICTDESC structure that describes this object's cursor.


 Cursor.getPosition

Cursor.getPosition

Retrieves the screen coordinates for the cursor's current position.

Syntax

public final static Point getPosition()

Return Value

Returns a Point object that contains the x and y coordinates of the cursor position.

See Also setPosition


 Cursor.getSize

Cursor.getSize

Retrieves the size of the cursor, in pixels.

Syntax

public final Point getSize()

Return Value

Returns a Point object that contains the height and width of the cursor in pixels.


 Cursor.hide

Cursor.hide

Hides the cursor.

Syntax

public final static void hide()

Remarks

For every call to hide, there must be a corresponding call to show.


 Cursor.setClip

Cursor.setClip

Specifies the cursor's clipping rectangle.

Syntax

public final static void setClip( Rectangle r )

Parameters

r

A Rectangle object that specifies the clipping rectangle. If this parameter is null, the cursor is free to move anywhere on the screen.

Remarks

When you set a clipping rectangle on a cursor, the cursor is confined to the specified area of the screen. If a subsequent cursor position (set by calling setClip or by moving the mouse) lies outside this rectangle, Windows automatically adjusts the cursor position to remain in the clip area.

Cursor clipping is reset if the user switches applications.

See Also getClip


 Cursor.setCurrent

Cursor.setCurrent

Sets the current system cursor as the cursor for this object.

Syntax

public final void setCurrent()


 Cursor.setPosition

Cursor.setPosition

Moves the cursor to the specified position (in screen coordinates).

Syntax

public final static void setPosition( Point p )

Parameters

p

A Point object that specifies the x and y coordinates of the desired cursor position.

Remarks

If the specified coordinates are not within the screen rectangle set by the most recent call to setClip, Windows automatically adjusts the coordinates so that the cursor stays within its clipping rectangle.

See Also getPosition


 Cursor.show

Cursor.show

Displays the cursor.

Syntax

public final static void show()

Remarks

For every call to hide, there must be a balancing call to show.

See Also hide


 Cursor.toString

Cursor.toString

Retrieves a string representation of this Cursor object.

Syntax

public String toString()

Return Value

Returns a String object that describes this object.


 Cursor Fields

Cursor Fields

Fields | Description
APPSTARTING | Specifies the cursor that appears as an application is starting.
ARROW | Specifies an arrow cursor.
CROSS | Specifies a crosshair cursor.
DEFAULT | Specifies the default cursor, which is usually an arrow cursor.
HELP | Specifies a help cursor, which is a combination of an arrow and a question mark.
HSPLIT | Specifies the cursor that appears when the mouse is positioned over a horizontal splitter bar.
IBEAM | Specifies an I-beam cursor, which is used to show where the text cursor will appear when the mouse is clicked.
NO | Specifies a cursor which indicates that a particular region is invalid for a given operation.
SIZEALL | Specifies a four-headed sizing cursor, which consists of four joined arrows, which point north, south, east, and west.
SIZENESW | Specifies a two-headed northeast/southwest sizing cursor.
SIZENS | Specifies a two-headed north/south sizing cursor.
SIZENWSE | Specifies a two-headed northwest/southeast sizing cursor.
SIZEWE | Specifies a two-headed west/east sizing cursor.
UPARROW | Specifies an up arrow, typically used to identify an insertion point.
VSPLIT | Specifies a vertical splitter bar cursor.
WAIT | Specifies a standard "wait" (or hourglass) cursor.


 Cursor.APPSTARTING

Cursor.APPSTARTING

Specifies the cursor that appears as an application is starting.

Syntax

public static final Cursor APPSTARTING;

Remarks

Typically, this cursor combines an arrow and an hourglass, and indicates that although the system is loading information, the user interface can handle input.


 Cursor.ARROW

Cursor.ARROW

Specifies an arrow cursor.

Syntax

public static final Cursor ARROW;


 Cursor.CROSS

Cursor.CROSS

Specifies a crosshair cursor.

Syntax

public static final Cursor CROSS;

Remarks

This cursor typically appears over regions in which the user can use the mouse for drawing operations.


 Cursor.DEFAULT

Cursor.DEFAULT

Specifies the default cursor, which is usually an arrow cursor.

Syntax

public static final Cursor DEFAULT;


 Cursor.HELP

Cursor.HELP

Specifies a help cursor, which is a combination of an arrow and a question mark.

Syntax

public static final Cursor HELP;

Remarks

Typically, this cursor is displayed when a context-sensitive help click is active.


 Cursor.HSPLIT

Cursor.HSPLIT

Specifies the cursor that appears when the mouse is positioned over a horizontal splitter bar.

Syntax

public static final Cursor HSPLIT;


 Cursor.IBEAM

Cursor.IBEAM

Specifies an I-beam cursor, which is used to show where the text cursor will appear when the mouse is clicked.

Syntax

public static final Cursor IBEAM;


 Cursor.NO

Cursor.NO

Specifies a cursor which indicates that a particular region is invalid for a given operation.

Syntax

public static final Cursor NO;

Remarks

For example, this cursor appears during a drag and drop operation to indicate regions in which a drop is not allowed.


 Cursor.SIZEALL

Cursor.SIZEALL

Specifies a four-headed sizing cursor, which consists of four joined arrows, which point north, south, east, and west.

Syntax

public static final Cursor SIZEALL;


 Cursor.SIZENESW

Cursor.SIZENESW

Specifies a two-headed northeast/southwest sizing cursor.

Syntax

public static final Cursor SIZENESW;


 Cursor.SIZENS

Cursor.SIZENS

Specifies a two-headed north/south sizing cursor.

Syntax

public static final Cursor SIZENS;


 Cursor.SIZENWSE

Cursor.SIZENWSE

Specifies a two-headed northwest/southeast sizing cursor.

Syntax

public static final Cursor SIZENWSE;


 Cursor.SIZEWE

Cursor.SIZEWE

Specifies a two-headed west/east sizing cursor.

Syntax

public static final Cursor SIZEWE;


 Cursor.UPARROW

Cursor.UPARROW

Specifies an up arrow, typically used to identify an insertion point.

Syntax

public static final Cursor UPARROW;


 Cursor.VSPLIT

Cursor.VSPLIT

Specifies a vertical splitter bar cursor.

Syntax

public static final Cursor VSPLIT;


 Cursor.WAIT

Cursor.WAIT

Specifies a standard "wait" (or hourglass) cursor.

Syntax

public static final Cursor WAIT;


DateRangeEvent Class

Provides data for the dateChanged event and the dateSelected event of a MonthCalendar control.

Event
  |
  +--DateRangeEvent

package com.ms.wfc.ui

public class DateRangeEvent
extends Event

Remarks

The dateChanged event occurs when the currently selected date or range of dates changes; for example, when the user explicitly changes a selection within the current month or when the selection is implicitly changed in response to next/previous month navigation. The dateSelected event occurs when user explicitly changes a selection. A DateRangeEvent specifies the start and end for the new date range that has been selected.

For information about the WFC event model, see Handling Events in WFC.


 DateRangeEvent Methods

DateRangeEvent Methods

Constructors | Description
DateRangeEvent | Creates a DateRangeEvent object.


 DateRangeEvent.DateRangeEvent

DateRangeEvent.DateRangeEvent

Creates a DateRangeEvent object.

Syntax

public DateRangeEvent( Time start, Time end )

Parameters

start

The first date in the date range the user has selected.

end

The last date in the date range the user has selected.


 DateRangeEvent Fields

DateRangeEvent Fields

Fields | Description
end | Specifies the last date in the date range the user has selected.
start | Specifies the first date in the date range the user has selected.


 DateRangeEvent.end

DateRangeEvent.end

Specifies the last date in the date range the user has selected.

Syntax

public final Time end;


 DateRangeEvent.start

DateRangeEvent.start

Specifies the first date in the date range the user has selected.

Syntax

public final Time start;


DateRangeEventHandler Delegate

Identifies the method that will handle the dateChanged event and the dateSelected event of a MonthCalendar control.

package com.ms.wfc.ui

public multicast delegate
void DateRangeEventHandler( Object sender, DateRangeEvent e );

Remarks

The syntax of the DateRangeEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a DateRangeEvent object that provides the event data.

When you create a DateRangeEventHandler delegate, you specify the method that will handle the event. When the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered. For more information about delegates, see Handling Events in WFC.


DateTimeFormatEvent Class

Provides data for the format event of the DateTimePicker control.

Event
  |
  +--DateTimeFormatEvent

package com.ms.wfc.ui

public class DateTimeFormatEvent
extends Event

Remarks

The format event occurs when the DateTimePicker control needs to convert the time value to a string format to display. A DateTimeFormatEvent specifies which key was pressed to trigger the event, which custom date and time format the DateTimePicker control is using, and what string to display to the user.

For information about the WFC event model, see Handling Events in WFC.


 DateTimeFormatEvent Methods

DateTimeFormatEvent Methods

Constructors | Description
DateTimeFormatEvent | Creates a DateTimeFormatEvent object.


 DateTimeFormatEvent.DateTimeFormatEvent

DateTimeFormatEvent.DateTimeFormatEvent

Creates a DateTimeFormatEvent object.

Syntax

public DateTimeFormatEvent( String format, long time, String display )

Parameters

format

The custom format string the DateTimePicker control is using.

time

The time that the DateTimePicker control should be set to.

display

The date and time string to display to the user.


 DateTimeFormatEvent Fields

DateTimeFormatEvent Fields

Fields | Description
display | Specifies the date and time string to display to the user.
format | Specifies the custom format string the DateTimePicker control is using.
time | Specifies the time that the DateTimePicker control should be set to.


 DateTimeFormatEvent.display

DateTimeFormatEvent.display

Specifies the date and time string to display to the user.

Syntax

public String display;


 DateTimeFormatEvent.format

DateTimeFormatEvent.format

Specifies the custom format string the DateTimePicker control is using.

Syntax

public final String format;


 DateTimeFormatEvent.time

DateTimeFormatEvent.time

Specifies the time that the DateTimePicker control should be set to.

Syntax

public final long time;


DateTimeFormatEventHandler Delegate

Identifies the method that will handle the format event of a DateTimePicker control.

package com.ms.wfc.ui

public multicast delegate
void DateTimeFormatEventHandler( Object sender, DateTimeFormatEvent e );

Remarks

The syntax of the DateTimeFormatEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a DateTimeFormatEvent object that provides the event data.

When you create a DateTimeFormatEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC.


DateTimeFormatQueryEvent Class

Provides data for the formatQuery event of the DateTimePicker control.

Event
  |
  +--DateTimeFormatQueryEvent

package com.ms.wfc.ui

public class DateTimeFormatQueryEvent
extends Event

Remarks

The formatQuery event occurs when the DateTimePicker control needs to determine the maximum dimensions of the string that would be displayed for a specified date and time value. A DateTimeFormatQueryEvent specifies which key was pressed to trigger the event, which custom date and time format the DateTimePicker control is using, and what time to set the DateTimePicker control to.

For information about the WFC event model, see Handling Events in WFC.


 DateTimeFormatQueryEvent Methods

DateTimeFormatQueryEvent Methods

Constructors | Description
DateTimeFormatQueryEvent | Creates a DateTimeFormatQueryEvent object.


 DateTimeFormatQueryEvent.DateTimeFormatQueryEvent

DateTimeFormatQueryEvent.DateTimeFormatQueryEvent

Creates a DateTimeFormatQueryEvent object.

Syntax

public DateTimeFormatQueryEvent( String format, Point maxSize )

Parameters

format

The custom format string the DateTimePicker control is using.

maxSize

The maximum dimensions needed to display the time in the specified format.


 DateTimeFormatQueryEvent Fields

DateTimeFormatQueryEvent Fields

Fields | Description
format | Specifies the custom format string the DateTimePicker control is using.
maxSize | Specifies the maximum dimensions needed to display the time in the specified format.


 DateTimeFormatQueryEvent.format

DateTimeFormatQueryEvent.format

Specifies the custom format string the DateTimePicker control is using.

Syntax

public final String format;


 DateTimeFormatQueryEvent.maxSize

DateTimeFormatQueryEvent.maxSize

Specifies the maximum dimensions needed to display the time in the specified format.

Syntax

public Point maxSize;


DateTimeFormatQueryEventHandler Delegate

Identifies the method handling the formatQuery event of a DateTimePicker control.

package com.ms.wfc.ui

public multicast delegate
void DateTimeFormatQueryEventHandler( Object sender, DateTimeFormatQueryEvent e );

Remarks

The syntax of the DateTimeFormatQueryEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a DateTimeFormatQueryEvent object that provides the event data.

When you create a DateTimeFormatQueryEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC.


DateTimePicker Class

Encapsulates a Windows date and time picker control, which allows users to specify date and time information.

Component
  |
  +--Control
    |
    +--DateTimePicker

package com.ms.wfc.ui

public class DateTimePicker
extends Control

Remarks

Use the getValue method to return the date and time the user selected in the control. Set the showUpDown property of the DateTimePicker control to true to display the control as an edit control containing date and time fields that the user can set using an up/down arrow. Set the showUpDown property of the DateTimePicker control to false to display the control as an edit control with an attached drop-down month calendar in which the user can select a date.


 DateTimePicker Methods

DateTimePicker Methods

Constructors | Description
DateTimePicker | Creates a DateTimePicker control.

Methods | Description
addOnCloseUp | Assigns a delegate to the closeUp event.
addOnDropDown | Assigns a delegate to the dropDown event.
addOnFormat | Assigns a delegate to the format event.
addOnFormatQuery | Assigns a delegate to the formatQuery event.
addOnUserString | Assigns a delegate to the userString event.
addOnValueChanged | Assigns a delegate to the valueChanged event.
addOnWmKeyDown | Assigns a delegate to the wmKeyDown event.
getAllowUserString | Retrieves a boolean value indicating whether the user can edit the value in the control by pressing F2.
getCalendarFont | Retrieves the font currently used by the month calendar of the date and time picker control.
getCalendarForeColor | Retrieves the color used to display text within the current month in the month calendar.
getCalendarMonthBackground | Retrieves the background color used within the current month in the month calendar.
getCalendarTitleBackColor | Retrieves the background color displayed in the month calendar's title.
getCalendarTitleForeColor | Retrieves the color used to display text within the month calendar's title.
getCalendarTrailingForeColor | Retrieves the color used to display text for header and trailing-day days (days from the previous and following month that appear on the current calendar).
getCustomFormat | Retrieves a format string that specifies the custom format used by the control to display date and time information.
getDropDownAlign | Retrieves a value indicating whether the drop-down month calendar will be aligned to the right or left of the edit control of the date time picker control.
getFormat | Retrieves a value indicating the whether the control displays date and time information in long date format (for example, "Wednesday, April 7, 1999"), short date format (for example, "4/7/99"), time format (for example, "5:31:34 PM"), or custom format.
getMaxDate | Retrieves a value indicating the last date that the control allows the user to select.
getMinDate | Retrieves a value indicating the first date that the control allows the user to select.
getShowNone | Retrieves a boolean value indicating whether it is possible to have no date selected in the control.
getShowUpDown | Retrieves a boolean value indicating whether the control allows the user to select a date by displaying an up/down arrow to the right of the control or whether the control enables the user to display a drop-down calendar in which to select a date.
getValue | Retrieves the date and time value currently displayed in the control.
onCloseUp | Triggers the closeUp event.
onDropDown | Triggers the dropDown event.
onFormat | Triggers the format event.
onFormatQuery | Triggers the formatQuery event.
onUserString | Triggers the userString event.
onValueChanged | Triggers the valueChanged event.
onWmKeyDown | Triggers the wmKeyDown event.
removeOnCloseUp | Removes the delegate that is assigned to the closeUp event.
removeOnDropDown | Removes the delegate that is assigned to the dropDown event.
removeOnFormat | Removes the delegate that is assigned to the format event.
removeOnFormatQuery | Removes the delegate that is assigned to the formatQuery event.
removeOnUserString | Removes the delegate that is assigned to the userString event.
removeOnValueChanged | Removes the delegate that is assigned to the valueChanged event.
removeOnWmKeyDown | Removes the delegate that is assigned to the wmKeyDown event.
resetFormat | Resets the date and time display format of the calendar to DateTimePickerFormat.LONG.
resetMaxDate | Resets the calendar so that there is no upper limit to the selectable range of dates.
resetMinDate | Resets the calendar so that there is no lower limit to the selectable range of dates.
resetValue | Resets the value of the date and time picker control to the current time.
setAllowUserString | Sets a boolean value indicating whether the user can edit the value in the control by pressing F2.
setCalendarFont | Sets the font used by the month calendar of the date and time picker control.
setCalendarForeColor | Sets the color used to display text within the current month in the month calendar.
setCalendarMonthBackground | Sets the background color used within the current month in the month calendar.
setCalendarTitleBackColor | Sets the background color displayed in the month calendar's title.
setCalendarTitleForeColor | Sets the color used to display text within the month calendar's title.
setCalendarTrailingForeColor | Sets the color used to display text for header and trailing-day days (days from the previous and following month that appear on the current calendar).
setCustomFormat | Sets a format string that specifies the custom format used by the control to display date and time information.
setDropDownAlign | Sets a value indicating whether the drop-down month calendar will be aligned to the right or left of the edit control of the date time picker control.
setFormat | Sets a value indicating the whether the control displays date and time information in long date format (for example, "Wednesday, April 7, 1999"), short date format (for example, "4/7/99"), time format (for example, "5:31:34 PM"), or custom format.
setMaxDate | Sets a value indicating the last date that the control allows the user to select.
setMinDate | Sets a value indicating the first date that the control allows the user to select.
setShowNone | Sets a boolean value indicating whether it is possible to have no date selected in the control.
setShowUpDown | Sets a boolean value indicating whether the control allows the user to select a date by displaying an up/down arrow to the right of the control or whether the control enables the user to display a drop-down calendar in which to select a date.
setValue | Sets the date and time value to display in the control.
shouldPersistFormat | Retrieves a boolean value indicating whether the format property has been explicitly set.
shouldPersistMaxDate | Retrieves a boolean value indicating whether the value of the maxDate property has been explicitly set.
shouldPersistMinDate | Retrieves a boolean value indicating whether the value of the minDate property has been explicitly set.
shouldPersistValue | Retrieves a boolean value indicating whether the value property has been explicitly set.


 DateTimePicker.addOnCloseUp

DateTimePicker.addOnCloseUp

Assigns a delegate to the closeUp event.

Syntax

public final void addOnCloseUp( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the closeUp event to that method in the Properties window. The closeUp event occurs when the drop-down calendar closes. (The drop-down calendar closes automatically after the user selects a date.)

See Also removeOnCloseUp


 DateTimePicker.addOnDropDown

DateTimePicker.addOnDropDown

Assigns a delegate to the dropDown event.

Syntax

public final void addOnDropDown( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the dropDown event to that method in the Properties window. The dropDown event occurs when the drop-down calendar is displayed.

See Also removeOnDropDown


 DateTimePicker.addOnFormat

DateTimePicker.addOnFormat

Assigns a delegate to the format event.

Syntax

public final void addOnFormat( DateTimeFormatEventHandler value )

Parameters

value

The DateTimeFormatEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the format event to that method in the Properties window. The format event occurs when the DateTimePicker control needs to convert the time value to a string format.

See Also removeOnFormat


 DateTimePicker.addOnFormatQuery

DateTimePicker.addOnFormatQuery

Assigns a delegate to the formatQuery event.

Syntax

public final void addOnFormatQuery( DateTimeFormatQueryEventHandler value )

Parameters

value

The DateTimeFormatQueryEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the formatQuery event to that method in the Properties window. The formatQuery event occurs when the DateTimePicker control needs to determine the dimensions of the string that would be displayed for a specified date and time value.

See Also removeOnFormatQuery


 DateTimePicker.addOnUserString

DateTimePicker.addOnUserString

Assigns a delegate to the userString event.

Syntax

public final void addOnUserString( DateTimeUserStringEventHandler value )

Parameters

value

The DateTimeUserStringEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the userString event to that method in the Properties window. The userString event occurs when the user has finished editing the contents of the date and time picker control. This event can be triggered only if the allowUserString property is set to true.

See Also removeOnUserString


 DateTimePicker.addOnValueChanged

DateTimePicker.addOnValueChanged

Assigns a delegate to the valueChanged event.

Syntax

public final void addOnValueChanged( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the valueChanged event to that method in the Properties window. The valueChanged event occurs when the value in the DateTimePicker control changes.

See Also removeOnValueChanged


 DateTimePicker.addOnWmKeyDown

DateTimePicker.addOnWmKeyDown

Assigns a delegate to the wmKeyDown event.

Syntax

public final void addOnWmKeyDown( DateTimeWmKeyDownEventHandler value )

Parameters

value

The DateTimeWmKeyDownEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the wmKeyDown event to that method in the Properties window. The wmKeyDown event occurs when the user presses a key in a custom format field.

See Also removeOnWmKeyDown


 DateTimePicker.DateTimePicker

DateTimePicker.DateTimePicker

Creates a DateTimePicker control.

Syntax

public DateTimePicker()


 DateTimePicker.getAllowUserString

DateTimePicker.getAllowUserString

Retrieves a boolean value indicating whether the user can edit the value in the control by pressing F2.

Syntax

public final boolean getAllowUserString()

Return Value

Returns true if the user can edit the value in the control by pressing F2; otherwise, returns false.

Remarks

If this property is set to true, the userString event must be handled to correctly convert the user text into a time.

See Also setAllowUserString


 DateTimePicker.getCalendarFont

DateTimePicker.getCalendarFont

Retrieves the font currently used by the month calendar of the date and time picker control.

Syntax

public final Font getCalendarFont()

Return Value

Returns a Font object that represents the font currently used in the month calendar control of the date time picker control.

See Also setCalendarFont


 DateTimePicker.getCalendarForeColor

DateTimePicker.getCalendarForeColor

Retrieves the color used to display text within the current month in the month calendar.

Syntax

public final Color getCalendarForeColor()

Return Value

Returns a Color object that represents the text color for the month calendar.

See Also setCalendarForeColor


 DateTimePicker.getCalendarMonthBackground

DateTimePicker.getCalendarMonthBackground

Retrieves the background color used within the current month in the month calendar.

Syntax

public final Color getCalendarMonthBackground()

Return Value

Returns a Color object that represents the text color for the month calendar.

See Also setCalendarMonthBackground


 DateTimePicker.getCalendarTitleBackColor

DateTimePicker.getCalendarTitleBackColor

Retrieves the background color displayed in the month calendar's title.

Syntax

public final Color getCalendarTitleBackColor()

Return Value

Returns a Color object that represents background color displayed in the month calendar's title.

See Also setCalendarTitleBackColor


 DateTimePicker.getCalendarTitleForeColor

DateTimePicker.getCalendarTitleForeColor

Retrieves the color used to display text within the month calendar's title.

Syntax

public final Color getCalendarTitleForeColor()

Return Value

Returns a Color object that represents the text color for the month calendar's title.

See Also setCalendarTitleForeColor


 DateTimePicker.getCalendarTrailingForeColor

DateTimePicker.getCalendarTrailingForeColor

Retrieves the color used to display text for header and trailing-day days (days from the previous and following month that appear on the current calendar).

Syntax

public final Color getCalendarTrailingForeColor()

Return Value

Returns a Color object that represents the color used to display text for header and trailing-day days.

See Also setCalendarTrailingForeColor, setCalendarTrailingForeColor


 DateTimePicker.getCustomFormat

DateTimePicker.getCustomFormat

Retrieves a format string that specifies the custom format used by the control to display date and time information.

Syntax

public final String getCustomFormat()

Return Value

Returns a custom format string that is created by combining format characters from the following table. Nonformat characters in the output string are enclosed in single quotation marks. For example, if the output of the date and time picker looks like "The current time and date is: 05:31:42 Wednesday Apr 07, 1999", this method returns the following format string: "'The current time and date is: 'hh':'mm':'ss ddddMMMdd', 'yyy".

Format Characters | Description
d | The one- or two-digit day.
dd | The two-digit day. Single digit day values are preceded by a zero.
ddd | The three-character day-of-week abbreviation.
dddd | The full day-of-week name.
h | The one- or two-digit hour in 12-hour format.
hh | The two-digit hour in 12-hour format. Single digit values are preceded by a zero.
H | The one- or two-digit hour in 24-hour format.
HH | The two-digit hour in 24-hour format. Single digit values are preceded by a zero.
m | The one- or two-digit minute.
mm | The two-digit minute. Single digit values are preceded by a zero.
M | The one- or two-digit month number.
MM | The two-digit month number. Single digit values are preceded by a zero.
MMM | The three-character month abbreviation.
MMMM | The full month name.
s | The one- or two- digit seconds.
ss | The two-digit seconds. Single digit values are preceded by a zero.
t | The one-letter AM/PM abbreviation (that is, "AM" is displayed as "A").
tt | The two-letter AM/PM abbreviation (that is, "AM" is displayed as "AM").
X | A callback field that gives programmer control over the displayed field (see below.) Multiple X characters can be used in a series to signify unique callback fields.
y | The one-digit year (that is, 1996 is displayed as "6").
yy | The last two digits of the year (that is, 1996 is displayed as "96").
yyy | The full year (that is, 1996 is displayed as "1996").


 DateTimePicker.getDropDownAlign

DateTimePicker.getDropDownAlign

Retrieves a value indicating whether the drop-down month calendar will be aligned to the right or left of the edit control of the date time picker control.

Syntax

public final int getDropDownAlign()

Return Value

Returns an integer that specifies whether the drop-down month calendar aligns to the right or left of the edit control. Possible return values are constants defined in the LeftRightAlignment class.

See Also setDropDownAlign


 DateTimePicker.getFormat

DateTimePicker.getFormat

Retrieves a value indicating the whether the control displays date and time information in long date format (for example, "Wednesday, April 7, 1999"), short date format (for example, "4/7/99"), time format (for example, "5:31:34 PM"), or custom format.

Syntax

public final int getFormat()

Return Value

Returns an integer that specifies the date and time display format. Possible return values are constants defined in the DateTimePickerFormat class.

See Also setFormat


 DateTimePicker.getMaxDate

DateTimePicker.getMaxDate

Retrieves a value indicating the last date that the control allows the user to select.

Syntax

public final Time getMaxDate()

Return Value

Returns a Time object that represents the last date that is available for selection in the control. Returns null if there is no upper limit to allowable dates.

See Also setMaxDate


 DateTimePicker.getMinDate

DateTimePicker.getMinDate

Retrieves a value indicating the first date that the control allows the user to select.

Syntax

public final Time getMinDate()

Return Value

Returns a Time object that represents the first date that is available for selection in the control. Returns null if there is no lower limit to allowable dates.

See Also setMinDate


 DateTimePicker.getShowNone

DateTimePicker.getShowNone

Retrieves a boolean value indicating whether it is possible to have no date selected in the control.

Syntax

public final boolean getShowNone()

Return Value

Returns true if it is possible to have no date selected in the control; otherwise, returns false. When the showNone property is set to true, a check box appears to the left of the date. Until this check box is checked, the value of the control is -1, which indicates that no date is selected.

See Also setShowNone


 DateTimePicker.getShowUpDown

DateTimePicker.getShowUpDown

Retrieves a boolean value indicating whether the control allows the user to select a date by displaying an up/down arrow to the right of the control or whether the control enables the user to display a drop-down calendar in which to select a date.

Syntax

public final boolean getShowUpDown()

Return Value

Returns true if the control is displayed as an edit control containing date and time fields that the user can set using an up/down arrow; returns false if the control is displayed as an edit control with an attached drop-down month calendar in which the user can select a date.

See Also setShowUpDown


 DateTimePicker.getValue

DateTimePicker.getValue

Retrieves the date and time value currently displayed in the control.

Syntax

public final Time getValue()

Return Value

Returns a Time object that represents the date and time value currently displayed in the control. Returns null if no value is displayed.

See Also setValue


 DateTimePicker.onCloseUp

DateTimePicker.onCloseUp

Triggers the closeUp event.

Syntax

protected void onCloseUp( Event event )

Parameters

event

An Event object that provides the event data.

Remarks

When overriding this method, call super.onCloseUp.

See Also addOnCloseUp


 DateTimePicker.onDropDown

DateTimePicker.onDropDown

Triggers the dropDown event.

Syntax

protected void onDropDown( Event event )

Parameters

event

An Event object that provides the event data.

Remarks

When overriding this method, call super.onDropDown.

See Also addOnDropDown


 DateTimePicker.onFormat

DateTimePicker.onFormat

Triggers the format event.

Syntax

protected void onFormat( DateTimeFormatEvent event )

Parameters

event

A DateTimeFormatEvent object that provides the event data.

Remarks

When overriding this method, call super.onFormat.

See Also addOnFormat


 DateTimePicker.onFormatQuery

DateTimePicker.onFormatQuery

Triggers the formatQuery event.

Syntax

protected void onFormatQuery( DateTimeFormatQueryEvent event )

Parameters

event

A DateTimeFormatQueryEvent object that provides the event data.

Remarks

When overriding this method, call super.onFormatQuery.

See Also addOnFormatQuery


 DateTimePicker.onUserString

DateTimePicker.onUserString

Triggers the userString event.

Syntax

protected void onUserString( DateTimeUserStringEvent event )

Parameters

event

A DateTimeUserStringEvent object that provides the event data.

Remarks

When overriding this method, call super.onUserString.

See Also addOnUserString


 DateTimePicker.onValueChanged

DateTimePicker.onValueChanged

Triggers the valueChanged event.

Syntax

protected void onValueChanged( Event event )

Parameters

event

An Event object that provides the event data.

Remarks

When overriding this method, call super.onValueChanged.

See Also addOnValueChanged


 DateTimePicker.onWmKeyDown

DateTimePicker.onWmKeyDown

Triggers the wmKeyDown event.

Syntax

protected void onWmKeyDown( DateTimeWmKeyDownEvent event )

Parameters

event

A DateTimeWmKeyDownEvent object that provides the event data.

Remarks

When overriding this method, call super.onWmKeyDown.

See Also addOnWmKeyDown


 DateTimePicker.removeOnCloseUp

DateTimePicker.removeOnCloseUp

Removes the delegate that is assigned to the closeUp event.

Syntax

public final void removeOnCloseUp( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnCloseUp


 DateTimePicker.removeOnDropDown

DateTimePicker.removeOnDropDown

Removes the delegate that is assigned to the dropDown event.

Syntax

public final void removeOnDropDown( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnDropDown


 DateTimePicker.removeOnFormat

DateTimePicker.removeOnFormat

Removes the delegate that is assigned to the format event.

Syntax

public final void removeOnFormat( DateTimeFormatEventHandler value )

Parameters

value

The DateTimeFormatEventHandler delegate to be removed.

See Also addOnFormat


 DateTimePicker.removeOnFormatQuery

DateTimePicker.removeOnFormatQuery

Removes the delegate that is assigned to the formatQuery event.

Syntax

public final void removeOnFormatQuery( DateTimeFormatQueryEventHandler value )

Parameters

value

The DateTimeFormatQueryEventHandler delegate to be removed.

See Also addOnFormatQuery


 DateTimePicker.removeOnUserString

DateTimePicker.removeOnUserString

Removes the delegate that is assigned to the userString event.

Syntax

public final void removeOnUserString( DateTimeUserStringEventHandler value )

Parameters

value

The DateTimeUserStringEventHandler delegate to be removed.

See Also addOnUserString


 DateTimePicker.removeOnValueChanged

DateTimePicker.removeOnValueChanged

Removes the delegate that is assigned to the valueChanged event.

Syntax

public final void removeOnValueChanged( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnValueChanged


 DateTimePicker.removeOnWmKeyDown

DateTimePicker.removeOnWmKeyDown

Removes the delegate that is assigned to the wmKeyDown event.

Syntax

public final void removeOnWmKeyDown( DateTimeWmKeyDownEventHandler value )

Parameters

value

The DateTimeWmKeyDownEventHandler delegate to be removed.

See Also addOnWmKeyDown


 DateTimePicker.resetFormat

DateTimePicker.resetFormat

Resets the date and time display format of the calendar to DateTimePickerFormat.LONG.

Syntax

public void resetFormat()

See Also setFormat


 DateTimePicker.resetMaxDate

DateTimePicker.resetMaxDate

Resets the calendar so that there is no upper limit to the selectable range of dates.

Syntax

public void resetMaxDate()

See Also getMaxDate


 DateTimePicker.resetMinDate

DateTimePicker.resetMinDate

Resets the calendar so that there is no lower limit to the selectable range of dates.

Syntax

public void resetMinDate()

See Also getMinDate


 DateTimePicker.resetValue

DateTimePicker.resetValue

Resets the value of the date and time picker control to the current time.

Syntax

public void resetValue()

See Also getValue


 DateTimePicker.setAllowUserString

DateTimePicker.setAllowUserString

Sets a boolean value indicating whether the user can edit the value in the control by pressing F2.

Syntax

public final void setAllowUserString( boolean b )

Parameters

b

Set to true if the user can edit the value in the control by pressing F2; otherwise, set to false. The default value is false. After the user edits the value in the control by pressing F2, the userString event occurs. If this property is set to true, the userString event must be handled to correctly convert the user text into a time.

See Also getAllowUserString


 DateTimePicker.setCalendarFont

DateTimePicker.setCalendarFont

Sets the font used by the month calendar of the date and time picker control.

Syntax

public final void setCalendarFont( Font font )

Parameters

font

A Font object that represents the font used in the month calendar control of the date time picker control. The default value is the default graphical user interface (GUI) font.

See Also getCalendarFont


 DateTimePicker.setCalendarForeColor

DateTimePicker.setCalendarForeColor

Sets the color used to display text within the current month in the month calendar.

Syntax

public final void setCalendarForeColor( Color value )

Parameters

value

A Color object that represents the text color for the month calendar. The default value is the default window text color.

Exceptions

WFCInvalidArgumentException thrown if the specified parameter evaluates to null.

See Also getCalendarForeColor


 DateTimePicker.setCalendarMonthBackground

DateTimePicker.setCalendarMonthBackground

Sets the background color used within the current month in the month calendar.

Syntax

public final void setCalendarMonthBackground( Color value )

Parameters

value

A Color object that represents the text color for the month calendar. The default value is the default window background color.

Exceptions

WFCInvalidArgumentException thrown if the specified parameter evaluates to null.

See Also getCalendarMonthBackground


 DateTimePicker.setCalendarTitleBackColor

DateTimePicker.setCalendarTitleBackColor

Sets the background color displayed in the month calendar's title.

Syntax

public final void setCalendarTitleBackColor( Color value )

Parameters

value

A Color object that represents background color displayed in the month calendar's title. The default value is the default active window caption background color.

Exceptions

WFCInvalidArgumentException thrown if the specified parameter evaluates to null.

See Also getCalendarTitleBackColor


 DateTimePicker.setCalendarTitleForeColor

DateTimePicker.setCalendarTitleForeColor

Sets the color used to display text within the month calendar's title.

Syntax

public final void setCalendarTitleForeColor( Color value )

Parameters

value

A Color object that represents the text color for the month calendar's title. The default value is the default active window caption text color.

Exceptions

WFCInvalidArgumentException thrown if the specified parameter evaluates to null.

See Also getCalendarTitleForeColor


 DateTimePicker.setCalendarTrailingForeColor

DateTimePicker.setCalendarTrailingForeColor

Sets the color used to display text for header and trailing-day days (days from the previous and following month that appear on the current calendar).

Syntax

public final void setCalendarTrailingForeColor( Color value )

Parameters

value

A Color object that represents the color used to display text for header and trailing-day days. The default value is the default window gray text value.

Exceptions

WFCInvalidArgumentException thrown if the specified parameter evaluates to null.

See Also getCalendarTrailingForeColor


 DateTimePicker.setCustomFormat

DateTimePicker.setCustomFormat

Sets a format string that specifies the custom format used by the control to display date and time information.

Syntax

public final void setCustomFormat( String sz )

Parameters

sz

A custom format string that is created by combining format characters from the following table. You can include nonformat characters in the output string by enclosing them in single quotation marks. For example, to produce output like "The current time and date is: 05:31:42 Wednesday Apr 07, 1999", use the following format string: "'The current time and date is: 'hh':'mm':'ss ddddMMMdd', 'yyy".
Format String | Description
d | The one- or two-digit day.
dd | The two-digit day. Single digit day values are preceded by a zero.
ddd | The three-character day-of-week abbreviation.
dddd | The full day-of-week name.
h | The one- or two-digit hour in 12-hour format.
hh | The two-digit hour in 12-hour format. Single digit values are preceded by a zero.
H | The one- or two-digit hour in 24-hour format.
HH | The two-digit hour in 24-hour format. Single digit values are preceded by a zero.
m | The one- or two-digit minute.
mm | The two-digit minute. Single digit values are preceded by a zero.
M | The one- or two-digit month number.
MM | The two-digit month number. Single digit values are preceded by a zero.
MMM | The three-character month abbreviation.
MMMM | The full month name.
s | The one- or two- digit seconds.
ss | The two-digit seconds. Single digit values are preceded by a zero.
t | The one-letter AM/PM abbreviation (that is, "AM" is displayed as "A").
tt | The two-letter AM/PM abbreviation (that is, "AM" is displayed as "AM").
X | A callback field that gives programmer control over the displayed field (see below.) Multiple X characters can be used in a series to signify unique callback fields.
y | The one-digit year (that is, 1996 is displayed as "6").
yy | The last two digits of the year (that is, 1996 is displayed as "96").
yyy | The full year (that is, 1996 is displayed as "1996").


 DateTimePicker.setDropDownAlign

DateTimePicker.setDropDownAlign

Sets a value indicating whether the drop-down month calendar will be aligned to the right or left of the edit control of the date time picker control.

Syntax

public final void setDropDownAlign( int value )

Parameters

value

Set to LeftRightAlignment.LEFT to align the drop-down month calendar to the left of the control; set to LeftRightAlignment.RIGHT to align the drop-down month calendar to the right of the control. The default value is LeftRightAlignment.LEFT.

Exceptions

WFCInvalidEnumException thrown if the specified value is not a valid LeftRightAlignment constant.

See Also getDropDownAlign


 DateTimePicker.setFormat

DateTimePicker.setFormat

Sets a value indicating the whether the control displays date and time information in long date format (for example, "Wednesday, April 7, 1999"), short date format (for example, "4/7/99"), time format (for example, "5:31:34 PM"), or custom format.

Syntax

public final void setFormat( int format )

Parameters

format

An integer that specifies the date and time display format. Possible values are constants defined in the DateTimePickerFormat class. The default value is DateTimePickerFormat.LONG.

Exceptions

WFCInvalidEnumException thrown if the specified value is not a valid DateTimePickerFormat constant.

Remarks

If you use this method to specify that the control should display output in a custom format, use the setCustomFormat method to specify which custom format to use.

See Also getFormat


 DateTimePicker.setMaxDate

DateTimePicker.setMaxDate

Sets a value indicating the last date that the control allows the user to select.

Syntax

public final void setMaxDate( Time date )

Parameters

date

A Time object that represents the last date that is available for selection in the control. Set to null to remove any upper limit for allowable dates. The default value is null.

See Also getMaxDate


 DateTimePicker.setMinDate

DateTimePicker.setMinDate

Sets a value indicating the first date that the control allows the user to select.

Syntax

public final void setMinDate( Time date )

Parameters

date

A Time object that represents the first date that is available for selection in the control. Set to null to remove any lower limit for allowable dates. The default value is null.

See Also getMinDate


 DateTimePicker.setShowNone

DateTimePicker.setShowNone

Sets a boolean value indicating whether it is possible to have no date selected in the control.

Syntax

public final void setShowNone( boolean b )

Parameters

b

Set to true if it is possible to have no date selected in the control; otherwise, set to false. When the showNone property is set to true, a check box appears to the left of the date. Until this check box is checked, the value of the control is -1, which indicates that no date is selected. The default value is false.

See Also getShowNone


 DateTimePicker.setShowUpDown

DateTimePicker.setShowUpDown

Sets a boolean value indicating whether the control allows the user to select a date by displaying an up/down arrow to the right of the control or whether the control enables the user to display a drop-down calendar in which to select a date.

Syntax

public final void setShowUpDown( boolean b )

Parameters

b

Set to true if the control is displayed as an edit control containing date and time fields that the user can set using an up/down arrow; set to false if the control is displayed as an edit control with an attached drop-down month calendar in which the user can select a date. The default value is false.

See Also getShowUpDown


 DateTimePicker.setValue

DateTimePicker.setValue

Sets the date and time value to display in the control.

Syntax

public final void setValue( Time time )

Parameters

time

A Time object that represents the date and time value to display in the control. If the value of the showNone property is true, setting the value property to null indicates that no value should be displayed in the control. If the value of the showNone property is false, setting the value property to null indicates that the current date and time should be displayed in the control. The default value is the current system date and time.

See Also getValue


 DateTimePicker.shouldPersistFormat

DateTimePicker.shouldPersistFormat

Retrieves a boolean value indicating whether the format property has been explicitly set.

Syntax

public boolean shouldPersistFormat()

Return Value

Returns true if the property has been explicitly set; returns false if it still has the default value of DateTimePickerFormat.LONG.


 DateTimePicker.shouldPersistMaxDate

DateTimePicker.shouldPersistMaxDate

Retrieves a boolean value indicating whether the value of the maxDate property has been explicitly set.

Syntax

public boolean shouldPersistMaxDate()

Return Value

Returns true if the property has been explicitly set; returns false if it still has the default value null.


 DateTimePicker.shouldPersistMinDate

DateTimePicker.shouldPersistMinDate

Retrieves a boolean value indicating whether the value of the minDate property has been explicitly set.

Syntax

public boolean shouldPersistMinDate()

Return Value

Returns true if the property has been explicitly set; returns false if it still has the default value of null.


 DateTimePicker.shouldPersistValue

DateTimePicker.shouldPersistValue

Retrieves a boolean value indicating whether the value property has been explicitly set.

Syntax

public boolean shouldPersistValue()

Return Value

Returns true if the property has been explicitly set; returns false if it still has the default value of null.


DateTimePickerFormat Class

Defines constants that specify how the date and time picker control displays date and time information.

Enum
  |
  +--DateTimePickerFormat

package com.ms.wfc.ui

public final class DateTimePickerFormat
extends Enum


 DateTimePickerFormat Methods

DateTimePickerFormat Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 DateTimePickerFormat.valid

DateTimePickerFormat.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 DateTimePickerFormat Fields

DateTimePickerFormat Fields

Fields | Description
CUSTOM | Specifies that the date/time picker control displays the date in a custom format.
LONG | Specifies that the date/time picker control displays the date in long format, which produces output in the form "Wednesday, April 7, 1999".
SHORT | Specifies that the date/time picker control displays the date in short format, which produces output in the form "4/7/99".
TIME | Specifies that the date/time picker control displays date/time information in time format.


 DateTimePickerFormat.CUSTOM

DateTimePickerFormat.CUSTOM

Specifies that the date/time picker control displays the date in a custom format.

Syntax

public static final int CUSTOM;

Remarks

To specify how to format the date and time output, you supply a format string to the DateTimePicker.setCustomFormat method.


 DateTimePickerFormat.LONG

DateTimePickerFormat.LONG

Specifies that the date/time picker control displays the date in long format, which produces output in the form "Wednesday, April 7, 1999".

Syntax

public static final int LONG;


 DateTimePickerFormat.SHORT

DateTimePickerFormat.SHORT

Specifies that the date/time picker control displays the date in short format, which produces output in the form "4/7/99".

Syntax

public static final int SHORT;


 DateTimePickerFormat.TIME

DateTimePickerFormat.TIME

Specifies that the date/time picker control displays date/time information in time format.

Syntax

public static final int TIME;

Remarks

The default time format is determined by your locale settings.


DateTimeUserStringEvent Class

Provides data for the userString event of the DateTimePicker control.

Event
  |
  +--DateTimeUserStringEvent

package com.ms.wfc.ui

public class DateTimeUserStringEvent
extends Event

Remarks

The userString event occurs when the user has finished editing the contents of the date/time picker control and the control needs to parse the entered string. A DateTimeUserStringEvent specifies what string the user entered, and what time that user string represents.

For information about the WFC event model, see Handling Events in WFC.


 DateTimeUserStringEvent Methods

DateTimeUserStringEvent Methods

Constructors | Description
DateTimeUserStringEvent | Creates a DateTimeUserStringEvent object.


 DateTimeUserStringEvent.DateTimeUserStringEvent

DateTimeUserStringEvent.DateTimeUserStringEvent

Creates a DateTimeUserStringEvent object.

Syntax

public DateTimeUserStringEvent( String userString, long time )

Parameters

userString

The string the user entered.

time

The time that the DateTimePicker control should be set to.


 DateTimeUserStringEvent Fields

DateTimeUserStringEvent Fields

Fields | Description
time | Specifies the time that the DateTimePicker control should be set to.
userString | Specifies the string the user entered.


 DateTimeUserStringEvent.time

DateTimeUserStringEvent.time

Specifies the time that the DateTimePicker control should be set to.

Syntax

public long time;


 DateTimeUserStringEvent.userString

DateTimeUserStringEvent.userString

Specifies the string the user entered.

Syntax

public final String userString;


DateTimeUserStringEventHandler Delegate

Identifies the method that will handle the userString event of a DateTimePicker control.

package com.ms.wfc.ui;

public multicast delegate
void DateTimeUserStringEventHandler( Object sender, DateTimeUserStringEvent e );

Remarks

The syntax of the DateTimeUserStringEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a DateTimeUserStringEvent object that provides the event data.

When you create a DateTimeUserStringEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC.


DateTimeWmKeyDownEvent Class

Provides data for the wmKeyDown event of the DateTimePicker control.

Event
  |
  +--DateTimeWmKeyDownEvent

package com.ms.wfc.ui

public class DateTimeWmKeyDownEvent
extends Event

Remarks

The wmKeyDown event occurs when the user presses a key in a custom field. A DateTimeWmKeyDownEvent specifies which key was pressed to trigger the event, which custom date and time format the DateTimePicker control is using, and what time to set the DateTimePicker control to.

For information about the WFC event model, see Handling Events in WFC.


 DateTimeWmKeyDownEvent Methods

DateTimeWmKeyDownEvent Methods

Constructors | Description
DateTimeWmKeyDownEvent | Creates a DateTimeWmKeyDownEvent object.


 DateTimeWmKeyDownEvent.DateTimeWmKeyDownEvent

DateTimeWmKeyDownEvent.DateTimeWmKeyDownEvent

Creates a DateTimeWmKeyDownEvent object.

Syntax

public DateTimeWmKeyDownEvent( int virtualKey, String format, long time )

Parameters

virtualKey

The keycode of the key that was pressed.

format

The custom format string the DateTimePicker control is using.

time

The time that the DateTimePicker control should be set to.


 DateTimeWmKeyDownEvent Fields

DateTimeWmKeyDownEvent Fields

Fields | Description
format | Specifies the custom format string the DateTimePicker control is using.
time | Specifies the time that the DateTimePicker control should be set to.
virtualKey | Specifies the keycode of the key that was pressed in the DateTimePicker control.


 DateTimeWmKeyDownEvent.format

DateTimeWmKeyDownEvent.format

Specifies the custom format string the DateTimePicker control is using.

Syntax

public final String format;


 DateTimeWmKeyDownEvent.time

DateTimeWmKeyDownEvent.time

Specifies the time that the DateTimePicker control should be set to.

Syntax

public long time;


 DateTimeWmKeyDownEvent.virtualKey

DateTimeWmKeyDownEvent.virtualKey

Specifies the keycode of the key that was pressed in the DateTimePicker control.

Syntax

public final int virtualKey;


DateTimeWmKeyDownEventHandler Delegate

Identifies the method that will handle the wmKeyDown event of a DateTimePicker control.

package com.ms.wfc.ui;

public multicast delegate
void DateTimeWmKeyDownEventHandler( Object sender, DateTimeWmKeyDownEvent e );

Remarks

The syntax of the DateTimeWmKeyDownEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a DateTimeWmKeyDownEvent object that provides the event data.

When you create a DateTimeWmKeyDownEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC.


Days Class

Defines constants that represent the days of the week.

Enum
  |
  +--Days

package com.ms.wfc.ui

public class Days
extends Enum


 Days Methods

Days Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 Days.valid

Days.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 Days Fields

Days Fields

Fields | Description
DEFAULT | Represents a default day of the week specified by the application.
FRIDAY | Represents Friday.
MONDAY | Represents Monday.
SATURDAY | Represents Saturday.
SUNDAY | Represents Sunday.
THURSDAY | Represents Thursday.
TUESDAY | Represents Tuesday.
WEDNESDAY | Represents Wednesday.


 Days.DEFAULT

Days.DEFAULT

Represents a default day of the week specified by the application.

Syntax

public static final int DEFAULT;


 Days.FRIDAY

Days.FRIDAY

Represents Friday.

Syntax

public static final int FRIDAY;


 Days.MONDAY

Days.MONDAY

Represents Monday.

Syntax

public static final int MONDAY;


 Days.SATURDAY

Days.SATURDAY

Represents Saturday.

Syntax

public static final int SATURDAY;


 Days.SUNDAY

Days.SUNDAY

Represents Sunday.

Syntax

public static final int SUNDAY;


 Days.THURSDAY

Days.THURSDAY

Represents Thursday.

Syntax

public static final int THURSDAY;


 Days.TUESDAY

Days.TUESDAY

Represents Tuesday.

Syntax

public static final int TUESDAY;


 Days.WEDNESDAY

Days.WEDNESDAY

Represents Wednesday.

Syntax

public static final int WEDNESDAY;


DialogResult Class

Defines constants that represent common results returned from dialog boxes.

Enum
  |
  +--DialogResult

package com.ms.wfc.ui

public class DialogResult
extends Enum

Remarks

If you assign a DialogResult value to the dialogResult property of a Button control, clicking the button closes the parent form and sets the form's dialogResult property to that value (if the form was displayed using the showDialog method).


 DialogResult Methods

DialogResult Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 DialogResult.valid

DialogResult.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 DialogResult Fields

DialogResult Fields

Fields | Description
ABORT | Specifies that the result sent from the dialog box is "ABORT" (usually sent from a button labeled "Abort").
CANCEL | Specifies that the result sent from the dialog box is "CANCEL" (usually sent from a button labeled "Cancel").
IGNORE | Specifies that the result sent from the dialog box is "IGNORE" (usually sent from a button labeled "Ignore").
NO | Specifies that the result sent from the dialog box is "NO" (usually sent from a button labeled "No").
NONE | Specifies that the result sent from the dialog box is "NONE" (this means that the modal dialog should continue running).
OK | Specifies that the result sent from the dialog box is "OK" (usually sent from a button labeled "OK").
RETRY | Specifies that the result sent from the dialog box is "RETRY" (usually sent from a button labeled "Retry").
YES | Specifies that the result sent from the dialog box is "YES" (usually sent from a button labeled "Yes").


 DialogResult.ABORT

DialogResult.ABORT

Specifies that the result sent from the dialog box is "ABORT" (usually sent from a button labeled "Abort").

Syntax

public static final int ABORT;


 DialogResult.CANCEL

DialogResult.CANCEL

Specifies that the result sent from the dialog box is "CANCEL" (usually sent from a button labeled "Cancel").

Syntax

public static final int CANCEL;


 DialogResult.IGNORE

DialogResult.IGNORE

Specifies that the result sent from the dialog box is "IGNORE" (usually sent from a button labeled "Ignore").

Syntax

public static final int IGNORE;


 DialogResult.NO

DialogResult.NO

Specifies that the result sent from the dialog box is "NO" (usually sent from a button labeled "No").

Syntax

public static final int NO;


 DialogResult.NONE

DialogResult.NONE

Specifies that the result sent from the dialog box is "NONE" (this means that the modal dialog should continue running).

Syntax

public static final int NONE;


 DialogResult.OK

DialogResult.OK

Specifies that the result sent from the dialog box is "OK" (usually sent from a button labeled "OK").

Syntax

public static final int OK;


 DialogResult.RETRY

DialogResult.RETRY

Specifies that the result sent from the dialog box is "RETRY" (usually sent from a button labeled "Retry").

Syntax

public static final int RETRY;


 DialogResult.YES

DialogResult.YES

Specifies that the result sent from the dialog box is "YES" (usually sent from a button labeled "Yes").

Syntax

public static final int YES;


Dimensions Class

Encapsulates a two-dimensional array.

package com.ms.wfc.ui

public class Dimensions
implements IConstructable, IPersistable

Remarks

The Dimensions class is used to store the number of columns and rows that should be displayed in the MonthCalendar control.


 Dimensions Methods

Dimensions Methods

Constructors | Description
Dimensions | Creates a Dimensions object.

Methods | Description
equals | Retrieves a boolean value that indicates whether the specified object is equivalent to this one.
getExtension | Retrieves a file name extension with which to save this object's persistent data.
save | Persists this object's settings to the specified data stream.
toString | Retrieves a human-readable string representation of this object.


 Dimensions.Dimensions

Dimensions.Dimensions

Creates a Dimensions object.

Syntax

public Dimensions()

public Dimensions( Dimensions range )

public Dimensions( int rows, int columns )

public Dimensions( IDataStream stream )

Parameters

range

A Dimensions object that contains the settings with which this object should be initialized.

rows

The number of rows in the object.

columns

The number of columns in the object.

stream

The data stream (IDataStream) from which to initialize the object.

Remarks

If you call the Dimensions constructor without any parameters, the rows and columns members take a default value of 1.


 Dimensions.equals

Dimensions.equals

Retrieves a boolean value that indicates whether the specified object is equivalent to this one.

Syntax

public boolean equals( Object obj )

Parameters

obj

The object to compare to this one.

Return Value

Returns true if the given object equals this object; otherwise, returns false.

Remarks

For this method to return true, the object specified in the obj parameter must be a Dimensions object with the same settings as this one.


 Dimensions.getExtension

Dimensions.getExtension

Retrieves a file name extension with which to save this object's persistent data.

Syntax

public String getExtension()

Return Value

Returns a file name extension to use during object persistence. Because Font objects do not use an extension, this method always returns null.

See Also IPersistable


 Dimensions.save

Dimensions.save

Persists this object's settings to the specified data stream.

Syntax

public void save( IDataStream stream )

Parameters

stream

The data stream (IDataStream) to which to persist this object's settings.

See Also IPersistable


 Dimensions.toString

Dimensions.toString

Retrieves a human-readable string representation of this object.

Syntax

public String toString()

Return Value

Returns a string representation of this object.


 Dimensions Fields

Dimensions Fields

Fields | Description
columns | Specifies the number of columns.
rows | Specifies the number of rows.


 Dimensions.columns

Dimensions.columns

Specifies the number of columns.

Syntax

public int columns;


 Dimensions.rows

Dimensions.rows

Specifies the number of rows.

Syntax

public int rows;


DocumentReadyEvent Class

Provides data for the documentReady event of the HTMLControl object.

Event
  |
  +--DocumentReadyEvent

package com.ms.wfc.ui

public class DocumentReadyEvent
extends Event

Remarks

The documentReady event occurs when the document referenced by the HTML control's setURL method has been loaded into the control.

When this event is triggered, you can call the HTML control's getDocument method to retrieve a DhDocument method that represents the control's contents.

For information about the WFC event model, see Handling Events in WFC.


 DocumentReadyEvent Methods

DocumentReadyEvent Methods

Constructors | Description
DocumentReadyEvent | Creates a DocumentReadyEvent object.


 DocumentReadyEvent.DocumentReadyEvent

DocumentReadyEvent.DocumentReadyEvent

Creates a DocumentReadyEvent object.

Syntax

public DocumentReadyEvent()


DocumentReadyEventHandler Delegate

Identifies the method that will handle the documentReady event of an HTML control.

package com.ms.wfc.ui

public multicast delegate
void DocumentReadyEventHandler( Object sender, DocumentReadyEvent e );

Remarks

The syntax of the DocumentReadyEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a DocumentReadyEvent object that provides the event data.

When you create a DocumentReadyEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC.


DragAction Class

Defines constants that specify how and if a drag-and-drop operation should continue.

Enum
  |
  +--DragAction

package com.ms.wfc.ui

public class DragAction
extends Enum


 DragAction Methods

DragAction Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 DragAction.valid

DragAction.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 DragAction Fields

DragAction Fields

Fields | Description
CANCEL | Specifies that the operation should be canceled and no drop message should be sent.
CONTINUE | Specifies that the operation should continue.
DROP | Specifies that the operation should stop by performing a drop.


 DragAction.CANCEL

DragAction.CANCEL

Specifies that the operation should be canceled and no drop message should be sent.

Syntax

public static final int CANCEL;


 DragAction.CONTINUE

DragAction.CONTINUE

Specifies that the operation should continue.

Syntax

public static final int CONTINUE;


 DragAction.DROP

DragAction.DROP

Specifies that the operation should stop by performing a drop.

Syntax

public static final int DROP;


DragDropEffect Class

Defines constants that specify the the effects of a drag-and-drop operation.

Enum
  |
  +--DragDropEffect

package com.ms.wfc.ui

public class DragDropEffect
extends Enum


 DragDropEffect Methods

DragDropEffect Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 DragDropEffect.valid

DragDropEffect.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 DragDropEffect Fields

DragDropEffect Fields

Fields | Description
ALL | Specifies that the drag-and-drop operation results in copying the data, removing the data from the drag source, and scrolling in the drop target.
COPY | Specifies that the drag-and-drop operation results in copying the data to the drop target.
MOVE | Specifies that the drag-and-drop operation results in the original data being from the drag source.
NONE | Specifies that the drop target cannot accept the data.
SCROLL | Specifies that scrolling is about to start or is currently occurring in the drop target.


 DragDropEffect.ALL

DragDropEffect.ALL

Specifies that the drag-and-drop operation results in copying the data, removing the data from the drag source, and scrolling in the drop target.

Syntax

public static final int ALL;


 DragDropEffect.COPY

DragDropEffect.COPY

Specifies that the drag-and-drop operation results in copying the data to the drop target.

Syntax

public static final int COPY;

Remarks

The original data is untouched by the drag source.


 DragDropEffect.MOVE

DragDropEffect.MOVE

Specifies that the drag-and-drop operation results in the original data being from the drag source.

Syntax

public static final int MOVE;


 DragDropEffect.NONE

DragDropEffect.NONE

Specifies that the drop target cannot accept the data.

Syntax

public static final int NONE;


 DragDropEffect.SCROLL

DragDropEffect.SCROLL

Specifies that scrolling is about to start or is currently occurring in the drop target.

Syntax

public static final int SCROLL;


DragEvent Class

Provides data for the the dragDrop, dragEnter, dragLeave, or dragOver event of a Control object.

Event
  |
  +--DragEvent

package com.ms.wfc.ui

public class DragEvent
extends Event

Remarks

The dragDrop event occurs when the user completes a drag-and-drop operation by dragging an object over the control and then dropping it onto the control by releasing the mouse button. The dragEnter event occurs when the user moves the mouse pointer onto the control while dragging an object with the mouse. The dragOver event occurs when the user moves the mouse pointer over the control while dragging an object with the mouse. The dragLeave event occurs when the user moves the mouse pointer out of the control while dragging an object with the mouse. A DragEvent object specifies any data associated with this event, the current state of the SHIFT, CTRL, and ALT keys, the location of the mouse pointer, and the drag-and-drop effect.

For information about the WFC event model, see Handling Events in WFC.


 DragEvent Methods

DragEvent Methods

Constructors | Description
DragEvent | Creates a DragEvent object.


 DragEvent.DragEvent

DragEvent.DragEvent

Creates a DragEvent object.

Syntax

public DragEvent( IDataObject data, int keyState, int x, int y, int effect )

Parameters

data

The IDataObject that contains the data associated with this event.

keyState

The current state of the SHIFT, CTRL, and ALT keys. Valid values are obtained by applying the bitwise OR operation (|) to the Key.SHIFT, Key.CONTROL, and Key.ALT constants defined in the Key class.

x

The x-coordinate of the mouse pointer.

y

The y-coordinate of the mouse pointer.

effect

An integer that represents the allowed drag-and-drop operations. Valid values are obtained by applying the bitwise OR operation (|) to the constants defined in the DragDropEffect class.


 DragEvent Fields

DragEvent Fields

Fields | Description
data | Specifies the IDataObject that contains the data associated with this event.
effect | Specifies which drag-and-drop operations are allowed; can be set to specify the current drag-and-drop operation.
keyState | Specifies the current state of the SHIFT, CTRL, and ALT keys.
x | Specifies the x-coordinate of the mouse pointer.
y | Specifies the y-coordinate of the mouse pointer.


 DragEvent.data

DragEvent.data

Specifies the IDataObject that contains the data associated with this event.

Syntax

public final IDataObject data;


 DragEvent.effect

DragEvent.effect

Specifies which drag-and-drop operations are allowed; can be set to specify the current drag-and-drop operation.

Syntax

public int effect;

Remarks

The value of the effect field passed with an event initially represents the drag-and-drop effects allowed for the control. The value passed is the result of applying the bitwise OR operation (|) to constants defined in the DragDropEffect class. You can use the effect field to store the current drag-and-drop effect. This information can be used to optimize a drag-and-drop operation, as shown in the following code:

private int
effect = 0;

private void testControl_dragEnter(Object sender, DragEvent e) {
// Check if the COPY effect is allowed.
if ((e.effect & DragDropEffect.COPY) != 0) {
// If so, set the current effect to COPY.
e.effect = DragDropEffect.COPY;
}
// Store the current effect. This can then be used to optimize the
dragOver event handler.
effect = e.effect;
}

private void testControl_dragOver(Object sender, DragEvent e) {
// Set the effect for the dragOver event to the current effect.
e.effect = effect;
}


 DragEvent.keyState

DragEvent.keyState

Specifies the current state of the SHIFT, CTRL, and ALT keys.

Syntax

public final int keyState;

Remarks

Valid values are obtained by applying the bitwise OR operation (|) to the Key.SHIFT, Key.CONTROL, and Key.ALT constants defined in the Key class.


 DragEvent.x

DragEvent.x

Specifies the x-coordinate of the mouse pointer.

Syntax

public final int x;


 DragEvent.y

DragEvent.y

Specifies the y-coordinate of the mouse pointer.

Syntax

public final int y;


DragEventHandler Delegate

Identifies the method handling the dragDrop, dragEnter, dragLeave, or dragOver event of a Control control.

package com.ms.wfc.ui

public multicast delegate
void DragEventHandler( Object sender, DragEvent e );

Remarks

The syntax of the DragEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a DragEvent object that provides the event data.

When you create a DragEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC.


DrawItemEvent Class

Provides data for the drawItem event of a ComboBox, ListBox, StatusBar, TabStrip, or TabControl control.

Event
  |
  +--DrawItemEvent

package com.ms.wfc.ui

public class DrawItemEvent
extends Event

Remarks

The drawItem event occurs when a visual aspect of an owner-drawn combo box changes. A DrawItemEvent object specifies whether the drawing takes place in a combo box, whether the item to draw has the focus, and whether the item to draw is selected. This event also provides the Graphics object to use to draw the item, the Rectangle object in which to draw the item, and the item index.

For information about the WFC event model, see Handling Events in WFC.

See Also DrawItemState


 DrawItemEvent Methods

DrawItemEvent Methods

Constructors | Description
DrawItemEvent | Creates a DrawItemEvent object.

Methods | Description
drawBackground | Draws the background for the rectangle in which the item is drawn with default Windows control colors.
drawFocusRect | Draws a focus rectangle around the item if the item is selected.


 DrawItemEvent.drawBackground

DrawItemEvent.drawBackground

Draws the background for the rectangle in which the item is drawn with default Windows control colors.

Syntax

public void drawBackground()


 DrawItemEvent.drawFocusRect

DrawItemEvent.drawFocusRect

Draws a focus rectangle around the item if the item is selected.

Syntax

public void drawFocusRect()


 DrawItemEvent.DrawItemEvent

DrawItemEvent.DrawItemEvent

Creates a DrawItemEvent object.

Syntax

public DrawItemEvent( Graphics graphics, Rectangle rect, int index, int state )

Parameters

graphics

The Graphics object used to draw the item.

rect

The Rectangle object that represents the rectangle in which the item will be drawn.

index

The zero-based index of the item.

state

An integer that includes state information, such as whether the item is selected, whether the item has the focus, and whether the item is drawn in the edit control of an owner-drawn combo box.


 DrawItemEvent Fields

DrawItemEvent Fields

Fields | Description
graphics | Specifies the Graphics object used to draw the item.
index | Specifies the zero-based index of the item.
rect | Specifies the Rectangle object that represents the rectangle in which the item will be drawn.
state | Specifies state information, such as whether the item is selected, whether the item has the focus, and whether the item is drawn in the edit control of an owner-drawn combo box.


 DrawItemEvent.graphics

DrawItemEvent.graphics

Specifies the Graphics object used to draw the item.

Syntax

public final Graphics graphics;


 DrawItemEvent.index

DrawItemEvent.index

Specifies the zero-based index of the item.

Syntax

public final int index;


 DrawItemEvent.rect

DrawItemEvent.rect

Specifies the Rectangle object that represents the rectangle in which the item will be drawn.

Syntax

public final Rectangle rect;


 DrawItemEvent.state

DrawItemEvent.state

Specifies state information, such as whether the item is selected, whether the item has the focus, and whether the item is drawn in the edit control of an owner-drawn combo box.

Syntax

public final int state;

See Also DrawItemState


DrawItemEventHandler Delegate

Identifies the method that will handle the drawItem event of a ComboBox, ListBox, StatusBar, TabStrip, or TabControl control.

package com.ms.wfc.ui

public multicast delegate
void DrawItemEventHandler( Object sender, DrawItemEvent e );

Remarks

The syntax of the DrawItemEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a DrawItemEvent object that provides the event data.

When you create a DrawItemEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC.


DrawItemState Class

Defines constants that specify state information for a drawing operation.

Enum
    |
    +--DrawItemState

package com.ms.wfc.ui

public class DrawItemState
extends Enum


 DrawItemState Methods

DrawItemState Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 DrawItemState.valid

DrawItemState.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 DrawItemState Fields

DrawItemState Fields

Fields | Description
COMBOBOXEDIT | Specifies that the drawing takes place in the edit control of an owner-drawn combo box.
FOCUS | Specifies that the item being drawn has the focus.
NONE | Specifies that the item being drawn is not selected and does not have the focus.
SELECTED | Specifies that the item being drawn is selected.


 DrawItemState.COMBOBOXEDIT

DrawItemState.COMBOBOXEDIT

Specifies that the drawing takes place in the edit control of an owner-drawn combo box.

Syntax

public static final int COMBOBOXEDIT;


 DrawItemState.FOCUS

DrawItemState.FOCUS

Specifies that the item being drawn has the focus.

Syntax

public static final int FOCUS;


 DrawItemState.NONE

DrawItemState.NONE

Specifies that the item being drawn is not selected and does not have the focus.

Syntax

public static final int NONE;


 DrawItemState.SELECTED

DrawItemState.SELECTED

Specifies that the item being drawn is selected.

Syntax

public static final int SELECTED;


DrawMode Class

Defines a group of constants that specify how the elements of a list box or combo box are drawn.

Enum
  |
  +--DrawMode

package com.ms.wfc.ui

public class DrawMode
extends Enum

Remarks

When you draw a list box or combo box on a form, you can set its drawMode property (or call the class' setDrawMode method) to specify how items in the list box or combo box are drawn.

The constants defined in this class represent the variables that you can pass to the ListBox or ComboBox control's setDrawMode method.


 DrawMode Methods

DrawMode Methods

Methods | Description
valid | Retrieves a boolean value that indicates whether the specified value is a valid DrawMode constant.


 DrawMode.valid

DrawMode.valid

Retrieves a boolean value that indicates whether the specified value is a valid DrawMode constant.

Syntax

public static boolean valid( int value )

Parameters

value

The value to verify against the constants defined in this class.

Return Value

Returns true if the specified value is valid; otherwise, returns false.


 DrawMode Fields

DrawMode Fields

Fields | Description
NORMAL | Represents a drawing mode in which all the items in a list box or combo box are painted by the operating system and are of the same size.
OWNERDRAWFIXED | Represents a drawing mode in which the items in the list box or combo box are painted manually, but are of the same height.
OWNERDRAWVARIABLE | Represents a drawing mode in which the items in the list box or combo box are painted manually, but are not necessarily the same size.


 DrawMode.NORMAL

DrawMode.NORMAL

Represents a drawing mode in which all the items in a list box or combo box are painted by the operating system and are of the same size.

Syntax

public static final int NORMAL;


 DrawMode.OWNERDRAWFIXED

DrawMode.OWNERDRAWFIXED

Represents a drawing mode in which the items in the list box or combo box are painted manually, but are of the same height.

Syntax

public static final int OWNERDRAWFIXED;


 DrawMode.OWNERDRAWVARIABLE

DrawMode.OWNERDRAWVARIABLE

Represents a drawing mode in which the items in the list box or combo box are painted manually, but are not necessarily the same size.

Syntax

public static final int OWNERDRAWVARIABLE;


Edit Class

Encapsulates a Windows edit control, which is a rectangular control that the user can enter text into.

Component
  |
  +--Control
    |
    +--Edit

package com.ms.wfc.ui

public class Edit
extends Control


 Edit Methods

Edit Methods

Constructors | Description
Edit | Creates an Edit control.

Methods | Description
addOnTextChanged | Assigns a delegate to the textChanged event.
canUndo | Retrieves a boolean value indicating whether the edit control can undo the last operation.
clear | Clears the edit control.
clearUndo | Clears information about the most recent operation from the undo buffer of the edit control.
copy | Copies the current selection in the edit control to the Clipboard.
cut | Removes the current selection from the edit control and moves it to the Clipboard.
getAcceptsReturn | Retrieves a boolean value indicating whether pressing ENTER in a multiline edit control creates a new line of text in the edit control instead of activating the default button for the form.
getAcceptsTab | Retrieves a boolean value indicating that pressing TAB in the edit control types a TAB character in the control instead of moving the focus to the next control in the tab order.
getAutoSize | Retrieves a boolean value indicating whether the size of the control automatically adjusts when the font is changed.
getBorderStyle | Retrieves a value indicating the kind of border the edit control has.
getCharacterCasing | Retrieves a value indicating whether the edit control modifies the case of characters as they are typed into the control.
getHideSelection | Retrieves a boolean value indicating whether the selected text in the edit control remains highlighted when the control loses the focus.
getLines | Retrieves the text in the edit control.
getMaxLength | Retrieves the maximum length, in bytes, of the text the user can type into the edit control.
getMultiline | Retrieves a boolean value indicating whether this is a multiline edit control.
getPasswordChar | Retrieves the character used to mask characters in a single-line edit control used to enter passwords.
getPreferredHeight | Retrieves the preferred height for the edit control.
getReadOnly | Retrieves a boolean value indicating whether the edit control is read-only.
getScrollBars | Retrieves a value indicating which scroll bars appear on a multiline edit control.
getSelectedText | Retrieves the currently selected text in the edit control.
getSelectionEnd | Retrieves the zero-based index of the first character after the end of the current text selection in the edit control.
getSelectionStart | Retrieves the zero-based index of the first character in the current text selection in the edit control.
getTextAlign | Retrieves a value indicating how text is aligned in an edit control.
getWordWrap | Retrieves a boolean value indicating whether a multiline edit control automatically wraps words to the beginning of the next line when necessary.
onTextChanged | Triggers the textChanged event.
paste | Replaces the current selection in the edit control with the contents of the Clipboard.
removeOnTextChanged | Removes the delegate that is assigned to the textChanged event.
select | Selects a range of text in the edit control.
selectAll | Selects all the text in the edit control.
setAcceptsReturn | Sets a boolean value indicating whether pressing ENTER in a multiline edit control creates a new line of text in the edit control instead of activating the default button for the form.
setAcceptsTab | Sets a boolean value indicating that pressing TAB in the edit control types a TAB character in the control instead of moving the focus to the next control in the tab order.
setAutoSize | Sets a boolean value indicating whether the size of the control automatically adjusts when the font is changed.
setBorderStyle | Sets a value indicating the kind of border the edit control has.
setCharacterCasing | Sets a value indicating whether the edit control modifies the case of characters as they are typed into the control.
setHideSelection | Sets a boolean value indicating whether the selected text in the edit control remains highlighted when the control loses the focus.
setLines | Sets the text in the edit control.
setMaxLength | Sets the maximum length, in bytes, of the text the user can type into the edit control.
setMultiline | Sets a boolean value indicating whether this is a multiline edit control.
setPasswordChar | Sets the character used to mask characters in a single-line edit control used to enter passwords.
setReadOnly | Sets a boolean value indicating whether the edit control is read-only.
setScrollBars | Sets a value indicating which scroll bars appear in a multiline edit control.
setSelectedText | Replaces the currently selected text in the edit control with the specified text.
setSelectionEnd | Sets the end position of the text selection in the edit control.
setSelectionStart | Sets the starting position of the text selection in the edit control.
setTextAlign | Sets a value indicating how text is aligned in an edit control.
setWordWrap | Sets a boolean value indicating whether a multiline edit control automatically wraps words to the beginning of the next line when necessary.
toString | Retrieves a string that contains information about the edit control.
undo | Undoes the last operation in the edit control if the canUndo property is set to true.


 Edit.addOnTextChanged

Edit.addOnTextChanged

Assigns a delegate to the textChanged event.

Syntax

public final void addOnTextChanged( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the textChanged event to that method in the Properties window. The textChanged event occurs when the user takes an action that may have altered the text in the edit control.

See Also removeOnTextChanged


 Edit.canUndo

Edit.canUndo

Retrieves a boolean value indicating whether the edit control can undo the last operation.

Syntax

public final boolean canUndo()

Return Value

Returns true if the edit control can undo the last operation; otherwise, returns false.

Remarks

If this method returns true, you can call the undo method to undo the last operation.


 Edit.clear

Edit.clear

Clears the edit control.

Syntax

public final void clear()


 Edit.clearUndo

Edit.clearUndo

Clears information about the most recent operation from the undo buffer of the edit control.

Syntax

public final void clearUndo()

Remarks

The control cannot undo the operation that was stored in the buffer.


 Edit.copy

Edit.copy

Copies the current selection in the edit control to the Clipboard.

Syntax

public final void copy()


 Edit.cut

Edit.cut

Removes the current selection from the edit control and moves it to the Clipboard.

Syntax

public final void cut()


 Edit.Edit

Edit.Edit

Creates an Edit control.

Syntax

public Edit()


 Edit.getAcceptsReturn

Edit.getAcceptsReturn

Retrieves a boolean value indicating whether pressing ENTER in a multiline edit control creates a new line of text in the edit control instead of activating the default button for the form.

Syntax

public final boolean getAcceptsReturn()

Return Value

Returns true if pressing ENTER in the multiline edit control creates a new line of text in the edit control; returns false if pressing ENTER in the multiline edit control activates the default button for the form. If this value returns false, the user must press CTRL+ENTER to create a new line in the multiline edit control.

See Also setAcceptsReturn


 Edit.getAcceptsTab

Edit.getAcceptsTab

Retrieves a boolean value indicating that pressing TAB in the edit control types a TAB character in the control instead of moving the focus to the next control in the tab order.

Syntax

public final boolean getAcceptsTab()

Return Value

Returns true if users can enter tabs in the control; returns false if pressing TAB moves the focus to the next control in the tab order. If a control allows the user to enter tabs, the user must press CTRL+TAB to move to the next control in the tab order.

See Also setAcceptsTab


 Edit.getAutoSize

Edit.getAutoSize

Retrieves a boolean value indicating whether the size of the control automatically adjusts when the font is changed.

Syntax

public final boolean getAutoSize()

Return Value

Returns true if the size of the control automatically adjusts when the font is changed; otherwise, returns false.

Remarks

Multiline edit controls ignore the autoSize property setting.

See Also setAutoSize


 Edit.getBorderStyle

Edit.getBorderStyle

Retrieves a value indicating the kind of border the edit control has.

Syntax

public final int getBorderStyle()

Return Value

Returns an integer that specifies the kind of border the edit control has. Possible return values are constants defined in the BorderStyle class. If the value is BorderStyle.FIXED_3D, the edit control has a three-dimensional border.

See Also setBorderStyle


 Edit.getCharacterCasing

Edit.getCharacterCasing

Retrieves a value indicating whether the edit control modifies the case of characters as they are typed into the control.

Syntax

public final int getCharacterCasing()

Return Value

Returns an integer that specifies whether the edit control modifies the case of characters as they are typed into the control. Possible return values are constants defined in the CharacterCasing class.

See Also setCharacterCasing


 Edit.getHideSelection

Edit.getHideSelection

Retrieves a boolean value indicating whether the selected text in the edit control remains highlighted when the control loses the focus.

Syntax

public final boolean getHideSelection()

Return Value

Returns true if the selected text does not appear highlighted when the edit control loses the focus; returns false if the selected text still appears highlighted when the edit control loses the focus.

See Also setHideSelection


 Edit.getLines

Edit.getLines

Retrieves the text in the edit control.

Syntax

public final String[] getLines()

Return Value

Returns an array of String objects that contains the contents of the edit control. Each line of text in the edit control becomes an element in the returned array. For single-line edit controls, the returned array contains a single element.

See Also setLines


 Edit.getMaxLength

Edit.getMaxLength

Retrieves the maximum length, in bytes, of the text the user can type into the edit control.

Syntax

public final int getMaxLength()

Return Value

Returns the maximum length, in bytes, of text that the user can type into the edit control. Returns zero (0) if the maximum capacity of the edit control is limited only to available memory.

See Also setMaxLength


 Edit.getMultiline

Edit.getMultiline

Retrieves a boolean value indicating whether this is a multiline edit control.

Syntax

public final boolean getMultiline()

Return Value

Returns true if the control is a multiline edit control; otherwise, returns false.

See Also setMultiline


 Edit.getPasswordChar

Edit.getPasswordChar

Retrieves the character used to mask characters in a single-line edit control used to enter passwords.

Syntax

public final char getPasswordChar()

Return Value

Returns the character used to mask characters in an edit control used to enter passwords.

See Also setPasswordChar


 Edit.getPreferredHeight

Edit.getPreferredHeight

Retrieves the preferred height for the edit control.

Syntax

public final int getPreferredHeight()

Return Value

Returns the combined height, in pixels, of a single line of text displayed in the current font plus the borders of the edit control.


 Edit.getReadOnly

Edit.getReadOnly

Retrieves a boolean value indicating whether the edit control is read-only.

Syntax

public final boolean getReadOnly()

Return Value

Returns true if the control is read-only; otherwise, returns false.

See Also setReadOnly


 Edit.getScrollBars

Edit.getScrollBars

Retrieves a value indicating which scroll bars appear on a multiline edit control.

Syntax

public final int getScrollBars()

Return Value

Returns an integer that indicates whether the multiline edit control appears with no scroll bars, a horizontal scroll bar, a vertical scroll bar, or with both scroll bars. Possible return values are constants defined in the ScrollBars class.

See Also setScrollBars


 Edit.getSelectedText

Edit.getSelectedText

Retrieves the currently selected text in the edit control.

Syntax

public final String getSelectedText()

Return Value

Returns a String object containing the text that is selected in the edit control; if no text is selected, returns null.

See Also setSelectedText


 Edit.getSelectionEnd

Edit.getSelectionEnd

Retrieves the zero-based index of the first character after the end of the current text selection in the edit control.

Syntax

public final int getSelectionEnd()

Return Value

Returns the zero-based index of the first character after the end of the current text selection in the edit control. For example, if the third through fifth characters are selected in the edit control (with zero-based indexes 2 through 4), the getSelectionEnd method returns 5. If the cursor is in the edit control but no text is selected, both the getSelectionStart method and the getSelectionEnd method return the same value. For example, if the cursor is between the third and fourth characters, both methods return 3.

See Also setSelectionEnd


 Edit.getSelectionStart

Edit.getSelectionStart

Retrieves the zero-based index of the first character in the current text selection in the edit control.

Syntax

public final int getSelectionStart()

Return Value

Returns the zero-based index of the first character in the current text selection in the edit control. For example, if the third through fifth characters are selected in the edit control (with zero-based indexes 2 through 4), the getSelectionStart method returns 2. If the cursor is in the edit control but no text is selected, both the getSelectionStart method and the getSelectionEnd method return the same value. For example, if the cursor is between the third and fourth characters, both methods return 3.

See Also setSelectionStart


 Edit.getTextAlign

Edit.getTextAlign

Retrieves a value indicating how text is aligned in an edit control.

Syntax

public final int getTextAlign()

Return Value

Returns an integer that specifies how text is aligned in an edit control. Possible return values are constants defined in the HorizontalAlignment class.

See Also setTextAlign


 Edit.getWordWrap

Edit.getWordWrap

Retrieves a boolean value indicating whether a multiline edit control automatically wraps words to the beginning of the next line when necessary.

Syntax

public final boolean getWordWrap()

Return Value

Returns true if the multiline edit control automatically wraps words to the beginning of the next line when necessary; returns false if instead of wrapping to the next line, the edit control automatically scrolls horizontally when the user types past the right edge of the edit control.

See Also setWordWrap


 Edit.onTextChanged

Edit.onTextChanged

Triggers the textChanged event.

Syntax

protected void onTextChanged( Event e )

Parameters

e

An Event object that provides the event data.

Remarks

When overriding this method, call super.onTextChanged.

See Also addOnTextChanged


 Edit.paste

Edit.paste

Replaces the current selection in the edit control with the contents of the Clipboard.

Syntax

public final void paste()


 Edit.removeOnTextChanged

Edit.removeOnTextChanged

Removes the delegate that is assigned to the textChanged event.

Syntax

public final void removeOnTextChanged( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnTextChanged


 Edit.select

Edit.select

Selects a range of text in the edit control.

Syntax

public final void select( int start, int end )

Parameters

start

The position of the last character before the beginning of the current text selection in the edit control.

end

The position of the last character before the end of the current text selection in the edit control.


 Edit.selectAll

Edit.selectAll

Selects all the text in the edit control.

Syntax

public final void selectAll()


 Edit.setAcceptsReturn

Edit.setAcceptsReturn

Sets a boolean value indicating whether pressing ENTER in a multiline edit control creates a new line of text in the edit control instead of activating the default button for the form.

Syntax

public final void setAcceptsReturn( boolean value )

Parameters

value

Set to true pressing ENTER in the multiline edit control creates a new line of text in the edit control; set to false if pressing ENTER in the multiline edit control activates the default button for the form. If you set this to false, the user must press CTRL+ENTER to create a new line in the multiline edit control. The default value is true.

See Also getAcceptsReturn


 Edit.setAcceptsTab

Edit.setAcceptsTab

Sets a boolean value indicating that pressing TAB in the edit control types a TAB character in the control instead of moving the focus to the next control in the tab order.

Syntax

public final void setAcceptsTab( boolean value )

Parameters

value

Set to true if users can enter tabs in the control; set to false if pressing TAB moves the focus to the next control in the tab order. If a control allows the user to enter tabs, the user must press CTRL+TAB to move to the next control in the tab order. The default value is false.

See Also getAcceptsTab


 Edit.setAutoSize

Edit.setAutoSize

Sets a boolean value indicating whether the size of the control automatically adjusts when the font is changed.

Syntax

public final void setAutoSize( boolean value )

Parameters

value

Set to true if the size of the control automatically adjusts when the font is changed; otherwise, set to false. The default value is true.

Remarks

Multiline edit controls ignore the autoSize property setting.

See Also getAutoSize


 Edit.setBorderStyle

Edit.setBorderStyle

Sets a value indicating the kind of border the edit control has.

Syntax

public final void setBorderStyle( int value )

Parameters

value

An integer that specifies the kind of border the edit control has. Possible return values are constants defined in the BorderStyle class. If the value is BorderStyle.FIXED_3D, the edit control has a three-dimensional border. The default value is BorderStyle.FIXED_3D.

Exceptions

WFCInvalidEnumException thrown if the specified value is not a valid BorderStyle constant.

See Also getBorderStyle


 Edit.setCharacterCasing

Edit.setCharacterCasing

Sets a value indicating whether the edit control modifies the case of characters as they are typed into the control.

Syntax

public final void setCharacterCasing( int value )

Parameters

value

An integer that specifies whether the edit control modifies the case of characters as they are typed into the control. Possible return values are constants defined in the CharacterCasing class. The default value is CharacterCasing.NORMAL.

Exceptions

WFCInvalidEnumException thrown if the specified value is not a valid CharacterCasing constant.

See Also getCharacterCasing


 Edit.setHideSelection

Edit.setHideSelection

Sets a boolean value indicating whether the selected text in the edit control remains highlighted when the control loses the focus.

Syntax

public final void setHideSelection( boolean value )

Parameters

value

Set to true if the selected text does not appear highlighted when the edit control loses the focus; set to false if the selected text still appears highlighted when the edit control loses the focus. The default value is true.

See Also getHideSelection


 Edit.setLines

Edit.setLines

Sets the text in the edit control.

Syntax

public final void setLines( String[] lines )

Parameters

lines

An array of String objects that contains the text you want to show in the edit control. Each element in the array becomes a line of text in the edit control. If a newline character appears in an element of the array, the text following it will be placed on a new line in the edit control.

See Also getLines


 Edit.setMaxLength

Edit.setMaxLength

Sets the maximum length, in bytes, of the text the user can type into the edit control.

Syntax

public final void setMaxLength( int value )

Parameters

value

The maximum length, in bytes, of text that the user can type into the edit control. Set to a value less than or equal to zero (0) to indicate that the maximum capacity of the edit control is limited only to available memory. The default value is zero (0).

See Also getMaxLength


 Edit.setMultiline

Edit.setMultiline

Sets a boolean value indicating whether this is a multiline edit control.

Syntax

public final void setMultiline( boolean value )

Parameters

value

Set to true if the control is a multiline edit control; otherwise, set to false. The default value is false.

See Also getMultiline


 Edit.setPasswordChar

Edit.setPasswordChar

Sets the character used to mask characters in a single-line edit control used to enter passwords.

Syntax

public final void setPasswordChar( char value )

Parameters

value

The character used to mask characters in an edit control used to enter passwords. Set to zero (0) if you do not want the edit control to mask characters as they are typed (that is, if you want the characters typed by the user to appear in the control). By default, characters are not masked.

See Also getPasswordChar


 Edit.setReadOnly

Edit.setReadOnly

Sets a boolean value indicating whether the edit control is read-only.

Syntax

public final void setReadOnly( boolean value )

Parameters

value

Set to true if the control is read-only; otherwise, set to false. The default value is false.

See Also getReadOnly


 Edit.setScrollBars

Edit.setScrollBars

Sets a value indicating which scroll bars appear in a multiline edit control.

Syntax

public final void setScrollBars( int value )

Parameters

value

An integer that indicates whether the multiline edit control appears with no scroll bars, a horizontal scroll bar, a vertical scroll bar, or with both scroll bars. Possible values are constants defined in the ScrollBars class.

Exceptions

WFCInvalidEnumException thrown if the specified value is not a valid ScrollBars constant. The default value is ScrollBars.NONE.

See Also getScrollBars


 Edit.setSelectedText

Edit.setSelectedText

Replaces the currently selected text in the edit control with the specified text.

Syntax

public final void setSelectedText( String value )

Parameters

value

The text with which to replace the currently selected text.

See Also getSelectedText


 Edit.setSelectionEnd

Edit.setSelectionEnd

Sets the end position of the text selection in the edit control.

Syntax

public final void setSelectionEnd( int value )

Parameters

value

The zero-based index of the first character after the end of the text to select in the edit control. For example, to select the third through fifth characters are selected in the edit control (with zero-based indexes 2 through 4), set this value to 5, and set the value parameter of the setSelectionStart method to 2. To place the cursor in the edit control without selecting text, specify the same value for both the getSelectionStart method and the getSelectionEnd method. For example, to place the cursor between the third and fourth characters, pass the value 3 to both methods.

See Also getSelectionEnd


 Edit.setSelectionStart

Edit.setSelectionStart

Sets the starting position of the text selection in the edit control.

Syntax

public final void setSelectionStart( int value )

Parameters

value

The zero-based index of the first character to include in the text selection in the edit control. For example, to select the third through fifth characters in the edit control (with zero-based indexes 2 through 4), set this value to 2, and set the value parameter of the setSelectionEnd method to 5. To place the cursor in the edit control without selecting text, specify the same value for both the getSelectionStart method and the getSelectionEnd method. For example, to place the cursor between the third and fourth characters, pass the value 3 to both methods.

See Also getSelectionStart


 Edit.setTextAlign

Edit.setTextAlign

Sets a value indicating how text is aligned in an edit control.

Syntax

public void setTextAlign( int value )

Parameters

value

An integer that specifies how text is aligned in an edit control. Possible values are constants defined in the HorizontalAlignment class. The default value is HorizontalAlignment.LEFT.

Exceptions

WFCInvalidEnumException thrown if the specified value is not a valid HorizontalAlignment constant.

See Also getTextAlign


 Edit.setWordWrap

Edit.setWordWrap

Sets a boolean value indicating whether a multiline edit control automatically wraps words to the beginning of the next line when necessary.

Syntax

public final void setWordWrap( boolean value )

Parameters

value

Set to true if the multiline edit control automatically wraps words to the beginning of the next line when necessary; set to false if the edit control automatically scrolls horizontally when the user types past the right edge of the edit control. The default value is true.

See Also getWordWrap


 Edit.toString

Edit.toString

Retrieves a string that contains information about the edit control.

Syntax

public String toString()

Return Value

Returns a String that contains the name of the edit control and the first 40 characters it contains.


 Edit.undo

Edit.undo

Undoes the last operation in the edit control if the canUndo property is set to true.

Syntax

public final void undo()


EraseBackgroundEvent Class

Provides data for the eraseBackground event of the Control object.

Event
  |
  +--EraseBackgroundEvent

package com.ms.wfc.ui

public class EraseBackgroundEvent
extends Event

Remarks

The eraseBackground event occurs when the control background must be erased (for example, when the control is resized). An EraseBackgroundEvent object specifies the device context used to display the control and specifies whether the event is handled.

For information about the WFC event model, see Handling Events in WFC.


 EraseBackgroundEvent Methods

EraseBackgroundEvent Methods

Constructors | Description
EraseBackgroundEvent | Creates an EraseBackgroundEvent object.


 EraseBackgroundEvent.EraseBackgroundEvent

EraseBackgroundEvent.EraseBackgroundEvent

Creates an EraseBackgroundEvent object.

Syntax

public EraseBackgroundEvent( Graphics graphics, boolean handled )

Parameters

graphics

The Graphics object that represents the device context that displays the control.

handled

Set to true to specify that the event is handled; otherwise, set to false. If you do not want the default Windows background-erasing behavior, set this parameter to true.


 EraseBackgroundEvent Fields

EraseBackgroundEvent Fields

Fields | Description
graphics | Specifies the Graphics object that represents the device context that displays the control.
handled | Specifies whether the event is handled.


 EraseBackgroundEvent.graphics

EraseBackgroundEvent.graphics

Specifies the Graphics object that represents the device context that displays the control.

Syntax

public final Graphics graphics;


 EraseBackgroundEvent.handled

EraseBackgroundEvent.handled

Specifies whether the event is handled.

Syntax

public boolean handled;


FileDialog Class

Defines the base class for the OpenFileDialog and SaveFileDialog classes.

Component
  |
  +--CommonDialog
    |
    +--FileDialog

package com.ms.wfc.ui

public abstract class FileDialog
extends CommonDialog


 FileDialog Methods

FileDialog Methods

Constructors | Description
FileDialog | Creates a FileDialog control.

Methods | Description
addOnFileOk | Assigns a delegate to the fileOk event.
getAddExtension | Retrieves a boolean value indicating whether the dialog box automatically adds an extension to a file name when the user omits the extension.
getCheckFileExists | Retrieves a boolean value indicating whether the dialog box should display a warning if the user specifies a file name that does not exist.
getCheckPathExists | Retrieves a boolean value indicating whether the dialog box should display a warning if the user specifies a path that does not exist.
getDefaultExt | Retrieves the default file extension.
getDereferenceLinks | Retrieves a boolean value indicating whether the dialog box returns the path and file name of the file referenced by the a shortcut or whether it returns the path and file name of the shortcut (.LNK) file.
getFileName | Retrieves the file name of the selected file.
getFileNames | Retrieves the file names of all selected files in the dialog box.
getFilter | Retrieves the current filter string (the string that determines the choices that appear in the Save as file type or Files of type box in the dialog box and allow the user to filter out the kinds of files that are shown in the dialog box).
getFilterIndex | Retrieves a value indicating the one-based index of the filter currently selected in the dialog box.
getInitialDir | Retrieves the path for the directory whose contents are initially displayed in the dialog box.
getRestoreDirectory | Retrieves a boolean value indicating whether the dialog box restores the current directory before closing.
getShowHelp | Retrieves a boolean value indicating whether the dialog box contains a Help button.
getTitle | Retrieves the text that appears in the title bar of the dialog box.
getValidateNames | Retrieves a boolean value indicating whether the dialog box accepts only valid Win32 file names.
onFileOk | Triggers the fileOk event.
promptFileCreate | Prompts the user when a file is about to be created.
promptFileNotFound | Prompts the user when a file does not exist.
promptFileOverwrite | Prompts the user when a file is about to be overwritten.
removeOnFileOk | Removes the delegate that is assigned to the fileOk event.
reset | Resets all dialog box options to their default values.
setAddExtension | Sets a boolean value indicating whether the dialog box automatically adds an extension to a file name when the user omits the extension.
setCheckFileExists | Sets a boolean value indicating whether the dialog box should display a warning if the user specifies a file name that does not exist.
setCheckPathExists | Sets a boolean value indicating whether the dialog box should display a warning if the user specifies a path that does not exist.
setDefaultExt | Sets the default file extension, which is appended to a file name if the user fails to type an extension.
setDereferenceLinks | Sets a boolean value indicating whether the dialog box returns the path and file name of the file referenced by the a shortcut or whether it returns the path and file name of the shortcut (.LNK) file.
setFileName | Sets a value that indicates which file name is selected by default when the dialog box is opened.
setFilter | Sets the current filter string (the string that determines the choices that appear in the Save as file type or Files of type box in the dialog box and allow the user to filter out the kinds of files that are shown in the dialog box).
setFilterIndex | Sets a value representing the one-based index of the filter that is selected by default when the dialog box is opened.
setInitialDir | Sets the path for the directory whose contents are initially displayed in the dialog box.
setRestoreDirectory | Sets a boolean value indicating whether the dialog box restores the current directory before closing.
setShowHelp | Sets a boolean value indicating whether the dialog box contains a Help button.
setTitle | Sets the text that appears in the title bar of the dialog box.
setValidateNames | Sets a boolean value indicating whether the dialog box accepts only valid Win32 file names.


 FileDialog.addOnFileOk

FileDialog.addOnFileOk

Assigns a delegate to the fileOk event.

Syntax

public final void addOnFileOk( CancelEventHandler value )

Parameters

value

The CancelEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the fileOk event to that method in the Properties window. The fileOk event occurs when the user clicks Open or Save in the dialog box. An event handler can prevent the dialog box from closing by setting the cancel field of the CancelEvent object used by the event handler to true.

See Also removeOnFileOk


 FileDialog.FileDialog

FileDialog.FileDialog

Creates a FileDialog control.

Syntax

protected FileDialog()


 FileDialog.getAddExtension

FileDialog.getAddExtension

Retrieves a boolean value indicating whether the dialog box automatically adds an extension to a file name when the user omits the extension.

Syntax

public final boolean getAddExtension()

Return Value

Returns true if the dialog box adds an extension to a file name when the user omits the extension; otherwise, returns false.

Remarks

The extension added to a file name depends on the currently selected file filter and the value of the checkFileExists property. If the checkFileExists property is true, the dialog box adds the first extension from the current file filter that matches an existing file; if no files match the current file filter, the dialog box adds the extension specified in the defaultExt property. If the checkFileExists property is false, the dialog box adds the first valid file extension from the current file filter; if the current file filter contains no valid file extensions, the dialog box adds the extension specified in the defaultExt property.

See Also setAddExtension


 FileDialog.getCheckFileExists

FileDialog.getCheckFileExists

Retrieves a boolean value indicating whether the dialog box should display a warning if the user specifies a file name that does not exist.

Syntax

public final boolean getCheckFileExists()

Return Value

Returns true if the dialog box displays a warning when the user specifies a file name that does not exist; otherwise, returns false.

See Also setCheckFileExists


 FileDialog.getCheckPathExists

FileDialog.getCheckPathExists

Retrieves a boolean value indicating whether the dialog box should display a warning if the user specifies a path that does not exist.

Syntax

public final boolean getCheckPathExists()

Return Value

Returns true if the dialog box displays a warning when the user specifies a path that does not exist; otherwise, returns false.

See Also setCheckPathExists


 FileDialog.getDefaultExt

FileDialog.getDefaultExt

Retrieves the default file extension.

Syntax

public final String getDefaultExt()

Return Value

Returns the default file extension. The returned string does not include the period (.).

See Also setDefaultExt


 FileDialog.getDereferenceLinks

FileDialog.getDereferenceLinks

Retrieves a boolean value indicating whether the dialog box returns the path and file name of the file referenced by the a shortcut or whether it returns the path and file name of the shortcut (.LNK) file.

Syntax

public final boolean getDereferenceLinks()

Return Value

Returns true if the dialog box returns the path and file name of the file referenced by the a shortcut; returns false if the dialog box returns the path and file name of the shortcut (.lnk) file.

See Also setDereferenceLinks


 FileDialog.getFileName

FileDialog.getFileName

Retrieves the file name of the selected file.

Syntax

public final String getFileName()

Return Value

Returns the file name of the selected file. The name of the file includes both the file path and the extension. If multiple files are selected, this method returns the first file name in the list. If no file is selected, this method returns an empty string.

Remarks

This method can return only the name of one selected file. If you want to return an array containing the names of all selected files in a multiple-selection dialog box, use the getFileNames method. See the SaveFileDialog control topic for a code example using this method.

See Also setFileName


 FileDialog.getFileNames

FileDialog.getFileNames

Retrieves the file names of all selected files in the dialog box.

Syntax

public final String[] getFileNames()

Return Value

Returns an array containing the file names of all selected files in the dialog box. Each file name includes both the file path and the extension. If multiple files are selected, this method returns the first file name in the list. If no files are selected, this method returns an empty array.

Remarks

See the OpenFileDialog control topic for a code example using this method.


 FileDialog.getFilter

FileDialog.getFilter

Retrieves the current filter string (the string that determines the choices that appear in the Save as file type or Files of type box in the dialog box and allow the user to filter out the kinds of files that are shown in the dialog box).

Syntax

public final String getFilter()

Return Value

Returns a string that contains information about all the file filtering options available in the dialog box. For each filtering option, the filter string contains a description of the filter, followed by the vertical bar (|), followed by the filter pattern. The strings for different filtering options are separated by the vertical bar. The following is an example of a filter string: "Text files (*.txt)|*.txt|All files (*.*)|*.*"

See Also setFilter


 FileDialog.getFilterIndex

FileDialog.getFilterIndex

Retrieves a value indicating the one-based index of the filter currently selected in the dialog box.

Syntax

public final int getFilterIndex()

Return Value

Returns an integer that represents the zero-based index of the currently selected filter.

See Also setFilterIndex


 FileDialog.getInitialDir

FileDialog.getInitialDir

Retrieves the path for the directory whose contents are initially displayed in the dialog box.

Syntax

public final String getInitialDir()

Return Value

Returns the full path of the initial directory for the dialog box. If the initialDir property has not been explicitly set using the setInitialDir property, the initial directory is the current directory, and this method returns an empty string.

See Also setInitialDir


 FileDialog.getRestoreDirectory

FileDialog.getRestoreDirectory

Retrieves a boolean value indicating whether the dialog box restores the current directory before closing.

Syntax

public final boolean getRestoreDirectory()

Return Value

Returns true if the dialog box restores the current directory to its original value if the user changed the directory while searching for files; otherwise, returns false.

See Also setRestoreDirectory


 FileDialog.getShowHelp

FileDialog.getShowHelp

Retrieves a boolean value indicating whether the dialog box contains a Help button.

Syntax

public final boolean getShowHelp()

Return Value

Returns true if the dialog box includes a Help button; otherwise, returns false.

See Also setShowHelp


 FileDialog.getTitle

FileDialog.getTitle

Retrieves the text that appears in the title bar of the dialog box.

Syntax

public final String getTitle()

Return Value

Returns the text that appears in the title bar of the dialog box. If the title has not been explicitly set using the setTitle property, the title bar contains the default text (either "Open" or "Save As"), and this property returns an empty string.

See Also setTitle


 FileDialog.getValidateNames

FileDialog.getValidateNames

Retrieves a boolean value indicating whether the dialog box accepts only valid Win32 file names.

Syntax

public final boolean getValidateNames()

Return Value

Returns true if the dialog box checks file names to make sure they are valid Win32 file names before returning them; returns false if the dialog box will return invalid file names.

See Also setValidateNames


 FileDialog.onFileOk

FileDialog.onFileOk

Triggers the fileOk event.

Syntax

protected void onFileOk( CancelEvent e )

Parameters

e

An CancelEventobject that provides the event data. An event handler can prevent the dialog box from closing by setting the cancel field of the CancelEvent object used by the event handler to true.

Remarks

When overriding this method, call super.onFileOk.

See Also addOnFileOk


 FileDialog.promptFileCreate

FileDialog.promptFileCreate

Prompts the user when a file is about to be created.

Syntax

protected boolean promptFileCreate( String fileName )

Parameters

fileName

The name of the file to create.

Remarks

This method is invoked when the createPrompt property is set to true and the specified file does not exist. A return value of false prevents the dialog box from closing.


 FileDialog.promptFileNotFound

FileDialog.promptFileNotFound

Prompts the user when a file does not exist.

Syntax

protected void promptFileNotFound( String fileName )

Parameters

fileName

The name of the file to search for.

Remarks

This method is invoked when the checkFileExists property is set to true and the specified file does not exist.


 FileDialog.promptFileOverwrite

FileDialog.promptFileOverwrite

Prompts the user when a file is about to be overwritten.

Syntax

protected boolean promptFileOverwrite( String fileName )

Parameters

fileName

The name of the file to write to.

Remarks

This method is invoked when the overwritePrompt property is set to true and the specified file already exists. A return value of false prevents the dialog box from closing.


 FileDialog.removeOnFileOk

FileDialog.removeOnFileOk

Removes the delegate that is assigned to the fileOk event.

Syntax

public final void removeOnFileOk( CancelEventHandler value )

Parameters

value

The CancelEventHandler delegate to be removed.

See Also addOnFileOk


 FileDialog.reset

FileDialog.reset

Resets all dialog box options to their default values.

Syntax

public void reset()

Overrides

CommonDialog.reset.


 FileDialog.setAddExtension

FileDialog.setAddExtension

Sets a boolean value indicating whether the dialog box automatically adds an extension to a file name when the user omits the extension.

Syntax

public final void setAddExtension( boolean value )

Parameters

value

Set to true if you want the dialog box to add an extension to a file name when the user omits the extension; otherwise, set to false. The default value is true.

Remarks

The extension added to a file name depends on the currently selected file filter and the value of the checkFileExists property. If the checkFileExists property is true, the dialog box adds the first extension from the current file filter that matches an existing file; if no files match the current file filter, the dialog box adds the extension specified in the defaultExt property. If the checkFileExists property is false, the dialog box adds the first valid file extension from the current file filter; if the current file filter contains no valid file extensions, the dialog box adds the extension specified in the defaultExt property.

See Also getAddExtension


 FileDialog.setCheckFileExists

FileDialog.setCheckFileExists

Sets a boolean value indicating whether the dialog box should display a warning if the user specifies a file name that does not exist.

Syntax

public final void setCheckFileExists( boolean value )

Parameters

value

Set to true if you want the dialog box to display a warning when the user specifies a file name that does not exist; otherwise, set to false. The default value is true for an OpenFileDialog control and false for a SaveFileDialog control.

See Also getCheckFileExists


 FileDialog.setCheckPathExists

FileDialog.setCheckPathExists

Sets a boolean value indicating whether the dialog box should display a warning if the user specifies a path that does not exist.

Syntax

public final void setCheckPathExists( boolean value )

Parameters

value

Set to true if the dialog box displays a warning when the user specifies a path that does not exist; otherwise, set to false. The default value is true.

See Also getCheckPathExists


 FileDialog.setDefaultExt

FileDialog.setDefaultExt

Sets the default file extension, which is appended to a file name if the user fails to type an extension.

Syntax

public final void setDefaultExt( String value )

Parameters

value

A string that represents the default file extension. The specified string can be any length, but only the first three characters are appended to the file name. The string should not contain a period. The default value for the default extension is an empty string, which causes no extension to be appended.

Remarks

See the OpenFileDialog control topic for a code example using this method.

See Also getDefaultExt


 FileDialog.setDereferenceLinks

FileDialog.setDereferenceLinks

Sets a boolean value indicating whether the dialog box returns the path and file name of the file referenced by the a shortcut or whether it returns the path and file name of the shortcut (.LNK) file.

Syntax

public final void setDereferenceLinks( boolean value )

Parameters

value

Set to true if the dialog box returns the path and file name of the file referenced by the a shortcut; set to false if the dialog box returns the path and file name of the shortcut (.lnk) file. The default value is true.

See Also getDereferenceLinks


 FileDialog.setFileName

FileDialog.setFileName

Sets a value that indicates which file name is selected by default when the dialog box is opened.

Syntax

public final void setFileName( String value )

Parameters

value

The name of the file that is selected by default when the dialog box is opened. By default, no file is selected when the dialog box first opens.

See Also getFileName


 FileDialog.setFilter

FileDialog.setFilter

Sets the current filter string (the string that determines the choices that appear in the Save as file type or Files of type box in the dialog box and allow the user to filter out the kinds of files that are shown in the dialog box).

Syntax

public final void setFilter( String value )

Parameters

value

A string that contains information about all the available file filters in the dialog box. For each filter, the filter string contains a description of the filter, followed by the vertical bar (|), followed by the filter pattern. The strings for different filters are separated by the "|" character. The following is an example of a filter string: "Text files (*.txt)|*.txt|All files (*.*)|*.*" To specify multiple filter patterns for a single filter, use a semicolon to separate the patterns (for example, "*.txt;*.doc;*.bak"). A pattern string can be a combination of valid file name characters and the asterisk (*) wildcard character. Do not include spaces in the pattern string. Filters are displayed in the dialog box in the order they are specified in the value parameter to the setFilter property.

Remarks

See the OpenFileDialog control topic for a code example using this method.

See Also getFilter


 FileDialog.setFilterIndex

FileDialog.setFilterIndex

Sets a value representing the one-based index of the filter that is selected by default when the dialog box is opened.

Syntax

public final void setFilterIndex( int value )

Parameters

value

The one-based index of the filter to be selected in the Save as file type or Files of type box when the dialog box is opened. By default, the most recently selected filter is selected when the dialog box opens.

Remarks

Use the getFilterIndex method to return the one-based index of the currently selected filter. See the OpenFileDialog control topic for a code example using this method.

See Also getFilterIndex


 FileDialog.setInitialDir

FileDialog.setInitialDir

Sets the path for the directory whose contents are initially displayed in the dialog box.

Syntax

public final void setInitialDir( String value )

Parameters

value

The path of the initial directory for the dialog box. If you specify an empty string for the value parameter, the initial directory will be the current directory.

Remarks

See the OpenFileDialog control topic for a code example using this method.

See Also getInitialDir


 FileDialog.setRestoreDirectory

FileDialog.setRestoreDirectory

Sets a boolean value indicating whether the dialog box restores the current directory before closing.

Syntax

public final void setRestoreDirectory( boolean value )

Parameters

value

Set to true if you want the dialog box to restore the current directory to its original value if the user changes the directory while searching for files; otherwise, set to false. The default value is false.

See Also getRestoreDirectory


 FileDialog.setShowHelp

FileDialog.setShowHelp

Sets a boolean value indicating whether the dialog box contains a Help button.

Syntax

public final void setShowHelp( boolean value )

Parameters

value

Set to true if you want the dialog box to include a Help button; otherwise, set to false. The default value is false.

See Also getShowHelp


 FileDialog.setTitle

FileDialog.setTitle

Sets the text that appears in the title bar of the dialog box.

Syntax

public final void setTitle( String value )

Parameters

value

The text that appears in the title bar of the dialog box. If you specify an empty string, the title bar will contain the default text (either "Open" or "Save As"). The default value is an empty string.

See Also getTitle


 FileDialog.setValidateNames

FileDialog.setValidateNames

Sets a boolean value indicating whether the dialog box accepts only valid Win32 file names.

Syntax

public final void setValidateNames( boolean value )

Parameters

value

Set to true if you want the dialog box to check file names to make sure they are valid Win32 file names before returning them; returns false if you want the dialog box to return any file name specified in the File name box, whether it is valid or not. The default value is true.

Remarks

See the SaveFileDialog control topic for a code example using this method.

See Also getValidateNames


FloodFillType Class

Defines the filling modes used by the Graphics object to fill an area.

Enum
  |
  +--FloodFillType

package com.ms.wfc.ui

public class FloodFillType
extends Enum

Remarks

This class defines the constants that can be passed to the Graphics object's floodFill method to determine how an area is filled.


 FloodFillType Methods

FloodFillType Methods

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value is a valid member of this class.


 FloodFillType.valid

FloodFillType.valid

Retrieves a boolean value that indicates whether a specified value is a valid member of this class.

Syntax

public static boolean valid( int value )

Parameters

value

A value to compare to the constants defined in this class.

Return Value

Returns true if the value is valid; otherwise, returns false.


 FloodFillType Fields

FloodFillType Fields

Fields | Description
BORDER | Specifies that a border flood fill begins filling at a specified point and continues in all directions until it reaches a boundary color.
SURFACE | Specifies that a surface flood fill begins filling the area at a specified point and continues in all directions, filling all adjacent regions containing a specified color.


 FloodFillType.BORDER

FloodFillType.BORDER

Specifies that a border flood fill begins filling at a specified point and continues in all directions until it reaches a boundary color.

Syntax

public static final int BORDER;


 FloodFillType.SURFACE

FloodFillType.SURFACE

Specifies that a surface flood fill begins filling the area at a specified point and continues in all directions, filling all adjacent regions containing a specified color.

Syntax

public static final int SURFACE;


Font Class

Encapsulates a Win32 font, which is used to draw text on video displays and other output devices.

package com.ms.wfc.ui

public final class Font
implements IConstructable, IPersistable

Remarks

The Font object encapsulates a Windows font and provides the member functions for manipulating that font. To explicitly use a Font object, construct the object and call the appropriate object's setFont method.

All Font object initialization occurs in the constructor; once the object is constructed, its attributes cannot be changed.


 Font Methods

Font Methods

Constructors | Description
Font | Creates a new Font object.

Methods | Description
clone | Clones the Font object, creating a duplicate font.
copyHandle | Duplicates the Win32 font handle associated with this Font object.
destroyHandle | Called when this object is going to destroy its Win32 handle.
dispose | Frees all the resources allocated by this object.
equals | Retrieves a boolean value that indicates whether the specified object is equivalent to this one.
equalsBase | Retrieves a boolean value that indicates whether the base font used by the specified Font object is identical to that used by this Font object.
finalize | Releases all resources allocated by this object.
getBold | Retrieves a boolean value that indicates if the font is bold.
getCharacterSet | Retrieves the character set the font is using.
getConstructorArgs | Retrieves an array of ConstructorArg objects that describe the data types and values needed to persist this object.
getExtension | Retrieves a file name extension with which to save this object's persistent data.
getFamily | Retrieves the font family for the font on which this object is based.
getFontMetrics | Retrieves a FontMetrics object that describes the characteristics of this Font object.
getHandle | Retrieves the Win32 font handle (HFONT) for this object's underlying font.
getItalic | Retrieves a boolean value that indicates whether the font is italicized.
getName | Retrieves the face name of the font and returns the name in a String object.
getOrientation | Retrieves the orientation of the font, in tenths of a degree, from the x-axis of the device.
getPitch | Retrieves the pitch of the font on which this object is based.
getSize | Retrieves the size of the font in the units with which the font was created.
getStock | Retrieves a stock font, based on a specified index.
getStrikeout | Retrieves a boolean value that indicates whether the current font is a strikeout font.
getUnderline | Retrieves a boolean value that indicates whether the font is underlined.
getUnits | Retrieves the units in which the font's size is measured.
getWeight | Retrieves the font's weight.
hashCode | Retrieves a hash code value for this font.
save | Persists this font to the specified data stream.
toString | Retrieves a human-readable string representation of this object.


 Font.clone

Font.clone

Clones the Font object, creating a duplicate font.

Syntax

public Object clone()

Return Value

Returns an Object that can be cast to a Font object.


 Font.copyHandle

Font.copyHandle

Duplicates the Win32 font handle associated with this Font object.

Syntax

public final int copyHandle()

Return Value

Returns the font handle for this object.

Remarks

If you use this method to duplicate the font handle, you are responsible for freeing this handle.


 Font.destroyHandle

Font.destroyHandle

Called when this object is going to destroy its Win32 handle.

Syntax

protected void destroyHandle()

Remarks

The Font class' implementation of the destroyHandle method frees only handles owned by the Font object. If you have used the object to retrieve a handle to this font (using the copyHandle method), or if you have created a Font object based on a previously allocated handle, this handle is not freed by the object's call to destroyHandle; you are responsible for freeing these handles.

However, you can override this method in your Font-derived class to define your own custom semantics for handle creation and destruction.

The default implementation of this method calls the appropriate Win32 method to destroy the handle if the object currently owns the handle. The method does nothing if the handle is not owned by this object.

A Font object can have more than one handle associated with it. This method is called when all of the handles associated with the Font object should be destroyed.


 Font.dispose

Font.dispose

Frees all the resources allocated by this object.

Syntax

public void dispose()

Remarks

The dispose method frees only those resources allocated by the object. Such resources do not include handle copies that you retrieve using the object's copyHandle method; you must free these manually.

Once the dispose method is called, the Font object cannot be used.


 Font.equals

Font.equals

Retrieves a boolean value that indicates whether the specified object is equivalent to this one.

Syntax

public boolean equals( Object obj )

Parameters

obj

The object to compare to this one.

Return Value

Returns true if the given object equals this object; otherwise, returns false.


 Font.equalsBase

Font.equalsBase

Retrieves a boolean value that indicates whether the base font used by the specified Font object is identical to that used by this Font object.

Syntax

public boolean equalsBase( Font font )

Parameters

font

The font to evaluate.

Return Value

Returns true if the given font has the same base characteristics as this font; otherwise, returns false.

Remarks

A font shares the same base characteristics as another if the fonts have the same typeface name and use the same character set.


 Font.finalize

Font.finalize

Releases all resources allocated by this object.

Syntax

protected void finalize() throws Throwable

Exceptions

Throwable thrown if a problem occurs while freeing the object's resources.

Remarks

This method releases only those resources allocated by this Font object. If you create a Font object based on a previously allocated font handle, you must release this handle. Additionally, if you use the copyHandle method to retrieve the handle to the font underlying the Font object, you must manually free this handle.


 Font.Font

Font.Font

Creates a new Font object.

Syntax

public Font( int handle )

public Font( String name, float size )

public Font( String name, float size, int units )

public Font( String name, float size, int units, int weight, boolean italic, boolean underline, boolean strikeOut )

public Font( String name, float size, int units, int weight, boolean italic, boolean underline, boolean strikeOut, int charSet, int orientation )

public Font( Font font, float size, int units )

public Font( Font font, int weight, boolean italic, boolean underline, boolean strikeOut )

public Font( Font font, float size, int units, int weight, boolean italic, boolean underline, boolean strikeOut )

public Font( int family, int pitch, float size, int units )

public Font( int family, int pitch, float size, int units, int weight, boolean italic, boolean underline, boolean strikeOut )

public Font( int family, int pitch, float size, int units, int weight, boolean italic, boolean underline, boolean strikeOut, int charSet, int orientation )

public Font( FontMetrics fm )

public Font( FontDescriptor fd )

public Font( IDataStream stream )

Parameters

handle

The handle to a Win32 font. If you create a Font object based on a handle that you have allocated, the Font object does not dispose of this handle. Instead, you must free it manually.

name

The face name of the font to create.

size

The size of the font, measured in the units specified in the units parameter. If no units are specified, the size is measured in points. Each point measures 1/72 of an inch.

units

The units in which the size of the font is specified. This value must be one of the enumeration constants defined in the FontSize class.

weight

The weight of the font. This value can be any value from 1 to 1000. For some of the common values used for this parameter, see the FontWeight class.

italic

Set to true if the font is to be italicized; otherwise, set to false.

underline

Set to true if the font is to be underlined; otherwise, set to false.

strikeOut

Set to true if the font is to be struck through; otherwise, set to false.

charSet

The character set of the font. This value must be one of the enumeration constants defined in the com.ms.wfc.app.CharacterSet class.

orientation

Orientation of the font. This is the angle, in tenths of a degree, between a character's baseline and the x-axis of a device.

font

The existing font to use as a template.

family

The family of the font you want to create. This value must be one of the enumeration constants defined in the FontFamily class.

pitch

The pitch of the font you want to create. This value must be one of the enumeration values defined in the FontPitch class.

fm

A FontMetrics object that describes the font to create.

fd

A FontDescriptor object that describes the font to create.

stream

The IDataStream from which to read the font.


 Font.getBold

Font.getBold

Retrieves a boolean value that indicates if the font is bold.

Syntax

public final boolean getBold()

Return Value

Returns true if the font is bold; otherwise, returns false.


 Font.getCharacterSet

Font.getCharacterSet

Retrieves the character set the font is using.

Syntax

public final int getCharacterSet()

Return Value

Returns one of the enumeration constants defined in the com.ms.wfc.app.CharacterSet class.


 Font.getConstructorArgs

Font.getConstructorArgs

Retrieves an array of ConstructorArg objects that describe the data types and values needed to persist this object.

Syntax

public ConstructorArg[] getConstructorArgs()

Return Value

Returns a ConstructorArg array.

See Also IConstructable


 Font.getExtension

Font.getExtension

Retrieves a file name extension with which to save this object's persistent data.

Syntax

public String getExtension()

Return Value

Returns a file name extension to use during object persistence. Because Font objects do not use an extension, this method always returns null.

See Also IPersistable


 Font.getFamily

Font.getFamily

Retrieves the font family for the font on which this object is based.

Syntax

public final int getFamily()

Return Value

Returns an integer that identifies the font family. This value maps to one of the enumeration constants defined in the FontFamily class.


 Font.getFontMetrics

Font.getFontMetrics

Retrieves a FontMetrics object that describes the characteristics of this Font object.

Syntax

public final FontMetrics getFontMetrics()

public final FontMetrics getFontMetrics( Graphics gr )

Parameters

gr

The Graphics object to which to map the font.

Return Value

Returns a FontMetrics object that has been initialized to describe this Font object's underlying font.

Remarks

While a Font object maintains the requested characteristics of a font, a FontMetrics object contains information about the actual font as it will be rendered to a Graphics object. This information may or may not match the requested characteristics, depending on what font information is available. This function assumes a default Graphics object of the screen.


 Font.getHandle

Font.getHandle

Retrieves the Win32 font handle (HFONT) for this object's underlying font.

Syntax

public int getHandle()

public int getHandle( Graphics gr )

Parameters

gr

A Graphics object to render the font against.

Return Value

Returns a handle to the font.

Remarks

If you pass a Graphics object instance to getHandle, the method uses the rendering dimensions of the Graphics object to retrieve the font handle.


 Font.getItalic

Font.getItalic

Retrieves a boolean value that indicates whether the font is italicized.

Syntax

public final boolean getItalic()

Return Value

Returns true if the font is italicized; otherwise, returns false.


 Font.getName

Font.getName

Retrieves the face name of the font and returns the name in a String object.

Syntax

public final String getName()

Return Value

Returns the font's face name.


 Font.getOrientation

Font.getOrientation

Retrieves the orientation of the font, in tenths of a degree, from the x-axis of the device.

Syntax

public final int getOrientation()

Return Value

Returns the orientation of the font.

Remarks

You specify a font's orientation when you construct the Font object.


 Font.getPitch

Font.getPitch

Retrieves the pitch of the font on which this object is based.

Syntax

public final int getPitch()

Return Value

Returns an integer constant that identifies the font's pitch. This value maps to one of the enumeration constants defined in the FontPitch class.


 Font.getSize

Font.getSize

Retrieves the size of the font in the units with which the font was created.

Syntax

public final float getSize()

public float getSize( int units )

public float getSize( Graphics gr, int units )

Parameters

units

The units in which the font's size should be measured. This value must be one of the enumeration constants defined in the FontSize class.

gr

A Graphics object used to convert the font's size to the specified units.

Return Value

Returns the font size.

Remarks

Windows defines a font's positive size as its cell height, which is usually the distance from the bottom of a g to the top of an M.

You define the units in which a font's size is measured when you construct the font. If you create a Font object using a constructor that takes no units, a default value of FontSize.POINTS is used.

If your call to getSize does not specify the units in which you want the font size returned, the units specified when the Font object was created are returned.


 Font.getStock

Font.getStock

Retrieves a stock font, based on a specified index.

Syntax

public final static Font getStock( int index )

Parameters

index

The stock font index as defined in com.ms.wfc.win32.Windows.

Return Value

Returns the stock font that corresponds to the specified index.

Remarks

All stock fonts are available as field constants.


 Font.getStrikeout

Font.getStrikeout

Retrieves a boolean value that indicates whether the current font is a strikeout font.

Syntax

public final boolean getStrikeout()

Return Value

Returns true if the font is a strikeout font; otherwise, returns false.

Remarks

You specify whether a font is a strikeout font when you construct the Font object. By default, fonts are not strikeout fonts.

A strikeout font is one in which a line is drawn through displayed text.


 Font.getUnderline

Font.getUnderline

Retrieves a boolean value that indicates whether the font is underlined.

Syntax

public final boolean getUnderline()

Return Value

Returns true if the font is underlined; otherwise, returns false.

Remarks

You specify whether a font is underlined when you construct the Font object. By default, fonts are not underlined.


 Font.getUnits

Font.getUnits

Retrieves the units in which the font's size is measured.

Syntax

public final int getUnits()

Return Value

Returns one of the enumeration constants defined in the FontSize class.

Remarks

You specify the units in which a font's size are measured when you construct the Font object.


 Font.getWeight

Font.getWeight

Retrieves the font's weight.

Syntax

public final int getWeight()

Return Value

Returns one of the enumeration values defined in the FontWeight class.

Remarks

You specify a font's weight when you construct the Font object. By default, this value is FontWeight.NORMAL.


 Font.hashCode

Font.hashCode

Retrieves a hash code value for this font.

Syntax

public int hashCode()

Return Value

Returns a hash code value for this font.


 Font.save

Font.save

Persists this font to the specified data stream.

Syntax

public void save( IDataStream stream )

Parameters

stream

The stream to which to persist the font information.

See Also IPersistable


 Font.toString

Font.toString

Retrieves a human-readable string representation of this object.

Syntax

public String toString()

Return Value

Returns a string representation of this object.


 Font Fields

Font Fields

Fields | Description
ANSI_FIXED | Represents a standard ANSI fixed-width font.
ANSI_VAR | Represents a standard ANSI variable-width font.
DEFAULT_GUI | Represents the default font for the current graphical user interface.
DEVICE_DEFAULT | Represents the standard font for the current graphics device.
OEM_FIXED | Represents the standard original equipment manufacturer (OEM) fixed font.
SYSTEM | Represents the standard Windows variable-width system font.
SYSTEM_FIXED | Represents the standard Windows fixed-width system font.


 Font.ANSI_FIXED

Font.ANSI_FIXED

Represents a standard ANSI fixed-width font.

Syntax

public static final Font ANSI_FIXED;


 Font.ANSI_VAR

Font.ANSI_VAR

Represents a standard ANSI variable-width font.

Syntax

public static final Font ANSI_VAR;


 Font.DEFAULT_GUI

Font.DEFAULT_GUI

Represents the default font for the current graphical user interface.

Syntax

public static final Font DEFAULT_GUI;

Remarks

This font automatically adapts its character set to the locale of the user.


 Font.DEVICE_DEFAULT

Font.DEVICE_DEFAULT

Represents the standard font for the current graphics device.

Syntax

public static final Font DEVICE_DEFAULT;


 Font.OEM_FIXED

Font.OEM_FIXED

Represents the standard original equipment manufacturer (OEM) fixed font.

Syntax

public static final Font OEM_FIXED;


 Font.SYSTEM

Font.SYSTEM

Represents the standard Windows variable-width system font.

Syntax

public static final Font SYSTEM;


 Font.SYSTEM_FIXED

Font.SYSTEM_FIXED

Represents the standard Windows fixed-width system font.

Syntax

public static final Font SYSTEM_FIXED;


FontDescriptor Class

The FontDescriptor object, like the FontMetrics object that it extends, provides information about the font that underlies a Font object.

FontMetrics
  |
  +--FontDescriptor

package com.ms.wfc.ui

public class FontDescriptor
extends FontMetrics

Remarks

Once you have initialized a FontDescriptor object, you can create a Font object based on the font description. Additionally, you can retrieve a FontDescriptor object that contains information about one or more fonts by using the Graphics object's getFontDescriptors method.


 FontDescriptor Methods

FontDescriptor Methods

Constructors | Description
FontDescriptor | Creates a FontDescriptor object for the specified font as it will be rendered to a specified Graphics object.


 FontDescriptor.FontDescriptor

FontDescriptor.FontDescriptor

Creates a FontDescriptor object for the specified font as it will be rendered to a specified Graphics object.

Syntax

public FontDescriptor( Font font, Graphics g )

Parameters

font

A Font object that specifies the font on which to base the FontDescriptor object.

gr

The Graphics object to which the font will be rendered.


 FontDescriptor Fields

FontDescriptor Fields

Fields | Description
fullName | Specifies the full name of the font.
orientation | Specifies the font's orientation.
script | Specifies the font's script.
style | Specifies the font's style.
type | Specifies the font type.


 FontDescriptor.fullName

FontDescriptor.fullName

Specifies the full name of the font.

Syntax

public String fullName;

Remarks

The full name of a font generally consists of the name of the company that created the font and the font's face name and style (for example, "Microsoft Sans Serif Bold").


 FontDescriptor.orientation

FontDescriptor.orientation

Specifies the font's orientation.

Syntax

public int orientation;

Remarks

The orientation of a font is the angle, in tenths of a degree, between a character's baseline and the x-axis of a device.


 FontDescriptor.script

FontDescriptor.script

Specifies the font's script.

Syntax

public String script;

Remarks

The script of a font consists of a textual description of its character set and has been localized into the user's language. Examples include modifiers such as "Western" and "Cyrillic".


 FontDescriptor.style

FontDescriptor.style

Specifies the font's style.

Syntax

public String style;

Remarks

The style of a font consists of a descriptive term such as "Bold" or "Bold Italic".


 FontDescriptor.type

FontDescriptor.type

Specifies the font type.

Syntax

public int type;

Remarks

This value specifies one of the enumeration constants defined in the FontType class.


FontDevice Class

Defines a group of constants that determine what types of fonts will be listed in a font dialog box.

Enum
  |
  +--FontDevice

package com.ms.wfc.ui

public class FontDevice
extends Enum

Remarks

The fonts that you display in a font dialog using the FontDialog class can be screen fonts, printer fonts, or both. To specify what fonts are displayed in the common font dialog box, combine one or more of the values defined in this class using the bitwise OR operator, and pass the resulting value to the FontDialog object's setFontDevice method.


 FontDevice Methods

FontDevice Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 FontDevice.valid

FontDevice.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 FontDevice Fields

FontDevice Fields

Fields | Description
BOTH | Indicates that the font is designed to be used both with screens and printers.
PRINTER | Indicates that the font is designed primarily for printer use.
SCREEN | Indicates that the font is designed primarily for screen operations.


 FontDevice.BOTH

FontDevice.BOTH

Indicates that the font is designed to be used both with screens and printers.

Syntax

public static final int BOTH;


 FontDevice.PRINTER

FontDevice.PRINTER

Indicates that the font is designed primarily for printer use.

Syntax

public static final int PRINTER;


 FontDevice.SCREEN

FontDevice.SCREEN

Indicates that the font is designed primarily for screen operations.

Syntax

public static final int SCREEN;


FontDialog Class

Represents a common dialog box that displays a list of fonts that are currently installed on the system.

Component
  |
  +--CommonDialog
    |
    +--FontDialog

package com.ms.wfc.ui

public class FontDialog
extends CommonDialog

Remarks

The user can select a particular font from the list, and this selection is then reported back to the application. Use the showDialog method to show the dialog box. Use the getFont method to get the font the user selected.

The following example opens a Font dialog box and set the font for the form to the font the user selects:

private void btnFont_click(Object source, Event e)
{
    FontDialog fd = new FontDialog();
    fd.setFont(Font.SYSTEM); //sets the font that is selected when the dialog box opens
    int dlgResult = fd.showDialog();
    if (dlgResult == DialogResult.OK) {
        Font font = fd.getFont(); //gets the font the user chose
        this.setFont(font);  //sets the form font to the chosen font
    }
}


 FontDialog Methods

FontDialog Methods

Constructors | Description
FontDialog | Creates a FontDialog control.

Methods | Description
addOnApply | Assigns a delegate to the apply event.
getAllowScriptChange | Retrieves a boolean value indicating whether the user can change the character set specified in the Script combo box to display a character set other than the current one.
getAllowSimulations | Retrieves a boolean value indicating whether the dialog box allows graphics device interface (GDI) font simulations.
getAllowVectorFonts | Retrieves a boolean value indicating whether the dialog box allows vector font selections.
getAllowVerticalFonts | Retrieves a boolean value indicating whether the dialog box displays both vertically oriented and horizontally oriented fonts or only horizontally oriented fonts.
getColor | Retrieves the selected font color.
getFixedPitchOnly | Retrieves a boolean value indicating whether the dialog box should allow only the selection of fixed-pitch fonts.
getFont | Retrieves a value indicating the font the user selected in the dialog box.
getFontDevice | Retrieves a value indicating whether the dialog box will show screen fonts, printer fonts, or both.
getFontMustExist | Retrieves a boolean value indicating whether the dialog box should indicate an error condition if the user attempts to select a font or style that does not exist.
getMaxSize | Retrieves a value indicating the maximum point size a user can select.
getMinSize | Retrieves a value indicating the minimum point size a user can select.
getPrinterDC | Retrieves a value identifying the device context of the printer whose fonts will be listed in the dialog box.
getScalableOnly | Retrieves a boolean value indicating whether the dialog box allows only the selection of scalable fonts.
getScriptsOnly | Retrieves a boolean value indicating whether the dialog box allows selection of fonts for all non-OEM and Symbol character sets, as well as the American National Standards Institute (ANSI) character set.
getShowApply | Retrieves a boolean value indicating whether the dialog box contains an Apply button.
getShowColor | Retrieves a boolean value indicating whether or not the color choice is shown.
getShowEffects | Retrieves a boolean value indicating whether the dialog box displays the controls that allow the user to specify strikeout, underline, and text color options.
getShowHelp | Retrieves a boolean value indicating whether the dialog box contains a Help button.
getTrueTypeOnly | Retrieves a boolean value indicating whether the dialog box displays only TrueType fonts.
getWysiwyg | Retrieves a boolean value indicating whether the dialog box allows only the selection of fonts available on both the printer and the display.
onApply | Triggers the apply event.
removeOnApply | Removes the delegate that is assigned to the apply event.
reset | Resets all dialog box options to their default values.
runDialog | Implements running the dialog box.
setAllowScriptChange | Sets a boolean value indicating whether the user can change the character set specified in the Script combo box to display a character set other than the current one.
setAllowSimulations | Sets a boolean value indicating whether the dialog box allows graphics device interface (GDI) font simulations.
setAllowVectorFonts | Sets a boolean value indicating whether the dialog box allows vector font selections.
setAllowVerticalFonts | Sets a boolean value indicating whether the dialog box displays both vertical and horizontal fonts or only horizontal fonts.
setColor | Sets a value that indicates which color is selected by default when the dialog box is opened.
setFixedPitchOnly | Sets a boolean value indicating whether the dialog box should allow only the selection of fixed-pitch fonts.
setFont | Sets a value that indicates which font is selected by default when the dialog box is opened.
setFontDevice | Sets a value indicating whether the dialog box will show screen fonts, printer fonts, or both.
setFontMustExist | Sets a boolean value indicating whether the dialog box should indicate an error condition if the user attempts to select a font or style that does not exist.
setMaxSize | Sets a value indicating the maximum point size a user can select.
setMinSize | Sets a value indicating the minimum point size a user can select.
setPrinterDC | Sets a value identifying the device context of the printer whose fonts will be listed in the dialog box.
setScalableOnly | Sets a boolean value indicating whether the dialog box allows only the selection of scalable fonts.
setScriptsOnly | Sets a boolean value indicating whether the dialog box allows selection of fonts for all non-OEM and Symbol character sets, as well as the ANSI character set.
setShowApply | Sets a boolean value indicating whether the dialog box contains an Apply button.
setShowColor | Sets a boolean value indicating whether or not the color choice is shown.
setShowEffects | Sets a boolean value indicating whether the dialog box displays the controls that allow the user to specify strikeout, underline, and text color options.
setShowHelp | Sets a boolean value indicating whether the dialog box contains a Help button.
setTrueTypeOnly | Sets a boolean value indicating whether the dialog box displays only TrueType fonts.
setWysiwyg | Sets a boolean value indicating whether the dialog box allows only the selection of fonts available on both the printer and the display.
toString | Retrieves a string that includes the name of the current font selected in the dialog box.


 FontDialog.addOnApply

FontDialog.addOnApply

Assigns a delegate to the apply event.

Syntax

public final void addOnApply( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the apply event to that method in the Properties window. The apply event occurs when the user clicks Apply in the dialog box.

See Also removeOnApply


 FontDialog.FontDialog

FontDialog.FontDialog

Creates a FontDialog control.

Syntax

protected FontDialog()


 FontDialog.getAllowScriptChange

FontDialog.getAllowScriptChange

Retrieves a boolean value indicating whether the user can change the character set specified in the Script combo box to display a character set other than the current one.

Syntax

public final boolean getAllowScriptChange()

Return Value

Returns true if the user can change the character set specified in the Script combo box; returns false if only fonts in the current character set can be displayed.

See Also setAllowScriptChange


 FontDialog.getAllowSimulations

FontDialog.getAllowSimulations

Retrieves a boolean value indicating whether the dialog box allows graphics device interface (GDI) font simulations.

Syntax

public final boolean getAllowSimulations()

Return Value

Returns true if font simulations are allowed; otherwise, returns false.

See Also setAllowSimulations


 FontDialog.getAllowVectorFonts

FontDialog.getAllowVectorFonts

Retrieves a boolean value indicating whether the dialog box allows vector font selections.

Syntax

public final boolean getAllowVectorFonts()

Return Value

Returns true if vector fonts are allowed; otherwise, returns false.

See Also setAllowVectorFonts


 FontDialog.getAllowVerticalFonts

FontDialog.getAllowVerticalFonts

Retrieves a boolean value indicating whether the dialog box displays both vertically oriented and horizontally oriented fonts or only horizontally oriented fonts.

Syntax

public final boolean getAllowVerticalFonts()

Return Value

Returns true if the dialog box displays vertically oriented and horizontally oriented fonts; returns false if the dialog box displays only horizontally oriented fonts.

See Also setAllowVerticalFonts


 FontDialog.getColor

FontDialog.getColor

Retrieves the selected font color.

Syntax

public final Color getColor()

Return Value

Returns a Color object that represents the selected font color.

See Also setColor


 FontDialog.getFixedPitchOnly

FontDialog.getFixedPitchOnly

Retrieves a boolean value indicating whether the dialog box should allow only the selection of fixed-pitch fonts.

Syntax

public final boolean getFixedPitchOnly()

Return Value

Returns true if only fixed-pitch fonts can be selected; otherwise, returns false.

See Also setFixedPitchOnly


 FontDialog.getFont

FontDialog.getFont

Retrieves a value indicating the font the user selected in the dialog box.

Syntax

public final Font getFont()

Return Value

Returns a Font object that represents the font the user selected in the dialog box.

Remarks

For a code example using this method, see the FontDialog control topic.

See Also setFont


 FontDialog.getFontDevice

FontDialog.getFontDevice

Retrieves a value indicating whether the dialog box will show screen fonts, printer fonts, or both.

Syntax

public final int getFontDevice()

Return Value

Returns an integer that indicates whether the dialog box will show screen fonts, printer fonts, or both. Possible return values are constants defined in the FontDevice class.

See Also setFontDevice


 FontDialog.getFontMustExist

FontDialog.getFontMustExist

Retrieves a boolean value indicating whether the dialog box should indicate an error condition if the user attempts to select a font or style that does not exist.

Syntax

public final boolean getFontMustExist()

Return Value

Returns true if the dialog box indicates an error condition when the user tries to select a font or style that does not exist; otherwise, returns false.

See Also setFontMustExist


 FontDialog.getMaxSize

FontDialog.getMaxSize

Retrieves a value indicating the maximum point size a user can select.

Syntax

public final int getMaxSize()

Return Value

Returns an integer that represents the the maximum point size a user can select; returns zero (0) if there is no size limit.

See Also setMaxSize


 FontDialog.getMinSize

FontDialog.getMinSize

Retrieves a value indicating the minimum point size a user can select.

Syntax

public final int getMinSize()

Return Value

Returns an integer that represents the the minimum point size a user can select; returns zero (0) if there is no size limit.

Remarks

In order for the maximum and minimum size settings to take effect, maxSize must be greater than minSize, and both must be greater than zero.

See Also setMinSize


 FontDialog.getPrinterDC

FontDialog.getPrinterDC

Retrieves a value identifying the device context of the printer whose fonts will be listed in the dialog box.

Syntax

public final int getPrinterDC()

Return Value

Returns an integer that represents a Win32 Graphics Device Context handle that identifies the device context of the printer whose fonts will be listed in the dialog box.

See Also setPrinterDC


 FontDialog.getScalableOnly

FontDialog.getScalableOnly

Retrieves a boolean value indicating whether the dialog box allows only the selection of scalable fonts.

Syntax

public final boolean getScalableOnly()

Return Value

Returns true if only scalable fonts are allowed; otherwise, returns false.

Remarks

Scalable fonts include vector fonts, scalable printer fonts, TrueType fonts, and fonts scaled by other technologies.

See Also setScalableOnly


 FontDialog.getScriptsOnly

FontDialog.getScriptsOnly

Retrieves a boolean value indicating whether the dialog box allows selection of fonts for all non-OEM and Symbol character sets, as well as the American National Standards Institute (ANSI) character set.

Syntax

public final boolean getScriptsOnly()

Return Value

Returns true if selection of fonts for all non-OEM and Symbol character sets, as well as the ANSI character set is allowed; otherwise, returns false.

See Also setScriptsOnly


 FontDialog.getShowApply

FontDialog.getShowApply

Retrieves a boolean value indicating whether the dialog box contains an Apply button.

Syntax

public final boolean getShowApply()

Return Value

Returns true if the dialog box includes an Apply button; otherwise, returns false.

See Also setShowApply


 FontDialog.getShowColor

FontDialog.getShowColor

Retrieves a boolean value indicating whether or not the color choice is shown.

Syntax

public final boolean getShowColor()

Return Value

Returns true if the color choice is shown; otherwise, returns false.

See Also setShowColor


 FontDialog.getShowEffects

FontDialog.getShowEffects

Retrieves a boolean value indicating whether the dialog box displays the controls that allow the user to specify strikeout, underline, and text color options.

Syntax

public final boolean getShowEffects()

Return Value

Returns true if dialog box contains controls to set strikeout, underline, and text color options; otherwise, returns false.

See Also setShowEffects


 FontDialog.getShowHelp

FontDialog.getShowHelp

Retrieves a boolean value indicating whether the dialog box contains a Help button.

Syntax

public final boolean getShowHelp()

Return Value

Returns true if the dialog box includes a Help button; otherwise, returns false.

See Also setShowHelp


 FontDialog.getTrueTypeOnly

FontDialog.getTrueTypeOnly

Retrieves a boolean value indicating whether the dialog box displays only TrueType fonts.

Syntax

public final boolean getTrueTypeOnly()

Return Value

Returns true if the dialog displays only TrueType fonts; otherwise, returns false.

See Also setTrueTypeOnly


 FontDialog.getWysiwyg

FontDialog.getWysiwyg

Retrieves a boolean value indicating whether the dialog box allows only the selection of fonts available on both the printer and the display.

Syntax

public final boolean getWysiwyg()

Return Value

Returns true if only fonts available on both the printer and the display are allowed; otherwise, returns false.

See Also setWysiwyg


 FontDialog.onApply

FontDialog.onApply

Triggers the apply event.

Syntax

protected void onApply( Event e )

Parameters

e

An Event object that provides the event data.

Remarks

When overriding this method, call super.onApply.

See Also addOnApply


 FontDialog.removeOnApply

FontDialog.removeOnApply

Removes the delegate that is assigned to the apply event.

Syntax

public final void removeOnApply( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnApply


 FontDialog.reset

FontDialog.reset

Resets all dialog box options to their default values.

Syntax

public final void reset()


 FontDialog.runDialog

FontDialog.runDialog

Implements running the dialog box.

Syntax

protected boolean runDialog( int hwndOwner, int hookProcPtr )

Parameters

hwndOwner

The handle to the window that owns the dialog box.

hookProcPtr

A pointer to the hook procedure that must be set up for the ChooseFont call.

Return Value

Returns true if the user clicks OK; returns false if the user clicks Cancel.

Remarks

When overriding this method, call super.runDialog.


 FontDialog.setAllowScriptChange

FontDialog.setAllowScriptChange

Sets a boolean value indicating whether the user can change the character set specified in the Script combo box to display a character set other than the current one.

Syntax

public final void setAllowScriptChange( boolean value )

Parameters

value

Set to true if the user can change the character set specified in the Script combo box; set to false if only fonts in the current character set can be displayed. The default value is true.

See Also getAllowScriptChange


 FontDialog.setAllowSimulations

FontDialog.setAllowSimulations

Sets a boolean value indicating whether the dialog box allows graphics device interface (GDI) font simulations.

Syntax

public final void setAllowSimulations( boolean value )

Parameters

value

Set to true if simulations are allowed; otherwise, set to false. The default value is true.

See Also getAllowSimulations


 FontDialog.setAllowVectorFonts

FontDialog.setAllowVectorFonts

Sets a boolean value indicating whether the dialog box allows vector font selections.

Syntax

public final void setAllowVectorFonts( boolean value )

Parameters

value

Set to true if vector fonts are allowed; otherwise, set to false. The default value is true.

See Also getAllowVectorFonts


 FontDialog.setAllowVerticalFonts

FontDialog.setAllowVerticalFonts

Sets a boolean value indicating whether the dialog box displays both vertical and horizontal fonts or only horizontal fonts.

Syntax

public final void setAllowVerticalFonts( boolean value )

Parameters

value

Set to true if the dialog box displays vertical and horizontal fonts; set to false if the dialog box displays only horizontal fonts. The default value is true.

See Also getAllowVerticalFonts


 FontDialog.setColor

FontDialog.setColor

Sets a value that indicates which color is selected by default when the dialog box is opened.

Syntax

public final void setColor( Color value )

Parameters

value

A Color object that represents the color that is selected by default when the dialog box is opened. The default value is black.

See Also getColor


 FontDialog.setFixedPitchOnly

FontDialog.setFixedPitchOnly

Sets a boolean value indicating whether the dialog box should allow only the selection of fixed-pitch fonts.

Syntax

public final void setFixedPitchOnly( boolean value )

Parameters

value

Set to true if only fixed-pitch fonts can be selected; otherwise, set to false. The default value is false.

See Also getFixedPitchOnly


 FontDialog.setFont

FontDialog.setFont

Sets a value that indicates which font is selected by default when the dialog box is opened.

Syntax

public final void setFont( Font value )

Parameters

value

A Font object that represents the font that is selected by default when the dialog box is opened. The default value is the default GUI font.

Remarks

For a code example using this method, see the FontDialog control topic.

See Also getFont


 FontDialog.setFontDevice

FontDialog.setFontDevice

Sets a value indicating whether the dialog box will show screen fonts, printer fonts, or both.

Syntax

public final void setFontDevice( int value )

Parameters

value

An integer that indicates whether the dialog box will show screen fonts, printer fonts, or both. Possible return values are constants defined in the FontDevice class.

Exceptions

WFCInvalidArgumentException thrown if value is not a valid FontDevice constant.

See Also getFontDevice


 FontDialog.setFontMustExist

FontDialog.setFontMustExist

Sets a boolean value indicating whether the dialog box should indicate an error condition if the user attempts to select a font or style that does not exist.

Syntax

public final void setFontMustExist( boolean value )

Parameters

value

Set to true for the dialog box to indicate an error condition when the user tries to select a font or style that does not exist; otherwise, set to false. The default value is false.

See Also getFontMustExist


 FontDialog.setMaxSize

FontDialog.setMaxSize

Sets a value indicating the maximum point size a user can select.

Syntax

public final void setMaxSize( int value )

Parameters

value

An integer that represents the the maximum point size a user can select. Set to zero (0) if there is no size limit.

See Also getMaxSize


 FontDialog.setMinSize

FontDialog.setMinSize

Sets a value indicating the minimum point size a user can select.

Syntax

public final void setMinSize( int value )

Parameters

value

An integer that represents the the minimum point size a user can select; returns zero (0) if there is no size limit.

Remarks

In order for the maximum and minimum size settings to take effect, maxSize must be greater than minSize, and both must be greater than zero.

See Also getMinSize


 FontDialog.setPrinterDC

FontDialog.setPrinterDC

Sets a value identifying the device context of the printer whose fonts will be listed in the dialog box.

Syntax

public final void setPrinterDC( int value )

Parameters

value

An integer that represents a Win32 Graphics Device Context handle that identifies the device context of the printer whose fonts will be listed in the dialog box.

See Also getPrinterDC


 FontDialog.setScalableOnly

FontDialog.setScalableOnly

Sets a boolean value indicating whether the dialog box allows only the selection of scalable fonts.

Syntax

public final void setScalableOnly( boolean value )

Parameters

value

Set to true if only scalable fonts are allowed; otherwise, set to false. The default value is false.

Remarks

Scalable fonts include vector fonts, scalable printer fonts, TrueType fonts, and fonts scaled by other technologies.

See Also getScalableOnly


 FontDialog.setScriptsOnly

FontDialog.setScriptsOnly

Sets a boolean value indicating whether the dialog box allows selection of fonts for all non-OEM and Symbol character sets, as well as the ANSI character set.

Syntax

public final void setScriptsOnly( boolean value )

Parameters

value

Set to true if selection of fonts for all non-OEM and Symbol character sets, as well as the ANSI character set is allowed; otherwise, set to false. The default value is false.

See Also getScriptsOnly


 FontDialog.setShowApply

FontDialog.setShowApply

Sets a boolean value indicating whether the dialog box contains an Apply button.

Syntax

public final void setShowApply( boolean value )

Parameters

value

Set to true to include an Apply button in the dialog box; otherwise, set to false. The default value is false.

See Also getShowApply


 FontDialog.setShowColor

FontDialog.setShowColor

Sets a boolean value indicating whether or not the color choice is shown.

Syntax

public final void setShowColor( boolean value )

Parameters

value

Set to true to show the color choice; otherwise, set to false. The default value is false.

See Also getShowColor


 FontDialog.setShowEffects

FontDialog.setShowEffects

Sets a boolean value indicating whether the dialog box displays the controls that allow the user to specify strikeout, underline, and text color options.

Syntax

public final void setShowEffects( boolean value )

Parameters

value

Set to true to include controls to set strikeout, underline, and text color options in the dialog box; otherwise, set to false. The default value is true.

See Also getShowEffects


 FontDialog.setShowHelp

FontDialog.setShowHelp

Sets a boolean value indicating whether the dialog box contains a Help button.

Syntax

public final void setShowHelp( boolean value )

Parameters

value

Set to true to include a Help button in the dialog box; otherwise, set to false. The default value is false.

See Also getShowHelp


 FontDialog.setTrueTypeOnly

FontDialog.setTrueTypeOnly

Sets a boolean value indicating whether the dialog box displays only TrueType fonts.

Syntax

public final void setTrueTypeOnly( boolean value )

Parameters

value

Set to true if the dialog displays only TrueType fonts; otherwise, set to false. The default value is false.

See Also getTrueTypeOnly


 FontDialog.setWysiwyg

FontDialog.setWysiwyg

Sets a boolean value indicating whether the dialog box allows only the selection of fonts available on both the printer and the display.

Syntax

public final void setWysiwyg( boolean value )

Parameters

value

Set to true if only fonts available on both the printer and the display are allowed. The default value is false.

See Also getWysiwyg


 FontDialog.toString

FontDialog.toString

Retrieves a string that includes the name of the current font selected in the dialog box.

Syntax

public String toString()

Return Value

Returns a string that includes the name of the currently selected font.


FontFamily Class

Defines a group of constants that represent the families to which a font may belong.

Enum
  |
  +--FontFamily

package com.ms.wfc.ui

public final class FontFamily
extends Enum

Remarks

The term font family designates one of several attributes used to organize TrueType fonts. Family names include Courier New, Arial, and Times New Roman.

The FontFamily class defines constants for the families to which a font can belong. When you create a Font object, you can specify the font family for the object's underlying font by using the constants defined in this class.

If you create a Font object without specifying a font family, a default value of FontFamily.DEFAULT is used.


 FontFamily Methods

FontFamily Methods

Methods | Description
valid | Retrieves a boolean value that indicates whether the specified value is a valid FontFamily constant.


 FontFamily.valid

FontFamily.valid

Retrieves a boolean value that indicates whether the specified value is a valid FontFamily constant.

Syntax

public static boolean valid( int value )

Parameters

value

The value to verify against the constants defined in this class.

Return Value

Returns true if the specified value is valid; otherwise, returns false.


 FontFamily Fields

FontFamily Fields

Fields | Description
DECORATIVE | Represents the Decorative font family, which consists of novelty typefaces of both variable and fixed pitch.
DEFAULT | Represents the Default font family. When you create a Font object without specifying a font family, this value is used to create the object.
DONTCARE | Represents the default font family (identical to DEFAULT).
MODERN | Represents the Modern font family, which consist of fonts that have fixed pitch and that may or may not have serifs.
ROMAN | Represents the Roman font family, which consists of fonts that are of variable pitch and that have serifs.
SCRIPT | Represents the Script font family, which consists of fonts that are designed to look like handwriting.
SWISS | Represents the Swiss font family, which consists of fonts that are of variable pitch and that are without serifs.


 FontFamily.DECORATIVE

FontFamily.DECORATIVE

Represents the Decorative font family, which consists of novelty typefaces of both variable and fixed pitch.

Syntax

public static final int DECORATIVE;

Remarks

Examples of fonts belonging to this family include Comic Sans and Old English fonts.


 FontFamily.DEFAULT

FontFamily.DEFAULT

Represents the Default font family. When you create a Font object without specifying a font family, this value is used to create the object.

Syntax

public static final int DEFAULT;


 FontFamily.DONTCARE

FontFamily.DONTCARE

Represents the default font family (identical to DEFAULT).

Syntax

public static final int DONTCARE;


 FontFamily.MODERN

FontFamily.MODERN

Represents the Modern font family, which consist of fonts that have fixed pitch and that may or may not have serifs.

Syntax

public static final int MODERN;

Remarks

Examples of fonts belonging to this family include Courier New and Lucida Console.


 FontFamily.ROMAN

FontFamily.ROMAN

Represents the Roman font family, which consists of fonts that are of variable pitch and that have serifs.

Syntax

public static final int ROMAN;

Remarks

Examples of fonts belonging to this family include the Times New Roman font face.


 FontFamily.SCRIPT

FontFamily.SCRIPT

Represents the Script font family, which consists of fonts that are designed to look like handwriting.

Syntax

public static final int SCRIPT;

Remarks

Examples of fonts belonging to this family include the Script and Cursive fonts.


 FontFamily.SWISS

FontFamily.SWISS

Represents the Swiss font family, which consists of fonts that are of variable pitch and that are without serifs.

Syntax

public static final int SWISS;

Remarks

An example of fonts belonging to this family is the Arial font.


FontMetrics Class

Defines the physical characteristics of a font as it is mapped into a Graphics object.

package com.ms.wfc.ui

public class FontMetrics

Remarks

You can specify the font metrics on which a font is based when you create a Font object.

In addition, given a Font object, you can use its getFontMetrics method to retrieve the FontMetrics object on which the font is based.


 FontMetrics Methods

FontMetrics Methods

Constructors | Description
FontMetrics | Creates a new FontMetrics object.

Methods | Description
equals | Retrieves a boolean value that indicates whether the specified object is equivalent to this FontMetrics object.
equalsBase | Retrieves a boolean value that indicates whether the specified FontMetrics object uses the same base font base as this one.
fillFontMetrics | Initializes this object based on the contents of a Win32 TEXTMETRIC structure.
hashCode | Retrieves a hash code for this FontMetrics object.
toString | Retrieves a human-readable, string representation of this object.


 FontMetrics.equals

FontMetrics.equals

Retrieves a boolean value that indicates whether the specified object is equivalent to this FontMetrics object.

Syntax

public boolean equals( Object obj )

Parameters

obj

The object to compare to this one.

Return Value

Returns true if the given object is equal to this one; otherwise, returns false.

See Also java.lang.Object


 FontMetrics.equalsBase

FontMetrics.equalsBase

Retrieves a boolean value that indicates whether the specified FontMetrics object uses the same base font base as this one.

Syntax

public boolean equalsBase( FontMetrics fi )

Parameters

fi

The FontMetrics object to evaluate.

Return Value

Returns true if the given FontMetrics object has the same base characteristics as this object; otherwise, returns false.


 FontMetrics.fillFontMetrics

FontMetrics.fillFontMetrics

Initializes this object based on the contents of a Win32 TEXTMETRIC structure.

Syntax

protected final void fillFontMetrics( TEXTMETRIC tm )

Parameters

tm

A Win32 TEXTMETRIC structure from which to initialize this object.


 FontMetrics.FontMetrics

FontMetrics.FontMetrics

Creates a new FontMetrics object.

Syntax

public FontMetrics()

public FontMetrics( Font font, Graphics g )

Parameters

font

The font for which to get the FontMetrics.

g

The Graphics object to which to render the font.

Remarks

A FontMetrics object describes the attributes of a font. Once you have initialized a FontMetrics object, you can pass that object as a parameter to the Font object constructor.


 FontMetrics.hashCode

FontMetrics.hashCode

Retrieves a hash code for this FontMetrics object.

Syntax

public int hashCode()

Return Value

Returns the hash code for this object.

See Also java.lang.Object


 FontMetrics.toString

FontMetrics.toString

Retrieves a human-readable, string representation of this object.

Syntax

public String toString()

Return Value

Returns a string representing this object.

See Also java.lang.Object


 FontMetrics Fields

FontMetrics Fields

Fields | Description
ascent | Represents the font ascent, which is the distance from the base line to the top of most alphanumeric characters.
averageWidth | Represents the average character width for characters drawn using the described font.
breakChar | Specifies the value of the character that will be used to define word breaks for text justification.
charSet | Specifies the font's character set. This value must be one of the enumeration constants defined in the com.ms.wfc.app.CharacterSet class.
defaultChar | Specifies the value of the character to be substituted for characters not found in the font.
descent | Specifies the descent (units below the base line) of characters.
digitizedAspectX | Specifies the horizontal aspect of the device for which the font was designed.
digitizedAspectY | Specifies the vertical aspect of the device for which the font was designed.
externalLeading | Specifies the amount of extra leading (space) that the application adds between rows. The designer may set this member to zero.
family | Specifies the font family.
firstChar | Specifies the value of the first character defined in the font.
font | Specifies the font on which this FontMetrics object is based (in cases where the object is constructed based on a Font object).
height | Represents the height (ascent + descent) of characters.
internalLeading | Specifies the amount of leading (space) inside the bounds set by the height member.
italic | Specifies whether the font is italicized.
lastChar | Specifies the value of the last character defined in the font.
maxWidth | Specifies the width of the widest character in the font.
name | Specifies the name of the font face (in cases where the object is constructed based on a Font object).
overhang | Specifies the extra width per string that may be added to some synthesized fonts.
pitch | Specifies the pitch of the font.
strikeOut | Specifies whether the font is a strikeout font.
underline | Specifies whether the font is underlined.
weight | Specifies the font weight.


 FontMetrics.ascent

FontMetrics.ascent

Represents the font ascent, which is the distance from the base line to the top of most alphanumeric characters.

Syntax

public int ascent;


 FontMetrics.averageWidth

FontMetrics.averageWidth

Represents the average character width for characters drawn using the described font.

Syntax

public int averageWidth;

Remarks

The average width of a character is generally defined as the width of the letter x and does not include the overhang required for bold or italic characters.


 FontMetrics.breakChar

FontMetrics.breakChar

Specifies the value of the character that will be used to define word breaks for text justification.

Syntax

public int breakChar;


 FontMetrics.charSet

FontMetrics.charSet

Specifies the font's character set. This value must be one of the enumeration constants defined in the com.ms.wfc.app.CharacterSet class.

Syntax

public int charSet;


 FontMetrics.defaultChar

FontMetrics.defaultChar

Specifies the value of the character to be substituted for characters not found in the font.

Syntax

public char defaultChar;


 FontMetrics.descent

FontMetrics.descent

Specifies the descent (units below the base line) of characters.

Syntax

public int descent;


 FontMetrics.digitizedAspectX

FontMetrics.digitizedAspectX

Specifies the horizontal aspect of the device for which the font was designed.

Syntax

public int digitizedAspectX;


 FontMetrics.digitizedAspectY

FontMetrics.digitizedAspectY

Specifies the vertical aspect of the device for which the font was designed.

Syntax

public int digitizedAspectY;

Remarks

The ratio of the digitizedAspectX and digitizedAspectY members defines the aspect ratio of the device for which the font was designed.


 FontMetrics.externalLeading

FontMetrics.externalLeading

Specifies the amount of extra leading (space) that the application adds between rows. The designer may set this member to zero.

Syntax

public int externalLeading;


 FontMetrics.family

FontMetrics.family

Specifies the font family.

Syntax

public int family;

Remarks

This value, if initialized, must be one of the enumeration constants defined in the FontFamily class.


 FontMetrics.firstChar

FontMetrics.firstChar

Specifies the value of the first character defined in the font.

Syntax

public char firstChar;


 FontMetrics.font

FontMetrics.font

Specifies the font on which this FontMetrics object is based (in cases where the object is constructed based on a Font object).

Syntax

protected Font font;


 FontMetrics.height

FontMetrics.height

Represents the height (ascent + descent) of characters.

Syntax

public int height;


 FontMetrics.internalLeading

FontMetrics.internalLeading

Specifies the amount of leading (space) inside the bounds set by the height member.

Syntax

public int internalLeading;

Remarks

Accent marks and other diacritical characters may occur in the internal leading area of a font.


 FontMetrics.italic

FontMetrics.italic

Specifies whether the font is italicized.

Syntax

public boolean italic;


 FontMetrics.lastChar

FontMetrics.lastChar

Specifies the value of the last character defined in the font.

Syntax

public char lastChar;


 FontMetrics.maxWidth

FontMetrics.maxWidth

Specifies the width of the widest character in the font.

Syntax

public int maxWidth;


 FontMetrics.name

FontMetrics.name

Specifies the name of the font face (in cases where the object is constructed based on a Font object).

Syntax

public String name;


 FontMetrics.overhang

FontMetrics.overhang

Specifies the extra width per string that may be added to some synthesized fonts.

Syntax

public int overhang;

Remarks

When synthesizing some attributes, such as bold or italic, a graphics device interface (GDI) or a device may have to add width to a string on both a per-character and per-string basis. For example, GDI makes a string bold by expanding the spacing of each character and overstriking by an offset value; it italicizes a font by shearing the string. In either case, there is an overhang past the basic string. For bold strings, the overhang is the distance by which the overstrike is offset. For italic strings, the overhang is the amount the top of the font is sheared past the bottom of the font.


 FontMetrics.pitch

FontMetrics.pitch

Specifies the pitch of the font.

Syntax

public int pitch;

Remarks

This value, if initialized, must be one of the enumeration constants defined in the FontPitch class.


 FontMetrics.strikeOut

FontMetrics.strikeOut

Specifies whether the font is a strikeout font.

Syntax

public boolean strikeOut;


 FontMetrics.underline

FontMetrics.underline

Specifies whether the font is underlined.

Syntax

public boolean underline;


 FontMetrics.weight

FontMetrics.weight

Specifies the font weight.

Syntax

public int weight;

Remarks

This value, if initialized, must be a value between 0 and 1000. The most commonly used font weights are defined as enumeration constants in the FontWeight class.


FontPitch Class

Encapsulates a font's pitch.

Enum
  |
  +--FontPitch

package com.ms.wfc.ui

public final class FontPitch
extends Enum

Remarks

An application specifies the pitch of a font when it creates the Font object. All Font object initialization occurs in the Font object's constructor; once the object is constructed, its settings cannot be modified.


 FontPitch Methods

FontPitch Methods

Methods | Description
valid | Retrieves a boolean value that indicates whether the specified value is a valid FontFamily value.


 FontPitch.valid

FontPitch.valid

Retrieves a boolean value that indicates whether the specified value is a valid FontFamily value.

Syntax

public static boolean valid( int value )

Parameters

value

The value to evaluate against the constants defined in this class.

Return Value

Returns true if value is a valid FontPitch constant; otherwise, returns false.


 FontPitch Fields

FontPitch Fields

Fields | Description
DEFAULT | Represents a default pitch.
FIXED | Represents a fixed-pitch font.
VARIABLE | Represents a variable-pitch font.


 FontPitch.DEFAULT

FontPitch.DEFAULT

Represents a default pitch.

Syntax

public static final int DEFAULT;

Remarks

If you specify this value at font creation, Windows determines the pitch for characters drawn using the font.


 FontPitch.FIXED

FontPitch.FIXED

Represents a fixed-pitch font.

Syntax

public static final int FIXED;

Remarks

A fixed-pitch font is one in which all characters have the same width.


 FontPitch.VARIABLE

FontPitch.VARIABLE

Represents a variable-pitch font.

Syntax

public static final int VARIABLE;

Remarks

A variable-pitch font is one in which characters have varying width.


FontSize Class

Defines a group of constants that represent the units in which font sizes can be specified.

Enum
  |
  +--FontSize

package com.ms.wfc.ui

public final class FontSize
extends Enum

Remarks

The following is an example of the context in which the FontSize class is used.

When creating a Font object, you can specify the font's size. If you specify that the font's size is 10, this size can represent 10 millimeters, 10 pixels, 10 logical units (and so on), depending on the units in which this size is expressed. The FontSize class identifies the units in which the size designation are to be measured.


 FontSize Methods

FontSize Methods

Methods | Description
valid | Retrieves a boolean value that indicates whether the specified value is a valid FontSize constant.


 FontSize.valid

FontSize.valid

Retrieves a boolean value that indicates whether the specified value is a valid FontSize constant.

Syntax

public static boolean valid( int value )

Parameters

value

The value to verify against the constants defined in this class.

Return Value

Returns true if the value is valid; otherwise, returns false.


 FontSize Fields

FontSize Fields

Fields | Description
CELLHEIGHT | Represents the size of the font in logical units.
CENTIMETERS | Represents the size of the font in centimeters.
CHARACTERHEIGHT | Represents the size of the font in logical units.
EM | Represents the size of the font as a percentage of the system default font's character height.
EX | Represents the size of the font as a percentage of the system default font's cell height.
INCHES | Represents the size of the font in inches.
MILLIMETERS | Represents the size of the font in millimeters.
PIXELS | Represents the size of the font in pixels.
POINTS | Represents the size of the font specified in points or 1/72nds of an inch.


 FontSize.CELLHEIGHT

FontSize.CELLHEIGHT

Represents the size of the font in logical units.

Syntax

public static final int CELLHEIGHT;

Remarks

The size of the font is the entire height of the font cell, including internal leading (spaces). Logical units scale differently on different coordinate systems.


 FontSize.CENTIMETERS

FontSize.CENTIMETERS

Represents the size of the font in centimeters.

Syntax

public static final int CENTIMETERS;

Remarks

This unit remains constant across varying coordinate systems.


 FontSize.CHARACTERHEIGHT

FontSize.CHARACTERHEIGHT

Represents the size of the font in logical units.

Syntax

public static final int CHARACTERHEIGHT;

Remarks

The actual size of the font will be the height of a character only, excluding the internal leading. Logical units scale differently on different coordinate systems.


 FontSize.EM

FontSize.EM

Represents the size of the font as a percentage of the system default font's character height.

Syntax

public static final int EM;

Remarks

This size scales differently with different coordinate systems.


 FontSize.EX

FontSize.EX

Represents the size of the font as a percentage of the system default font's cell height.

Syntax

public static final int EX;

Remarks

This size scales with different coordinate systems.


 FontSize.INCHES

FontSize.INCHES

Represents the size of the font in inches.

Syntax

public static final int INCHES;

Remarks

This unit remains constant across coordinate systems.


 FontSize.MILLIMETERS

FontSize.MILLIMETERS

Represents the size of the font in millimeters.

Syntax

public static final int MILLIMETERS;

Remarks

This unit remains constant across coordinate systems.


 FontSize.PIXELS

FontSize.PIXELS

Represents the size of the font in pixels.

Syntax

public static final int PIXELS;

Remarks

The effect of using this unit is identical to that of using CELLHEIGHT.


 FontSize.POINTS

FontSize.POINTS

Represents the size of the font specified in points or 1/72nds of an inch.

Syntax

public static final int POINTS;

Remarks

The size is the height of the character only, excluding the internal leading. Points remain constant with different coordinate systems because they are based on physical inches rather than logical units.


FontType Class

Encapsulates a font type.

package com.ms.wfc.ui

public class FontType

Remarks

You determine the type of a font based on the type of technology that will be used to render the font.

You specify the type of a font when you create a Font object based on the settings in a FontDescriptor object. The value to which you initialize the FontDescriptor object's public type member can consist of a logical combination of one or more of the values defined in this class.


 FontType Methods

FontType Methods

Methods | Description
valid | Retrieves a boolean value that indicates whether the specified value is a valid member of this class.


 FontType.valid

FontType.valid

Retrieves a boolean value that indicates whether the specified value is a valid member of this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check against the values defined in this class.

Return Value

Returns true if the value is valid; otherwise, returns false.


 FontType Fields

FontType Fields

Fields | Description
DEVICE | Specifies that the font will be rendered entirely by the device.
RASTER | Specifies a raster font type.
TRUETYPE | Specifies a TrueType font type.


 FontType.DEVICE

FontType.DEVICE

Specifies that the font will be rendered entirely by the device.

Syntax

public static final int DEVICE;

Remarks

The Windows operating system associates no device fonts with the screen. Printers, however, may support a wide variety of device fonts.


 FontType.RASTER

FontType.RASTER

Specifies a raster font type.

Syntax

public static final int RASTER;

Remarks

A raster font is a bitmapped font that cannot be smoothly scaled.

A raster font typically has several different sizes. If a raster font does not have a requested font size, the font mapper scales the bitmap of the font as appropriate.


 FontType.TRUETYPE

FontType.TRUETYPE

Specifies a TrueType font type.

Syntax

public static final int TRUETYPE;

Remarks

TrueType fonts are rendered by the Windows TrueType engine and can be scaled and rotated smoothly.


FontWeight Class

Defines constants that represent the different weights that you can associate with a font.

Enum
  |
  +--FontWeight

package com.ms.wfc.ui

public final class FontWeight
extends Enum

Remarks

A font's weight can range from 0 to 1000 inclusive. This class defines constants for some of the more commonly used font weights.

You specify the weight of a font when you create a Font object. If you create a Font object using a constructor that takes no weight parameter, or specify a value of 0, a default value of FontWeight.NORMAL is used.


 FontWeight Methods

FontWeight Methods

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value is a valid member of this class.


 FontWeight.valid

FontWeight.valid

Retrieves a boolean value that indicates whether a specified value is a valid member of this class.

Syntax

public static boolean valid( int value )

Parameters

value

A value to compare to the constants defined in this class.

Return Value

Returns true if the value is valid; otherwise, returns false.


 FontWeight Fields

FontWeight Fields

Fields | Description
BOLD | Represents a bold font.
EXTRABOLD | Represents an extra bold font.
EXTRALIGHT | Represents an extra light font.
HEAVY | Represents a heavy font.
LIGHT | Represents a light font.
MEDIUM | Represents a medium font weight.
NORMAL | Represents a normal font weight.
SEMIBOLD | Represents a weight between medium and bold.
THIN | Represents a thin font.


 FontWeight.BOLD

FontWeight.BOLD

Represents a bold font.

Syntax

public static final int BOLD;


 FontWeight.EXTRABOLD

FontWeight.EXTRABOLD

Represents an extra bold font.

Syntax

public static final int EXTRABOLD;


 FontWeight.EXTRALIGHT

FontWeight.EXTRALIGHT

Represents an extra light font.

Syntax

public static final int EXTRALIGHT;


 FontWeight.HEAVY

FontWeight.HEAVY

Represents a heavy font.

Syntax

public static final int HEAVY;


 FontWeight.LIGHT

FontWeight.LIGHT

Represents a light font.

Syntax

public static final int LIGHT;


 FontWeight.MEDIUM

FontWeight.MEDIUM

Represents a medium font weight.

Syntax

public static final int MEDIUM;


 FontWeight.NORMAL

FontWeight.NORMAL

Represents a normal font weight.

Syntax

public static final int NORMAL;


 FontWeight.SEMIBOLD

FontWeight.SEMIBOLD

Represents a weight between medium and bold.

Syntax

public static final int SEMIBOLD;


 FontWeight.THIN

FontWeight.THIN

Represents a thin font.

Syntax

public static final int THIN;


Form Class

Represents the basic top-level window.

Component
  |
  +--Control
    |
    +--Form

package com.ms.wfc.ui

public class Form
extends Control
implements ITopLevelWindow


 Form Methods

Form Methods

Constructors | Description
Form | Creates a Form object.

Methods | Description
add | Adds a control to the form.
addOnActivate | Assigns a delegate to the activate event.
addOnClosed | Assigns a delegate to the closed event.
addOnClosing | Assigns a delegate to the closing event.
addOnDeactivate | Assigns a delegate to the deactivate event.
addOnInputLangChange | Assigns a delegate to the inputLangChange event.
addOnInputLangChangeRequest | Assigns a delegate to the inputLangChangeRequest event.
addOnMDIChildActivate | Assigns a delegate to the mdiChildActivate event.
addOnMenuComplete | Assigns a delegate to the menuComplete event.
addOnMenuStart | Assigns a delegate to the menuStart event.
addOwnedForm | Adds a form to this Form object's internal list of owned forms.
adjustFormScrollbars | Adjusts the automatic scroll bars on the form based on current control positions and the currently selected control.
close | Closes the form.
createHandle | Creates the handle for the form.
defWndProc | Calls the default window procedure for this form.
dispose | Releases all the system resources associated with this form.
getAcceptButton | Retrieves the current accept button for this form.
getActiveControl | Retrieves the current active control.
getActiveMDIChild | Retrieves the currently active multiple document interface (MDI) child window.
getAutoScale | Retrieves a boolean value that indicates whether the form is currently configured to adjust its size to fit the height of the font used on the form and to scale its child controls.
getAutoScaleBaseSize | Retrieves the base size used for autoscaling.
getAutoScroll | Retrieves a boolean value that indicates whether the form will allow scrolling of the form's contents when controls are located outside the form's bounds.
getAutoScrollMargin | Retrieves the width and height of the autoscroll margin.
getAutoScrollPosition | Retrieves the current autoscroll position.
getBorderStyle | Retrieves the form's current border style.
getCancelButton | Retrieves the form's cancel button.
getControlBox | Retrieves a boolean value that indicates whether this form has a control box.
getCreateParams | Retrieves a CreateParams object that describes the settings used to create the form.
getDesktopBounds | Retrieves the bounds of the form in desktop coordinates.
getDesktopLocation | Retrieves the location of the form in desktop coordinates.
getDialogResult | Retrieves the dialog result which designates the value that is returned from this form when it is displayed as a modal dialog.
getDisplayRect | Retrieves the current display rectangle.
getForm | Retrieves this form's parent.
getHelpButton | Retrieves a boolean value that indicates whether this form contains a help button.
getHScroll | Retrieves a boolean value that indicates whether the horizontal scroll bar is currently displayed.
getIcon | Retrieves the form's current icon.
getIsMDIChild | Retrieves a boolean value that indicates whether this form is an MDI child form.
getIsMDIContainer | Retrieves a boolean value that indicates whether this form is an MDI container.
getIsMenuBarContainer | Retrieves a boolean value indicating whether this form contains a menu bar.
getKeyPreview | Retrieves a boolean value that indicates whether this form is set to receive key events for contained controls before the controls receive them.
getMaximizeBox | Retrieves a boolean value that indicates whether a maximize button is displayed in the upper-right corner of the form.
getMaximizedBounds | Retrieves the bounds of this form in its maximized state.
getMaxTrackSize | Retrieves the maximum size to which this form can be resized.
getMDIChildren | Retrieves the MDI children of this form.
getMDIClient | Retrieves the control that is the MDI client region.
getMDIParent | Retrieves the current MDI parent of this form.
getMenu | Retrieves the current menu for this form.
getMergedMenu | Retrieves the merged menu for the form.
getMinimizeBox | Retrieves a boolean value that indicates whether a minimize button is displayed on the current form.
getMinTrackSize | Retrieves the minimum size to which this form can be resized.
getModal | Retrieves a boolean value that indicates whether this form is modal.
getOwnedForms | Retrieves the forms owned by this one.
getOwner | Retrieves the owner of this form.
getPalette | Retrieves the palette currently being used by the form.
getPaletteMode | Retrieves the current palette mode for this form.
getPaletteSource | Retrieves the source for the palette being used by this form.
getParentForm | Retrieves the visual parent of this form.
getShowInTaskbar | Retrieves a boolean value that indicates whether this form is currently displayed in the taskbar.
getStartPosition | Retrieves the current start position of this form.
getWindowState | Retrieves the form's window state.
layoutMDI | Arranges the MDI children of this form according to a specified value.
notifyPaletteChange | Notifies this form that the palette has changed on a child control.
onActivate | Triggers the activate event.
onClosed | Triggers the closed event.
onClosing | Triggers the closing event.
onDeactivate | Triggers the deactivate event.
onInputLangChange | Triggers the inputLangChange event.
onInputLangChangeRequest | Triggers the inputLangChangeRequest event.
onMDIChildActivate | Triggers the MDIChildActivate event.
onMenuComplete | Triggers the menuComplete event.
onMenuStart | Triggers the menuStart event.
onNewPalette | Called by a child control to indicate that the palette needs to be rendered.
pointToScreen | Retrieves the screen coordinates for a specified location.
propertyChanged | Called when a control property changes.
rectToClient | Retrieves the specified screen rectangle in client coordinates.
rectToScreen | Retrieves the screen coordinates for the specified client rectangle.
removeOnActivate | Removes the delegate that is assigned to the activate event.
removeOnClosed | Removes the delegate that is assigned to the closed event.
removeOnClosing | Removes the delegate that is assigned to the closing event.
removeOnDeactivate | Removes the delegate that is assigned to the deactivate event.
removeOnInputLangChange | Removes the delegate that is assigned to the inputLangChange event.
removeOnInputLangChangeRequest | Removes the delegate that is assigned to the inputLangChangeRequest event.
removeOnMDIChildActivate | Removes the delegate that is assigned to the MDIChildActivate event.
removeOnMenuComplete | Removes the delegate that is assigned to the menuComplete event.
removeOnMenuStart | Removes the delegate that is assigned to the menuStart event.
removeOwnedForm | Removes a form from this Form object's internal list of owned forms.
setAcceptButton | Sets the accept button for this form.
setActiveControl | Sets the the input focus to the specified control.
setAutoScale | Sets the autoscaling on this form.
setAutoScaleBaseSize | Sets the base size used for autoscaling when the form is created.
setAutoScroll | Specifies whether the form implements autoscrolling.
setAutoScrollMargin | Sets the width and height of the autoscroll margin.
setAutoScrollPosition | Sets the autoscroll position that is used when the form is created.
setBorderStyle | Sets the border style for the form.
setCancelButton | Sets the cancel button for the form.
setControlBox | Specifies whether a control box is to be displayed on this form.
setDesktopBounds | Sets the bounds of the form in desktop coordinates.
setDesktopLocation | Sets the location of the form in desktop coordinates.
setDialogResult | Sets the value to be returned from the form when it is displayed as a modal dialog.
setHelpButton | Specifies whether a "What's This?" help icon should be displayed in the form's caption bar.
setIcon | Sets the icon to be displayed in the caption bar of the form.
setIsMDIContainer | Specifies whether this form is an MDI container.
setKeyPreview | Specifies whether the form should receive key events for all contained controls before the control receives them.
setMaximizeBox | Specifies whether a maximize button should be displayed in this form's caption bar.
setMDIParent | Sets the MDI parent for this form.
setMenu | Sets the main menu for this form.
setMinimizeBox | Specifies whether a minimize button should be displayed in the form's caption bar.
setNewControls | Arranges an array of controls on a form.
setOwner | Sets the owner for this form.
setPaletteMode | Specifies the palette mode for this form.
setPaletteSource | Specifies the source for this form's palette.
setShowInTaskbar | Specifies whether this form's icon should be displayed in the Windows taskbar.
setStartPosition | Specifies the initial position of this form.
setVisible | Specifies whether this form is visible.
setWindowState | Specifies the window state for this form.
shouldPersistAutoScrollPosition | Retrieves a boolean value that indicates whether the autoscroll position for this form should be persisted.
showDialog | Displays this form as a modal dialog.
wndProc | Encapsulates the base window procedure for this class.


 Form.add

Form.add

Adds a control to the form.

Syntax

public void add( Control control )

Parameters

control

A Control object that specifies the control to add to this form.

Remarks

A call to this method places the control visually on this form, and makes this form the control's parent.


 Form.addOnActivate

Form.addOnActivate

Assigns a delegate to the activate event.

Syntax

public final void addOnActivate( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

A Form object's activate event occurs when the form is activated.

See Also onActivate, removeOnActivate


 Form.addOnClosed

Form.addOnClosed

Assigns a delegate to the closed event.

Syntax

public final void addOnClosed( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

A Form object's closed event is fired when the form is closed.

See Also onClosed, removeOnClosed


 Form.addOnClosing

Form.addOnClosing

Assigns a delegate to the closing event.

Syntax

public final void addOnClosing( CancelEventHandler value )

Parameters

value

The CancelEventHandler delegate to be notified when the event occurs.

Remarks

The closing event occurs as the form is closing. If you cancel this event, the form does not close.

See Also removeOnClosing


 Form.addOnDeactivate

Form.addOnDeactivate

Assigns a delegate to the deactivate event.

Syntax

public final void addOnDeactivate( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

The deactivate event occurs when a form is deactivated.

See Also onDeactivate, removeOnDeactivate


 Form.addOnInputLangChange

Form.addOnInputLangChange

Assigns a delegate to the inputLangChange event.

Syntax

public final void addOnInputLangChange( InputLangChangeEventHandler value )

Parameters

value

The InputLangChangeEventHandler delegate to be notified when the event occurs.

Remarks

The inputLangChange event occurs after the input language has changed for this form.

See Also removeOnInputLangChange


 Form.addOnInputLangChangeRequest

Form.addOnInputLangChangeRequest

Assigns a delegate to the inputLangChangeRequest event.

Syntax

public final void addOnInputLangChangeRequest( InputLangChangeRequestEventHandler value )

Parameters

value

The InputLangChangeRequestEventHandler delegate to be notified when the event occurs.

Remarks

The inputLangChangeRequest event occurs when the user attempts to change the input language for this form. If the event is canceled, the input language is not changed.

See Also onInputLangChangeRequest, removeOnInputLangChangeRequest


 Form.addOnMDIChildActivate

Form.addOnMDIChildActivate

Assigns a delegate to the mdiChildActivate event.

Syntax

public final void addOnMDIChildActivate( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

The mdiChildActivate event occurs when a child window in an MDI application is activated.

See Also onMDIChildActivate, removeOnMDIChildActivate


 Form.addOnMenuComplete

Form.addOnMenuComplete

Assigns a delegate to the menuComplete event.

Syntax

public final void addOnMenuComplete( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

The menuComplete event occurs when the form's main menu loses input focus.

See Also onMenuComplete, removeOnMenuComplete


 Form.addOnMenuStart

Form.addOnMenuStart

Assigns a delegate to the menuStart event.

Syntax

public final void addOnMenuStart( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

The menuStart event occurs when the form's main menu receives the input focus.

See Also onMenuStart, removeOnMenuStart


 Form.addOwnedForm

Form.addOwnedForm

Adds a form to this Form object's internal list of owned forms.

Syntax

public final void addOwnedForm( Form ownedForm )

Parameters

ownedForm

A Form object that specifies the form to add to the list.

Remarks

An owned form is a top-level form that is a child of this one. If the form specified in ownedForm is currently owned by a form other than this one, that form ceases to own the child form.


 Form.adjustFormScrollbars

Form.adjustFormScrollbars

Adjusts the automatic scroll bars on the form based on current control positions and the currently selected control.

Syntax

protected final void adjustFormScrollbars( boolean displayScrollbars )

Parameters

displayScrollbars

Set to true to display the scroll bars; otherwise, set to false.

See Also getAutoScroll


 Form.close

Form.close

Closes the form.

Syntax

public final void close()


 Form.createHandle

Form.createHandle

Creates the handle for the form.

Syntax

protected void createHandle()

Remarks

When overriding createHandle, be sure to call super.createHandle.


 Form.defWndProc

Form.defWndProc

Calls the default window procedure for this form.

Syntax

protected void defWndProc( Message m )

Parameters

m

A Message object that specifies a message to this form.

Remarks

When overriding defWndProc, be sure to call super.defWndProc.


 Form.dispose

Form.dispose

Releases all the system resources associated with this form.

Syntax

public void dispose()

Remarks

When overriding dispose, be sure to call super.dispose.


 Form.Form

Form.Form

Creates a Form object.

Syntax

public Form()


 Form.getAcceptButton

Form.getAcceptButton

Retrieves the current accept button for this form.

Syntax

public final IButtonControl getAcceptButton()

Return Value

Returns the control that represents the form's accept button.

Remarks

The accept button designates a form control that is clicked when the user presses the ENTER key.

See Also setAcceptButton


 Form.getActiveControl

Form.getActiveControl

Retrieves the current active control.

Syntax

public final Control getActiveControl()

Return Value

Returns a Control object that specifies the current active control.

See Also setActiveControl


 Form.getActiveMDIChild

Form.getActiveMDIChild

Retrieves the currently active multiple document interface (MDI) child window.

Syntax

public final Form getActiveMDIChild()

Return Value

Returns a Form object that specifies the currently active MDI child window. If there are no currently active MDI child windows, this method returns null.


 Form.getAutoScale

Form.getAutoScale

Retrieves a boolean value that indicates whether the form is currently configured to adjust its size to fit the height of the font used on the form and to scale its child controls.

Syntax

public final boolean getAutoScale()

Return Value

Returns true if the form is set to scale automatically; otherwise, returns false.

Remarks

The ability of a form to scale automatically enables the form to resize to accommodate international systems and those that use Large Fonts.

See Also setAutoScale


 Form.getAutoScaleBaseSize

Form.getAutoScaleBaseSize

Retrieves the base size used for autoscaling.

Syntax

public final int getAutoScaleBaseSize()

Return Value

Returns the base size that this form uses for autoscaling.

Remarks

The autoscaling base size is used by the form as a baseline for comparison to the system's font size to determine how much to scale the form when autoscaling is used.

See Also setAutoScaleBaseSize, setAutoScale


 Form.getAutoScroll

Form.getAutoScroll

Retrieves a boolean value that indicates whether the form will allow scrolling of the form's contents when controls are located outside the form's bounds.

Syntax

public final boolean getAutoScroll()

Return Value

Returns true if autoscrolling is allowed; otherwise, returns false.

Remarks

The ability to autoscroll a form allows the form to have a virtual size that is larger than the current form bounds.

See Also setAutoScroll


 Form.getAutoScrollMargin

Form.getAutoScrollMargin

Retrieves the width and height of the autoscroll margin.

Syntax

public final Point getAutoScrollMargin()

Return Value

Returns a Point object that identifies the width and height of the autoscroll margin. If this value has not been set, this object's x and y members are set to zero.

Remarks

The autoscroll margins define the width and height of the border around each control. This border is used to determine when scroll bars are needed on the form and where to scroll to when a control is selected.

See Also setAutoScrollMargin


 Form.getAutoScrollPosition

Form.getAutoScrollPosition

Retrieves the current autoscroll position.

Syntax

public final Point getAutoScrollPosition()

Return Value

Returns a Point object that specifies the current autoscroll position. If the autoscroll position has not been set, this Point object contains the x and y-coordinates of the form's rectangular area.

Remarks

The autoscroll position is used by the Form object to adjust the position of controls that are placed on the form through the Form's Designer.

See Also setAutoScrollPosition


 Form.getBorderStyle

Form.getBorderStyle

Retrieves the form's current border style.

Syntax

public final int getBorderStyle()

Return Value

Returns the form's border style. This value equates to one of the enumeration constants defined in the FormBorderStyle class.

Remarks

The border style of the form determines the appearance and behavior of the form's outer edge, including whether the form can be resized.

See Also setBorderStyle


 Form.getCancelButton

Form.getCancelButton

Retrieves the form's cancel button.

Syntax

public final IButtonControl getCancelButton()

Return Value

Returns the control that represents the form's cancel button.

Remarks

The cancel button designates the control on a form that is clicked when the user presses the ESC key.

See Also setCancelButton


 Form.getControlBox

Form.getControlBox

Retrieves a boolean value that indicates whether this form has a control box.

Syntax

public final boolean getControlBox()

Return Value

Returns true if this form has a control box; otherwise, returns false.

Remarks

The control box designates the icon or button displayed in the upper-left corner of the caption bar. A user uses the control box to access the system menu.

See Also setControlBox


 Form.getCreateParams

Form.getCreateParams

Retrieves a CreateParams object that describes the settings used to create the form.

Syntax

protected CreateParams getCreateParams()

Return Value

Returns a CreateParams object that describes the values used to create the window.

Remarks

When overriding getCreateParams, be sure to call super.getCreateParams.


 Form.getDesktopBounds

Form.getDesktopBounds

Retrieves the bounds of the form in desktop coordinates.

Syntax

public final Rectangle getDesktopBounds()

Return Value

Returns a Rectangle object that specifies the bounds of the form.

See Also setDesktopBounds


 Form.getDesktopLocation

Form.getDesktopLocation

Retrieves the location of the form in desktop coordinates.

Syntax

public final Point getDesktopLocation()

Return Value

Returns a Point object that specifies location of the form.

See Also setDesktopLocation


 Form.getDialogResult

Form.getDialogResult

Retrieves the dialog result which designates the value that is returned from this form when it is displayed as a modal dialog.

Syntax

public final int getDialogResult()

Return Value

Returns the dialog result. This value equates to one of the enumeration constants defined in the DialogResult class.

See Also setDialogResult


 Form.getDisplayRect

Form.getDisplayRect

Retrieves the current display rectangle.

Syntax

public Rectangle getDisplayRect()

Return Value

Returns a Rectangle object that specifies the display rectangle.

Remarks

The display rectangle designates the virtual display area used to arrange components on the form. The position and dimensions of the form's display rectangle change when the form is autoscrolled.


 Form.getForm

Form.getForm

Retrieves this form's parent.

Syntax

public final Form getForm()

Return Value

Returns this form's parent, if there is one; otherwise, returns null.


 Form.getHelpButton

Form.getHelpButton

Retrieves a boolean value that indicates whether this form contains a help button.

Syntax

public final boolean getHelpButton()

Return Value

Returns true if the form has a help button; otherwise, returns false.

Remarks

If a form has a help button, a small question mark appears in the caption bar to the left of the minimize, maximize, and close buttons.

See Also setHelpButton


 Form.getHScroll

Form.getHScroll

Retrieves a boolean value that indicates whether the horizontal scroll bar is currently displayed.

Syntax

protected final boolean getHScroll()

Return Value

Returns true if the horizontal scroll bar is currently visible; otherwise, returns false.

Remarks

For forms that are not configured to autoscroll, this method always returns false.


 Form.getIcon

Form.getIcon

Retrieves the form's current icon.

Syntax

public final Icon getIcon()

Return Value

Returns an Icon object that specifies the form's icon.

Remarks

A form's icon designates the picture that represents the form in the task bar when the form is minimized.

See Also setIcon


 Form.getIsMDIChild

Form.getIsMDIChild

Retrieves a boolean value that indicates whether this form is an MDI child form.

Syntax

public final boolean getIsMDIChild()

Return Value

Returns true if this form is an MDI child window; otherwise, returns false.

See Also setMDIParent


 Form.getIsMDIContainer

Form.getIsMDIContainer

Retrieves a boolean value that indicates whether this form is an MDI container.

Syntax

public final boolean getIsMDIContainer()

Return Value

Returns true if this form is an MDI container; otherwise, returns false.

See Also setIsMDIContainer


 Form.getIsMenuBarContainer

Form.getIsMenuBarContainer

Retrieves a boolean value indicating whether this form contains a menu bar.

Syntax

public final boolean getIsMenuBarContainer()

Return Value

Returns true if this form is a menu bar container; otherwise, returns false.


 Form.getKeyPreview

Form.getKeyPreview

Retrieves a boolean value that indicates whether this form is set to receive key events for contained controls before the controls receive them.

Syntax

public final boolean getKeyPreview()

Return Value

Returns true if this form will receive key events before the contained controls receive them; otherwise, returns false.

See Also setKeyPreview


 Form.getMaximizeBox

Form.getMaximizeBox

Retrieves a boolean value that indicates whether a maximize button is displayed in the upper-right corner of the form.

Syntax

public final boolean getMaximizeBox()

Return Value

Returns true if the maximize button is displayed; otherwise, returns false.

See Also setMaximizeBox


 Form.getMaximizedBounds

Form.getMaximizedBounds

Retrieves the bounds of this form in its maximized state.

Syntax

protected Rectangle getMaximizedBounds()

Return Value

Returns a Rectangle object that specifies the bounds of the maximized form.

Remarks

Classes that extend the Form class can override this method to provide new bounds for the form when it is maximized. This method is called internally by the class when the form's maximize button is pressed.

See Also getMaxTrackSize, getMinTrackSize


 Form.getMaxTrackSize

Form.getMaxTrackSize

Retrieves the maximum size to which this form can be resized.

Syntax

protected Point getMaxTrackSize()

Return Value

Returns a Point object that specifies the maximum size to which the form can be resized.

Remarks

Classes that extend the Form class can override this method to provide a new maximum size for the form. This method is called internally by the Form class when the form is being resized.

See Also getMaximizedBounds, getMinTrackSize


 Form.getMDIChildren

Form.getMDIChildren

Retrieves the MDI children of this form.

Syntax

public final Form[] getMDIChildren()

Return Value

Returns an array of Form objects, each of which identifies one of this form's MDI children.

See Also getIsMDIContainer, getMDIClient, getMDIParent


 Form.getMDIClient

Form.getMDIClient

Retrieves the control that is the MDI client region.

Syntax

public final MDIClient getMDIClient()

Return Value

Returns an MDIClient object that specifies the MDI client.


 Form.getMDIParent

Form.getMDIParent

Retrieves the current MDI parent of this form.

Syntax

public final Form getMDIParent()

Return Value

Returns a Form object that represents this form's MDI parent.

See Also setMDIParent


 Form.getMenu

Form.getMenu

Retrieves the current menu for this form.

Syntax

public final MainMenu getMenu()

Return Value

Returns a MainMenu object that specifies the current menu for this form.

See Also setMenu


 Form.getMergedMenu

Form.getMergedMenu

Retrieves the merged menu for the form.

Syntax

public final MainMenu getMergedMenu()

Return Value

Returns a MainMenu object that specifies this form's merged menu.

Remarks

This method is used primarily in cases where a multiple document interface (MDI) child form merges its menu with the parent form's menu.


 Form.getMinimizeBox

Form.getMinimizeBox

Retrieves a boolean value that indicates whether a minimize button is displayed on the current form.

Syntax

public final boolean getMinimizeBox()

Return Value

Returns true if this form has a minimize button; otherwise, returns false.

See Also setMinimizeBox


 Form.getMinTrackSize

Form.getMinTrackSize

Retrieves the minimum size to which this form can be resized.

Syntax

protected Point getMinTrackSize()

Return Value

Returns a Point object that specifies the minimum size to which this form can be sized.

Remarks

Classes that extend the Form class can override this method to provide a new minimum size for the form. This method is called by the Form class when the form is being resized.

See Also getMaximizedBounds, getMaxTrackSize


 Form.getModal

Form.getModal

Retrieves a boolean value that indicates whether this form is modal.

Syntax

public final boolean getModal()

Return Value

Returns true if this form is currently modal; otherwise, returns false.

See Also showDialog


 Form.getOwnedForms

Form.getOwnedForms

Retrieves the forms owned by this one.

Syntax

public final Form[] getOwnedForms()

Return Value

Returns an array of Form objects, which contains an entry for each form owned by this one.

See Also addOwnedForm, removeOwnedForm


 Form.getOwner

Form.getOwner

Retrieves the owner of this form.

Syntax

public final Form getOwner()

Return Value

Returns a Form object that identifies the form that owns this one.


 Form.getPalette

Form.getPalette

Retrieves the palette currently being used by the form.

Syntax

public final Palette getPalette()

Return Value

Returns a Palette object that specifies the palette that this form is using.

See Also setPaletteMode, setPaletteSource


 Form.getPaletteMode

Form.getPaletteMode

Retrieves the current palette mode for this form.

Syntax

public final int getPaletteMode()

Return Value

Returns the current palette mode. This value equates to one of the enumeration constants defined in the FormPaletteMode class.

See Also setPaletteMode


 Form.getPaletteSource

Form.getPaletteSource

Retrieves the source for the palette being used by this form.

Syntax

public final Control getPaletteSource()

Return Value

Returns a Control object that specifies the control that this form is using as its palette.

See Also setPaletteSource


 Form.getParentForm

Form.getParentForm

Retrieves the visual parent of this form.

Syntax

public final Form getParentForm()

Return Value

Returns a Form object that specifies this form's parent.

See Also Control.setParent


 Form.getShowInTaskbar

Form.getShowInTaskbar

Retrieves a boolean value that indicates whether this form is currently displayed in the taskbar.

Syntax

public final boolean getShowInTaskbar()

Return Value

Returns true if the form is configured to be displayed in the taskbar; otherwise, returns false.

See Also setShowInTaskbar


 Form.getStartPosition

Form.getStartPosition

Retrieves the current start position of this form.

Syntax

public final int getStartPosition()

Return Value

Returns the start position. This value equates to one of the enumeration constants defined in the FormStartPosition class.

See Also setStartPosition


 Form.getWindowState

Form.getWindowState

Retrieves the form's window state.

Syntax

public final int getWindowState()

Return Value

Returns the window state. The returned value equates to one of the enumeration constants defined in the FormWindowState class.

See Also setWindowState


 Form.layoutMDI

Form.layoutMDI

Arranges the MDI children of this form according to a specified value.

Syntax

public void layoutMDI( int value )

Parameters

value

A constant that specifies how the method should arrange the child forms. This value must be one of the enumeration constants defined in the MDILayout class.


 Form.notifyPaletteChange

Form.notifyPaletteChange

Notifies this form that the palette has changed on a child control.

Syntax

public final void notifyPaletteChange()

Remarks

A call to this method results in an internal call to this object's onNewPalette handler.


 Form.onActivate

Form.onActivate

Triggers the activate event.

Syntax

protected void onActivate( Event e )

Parameters

e

An Event object that provides the event data.

Remarks

The activate event occurs when the form is activated.

See Also addOnActivate, removeOnActivate


 Form.onClosed

Form.onClosed

Triggers the closed event.

Syntax

protected void onClosed( Event e )

Parameters

e

An Event object that provides the event data.

Remarks

The closed event occurs when the form is closed.

See Also addOnClosed, removeOnClosed


 Form.onClosing

Form.onClosing

Triggers the closing event.

Syntax

protected void onClosing( CancelEvent e )

Parameters

e

A CancelEvent object that provides the event data.

Remarks

A closing event occurs as the form is being closed. If you cancel this event, the form does not close.

See Also addOnClosing, removeOnClosing


 Form.onDeactivate

Form.onDeactivate

Triggers the deactivate event.

Syntax

protected void onDeactivate( Event e )

Parameters

e

An Event object that provides the event data.

Remarks

The deactivate event occurs when the form is deactivated.

See Also addOnDeactivate, removeOnDeactivate


 Form.onInputLangChange

Form.onInputLangChange

Triggers the inputLangChange event.

Syntax

protected void onInputLangChange( InputLangChangeEvent e )

Parameters

e

An InputLangChangeEvent object that provides the event data.

Remarks

The inputLangChange event occurs after the input language has changed for this form. The inputLangChangeRequest event occurs when the user attempts to change the input language for this form.

See Also addOnInputLangChange, removeOnInputLangChange


 Form.onInputLangChangeRequest

Form.onInputLangChangeRequest

Triggers the inputLangChangeRequest event.

Syntax

protected void onInputLangChangeRequest( InputLangChangeRequestEvent e )

Parameters

e

An InputLangChangeRequestEvent object that provides the event data.

Remarks

The inputLangChangeRequest event occurs when the user attempts to change the input language for this form. If the event is canceled, the input language will not change.

See Also addOnInputLangChangeRequest, removeOnInputLangChangeRequest


 Form.onMDIChildActivate

Form.onMDIChildActivate

Triggers the MDIChildActivate event.

Syntax

protected void onMDIChildActivate( Form form )

protected void onMDIChildActivate( Event e )

Parameters

form

A Form object that identifies the form that is being activated.

e

An Event object that provides the event data.

Remarks

The MDIChildActivate event occurs when an MDI child form is activated.

When overriding onMDIChildActivate, be sure to call super.onMDIChildActivate.

See Also addOnMDIChildActivate, removeOnMDIChildActivate


 Form.onMenuComplete

Form.onMenuComplete

Triggers the menuComplete event.

Syntax

public final void onMenuComplete( Event e )

Parameters

e

An Event object that provides the event data.

Remarks

The menuComplete event occurs when the form's main menu loses the input focus.

See Also addOnMenuComplete, removeOnMenuComplete


 Form.onMenuStart

Form.onMenuStart

Triggers the menuStart event.

Syntax

public final void onMenuStart( Event e )

Parameters

e

An Event object that provides the event data.

Remarks

The menuStart event occurs when the form's main menu receives the input focus.

See Also addOnMenuStart, removeOnMenuStart


 Form.onNewPalette

Form.onNewPalette

Called by a child control to indicate that the palette needs to be rendered.

Syntax

protected boolean onNewPalette( boolean fForceBackground )

Parameters

fForceBackground

If set to true, the palette is rendered. Otherwise, the palette is rendered only when this form has the input focus.

Remarks

When a child control's palette is changed, the control calls the notifyPaletteChanged method. This class's implementation calls the onNewPaletteHandler, passing in true.

See Also notifyPaletteChange


 Form.pointToScreen

Form.pointToScreen

Retrieves the screen coordinates for a specified location.

Syntax

public Point pointToScreen( Point p )

Parameters

p

A Point object for which to return screen coordinates.

Return Value

Returns a Point object that contains the screen coordinates.


 Form.propertyChanged

Form.propertyChanged

Called when a control property changes.

Syntax

protected void propertyChanged( int property )

Parameters

property

Identifies the property that changed. For a list of values for this parameter, see the Control class documentation.

Remarks

Classes that extend Form can override this method to modify the way in which the class responds to a change in form properties. A subclass of the Form class must call the parent class' implementation of this method within its propertyChanged override.


 Form.rectToClient

Form.rectToClient

Retrieves the specified screen rectangle in client coordinates.

Syntax

public Rectangle rectToClient( Rectangle r )

Parameters

r

A Rectangle object that specifies the screen coordinates to convert.

Return Value

Returns a Rectangle object that specifies the client coordinates for the specified rectangle.


 Form.rectToScreen

Form.rectToScreen

Retrieves the screen coordinates for the specified client rectangle.

Syntax

public Rectangle rectToScreen( Rectangle r )

Parameters

r

A Rectangle object that specifies the client rectangle.

Return Value

Returns a Rectangle object that specifies the screen coordinates.


 Form.removeOnActivate

Form.removeOnActivate

Removes the delegate that is assigned to the activate event.

Syntax

public final void removeOnActivate( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnActivate, onActivate


 Form.removeOnClosed

Form.removeOnClosed

Removes the delegate that is assigned to the closed event.

Syntax

public final void removeOnClosed( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnClosed, onClosed


 Form.removeOnClosing

Form.removeOnClosing

Removes the delegate that is assigned to the closing event.

Syntax

public final void removeOnClosing( CancelEventHandler value )

Parameters

value

The CancelEventHandler delegate to be removed.

Remarks

A closing event occurs as the form is being closed. If you cancel this event, the form does not close.

See Also addOnClosing, onClosing


 Form.removeOnDeactivate

Form.removeOnDeactivate

Removes the delegate that is assigned to the deactivate event.

Syntax

public final void removeOnDeactivate( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnDeactivate, onDeactivate


 Form.removeOnInputLangChange

Form.removeOnInputLangChange

Removes the delegate that is assigned to the inputLangChange event.

Syntax

public void removeOnInputLangChange( InputLangChangeEventHandler value )

Parameters

value

The InputLangChangeEventHandler delegate to be removed.

See Also addOnInputLangChange, onInputLangChange


 Form.removeOnInputLangChangeRequest

Form.removeOnInputLangChangeRequest

Removes the delegate that is assigned to the inputLangChangeRequest event.

Syntax

public final void removeOnInputLangChangeRequest( InputLangChangeRequestEventHandler value )

Parameters

value

The InputLangChangeRequestEventHandler delegate to be removed.

See Also addOnInputLangChangeRequest, onInputLangChangeRequest


 Form.removeOnMDIChildActivate

Form.removeOnMDIChildActivate

Removes the delegate that is assigned to the MDIChildActivate event.

Syntax

public final void removeOnMDIChildActivate( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnMDIChildActivate, onMDIChildActivate


 Form.removeOnMenuComplete

Form.removeOnMenuComplete

Removes the delegate that is assigned to the menuComplete event.

Syntax

public final void removeOnMenuComplete( EventHandle value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnMenuStart, onMenuStart


 Form.removeOnMenuStart

Form.removeOnMenuStart

Removes the delegate that is assigned to the menuStart event.

Syntax

public final void removeOnMenuStart( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnMenuStart, onMenuStart


 Form.removeOwnedForm

Form.removeOwnedForm

Removes a form from this Form object's internal list of owned forms.

Syntax

public final void removeOwnedForm( Form ownedForm )

Parameters

ownedForm

A Form object that specifies the form to remove from the list.

Remarks

After a form is removed from another form's ownership list, a call to the removed form's getOwner method returns null.

See Also addOwnedForm


 Form.setAcceptButton

Form.setAcceptButton

Sets the accept button for this form.

Syntax

public final void setAcceptButton( IButtonControl button )

Parameters

button

The control that is the accept button for this form.

Remarks

The accept button designates a form control that is clicked when the user presses the ENTER key.

See Also getAcceptButton


 Form.setActiveControl

Form.setActiveControl

Sets the the input focus to the specified control.

Syntax

public final void setActiveControl( Control value )

Parameters

value

A Control object that specifies the control which to give the input focus.

Remarks

When you call this method, the control specified in the value parameter becomes the active control on the form, and receives the input focus, provided that the form itself has been activated. If the form is inactive, the control does not receive input focus until the form is activated. If you want to respond specifically to the activation or deactivation of a form, you must add activate and deactivate event handlers to your form-derived class.

When the control or a child of the control becomes the active control, an enter event is triggered for that control. When the control loses focus, the control's leave event is triggered.

See Also getActiveControl


 Form.setAutoScale

Form.setAutoScale

Sets the autoscaling on this form.

Syntax

public final void setAutoScale( boolean value )

Parameters

value

Set to true to turn on autoscaling; otherwise, set to false.

Remarks

The ability of a form to scale automatically enables the form to resize to accommodate international systems and those that use Large Fonts.

See Also getAutoScale


 Form.setAutoScaleBaseSize

Form.setAutoScaleBaseSize

Sets the base size used for autoscaling when the form is created.

Syntax

public final void setAutoScaleBaseSize( int value )

Parameters

value

The base size used for autoscaling.

Remarks

The value specified in value is used at form-display time to compute the scaling factor for the form. This value is used when the form is initially created, and once set, cannot be changed.

See Also getAutoScaleBaseSize, setAutoScale


 Form.setAutoScroll

Form.setAutoScroll

Specifies whether the form implements autoscrolling.

Syntax

public final void setAutoScroll( boolean value )

Parameters

value

Set to true to enable the form to autoscroll; otherwise, set to false.

Remarks

If value is set to true, scroll bars are displayed on the form if any controls are located outside the form's client region. Additionally, when autoscrolling is on, the client area of the form automatically scrolls to make the control that has input focus visible.

See Also getAutoScroll, setAutoScrollMargin


 Form.setAutoScrollMargin

Form.setAutoScrollMargin

Sets the width and height of the autoscroll margin.

Syntax

public final void setAutoScrollMargin( Point value )

Parameters

value

A Point object that specifies the width and height of the autoscroll margin.

Remarks

The autoscroll margins define the width and height of the border around each control. This border is used to determine when scroll bars are needed on the form and where to scroll to when a control is selected.

See Also getAutoScrollMargin, setAutoScroll


 Form.setAutoScrollPosition

Form.setAutoScrollPosition

Sets the autoscroll position that is used when the form is created.

Syntax

public final void setAutoScrollPosition( Point value )

Parameters

value

A Point object that specifies the autoscroll position.

Remarks

Once the form has been created, the autoscroll position cannot be changed.


 Form.setBorderStyle

Form.setBorderStyle

Sets the border style for the form.

Syntax

public final void setBorderStyle( int borderStyle )

Parameters

borderStyle

The border style for the form. This value must be one of the enumeration constants defined in the FormBorderStyle class.

See Also getBorderStyle


 Form.setCancelButton

Form.setCancelButton

Sets the cancel button for the form.

Syntax

public final void setCancelButton( IButtonControl button )

Parameters

button

The control that represents the form's cancel button.

Remarks

The cancel button designates the control on a form that is clicked when the user presses the ESC key.

See Also getCancelButton


 Form.setControlBox

Form.setControlBox

Specifies whether a control box is to be displayed on this form.

Syntax

public final void setControlBox( boolean controlBox )

Parameters

controlBox

Set to true to display the control box; otherwise, set to false.

Remarks

A control box refers to an icon that appears in the upper-left corner of the form. The control box displays the system menu when clicked.

See Also getControlBox


 Form.setDesktopBounds

Form.setDesktopBounds

Sets the bounds of the form in desktop coordinates.

Syntax

public final void setDesktopBounds( Rectangle bounds )

public final void setDesktopBounds( int x, int y, int width, int height )

Parameters

bounds

A Rectangle object that specifies the bounds for the form.

x

The x-coordinate of the form's location.

y

The y-coordinate of the form's location.

width

The width of the form.

height

The height of the form.

Remarks

Desktop coordinates are based on the working area of the screen, which excludes the taskbar.

See Also setDesktopLocation


 Form.setDesktopLocation

Form.setDesktopLocation

Sets the location of the form in desktop coordinates.

Syntax

public final void setDesktopLocation( Point loc )

public final void setDesktopLocation( int x, int y )

Parameters

loc

A Point object that specifies the location for the form.

x

The x-coordinate for the form.

y

The y-coordinate for the form.

See Also setDesktopBounds


 Form.setDialogResult

Form.setDialogResult

Sets the value to be returned from the form when it is displayed as a modal dialog.

Syntax

public final void setDialogResult( int value )

Parameters

value

The value to return.

Remarks

Calling this method sets the value of the dialog result, closes the modal dialog, and returns control to the calling form.

See Also getDialogResult, showDialog


 Form.setHelpButton

Form.setHelpButton

Specifies whether a "What's This?" help icon should be displayed in the form's caption bar.

Syntax

public final void setHelpButton( boolean helpButton )

Parameters

helpButton

Set to true to display the button; otherwise, set to false.

See Also getHelpButton


 Form.setIcon

Form.setIcon

Sets the icon to be displayed in the caption bar of the form.

Syntax

public final void setIcon( Icon icon )

Parameters

icon

An Icon object that specifies the icon to display.

See Also getIcon


 Form.setIsMDIContainer

Form.setIsMDIContainer

Specifies whether this form is an MDI container.

Syntax

public final void setIsMDIContainer( boolean value )

Parameters

value

Set to true to make this form an MDI container; otherwise, set to false.

See Also getIsMDIContainer


 Form.setKeyPreview

Form.setKeyPreview

Specifies whether the form should receive key events for all contained controls before the control receives them.

Syntax

public final void setKeyPreview( boolean keyPreview )

Parameters

keyPreview

Set to true if you want to form to receive its child controls key events before the child receives them; otherwise, set to false.

See Also getKeyPreview


 Form.setMaximizeBox

Form.setMaximizeBox

Specifies whether a maximize button should be displayed in this form's caption bar.

Syntax

public final void setMaximizeBox( boolean maxButton )

Parameters

maxButton

Set to true to display the maximize button; otherwise, set to false.

See Also getMaximizeBox


 Form.setMDIParent

Form.setMDIParent

Sets the MDI parent for this form.

Syntax

public final void setMDIParent( Form form )

Parameters

form

A Form object that specifies the form to make the parent of this one.

Exceptions

WFCException thrown if the Form object identified by the form parameter is not marked as an MDI container. To identify a form as an MDI container, use the setIsMDIContainer method.

See Also getMDIParent


 Form.setMenu

Form.setMenu

Sets the main menu for this form.

Syntax

public final void setMenu( MainMenu value )

Parameters

value

A MainMenu object that specifies the menu to use for this form.

See Also getMenu


 Form.setMinimizeBox

Form.setMinimizeBox

Specifies whether a minimize button should be displayed in the form's caption bar.

Syntax

public final void setMinimizeBox( boolean minButton )

Parameters

minButton

Set to true to display the minimize button; otherwise, set to false.

See Also getMinimizeBox


 Form.setNewControls

Form.setNewControls

Arranges an array of controls on a form.

Syntax

public void setNewControls( Control[] ctls )

Parameters

ctls

An array of Control objects to arrange on this form.


 Form.setOwner

Form.setOwner

Sets the owner for this form.

Syntax

public final void setOwner( Form owner )

Parameters

owner

A Form object that identifies the new owner for this form.

Remarks

A call to this method is identical to calling the owner form's addOwnedForm method, specifying this form object as a parameter.

See Also getOwner, removeOwnedForm


 Form.setPaletteMode

Form.setPaletteMode

Specifies the palette mode for this form.

Syntax

public final void setPaletteMode( int paletteMode )

Parameters

paletteMode

The palette mode for this form. This value must be one of the enumeration constants defined in the FormPaletteMode class.

Exceptions

WFCInvalidArgumentException thrown if the paletteMode parameter is not a valid member of the FormPaletteMode class.

Remarks

The valid values for paletteMode parameter are FormPaletteMode.HALFTONE, FormPaletteMode.NONE, and FormPaletteMode.USE_CONTROL.

See Also getPaletteMode


 Form.setPaletteSource

Form.setPaletteSource

Specifies the source for this form's palette.

Syntax

public final void setPaletteSource( Control paletteSource )

Parameters

paletteSource

A Control object that specifies the control to use as the source of this form's palette.

Remarks

Unless the form's palette mode is set to FormPaletteMode.USE_CONTROL, this method has no effect.

See Also getPaletteSource, setPaletteMode, FormPaletteMode


 Form.setShowInTaskbar

Form.setShowInTaskbar

Specifies whether this form's icon should be displayed in the Windows taskbar.

Syntax

public final void setShowInTaskbar( boolean showInTaskbar )

Parameters

showInTaskbar

Set to true to display this form's icon in the taskbar; otherwise, set to false.

See Also getShowInTaskbar


 Form.setStartPosition

Form.setStartPosition

Specifies the initial position of this form.

Syntax

public final void setStartPosition( int startPosition )

Parameters

startPosition

The initial position of the form. This value must be one of the enumeration constants defined in the FormStartPosition class.

Remarks

The valid values for the startPosition parameter are FormStartPosition.MANUAL, FormStartPosition.WINDOWS_DEFAULT_LOCATION, FormStartPosition.WINDOWS_DEFAULT_BOUNDS, and FormStartPosition.CENTER_SCREEN.

See Also getStartPosition


 Form.setVisible

Form.setVisible

Specifies whether this form is visible.

Syntax

public void setVisible( boolean value )

Parameters

value

Set to true to make the form visible; otherwise, set to false.

Remarks

By default, Form objects are visible.


 Form.setWindowState

Form.setWindowState

Specifies the window state for this form.

Syntax

public final void setWindowState( int windowState )

Parameters

windowState

The window state for this form. This value must be one of the enumeration constants defined in the FormWindowState class.

Remarks

The following constants are defined in the FormWindowState class: FormWindowState.NORMAL, FormWindowState.MAXIMIZED, and FormWindowState.MINIMIZED.

See Also getWindowState


 Form.shouldPersistAutoScrollPosition

Form.shouldPersistAutoScrollPosition

Retrieves a boolean value that indicates whether the autoscroll position for this form should be persisted.

Syntax

public boolean shouldPersistAutoScrollPosition()

Return Value

Returns true if the form should persist the autoscroll position; otherwise, returns false.

Remarks

If the form's autoscroll property is set to false or the current scroll position is zero, this method returns false.


 Form.showDialog

Form.showDialog

Displays this form as a modal dialog.

Syntax

public final int showDialog()

public final int showDialog( Form owner )

Parameters

owner

A Form object that identifies the owner of the dialog.

Return Value

Returns the dialog result. This value equates to one of the enumeration constants defined in the DialogResult class.


 Form.wndProc

Form.wndProc

Encapsulates the base window procedure for this class.

Syntax

protected void wndProc( Message m )

Parameters

m

A Message object that specifies the message posted to this window.

Remarks

Classes that extend the Form class can override the wndProc method to modify the default handling of standard Windows messages.


FormBorderStyle Class

Defines enumeration constants that represent the border styles of a form.

Enum
  |
  +--BorderStyle
    |
    +--FormBorderStyle

package com.ms.wfc.ui

public class FormBorderStyle
extends BorderStyle

Remarks

To set the border style on a form, use the Form object's setBorderStyle method.


 FormBorderStyle Methods

FormBorderStyle Methods

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value designates a valid FormBorderStyle constant.


 FormBorderStyle.valid

FormBorderStyle.valid

Retrieves a boolean value that indicates whether a specified value designates a valid FormBorderStyle constant.

Syntax

public static boolean valid( int value )

Parameters

value

A value to be compared to those defined in this class.

Return Value

Returns true if the value is valid; otherwise, returns false.


 FormBorderStyle Fields

FormBorderStyle Fields

Fields | Description
FIXED_DIALOG | Represents a thick, fixed dialog-style border.
FIXED_TOOLWINDOW | Represents a nonresizable tool window border.
SIZABLE | Represents a fully resizable border.
SIZABLE_TOOLWINDOW | Represents a resizable tool window border.


 FormBorderStyle.FIXED_DIALOG

FormBorderStyle.FIXED_DIALOG

Represents a thick, fixed dialog-style border.

Syntax

public static final int FIXED_DIALOG;


 FormBorderStyle.FIXED_TOOLWINDOW

FormBorderStyle.FIXED_TOOLWINDOW

Represents a nonresizable tool window border.

Syntax

public static final int FIXED_TOOLWINDOW;


 FormBorderStyle.SIZABLE

FormBorderStyle.SIZABLE

Represents a fully resizable border.

Syntax

public static final int SIZABLE;


 FormBorderStyle.SIZABLE_TOOLWINDOW

FormBorderStyle.SIZABLE_TOOLWINDOW

Represents a resizable tool window border.

Syntax

public static final int SIZABLE_TOOLWINDOW;


FormPaletteMode Class

Defines the palette modes supported by a WFC form on 256-color systems.

Enum
  |
  +--FormPaletteMode

package com.ms.wfc.ui

public class FormPaletteMode
extends Enum

Remarks

The FormPaletteMode class defines the constants that indicate the palette mode for a Form object. To set the palette mode on a form, call the Form object's setPaletteMode method, specifying one of the constants defined in this class as a parameter.


 FormPaletteMode Methods

FormPaletteMode Methods

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value designates a valid FormPaletteMode constant.


 FormPaletteMode.valid

FormPaletteMode.valid

Retrieves a boolean value that indicates whether a specified value designates a valid FormPaletteMode constant.

Syntax

public static boolean valid( int value )

Parameters

value

A value to be compared to those defined in this class.

Return Value

Returns true if the value is valid; otherwise, returns false.


 FormPaletteMode Fields

FormPaletteMode Fields

Fields | Description
HALFTONE | Indicates that a halftone palette should be used as the form's palette.
NONE | Indicates that no palette should be used.
USE_CONTROL | Indicates that a control should be used as the palette source.


 FormPaletteMode.HALFTONE

FormPaletteMode.HALFTONE

Indicates that a halftone palette should be used as the form's palette.

Syntax

public static final int HALFTONE;


 FormPaletteMode.NONE

FormPaletteMode.NONE

Indicates that no palette should be used.

Syntax

public static final int NONE;


 FormPaletteMode.USE_CONTROL

FormPaletteMode.USE_CONTROL

Indicates that a control should be used as the palette source.

Syntax

public static final int USE_CONTROL;

Remarks

If you call the Form object's setPaletteMode method and specify this parameter, you should also use the Form object's setPaletteSource method to specify which control to use as the form's palette source.


FormStartPosition Class

Defines constant values that describe the initial position of a form.

Enum
  |
  +--FormStartPosition

package com.ms.wfc.ui

public class FormStartPosition
extends Enum

Remarks

The position of a form is determined by passing one of the constants defined in this class to the Form class' setStartPosition method.


 FormStartPosition Methods

FormStartPosition Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 FormStartPosition.valid

FormStartPosition.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

A value to be compared to those defined in this class.

Return Value

Returns true if the value is valid; otherwise, returns false.


 FormStartPosition Fields

FormStartPosition Fields

Fields | Description
CENTER_SCREEN | Specifies that the form will be centered on the current primary monitor, and that its dimensions are determined by the form's size.
MANUAL | Specifies that the location and size of the form will determine the starting position.
WINDOWS_DEFAULT_BOUNDS | Specifies that the form will be positioned with the Windows default location and bounds.
WINDOWS_DEFAULT_LOCATION | Specifies that the form will be positioned at the Windows default location with its dimensions determined by the form's size.


 FormStartPosition.CENTER_SCREEN

FormStartPosition.CENTER_SCREEN

Specifies that the form will be centered on the current primary monitor, and that its dimensions are determined by the form's size.

Syntax

public static final int CENTER_SCREEN;


 FormStartPosition.MANUAL

FormStartPosition.MANUAL

Specifies that the location and size of the form will determine the starting position.

Syntax

public static final int MANUAL;


 FormStartPosition.WINDOWS_DEFAULT_BOUNDS

FormStartPosition.WINDOWS_DEFAULT_BOUNDS

Specifies that the form will be positioned with the Windows default location and bounds.

Syntax

public static final int WINDOWS_DEFAULT_BOUNDS;


 FormStartPosition.WINDOWS_DEFAULT_LOCATION

FormStartPosition.WINDOWS_DEFAULT_LOCATION

Specifies that the form will be positioned at the Windows default location with its dimensions determined by the form's size.

Syntax

public static final int WINDOWS_DEFAULT_LOCATION;


FormWindowState Class

Defines a group of constants that specify the state of a window.

Enum
  |
  +--FormWindowState

package com.ms.wfc.ui

public class FormWindowState
extends Enum

Remarks

The values in this class are passed to the Form class's setWindowState method to determine the state of a form.


 FormWindowState Methods

FormWindowState Methods

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value designates a valid FormWindowState constant.


 FormWindowState.valid

FormWindowState.valid

Retrieves a boolean value that indicates whether a specified value designates a valid FormWindowState constant.

Syntax

public static boolean valid( int value )

Parameters

value

A value to be compared to those defined in this class.

Return Value

Returns true if the value is valid; otherwise, returns false.


 FormWindowState Fields

FormWindowState Fields

Fields | Description
MAXIMIZED | Represents a maximized window.
MINIMIZED | Represents a minimized window.
NORMAL | Represents a normally sized window.


 FormWindowState.MAXIMIZED

FormWindowState.MAXIMIZED

Represents a maximized window.

Syntax

public static final int MAXIMIZED;


 FormWindowState.MINIMIZED

FormWindowState.MINIMIZED

Represents a minimized window.

Syntax

public static final int MINIMIZED;


 FormWindowState.NORMAL

FormWindowState.NORMAL

Represents a normally sized window.

Syntax

public static final int NORMAL;


GiveFeedbackEvent Class

Provides data for the giveFeedBack event of the Control object.

Event
  |
  +--GiveFeedbackEvent

package com.ms.wfc.ui

public class GiveFeedbackEvent
extends Event

Remarks

The giveFeedBack event occurs during a drag operation. It allows the source of a drag event to modify the mouse pointer to give the user visual feedback during a drag-and-drop operation. A GiveFeedbackEvent object specifies the type of drag-and-drop operation and whether default cursors are used.

For information about the WFC event model, see Handling Events in WFC.


 GiveFeedbackEvent Methods

GiveFeedbackEvent Methods

Constructors | Description
GiveFeedbackEvent | Creates a GiveFeedbackEvent object.


 GiveFeedbackEvent.GiveFeedbackEvent

GiveFeedbackEvent.GiveFeedbackEvent

Creates a GiveFeedbackEvent object.

Syntax

public GiveFeedbackEvent( int effect, boolean useDefaultCursors )

Parameters

effect

The type of drag-and-drop operation. Possible values are obtained by applying the bitwise OR operation (|) to the constants defined in the DragDropEffect class.

useDefaultCursors

Set to true if default cursors are used; otherwise, set to false.


 GiveFeedbackEvent Fields

GiveFeedbackEvent Fields

Fields | Description
effect | Specifies the type of drag-and-drop operation.
useDefaultCursors | Specifies whether default cursors are used.


 GiveFeedbackEvent.effect

GiveFeedbackEvent.effect

Specifies the type of drag-and-drop operation.

Syntax

public final int effect;

Remarks

Possible values are obtained by applying the bitwise OR operation (|) to the constants defined in the DragDropEffect class.


 GiveFeedbackEvent.useDefaultCursors

GiveFeedbackEvent.useDefaultCursors

Specifies whether default cursors are used.

Syntax

public boolean useDefaultCursors;


GiveFeedbackEventHandler Delegate

Identifies the method handling the giveFeedback event of a Control control.

package com.ms.wfc.ui

public multicast delegate
void GiveFeedbackEventHandler( Object sender, GiveFeedbackEvent e );

Remarks

The syntax of the GiveFeedbackEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a GiveFeedbackEvent object that provides the event data.

When you create a GiveFeedbackEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC.


Graphics Class

Encapsulates a Win32 device context (DC) and the drawing operations that are typically performed on a DC.

package com.ms.wfc.ui

public class Graphics

Remarks

These operations include the drawing of standard shapes, such as pies and arcs, as well as the drawing of Windows controls, such as buttons and check boxes. The Graphics object automatically performs garbage collection, freeing the resources allocated for various drawing objects. In addition, you can call the object's dispose method to enforce the cleanup of these resources. A Graphics object that is connected to a Windows control is valid only for the duration of the current event or message. For example, if a control processes its paint event, the Graphics object that is passed as a parameter to paint is valid only until paint returns.


 Graphics Methods

Graphics Methods

Constructors | Description
Graphics | Creates a Graphics object.

Methods | Description
clearClip | Clears the object's clipping rectangle.
clearRect | Clears the specified rectangle by filling with the background color for the Graphics object.
createScreenGraphics | Creates a Graphics object that can draw anywhere on the display.
destroyHandle | Called when the Graphics object needs to destroy the underlying device context handle (HDC).
dispose | Frees all resources allocated by this object.
drawAngleArc | Draws a line segment and an arc.
drawArc | Draws an elliptical arc in the specified bounding rectangle.
drawBezier | Draws one or more cubic Bezier curves by using the endpoints and control points specified by the array of Point objects.
drawBorder3D | Draws a three-dimensional style border around the specified rectangle.
drawButton | Draws a button control in the specified rectangle.
drawCaptionButton | Draws a Win32 window caption button in the specified rectangle.
drawCheckBox | Draws a Win32 CheckBox control in the specified rectangle.
drawChord | Draws a chord.
drawComboButton | Draws the drop-down button of a Win32 combo box in the specified rectangle.
drawEllipse | Draws an ellipse in the specified bounding rectangle.
drawFocusRect | Draws a Windows focus rectangle, a dotted rectangle that Windows uses to indicate that a specified control has the input focus.
drawImage | Draws an image at the specified location.
drawLine | Draws a line from one point to another using the current pen.
drawLines | Draws a series of connected lines based on an array of points, and applies a raster operation to the drawing.
drawMenuGlyph | Draws a menu glyph for a Win32 menu in the specified rectangle.
drawPie | Draws a pie-shaped wedge bounded by the intersection of an ellipse and two radials.
drawPolygon | Draws a polygon based on a specified array of vertices.
drawRadioButton | Draws a Win32 radio button in the specified rectangle.
drawRect | Draws a rectangle using the specified coordinates.
drawRoundedRect | Draws a rectangle with rounded corners using the current pen and fill brush.
drawScrollButton | Draws a button for a Win32 scroll bar.
drawSizeGrip | Draws a sizing grip at the specified location.
drawString | Draws a string at the specified point or within the specified area.
excludeFromClip | Removes the specified rectangle from the current clipping region.
fill | Fills a specified area of the display with the current or specified brush.
finalize | Disposes of the resources allocated by this object.
floodFill | Fills a specified area with the current brush.
getBackColor | Retrieves the current background color.
getBrush | Retrieves the current brush.
getBrushOrigin | Retrieves the current brush origin.
getClip | Retrieves the current clipping region for this object.
getCoordinateSystem | Retrieves the coordinate system that this object is currently using.
getDeviceOrigin | Retrieves the device origin for a user-defined coordinate system.
getDevicePoint | Converts the specified coordinates to device coordinates.
getDeviceScale | Retrieves the current device scale for a user-defined coordinate system.
getFont | Retrieves the current font for this object.
getFontDescriptors | Retrieves an array of FontDescriptor objects, which contains an entry for each font that matches the specified face name.
getHandle | Retrieves the Win32 device context handle (HDC) for this Graphics object.
getLogicalPoint | Converts the specified point to logical coordinates.
getLogicalSizeX | Retrieves the number of logical units that make up the specified number of inches.
getLogicalSizeY | Retrieves the number of logical units that make up the specified number of inches.
getNearestColor | Retrieves the closest solid color that the hardware will use for the specified color.
getOpaque | Retrieves the current fill mode on the Graphics object.
getPageOrigin | Retrieves the page origin for a user-defined coordinate system.
getPageScale | Retrieves the current page scale for a user-defined coordinate system.
getPen | Retrieves the pen associated with the Graphics object.
getPhysicalSizeX | Retrieves, in inches, the physical size for a specified number of horizontal logical coordinates.
getPhysicalSizeY | Retrieves, in inches, the physical size for a specified number of vertical logical coordinates.
getPixel | Retrieves the color of the specified pixel.
getTextColor | Retrieves the color used to display text in the Graphics object's bounding rectangle.
getTextSize | Retrieves the area required to display the specified text string using the current font settings.
getTextSpace | Retrieves the amount of extra space that will be used between characters when drawing text.
intersectWithClip | Sets the clipping region for this object to include the area of this object's clipping region that intersects with a specified rectangle or region.
invert | Inverts the pixels in the specified rectangle.
renderPalette | Renders the specified palette to this Graphics object.
scroll | Scrolls an area of the Graphics object.
setBackColor | Sets the background color for the Graphics object. After you set the background color for the Graphics object, that color is used to fill empty regions in the object's bounding rectangle.
setBrush | Associates a brush with this Graphics object.
setBrushOrigin | Sets the brush origin for this Graphics object. The default coordinates for the brush origin are 0,0.
setClip | Sets the clipping region for this Graphics object to the specified rectangle.
setCoordinateOrigin | Sets up the origin for a user-defined coordinate system.
setCoordinateScale | Sets up the coordinate scale for a user-defined coordinate system.
setCoordinateSystem | Sets the coordinate system for this Graphics object.
setFont | Associates a font with the Graphics object.
setHandle | This method is called when the Graphics object initializes a handle to device context (HDC) at object startup.
setOpaque | Sets the background fill mode for the Graphics object.
setPen | Associates a Pen object with the Graphics object.
setPixel | Sets a pixel to the specified color.
setTextColor | Specifies the color that will be used to draw text.
setTextSpace | Sets the amount of extra space to be used between characters when drawing text.


 Graphics.clearClip

Graphics.clearClip

Clears the object's clipping rectangle.

Syntax

public final void clearClip()

Remarks

The clipping rectangle refers to the rectangular area of the form or control in which graphical output occurs.

This method resets any clipping that has been set through a previous call to setClip. In addition, if the Graphics object is created with a specific clipping rectangle, a call to this method resets clipping to the original rectangle.

See Also getClip, excludeFromClip, intersectWithClip


 Graphics.clearRect

Graphics.clearRect

Clears the specified rectangle by filling with the background color for the Graphics object.

Syntax

public final void clearRect( Rectangle rect )

public final void clearRect( int x, int y, int width, int height )

Parameters

rect

A Rectangle object that specifies the area to clear.

x

The x-coordinate of the rectangular area to clear.

y

The y-coordinate of the rectangular area to clear.

width

The width of the area to clear.

height

The height of the area to clear.

Remarks

This method, though very fast, always fills the background with a solid color. If you need dithered color support, use the fill method.

See Also setBackColor


 Graphics.createScreenGraphics

Graphics.createScreenGraphics

Creates a Graphics object that can draw anywhere on the display.

Syntax

public static final Graphics createScreenGraphics()

Return Value

A Graphics object that encompasses the entire display.

Remarks

Because you can use screen graphics to overwrite information in another application's window, you should use screen Graphics objects carefully.


 Graphics.destroyHandle

Graphics.destroyHandle

Called when the Graphics object needs to destroy the underlying device context handle (HDC).

Syntax

protected void destroyHandle()

Remarks

The Graphics class's implementation of destroyHandle frees only handles owned by the Graphics object. If you created the Graphics object based on a previously allocated handle, this handle is not freed by the object's call to destroyHandle; you are responsible for freeing these handles.

However, you can override this method in your Graphics-derived class to define your own custom semantics for handle creation and destruction.


 Graphics.dispose

Graphics.dispose

Frees all resources allocated by this object.

Syntax

public void dispose()

Remarks

The Graphics object has function-level scope. When the object goes out of scope, this method is called automatically.

The dispose method frees only the resources that it allocates. Thus, if you create a Graphics object based on a handle that you have allocated manually, you must manually free this handle.

See Also destroyHandle


 Graphics.drawAngleArc

Graphics.drawAngleArc

Draws a line segment and an arc.

Syntax

public final void drawAngleArc( Point center, int radius, float startAngle, float endAngle )

public final void drawAngleArc( Point center, int radius, float startAngle, float endAngle, RasterOp op )

public final void drawAngleArc( int centerX, int centerY, int radius, float startAngle, float endAngle )

public final void drawAngleArc( int centerX, int centerY, int radius, float startAngle, float endAngle, RasterOp op )

Parameters

center

A Point object that identifies the center of the arc circle.

centerX

The x-coordinate of the center of the circle.

centerY

The y-coordinate of the center of the circle.

radius

The radius of the circle.

startAngle

The start angle, in degrees, relative to the x-axis.

endAngle

The end angle, in degrees, relative to the starting angle.

op

A RasterOp object that describes how to render the arc angle.

Remarks

The line segment that results from a call to this method is drawn from the current pen position to the beginning of the arc.

The arc is drawn along the perimeter of a circle with the specified radius and center. The length of the arc is defined by the specified start and end angles, and the arc's starting point is determined by measuring counterclockwise from the x-axis of the circle by the number of degrees specified in startAngle. Similarly, the ending point is located by measuring counterclockwise from the starting point by the number of degrees specified in endAngle.


 Graphics.drawArc

Graphics.drawArc

Draws an elliptical arc in the specified bounding rectangle.

Syntax

public final void drawArc( Rectangle rect, Point start, Point end )

public final void drawArc( Rectangle rect, Point start, Point end, RasterOp op )

public final void drawArc( int x, int y, int width, int height, int startX, int startY, int endX, int endY )

public final void drawArc( int x, int y, int width, int height, int startX, int startY, int endX, int endY, RasterOp op )

Parameters

rect

A Rectangle object that specifies the bounding rectangle for the ellipse.

start

A Point object that specifies the x and y coordinates for the arc's starting point.

end

A Point object that specifies the x and y coordinates for the arc's ending point.

op

A RasterOp object that describes how to render the arc.

x

The x-coordinate for the arc's bounding rectangle.

y

The y-coordinate for the arc's bounding rectangle.

width

The width of the arc's bounding rectangle.

height

The height of the arc's bounding rectangle.

startX

The x-coordinate for the arc's starting point.

startY

The y-coordinate for the arc's starting point.

endX

The x-coordinate for the arc's ending point.

endY

The y-coordinate for the arc's ending point.

Remarks

The drawArc method centers the arc in the specified bounding rectangle. From the center, the arc extends in the current drawing direction to the specified starting point. Next, the arc declines from the center to the specified ending point. If the starting point and ending point are the same, a complete ellipse is drawn.

The drawArc method always draws the arc counterclockwise.


 Graphics.drawBezier

Graphics.drawBezier

Draws one or more cubic Bezier curves by using the endpoints and control points specified by the array of Point objects.

Syntax

public final void drawBezier( Point[] points )

public final void drawBezier( Point[] points, RasterOp op )

Parameters

points

An array of Point objects that specify the starting, ending, and control points for the Bezier curves.

op

A RasterOp object that describes how to render the Bezier curves.

Remarks

The array in which you describe the Bezier curve that you want to draw must contain at least four elements. The first of these elements describes the first point in the curve, the fourth point describes the last point in the curve, and the second and third members describe the curves control points.

After the fourth member, you must add points in groups of three. The last point in the preceding Bezier curve becomes the first point in the next curve. The last member of the group of three becomes the curves end point, and the first and second members serve as its control points.


 Graphics.drawBorder3D

Graphics.drawBorder3D

Draws a three-dimensional style border around the specified rectangle.

Syntax

public final void drawBorder3D( Rectangle rect )

public final void drawBorder3D( Rectangle rect, int style )

public final void drawBorder3D( Rectangle rect, int style, int sides )

public final void drawBorder3D( int x, int y, int width, int height )

public final void drawBorder3D( int x, int y, int width, int height, int style )

public final void drawBorder3D( int x, int y, int width, int height, int style, int sides )

Parameters

rect

A Rectangle object that specifies the rectangle around which to draw the border.

style

The three-dimensional style to use when drawing the border. This value must be one of the enumeration constants defined in the Border3DStyle class.

sides

The sides of the rectangle you want to draw. This value must be one or more of the values defined in the Border3DSide enumeration.

x

The x-coordinate of the rectangle around which to draw the border.

y

The y-coordinate of the rectangle around which to draw the border.

width

The width of the rectangle around which to draw the border.

height

The height of the rectangle around which to draw the border.

Remarks

If you call this method without specifying a border style, the default three-dimensional style of Border3DStyle.ETCHED is used to draw the border.


 Graphics.drawButton

Graphics.drawButton

Draws a button control in the specified rectangle.

Syntax

public final void drawButton( Rectangle rect, int state )

public final void drawButton( int x, int y, int width, int height, int state )

Parameters

rect

A Rectangle object that specifies the size and position of the button to draw.

x

The x-coordinate of the rectangle in which to draw the button.

y

The y-coordinate of the rectangle in which to draw the button.

width

The width of the button.

height

The height of the button.

state

Specifies the state of the button to draw. This value must be one of the enumeration constants defined in the ButtonState class.

See Also drawCaptionButton, drawCheckBox, drawComboButton, drawMenuGlyph, drawRadioButton, drawScrollButton, drawSizeGrip


 Graphics.drawCaptionButton

Graphics.drawCaptionButton

Draws a Win32 window caption button in the specified rectangle.

Syntax

public final void drawCaptionButton( Rectangle rect, int button, int state )

public final void drawCaptionButton( int x, int y, int width, int height, int button, int state )

Parameters

rect

A Rectangle object that specifies the rectangle in which to draw the button.

button

A constant that identifies the caption button to draw. This value must be one of the enumeration constants defined in the CaptionButton class.

state

A constant that specifies the button state. This value must be one of the enumeration constants defined in the ButtonState class.

x

The x-coordinate of the upper-left corner of the drawing rectangle.

y

The y-coordinate of the upper-left corner of the drawing rectangle.

width

The width of the button.

height

The height of the button.

See Also drawButton, drawCheckBox, drawComboButton, drawMenuGlyph, drawRadioButton, drawScrollButton, drawSizeGrip


 Graphics.drawCheckBox

Graphics.drawCheckBox

Draws a Win32 CheckBox control in the specified rectangle.

Syntax

public final void drawCheckBox( Rectangle rect, int state )

public final void drawCheckBox( int x, int y, int width, int height, int state )

Parameters

rect

A Rectangle object that specifies the coordinates of the button to draw.

state

One or more ButtonState flags that determine how to draw the button.

x

The x-coordinate of the upper-left corner of the drawing rectangle.

y

The y-coordinate of the upper-left corner of the drawing rectangle.

width

The width of the button.

height

The height of the button.

See Also drawButton, drawCaptionButton, drawComboButton, drawMenuGlyph, drawRadioButton, drawScrollButton, drawSizeGrip


 Graphics.drawChord

Graphics.drawChord

Draws a chord.

Syntax

public final void drawChord( Rectangle rect, Point start, Point end )

public final void drawChord( Rectangle rect, Point start, Point end, RasterOp op )

public final void drawChord( int x, int y, int width, int height, int startX, int startY, int endX, int endY )

public final void drawChord( int x, int y, int width, int height, int startX, int startY, int endX, int endY, RasterOp op )

Parameters

rect

A Rectangle object that specifies the bounding rectangle for the ellipse.

start

A Point object that specifies the starting point for the chord.

end

A Point object that specifies the ending point for the chord.

op

A RasterOp object that describes how to draw the chord.

x

The x-coordinate of the bounding rectangle for the ellipse.

y

The y-coordinate of the bounding rectangle for the ellipse.

width

The width of the bounding rectangle for the ellipse.

height

The height of the bounding rectangle for the ellipse.

startX

The x-coordinate for the chord's starting point.

startY

The y-coordinate for the chord's starting point.

endX

The x-coordinate for the chord's ending point.

endY

The y-coordinate for the chord's ending point.

Remarks

A chord is a region bounded by the intersection of an ellipse and a line segment (this intersection is called a secant. The chord drawn by this method is outlined using the current pen and is filled using the current brush.

The curve of the chord is defined by an ellipse that fits the specified bounding rectangle. The curve begins at the point at which the ellipse intersects the first radial, and extends counterclockwise to the point at which the ellipse intersects the second radial. (A radial is a lone segment drawn from the center of the ellipse to a specified endpoint on the ellipse).

The chord is closed by drawing a line from the the point at which the first radial and the curve intersect to the point at which the second radial and curve intersect.


 Graphics.drawComboButton

Graphics.drawComboButton

Draws the drop-down button of a Win32 combo box in the specified rectangle.

Syntax

public final void drawComboButton( Rectangle rect, int state )

public final void drawComboButton( int x, int y, int width, int height, int state )

Parameters

rect

A Rectangle object that specifies the coordinates of the button to draw.

state

One or more ButtonState flags that determine how to draw the button.

x

The x-coordinate of the rectangle in which to draw the button.

y

The y-coordinate of the rectangle in which to draw the button.

width

The width of the rectangle in which to draw the button.

height

The height of the rectangle in which to draw the button.

state

One or more flags that determine how to draw the button. This value must be one or more of the enumeration constants defined in the ButtonState class.

See Also drawButton, drawCaptionButton, drawCheckBox, drawMenuGlyph, drawRadioButton, drawScrollButton, drawSizeGrip


 Graphics.drawEllipse

Graphics.drawEllipse

Draws an ellipse in the specified bounding rectangle.

Syntax

public final void drawEllipse( Rectangle rect )

public final void drawEllipse( int x, int y, int width, int height )

public final void drawEllipse( Rectangle rect, RasterOp op )

public final void drawEllipse( int x, int y, int width, int height, RasterOp op )

Parameters

rect

A Rectangle object that specifies the rectangle in which to draw the ellipse.

x

The x-coordinate of the rectangle in which to draw the ellipse.

y

The y-coordinate of the rectangle in which to draw the ellipse.

width

The width of the rectangle in which to draw the ellipse.

height

The height of the rectangle in which to draw the ellipse.

op

A RasterOp object that describes how to draw the ellipse.

Remarks

The ellipse is drawn using the current pen and filled using the current brush.


 Graphics.drawFocusRect

Graphics.drawFocusRect

Draws a Windows focus rectangle, a dotted rectangle that Windows uses to indicate that a specified control has the input focus.

Syntax

public final void drawFocusRect( Rectangle r )

public final void drawFocusRect( int x, int y, int width, int height )

Parameters

r

A Rectangle object that specifies the coordinates of the focus rectangle.

x

The x-coordinate of the focus rectangle.

y

The y-coordinate of the focus rectangle.

width

The width of the focus rectangle.

height

The height of the focus rectangle.


 Graphics.drawImage

Graphics.drawImage

Draws an image at the specified location.

Syntax

public final void drawImage( Image i, Point pt )

public final void drawImage( Image i, int x, int y )

public final void drawImage( Image i, Point pt, RasterOp op )

public final void drawImage( Image i, int x, int y, RasterOp op )

public final void drawImage( Image i, Rectangle r, boolean scale )

public final void drawImage( Image i, int x, int y, int width, int height, boolean scale )

public final void drawImage( Image i, Rectangle r, boolean scale, RasterOp op )

public final void drawImage( Image i, int x, int y, int width, int height, boolean scale, RasterOp op )

public final void drawImage( Image i, Rectangle imageRect, Rectangle targetRect, boolean scale )

public final void drawImage( Image i, Rectangle imageRect, Rectangle targetRect, boolean scale, RasterOp op )

Parameters

i

An Image object that specifies the image to draw.

pt

A Point object that specifies the location at which to draw the image.

x

The x-coordinate of the location at which to draw the image.

y

The y-coordinate of the location at which to draw the image.

width

The width of the rectangle in which to draw the image.

height

The height of the rectangle in which to draw the image.

op

A RasterOp object that specifies how to draw the image.

r

A Rectangle object that specifies the coordinates to which to draw the image.

scale

A boolean value that specifies whether the image should be stretched or shrunk to fit the specified rectangle. If true, the image is stretched or shrunk. If false, the image is cropped.

imageRect

A Rectangle object that specifies the coordinates of the source rectangle in the image.

targetRect

A Rectangle object that specifies the coordinates of the target rectangle.

Remarks

Three factors affect the approach that the drawImage method takes to rendering an image on the display.

The first factor is scale. The scale parameter indicates whether the image should be drawn or stretched to fill a specified rectangle. If this parameter is true, the image is scaled or shrunk, depending on the comparative size of the image and the target rectangle. If this parameter is false, the image is cropped.

The second factor affecting display is the raster operation used to render the image. The value that you specify in the RasterOp object of drawImage causes drawImage to perform one or more logical operations on the image.

The third factor affecting display is bitmap transparency. You determine which colors of a bitmap will be rendered transparent by using the setTransparent method on the Bitmap object.


 Graphics.drawLine

Graphics.drawLine

Draws a line from one point to another using the current pen.

Syntax

public final void drawLine( Point p1, Point p2 )

public final void drawLine( Point p1, Point p2, RasterOp op )

public final void drawLine( int x1, int y1, int x2, int y2 )

public final void drawLine( int x1, int y1, int x2, int y2, RasterOp op )

Parameters

p1

A Point object that specifies the coordinates at which to begin drawing the line.

p2

A Point object that specifies the coordinates at which to stop drawing the line.

x1

The x-coordinate at which to begin drawing the line.

y1

The y-coordinate at which to begin drawing the line.

x2

The x-coordinate at which to stop drawing the line.

y2

The y-coordinate at which to stop drawing the line.

op

A RasterOp object that describes how to draw the line.

See Also drawLines


 Graphics.drawLines

Graphics.drawLines

Draws a series of connected lines based on an array of points, and applies a raster operation to the drawing.

Syntax

public final void drawLines( Point[] points )

public final void drawLines( Point[] points, RasterOp op )

Parameters

points

An array of Point objects that specify the lines to draw.

op

A RasterOp object that describes how to render the points.


 Graphics.drawMenuGlyph

Graphics.drawMenuGlyph

Draws a menu glyph for a Win32 menu in the specified rectangle.

Syntax

public final void drawMenuGlyph( Rectangle rect, int glyph )

public final void drawMenuGlyph( int x, int y, int width, int height, int glyph )

Parameters

rect

A Rectangle object that specifies the glyph coordinates.

x

The x-coordinate of the rectangle in which to draw the glyph.

y

The y-coordinate of the rectangle in which to draw the glyph.

width

The width of the glyph.

height

The height of the glyph.

glyph

A constant that identifies the menu glyph to draw. This value must be one of the enumeration constants defined in the MenuGlyph class.

See Also drawButton, drawCaptionButton, drawCheckBox, drawComboButton, drawRadioButton, drawScrollButton, drawSizeGrip


 Graphics.drawPie

Graphics.drawPie

Draws a pie-shaped wedge bounded by the intersection of an ellipse and two radials.

Syntax

public final void drawPie( Rectangle rect, Point start, Point end )

public final void drawPie( Rectangle rect, Point start, Point end, RasterOp op )

public final void drawPie( int x, int y, int width, int height, int startX, int startY, int endX, int endY )

public final void drawPie( int x, int y, int width, int height, int startX, int startY, int endX, int endY, RasterOp op )

Parameters

rect

A Rectangle object that specifies the bounding rectangle for the ellipse.

x

The x-coordinate of the rectangle in which to draw the ellipse.

y

The y-coordinate of the rectangle in which to draw the ellipse.

width

The width of the rectangle in which to draw the ellipse.

height

The height of the rectangle in which to draw the ellipse.

start

A Point object that specifies the starting point for the pie.

end

A Point object that specifies the ending point for the pie.

startX

The x-coordinate at which to start drawing the pie.

startY

The y-coordinate at which to start drawing the pie.

endX

The x-coordinate at which the pie ends.

endY

The y-coordinate at which the pie ends.

op

A RasterOp object that describes how to render the pie.

Remarks

The pie is outlined using the current pen and is filled using the current brush. The curve of the pie is defined by an ellipse that fits the specified bounding rectangle. The curve begins at the point where the ellipse intersects the first radial and extends counterclockwise to the point at which the ellipse intersects the second radial. (A radial is a line drawn from the center of the ellipse to the specified endpoint on the ellipse.)


 Graphics.drawPolygon

Graphics.drawPolygon

Draws a polygon based on a specified array of vertices.

Syntax

public final void drawPolygon( Point[] vertices )

public final void drawPolygon( Point[] vertices, RasterOp op )

public final void drawPolygon( Point[] vertices, RasterOp op, int fillMode )

Parameters

vertices

An array of Point objects that define the vertices of the polygon. The array must consist of at least two points.

op

A RasterOp object that describes how to render the polygon.

fillMode

The polygon fill mode. This value must be one of the enumeration constants defined in the PolyFillMode class.

Remarks

This array specified by the vertices parameter must contain at least two elements. The polygon is drawn using the current pen and brush and is automatically closed.


 Graphics.drawRadioButton

Graphics.drawRadioButton

Draws a Win32 radio button in the specified rectangle.

Syntax

public final void drawRadioButton( Rectangle rect, int state )

public final void drawRadioButton( int x, int y, int width, int height, int state )

Parameters

rect

A Rectangle object that identifies the area in which to draw the button.

x

The x-coordinate of the upper-left corner of the drawing rectangle.

y

The y-coordinate of the upper-left corner of the drawing rectangle.

width

The width of the button.

height

The height of the button.

state

One or more flags that determine how to draw the button. This value must be one or more of the enumeration constants defined in the ButtonState class

See Also drawButton, drawCaptionButton, drawCheckBox, drawComboButton, drawMenuGlyph, drawScrollButton, drawSizeGrip


 Graphics.drawRect

Graphics.drawRect

Draws a rectangle using the specified coordinates.

Syntax

public final void drawRect( Rectangle rect )

public final void drawRect( int x, int y, int width, int height )

public final void drawRect( Rectangle rect, RasterOp op )

public final void drawRect( int x, int y, int width, int height, RasterOp op )

Parameters

rect

A Rectangle object that specifies the rectangle's coordinates.

x

The x-coordinate of top-left corner of rectangle.

y

The y-coordinate of top -left corner of rectangle.

width

The width of the rectangle.

height

The height of the rectangle.

op

A RasterOp object that describes how to render the rectangle.

Remarks

The rectangle is filled using the current brush, and the current pen is used to draw the rectangle's edge.

See Also drawRoundedRect


 Graphics.drawRoundedRect

Graphics.drawRoundedRect

Draws a rectangle with rounded corners using the current pen and fill brush.

Syntax

public final void drawRoundedRect( Rectangle rect, int radius )

public final void drawRoundedRect( Rectangle rect, int radius, RasterOp op )

public final void drawRoundedRect( int x, int y, int width, int height, int radius )

public final void drawRoundedRect( int x, int y, int width, int height, int radius, RasterOp op )

Parameters

rect

A Rectangle object that identifies the rectangle to draw.

x

The x-coordinate of the rectangle's upper-left corner.

y

The y-coordinate of the rectangle's upper-left corner.

width

The width of the rectangle.

height

The height of the rectangle.

radius

The radius of each of the corners or the rectangle.

op

A RasterOp object that describes how to render the rectangle.

See Also drawRect


 Graphics.drawScrollButton

Graphics.drawScrollButton

Draws a button for a Win32 scroll bar.

Syntax

public final void drawScrollButton( Rectangle rect, int button, int state )

public final void drawScrollButton( int x, int y, int width, int height, int button, int state )

Parameters

rect

A Rectangle object that identifies the area in which to draw the button.

button

A constant that identifies the scroll bar button to draw. This value must be one of the enumeration constants defined in the ScrollButton class.

x

The x-coordinate of the upper-left corner of the drawing rectangle.

y

The y-coordinate of the upper-left corner of the drawing rectangle.

width

The width of the button.

height

The height of the button.

button

A ScrollButton enumeration value to determine the scroll bar button to draw.

state

One or more flags that determine how to draw the button. This value must be one or more of the enumeration constants defined in the ButtonState class.

See Also drawButton, drawCaptionButton, drawCheckBox, drawComboButton, drawMenuGlyph, drawRadioButton, drawSizeGrip


 Graphics.drawSizeGrip

Graphics.drawSizeGrip

Draws a sizing grip at the specified location.

Syntax

public final void drawSizeGrip( Rectangle rect )

public final void drawSizeGrip( int x, int y, int width, int height )

Parameters

rect

A Rectangle object that specifies the area in which to draw the sizing grips.

x

The x-coordinate of the upper-left corner of the drawing rectangle.

y

The y-coordinate of the upper-left corner of the drawing rectangle.

width

The width of the sizing grips.

height

The height of the sizing grips.

Remarks

A sizing grip is usually located at the lower-right corner of a window.

See Also drawButton, drawCaptionButton, drawCheckBox, drawComboButton, drawMenuGlyph, drawRadioButton, drawScrollButton


 Graphics.drawString

Graphics.drawString

Draws a string at the specified point or within the specified area.

Syntax

public final void drawString( String s, Point p )

public final void drawString( String s, Point p, int format )

public final void drawString( String s, int x, int y )

public final void drawString( String s, int x, int y, int format )

public final void drawString( String s, Rectangle rect, int format )

public final void drawString( String s, int x, int y, int width, int height, int format )

public final void drawString( String s, Point p, int[] tabStops )

public final void drawString( String s, int x, int y, int[] tabStops )

Parameters

s

The string to draw.

p

A Point object that specifies the point at which to draw the string.

x

The x-coordinate at which to draw the string.

y

The y-coordinate at which to draw the string.

width

The width of the area in which to draw the string

height

The height of the area in which to draw the string.

rect

A Rectangle object that specifies the area in which to draw the string.

format

One or more flags that describe how to format the string. This value must be one of the enumeration constants defined in the TextFormat class.

tabStops

An array of tab positions. If the array contains a single value, that value is used for all tab stops. If tabStops is null, a default value of 8 is used for the tab width.

Remarks

The string specified in s is drawn using the current font.


 Graphics.excludeFromClip

Graphics.excludeFromClip

Removes the specified rectangle from the current clipping region.

Syntax

public int excludeFromClip( Rectangle lpRect )

public int excludeFromClip( int x, int y, int width, int height )

Parameters

lpRect

A Rectangle object that identifies the rectangle to exclude from the object's clipping region.

x

The x-coordinate of the rectangle to exclude from the clipping region.

y

The y-coordinate of the rectangle to exclude from the clipping region.

width

The width of the rectangle to exclude from the clipping region.

height

The height of the rectangle to exclude from the clipping region.

See Also getClip, setClip


 Graphics.fill

Graphics.fill

Fills a specified area of the display with the current or specified brush.

Syntax

public final void fill( Rectangle rc )

public final void fill( int x, int y, int width, int height )

public final void fill( Rectangle rc, Brush brush )

public final void fill( int x, int y, int width, int height, Brush brush )

public final void fill( Rectangle rc, Brush br, RasterOp op )

public final void fill( int x, int y, int width, int height, Brush brush, RasterOp op )

public final void fill( Region region )

public final void fill( Region region, Brush brush )

Parameters

rc

A Rectangle object that specifies the area to fill.

x

The x-coordinate of the rectangle to fill.

y

The y-coordinate of the rectangle to fill.

width

The width of the rectangle to fill.

height

The height of the rectangle to fill.

brush

A Brush object that specifies the brush to use to fill the area.

op

A RasterOp object that describes how to fill the specified area.

region

A Region object that specifies the area to fill.

See Also floodFill


 Graphics.finalize

Graphics.finalize

Disposes of the resources allocated by this object.

Syntax

protected void finalize()

Remarks

If you create a Graphics object based on a previously created Win32 handle, a call to this method does not free that handle; you must free it manually.

See Also dispose


 Graphics.floodFill

Graphics.floodFill

Fills a specified area with the current brush.

Syntax

public final void floodFill( Point start, Color color, int type )

public final void floodFill( int x, int y, Color color, int type )

Parameters

start

A Point object that specifies the starting point for the fill.

x

The x-coordinate at which to start the fill.

y

The y-coordinate at which to start the fill.

color

A Color object that specifies the color that the flood fill will use as a boundary.

type

The type of the flood fill. This value must be one of the enumeration constants defined in the FloodFillType class.

Remarks

This method fills an area of the display surface using the current brush. There are two types of flood fills: border and surface.

A border flood fill assumes that the area to be filled is completely bounded by the color specified in the color parameter. A border flood fill begins filling at the specified point and continues in all directions until it reaches the boundary color.

A surface fill assumes that the area to be filled is a single color. It begins filling the area at the specified point and continues in all directions, filling all adjacent regions containing the specified color. The starting point for this fill must already be the color specified in the color parameter.

See Also fill


 Graphics.getBackColor

Graphics.getBackColor

Retrieves the current background color.

Syntax

public final Color getBackColor()

Return Value

Returns a Color object that identifies the current background color.

See Also setBackColor


 Graphics.getBrush

Graphics.getBrush

Retrieves the current brush.

Syntax

public final Brush getBrush()

Return Value

Returns a Brush object that identifies the current brush if one is set; otherwise, returns null.

See Also setBrush


 Graphics.getBrushOrigin

Graphics.getBrushOrigin

Retrieves the current brush origin.

Syntax

public final Point getBrushOrigin()

Return Value

Returns a Point object that specifies the current brush origin.

See Also setBrushOrigin


 Graphics.getClip

Graphics.getClip

Retrieves the current clipping region for this object.

Syntax

public final Region getClip()

Return Value

Returns a Region object that specifies the object's clipping region, if there is one; otherwise, returns null.

See Also setClip


 Graphics.getCoordinateSystem

Graphics.getCoordinateSystem

Retrieves the coordinate system that this object is currently using.

Syntax

public final int getCoordinateSystem()

Return Value

Returns one of the enumeration constants defined in the CoordinateSystem class.

See Also setCoordinateSystem


 Graphics.getDeviceOrigin

Graphics.getDeviceOrigin

Retrieves the device origin for a user-defined coordinate system.

Syntax

public final Point getDeviceOrigin()

Return Value

Returns a Point object that specifies the current device origin.


 Graphics.getDevicePoint

Graphics.getDevicePoint

Converts the specified coordinates to device coordinates.

Syntax

public final Point getDevicePoint( Point pt )

public final Point getDevicePoint( int x, int y )

Parameters

pt

A Point object that specifies the point for which to retrieve the device coordinates.

x

The logical x-coordinate for which to retrieve device coordinates.

y

The logical y-coordinate for which to retrieve device coordinates.

Return Value

Returns a Point object that contains the device coordinates for the specified point.


 <b>Graphics.getDeviceScale</b>

Graphics.getDeviceScale

Retrieves the current device scale for a user-defined coordinate system.

Syntax

public final Point getDeviceScale()

Return Value

Returns a Point object that specifies the current device scaling units.

See Also setCoordinateScale


 Graphics.getFont

Graphics.getFont

Retrieves the current font for this object.

Syntax

public final Font getFont()

Return Value

Returns a Font object that identifies the font currently used to draw text on this object.

See Also setFont


 Graphics.getFontDescriptors

Graphics.getFontDescriptors

Retrieves an array of FontDescriptor objects, which contains an entry for each font that matches the specified face name.

Syntax

public final FontDescriptor[] getFontDescriptors()

public final FontDescriptor[] getFontDescriptors( int charSet )

public final FontDescriptor[] getFontDescriptors( String name )

public final FontDescriptor[] getFontDescriptors( int charSet, String name )

Parameters

charSet

The character set for which to search.

name

The font's face name.

Return Value

Returns an array of FontDescriptor objects.


 Graphics.getHandle

Graphics.getHandle

Retrieves the Win32 device context handle (HDC) for this Graphics object.

Syntax

public final int getHandle()

Return Value

Returns the handle to the device context (HDC).

Exceptions

WFCException thrown if this object has already been disposed.


 Graphics.getLogicalPoint

Graphics.getLogicalPoint

Converts the specified point to logical coordinates.

Syntax

public final Point getLogicalPoint( Point pt )

public final Point getLogicalPoint( int x, int y )

Parameters

pt

A Point object that specifies the point to convert to logical coordinates.

x

The device x-coordinate of the point to convert.

y

The device y-coordinate of the point to convert.

Return Value

Returns a Point object that contains the logical coordinate.


 Graphics.getLogicalSizeX

Graphics.getLogicalSizeX

Retrieves the number of logical units that make up the specified number of inches.

Syntax

public final int getLogicalSizeX( float inches )

Parameters

inches

The number of horizontal inches for which to retrieve the logical units.

Return Value

Returns the number of logical units that make up the specified number of inches.

See Also getLogicalSizeY


 Graphics.getLogicalSizeY

Graphics.getLogicalSizeY

Retrieves the number of logical units that make up the specified number of inches.

Syntax

public final int getLogicalSizeY( float inches )

Parameters

inches

The number of vertical inches for which to retrieve the logical units.

Return Value

Returns the number of logical units that make up the specified number of inches.

See Also getLogicalSizeX


 Graphics.getNearestColor

Graphics.getNearestColor

Retrieves the closest solid color that the hardware will use for the specified color.

Syntax

public final Color getNearestColor( Color color )

Parameters

color

A Color object that specifies the color you want to use.

Return Value

Returns a Color object that describes the color that will be used.


 Graphics.getOpaque

Graphics.getOpaque

Retrieves the current fill mode on the Graphics object.

Syntax

public final boolean getOpaque()

Return Value

Returns true if the background color should be used as a fill before drawing; otherwise, returns false.

See Also setOpaque


 Graphics.getPageOrigin

Graphics.getPageOrigin

Retrieves the page origin for a user-defined coordinate system.

Syntax

public final Point getPageOrigin()

Return Value

Returns a Point object that specifies the current page origin.

See Also setCoordinateOrigin


 Graphics.getPageScale

Graphics.getPageScale

Retrieves the current page scale for a user-defined coordinate system.

Syntax

public final Point getPageScale()

Return Value

Returns a Point object that specifies the current page scaling units.

See Also setCoordinateScale


 Graphics.getPen

Graphics.getPen

Retrieves the pen associated with the Graphics object.

Syntax

public final Pen getPen()

Return Value

Returns a Pen object that specifies the current pen if a pen is set; otherwise, returns null.

See Also setPen


 Graphics.getPhysicalSizeX

Graphics.getPhysicalSizeX

Retrieves, in inches, the physical size for a specified number of horizontal logical coordinates.

Syntax

public final float getPhysicalSizeX( int units )

Parameters

units

The number of logical units for which to retrieve the size.

Return Value

Returns the number of inches represented by the specified number of logical units.

See Also getPhysicalSizeY


 Graphics.getPhysicalSizeY

Graphics.getPhysicalSizeY

Retrieves, in inches, the physical size for a specified number of vertical logical coordinates.

Syntax

public final float getPhysicalSizeY( int units )

Parameters

units

The number of logical units for which to retrieve the size.

Return Value

Returns the number of inches represented by the specified number of logical units.

See Also getPhysicalSizeX


 Graphics.getPixel

Graphics.getPixel

Retrieves the color of the specified pixel.

Syntax

public final Color getPixel( Point pt )

public final Color getPixel( int x, int y )

Parameters

pt

A Point object that specifies the pixel to retrieve.

x

The x-coordinate of the pixel to get.

y

The y-coordinate of the pixel to get.

Return Value

Returns a Color object that describes the color of the pixel.

See Also setPixel


 Graphics.getTextColor

Graphics.getTextColor

Retrieves the color used to display text in the Graphics object's bounding rectangle.

Syntax

public final Color getTextColor()

Return Value

Returns a Color object that describes the text color for the Graphics object.

See Also setBackColor


 Graphics.getTextSize

Graphics.getTextSize

Retrieves the area required to display the specified text string using the current font settings.

Syntax

public Point getTextSize( String text )

public Point getTextSize( String text, int[] tabStops )

public Point getTextSize( String text, int width, int format )

Parameters

text

A string that specifies the text for which to retrieve the size.

tabstops

An array of integers that specify the tab stops to use to format this text.

width

The margin width where text wrapping, if specified, will be applied.

format

One or more text format options. This value must be designate one or more of the enumeration constants specified in the TextFormat class.

Return Value

Returns a Point object that specifies the width and height of the text.


 Graphics.getTextSpace

Graphics.getTextSpace

Retrieves the amount of extra space that will be used between characters when drawing text.

Syntax

public final int getTextSpace()

Return Value

Returns an integer that specifies the amount of extra space.


 Graphics.Graphics

Graphics.Graphics

Creates a Graphics object.

Syntax

public Graphics( int dc )

protected Graphics( Control control, int dc, int flags )

Parameters

dc

The handle to a device context (HDC).

control

A Control object that specifies the control with which to associate the specified device context.

flags

One or more flags to be passed to the Win32 GetDCEx function.

Remarks

If the device context passed to this constructor is 0, the constructor verifies that sufficient resources are available to create a device context and then retrieves the device context based on the specified window handle.


 Graphics.intersectWithClip

Graphics.intersectWithClip

Sets the clipping region for this object to include the area of this object's clipping region that intersects with a specified rectangle or region.

Syntax

public final void intersectWithClip( Rectangle rect )

public final void intersectWithClip( int x1, int y1, int width, int height )

public final void intersectWithClip( Region region )

Parameters

rect

A Rectangle object that specifies the rectangular area to intersect with this object's clipping region.

x

The x-coordinate of the rectangle to intersect with the clipping region.

y

The y-coordinate of the rectangle to intersect with the clipping region.

width

The width of the rectangle to intersect with the clipping region.

height

The height of the rectangle to intersect with the clipping region.

region

A Region object that specifies the region to intersect with this object's clipping region.


 Graphics.invert

Graphics.invert

Inverts the pixels in the specified rectangle.

Syntax

public final void invert( Rectangle rect )

public final void invert( int x, int y, int width, int height )

public final void invert( Region region )

Parameters

rect

A Rectangle object that specifies the rectangle to invert.

x

The x-coordinate of the rectangle to invert.

y

The y-coordinate the rectangle to invert.

width

The width of rectangle.

height

The height of rectangle.

region

A Region object that specifies the region to invert.

Remarks

The invert method performs the inversion by performing a logical NOT operation on every pixel in the specified rectangle's interior.


 Graphics.renderPalette

Graphics.renderPalette

Renders the specified palette to this Graphics object.

Syntax

public final Palette renderPalette( Palette palette, boolean forceBackground )

Parameters

palette

A Palette object that specifies the new palette to render.

forceBackground

Set to true to cause the logical palette to be mapped to the colors already in the physical palette; otherwise, set to false to cause the logical palette to be copied into the device palette when the application is running in the foreground.

Return Value

Returns a Palette object that represents the previous palette for this object.

Remarks

WFC Palette objects are used to control the colors that are available for drawing when using display devices that support only 256 colors. By using a palette to determine which 256 colors the display will use, bitmaps can be drawn with nearly true color quality.


 Graphics.scroll

Graphics.scroll

Scrolls an area of the Graphics object.

Syntax

public final void scroll( int scrollX, int scrollY, Rectangle scrollArea, Rectangle clipArea )

Parameters

scrollX

The amount to scroll in the x direction. Negative values will scroll to the left.

scrollY

The amount to scroll in the y direction. Negative values will scroll up.

scrollArea

A Rectangle object that specifies the area to scroll.

clipArea

A Rectangle object that specifies the area beyond which no scrolling occurs.


 Graphics.setBackColor

Graphics.setBackColor

Sets the background color for the Graphics object. After you set the background color for the Graphics object, that color is used to fill empty regions in the object's bounding rectangle.

Syntax

public final void setBackColor( Color color )

Parameters

color

A Color object that specifies the background color.

See Also getBackColor


 Graphics.setBrush

Graphics.setBrush

Associates a brush with this Graphics object.

Syntax

public final void setBrush( Brush brush )

Parameters

brush

A Brush object that describes the brush to use with this Graphics object.

Remarks

After you associate a brush with the Graphics object, all filled areas in the object's clipping rectangle are filled using that brush. You can modify this association as often as you want.

See Also getBrush


 Graphics.setBrushOrigin

Graphics.setBrushOrigin

Sets the brush origin for this Graphics object. The default coordinates for the brush origin are 0,0.

Syntax

public final void setBrushOrigin( Point pt )

public final void setBrushOrigin( int x, int y )

Parameters

pt

A Point object that specifies the coordinates to which the brush origin should be set.

x

The x-coordinate of the brush origin.

y

The y-coordinate of the brush origin.

See Also getBrushOrigin


 Graphics.setClip

Graphics.setClip

Sets the clipping region for this Graphics object to the specified rectangle.

Syntax

public final void setClip( Rectangle rect )

public final void setClip( int x, int y, int width, int height )

public final void setClip( Region region )

Parameters

rect

A Rectangle object that specifies the clipping region's coordinates.

x

The x-coordinate of the clipping region.

y

The y-coordinate of the clipping region.

width

The width of the clipping region.

height

The height of the clipping region.

region

A Region object that specifies the clipping region.

See Also getClip


 Graphics.setCoordinateOrigin

Graphics.setCoordinateOrigin

Sets up the origin for a user-defined coordinate system.

Syntax

public final void setCoordinateOrigin( Point page, Point device )

Parameters

page

A Point object that specifies the page space coordinate origin. This value is always expressed in logical coordinates for the page. To leave this setting at its current value, this parameter should be null.

device

A Point object that specifies the device space coordinate origin. This value is always expressed in physical device coordinates. To leave this setting at its current value, this parameter should be null.

Remarks

This method can be used only if the current coordinate system for this Graphics object is CoordinateSystem.ISOTROPIC or CoordinateSystem.ANISOTROPIC.

See Also setCoordinateScale, setCoordinateSystem


 Graphics.setCoordinateScale

Graphics.setCoordinateScale

Sets up the coordinate scale for a user-defined coordinate system.

Syntax

public final void setCoordinateScale( Point page, Point device )

Parameters

page

A Point object that specifies the page space coordinate scaling factor. This value is always expressed in logical device coordinates. To leave the current page scaling factor at its current setting, this parameter should be null.

device

A Point object that specifies the device space coordinate scaling factor. This value is always expressed in physical device coordinates. To leave the current device scaling factor at its current setting, this parameter should be null.

Remarks

Win32 defines all coordinates using page space or device space. Page space is the logical coordinate system that all Graphics object calls use. Device space is the physical coordinate system that represents a window or printer page. All page space coordinates are expressed in logical units for the page's coordinate system. All device space coordinates are expressed in pixels.

You can set both the scaling and origin of the transformation that the Graphics object uses to translate page space to device space. The scaling factor is set by calling setCoordinateScale. The origin is set by calling setCoordinateSystem.

Note The setCoordinateScale method can be used only if the coordinate system has been set to CoordinateSystem.ISOTROPIC or CoordinateSystem.ANISOTROPIC.

See Also CoordinateSystem


 Graphics.setCoordinateSystem

Graphics.setCoordinateSystem

Sets the coordinate system for this Graphics object.

Syntax

public final void setCoordinateSystem( int system )

Parameters

system

The coordinate system for this object. This value must be one of the enumeration constants defined in the CoordinateSystem class.

Remarks

The coordinate system for a Graphics object defines its mapping mode. The mapping mode for an object designates how units (such as the x, y measurements in a Point object) map to the physical display and also determines the orientation of the device's x- and y-axes.


 Graphics.setFont

Graphics.setFont

Associates a font with the Graphics object.

Syntax

public final void setFont( Font font )

Parameters

font

A Font object that describes the font to associate with this Graphics object.

Remarks

All text drawn within the Graphics object's clipping region is drawn using this font.

See Also getFont


 Graphics.setHandle

Graphics.setHandle

This method is called when the Graphics object initializes a handle to device context (HDC) at object startup.

Syntax

protected void setHandle( int dc )

Parameters

dc

The handle to a Win32 device context.

Remarks

If you extend the Graphics object, you may override this method. However, your method override should always include a call to super.setHandle.

In addition, the dc parameter to this method should never be null. To clear existing handles, use the dispose method.

See Also getHandle


 Graphics.setOpaque

Graphics.setOpaque

Sets the background fill mode for the Graphics object.

Syntax

public final void setOpaque( boolean opaque )

Parameters

opaque

Set to true if you want the current background color to be the fill color; otherwise, set to false.

See Also getOpaque


 Graphics.setPen

Graphics.setPen

Associates a Pen object with the Graphics object.

Syntax

public final void setPen( Pen pen )

Parameters

pen

A Pen object that describes the pen to associate with this object.

Remarks

After you associate a pen with a Graphics object, the object uses that pen to draw all lines, polygons, and ellipses. You can change the pen associated with a Graphics object as often as you want.

See Also getPen


 Graphics.setPixel

Graphics.setPixel

Sets a pixel to the specified color.

Syntax

public final void setPixel( Point pt )

public final void setPixel( Point pt, Color color )

public final void setPixel( Point pt, Color color, RasterOp op )

public final void setPixel( int x, int y )

public final void setPixel( int x, int y, Color color )

public final void setPixel( int x, int y, Color color, RasterOp op )

Parameters

pt

A Point object that specifies the pixel to set.

color

A Color object that describes the color to which to set the pixel.

op

A RasterOp object that describes how to render the pixel.

x

The x-coordinate of the pixel to set.

y

The y-coordinate of the pixel to set.

Remarks

If your call to this method specifies no color, the method uses the current text color set on this object.

See Also getPixel


 Graphics.setTextColor

Graphics.setTextColor

Specifies the color that will be used to draw text.

Syntax

public final void setTextColor( Color color )

Parameters

color

A Color object that describes the color to use when drawing text.

See Also getTextColor


 Graphics.setTextSpace

Graphics.setTextSpace

Sets the amount of extra space to be used between characters when drawing text.

Syntax

public final void setTextSpace( int space )

Parameters

space

The amount of extra space.

See Also getTextSpace


GroupBox Class

Encapsulates a group box control, which is a rectangle that contains other controls.

Component
  |
  +--Control
    |
    +--GroupBox

package com.ms.wfc.ui

public class GroupBox
extends Control

Remarks

A group box visually sets apart the controls it contains from other controls on a form by drawing a border around them and displaying a caption in the upper-left corner of the group box. In addition, a group box can alter the way the controls it contains behaves. For example, placing radio buttons (option buttons) in a group box makes them mutually exclusive within the group box instead of within the form. To add controls to a group box, use the setNewControls method. To set the text that appears in the corner of the group box, use the setText method.


 GroupBox Methods

GroupBox Methods

Constructors | Description
GroupBox | Creates a GroupBox control.


 GroupBox.GroupBox

GroupBox.GroupBox

Creates a GroupBox control.

Syntax

public GroupBox()


Help Class

Encapsulates the Win32 help engine.

package com.ms.wfc.ui

public class Help

Remarks

Applications can use the Help class to display either HTML Help or WinHelp, depending on the type of help files passed to the various functions defined by the Help class.


 Help Methods

Help Methods

Methods | Description
showHelp | Displays the contents of a help file.
showHelpIndex | Displays the index of the specified file.
showPopup | Displays a help pop-up window.


 Help.showHelp

Help.showHelp

Displays the contents of a help file.

Syntax

public static void showHelp( Control parent, String url )

public static void showHelp( Control parent, String url, String topic )

public static void showHelp( Control parent, String url, int command, Object param )

Parameters

parent

A Control object that identifies the parent of the help dialog box to be displayed.

url

The path to the HTML Help or WinHelp file.

topic

The topic to display. If the help file is an HTML Help file, this value should reference the page to display. If the file is a WinHelp file, this value should reference the numeric value of the topic's ID.

command

A constant that indicates what kind of information to display. Acceptable values are COMMAND_CONTENTS, COMMAND_FIND, COMMAND_INDEX, or COMMAND_TOPIC.

param

Command-specific data. If the value specified in the command parameter is COMMAND_CONTENTS, COMMAND_INDEX, or COMMAND_FIND, this value should be null. If the command parameter references COMMAND_TOPIC, this value should reference an Integer or String object that contains the integer value of the topic to display.

Remarks

Based on the value of the url parameter, this method automatically determines whether an HTML Help or WinHelp file should be displayed.

You can also specify a WinHelp or HTML Help command directly by using the constants defined by the showHelp routine documented in the Win32 SDK.


 Help.showHelpIndex

Help.showHelpIndex

Displays the index of the specified file.

Syntax

public static void showHelpIndex( Control parent, String url )

Parameters

parent

A Control object that identifies the parent of the help dialog box to be displayed.

url

The path to the HTML Help or WinHelp file.

Remarks

Based on the value of the url parameter, this method automatically determines whether an HTML Help or WinHelp file should be displayed.

See Also showHelp, showPopup


 Help.showPopup

Help.showPopup

Displays a help pop-up window.

Syntax

public static void showPopup( Control parent, String caption, Point location )

Parameters

parent

A Control object that identifies the parent of the help dialog box to be displayed.

caption

The string to display in the pop-up window.

location

A Point object that specifies the x and y coordinates at which to display the pop-up window.


 Help Fields

Help Fields

Fields | Description
COMMAND_CONTENTS | Specifies that the contents of the WinHelp or HTML Help file will be displayed.
COMMAND_FIND | Specifies that the search page of the specified URL should be displayed.
COMMAND_INDEX | Specifies that the index of the specified URL should be displayed.
COMMAND_TOPIC | Specifies that the topic referenced by the specified URL should be displayed.


 Help.COMMAND_CONTENTS

Help.COMMAND_CONTENTS

Specifies that the contents of the WinHelp or HTML Help file will be displayed.

Syntax

public static final int COMMAND_CONTENTS;

See Also showHelp


 Help.COMMAND_FIND

Help.COMMAND_FIND

Specifies that the search page of the specified URL should be displayed.

Syntax

public static final int COMMAND_FIND;

See Also showHelp


 Help.COMMAND_INDEX

Help.COMMAND_INDEX

Specifies that the index of the specified URL should be displayed.

Syntax

public static final int COMMAND_INDEX;

See Also showHelp


 Help.COMMAND_TOPIC

Help.COMMAND_TOPIC

Specifies that the topic referenced by the specified URL should be displayed.

Syntax

public static final int COMMAND_TOPIC;

See Also showHelp


HelpEvent Class

Provides data for the help event of the Control object.

Event
  |
  +--HelpEvent

package com.ms.wfc.ui

public class HelpEvent
extends Event

Remarks

The help event occurs when the user requests Help for this control. A HelpEvent object specifies whether Help was requested for a menu or a control, the identifier of the menu or control, the component that represents the menu or control, the Help context identifier for the control, the screen coordinates of the mouse pointer, and whether the event was handled.

For information about the WFC event model, see Handling Events in WFC.


 HelpEvent Methods

HelpEvent Methods

Constructors | Description
HelpEvent | Creates a HelpEvent object.


 HelpEvent.HelpEvent

HelpEvent.HelpEvent

Creates a HelpEvent object.

Syntax

public HelpEvent( int contextType, int controlId, IComponent component, int contextId, Point mousePos )

public HelpEvent( Object extendedInfo, int contextType, int controlId, IComponent component, int contextId, Point mousePos )

Parameters

extendedInfo

Additional information supplied by com.ms.wfc.html events. You should not pass a value for this parameter outside the context of the com.ms.wfc.html package. For more information, see Event.extendedInfo and DhEventInfo.

contextType

An integer that specifies whether Help was requested for a menu item or for a control. Possible values are HELPINFO_WINDOW and HELPINFO_MENUITEM.

controlId

The identifier of the control or menu item.

component

The control or menu item that the user wants Help on.

contextId

The Help context identifier of the control.

mousePos

The screen coordinates of the mouse pointer. This is useful for providing Help based on the position of the mouse pointer.


 HelpEvent Fields

HelpEvent Fields

Fields | Description
component | Specifies the control or menu item that the user wants Help on.
contextId | Specifies the Help context identifier of the control.
contextType | Specifies whether Help was requested for a menu item or for a control.
controlId | Specifies the identifier of the control or menu item.
handled | Specifies whether the event is handled.
mousePos | Specifies the screen coordinates of the mouse pointer.


 HelpEvent.component

HelpEvent.component

Specifies the control or menu item that the user wants Help on.

Syntax

public final IComponent component;


 HelpEvent.contextId

HelpEvent.contextId

Specifies the Help context identifier of the control.

Syntax

public final int contextId;


 HelpEvent.contextType

HelpEvent.contextType

Specifies whether Help was requested for a menu item or for a control.

Syntax

public final int contextType;

Remarks

Possible values are HELPINFO_WINDOW and HELPINFO_MENUITEM.


 HelpEvent.controlId

HelpEvent.controlId

Specifies the identifier of the control or menu item.

Syntax

public final int controlId;


 HelpEvent.handled

HelpEvent.handled

Specifies whether the event is handled.

Syntax

public boolean handled;

Remarks

If the event is not handled, the message is passed on for default Windows processing.


 HelpEvent.mousePos

HelpEvent.mousePos

Specifies the screen coordinates of the mouse pointer.

Syntax

public final Point mousePos;

Remarks

This is useful for providing Help based on the position of the mouse pointer.


HelpEventHandler Delegate

Identifies the method handling the help event of a Control control.

package com.ms.wfc.ui

public multicast delegate
void HelpEventHandler( Object sender, HelpEvent e );

Remarks

The syntax of the HelpEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a HelpEvent object that provides the event data.

When you create a HelpEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC.


HelpProvider Class

Defines methods that provide online help support for WFC controls.

Component
  |
  +--HelpProvider

package com.ms.wfc.ui

public class HelpProvider
extends Component
implements IExtenderProvider

Remarks

The HelpProvider class enables you to provide pop-up or full online help support for WFC controls.

To associate a help file (either HTML Help or WinHelp) with the HelpProvider object, use the setHelpFile method. To associate topics within the specified file with specific controls, make successive calls to the setHelpTopic method. The help that you specify for this method typically becomes available to the user when the user clicks the question mark icon that appears in the caption bar of a dialog box.

Optionally, to associate a specific help string with a control, use the setHelpString method. The string that you associate with a control using this method is displayed in a pop-up window when the user presses the F1 key while the control has input focus.


 HelpProvider Methods

HelpProvider Methods

Constructors | Description
HelpProvider | Creates a HelpProvider object.

Methods | Description
getHelpFile | Retrieves the name of the help file that is associated with this HelpProvider object.
getHelpString | Retrieves the contents of the pop-up help window for the specified control.
getHelpTopic | Retrieves the help topic associated with a specified control.
getShowHelp | Retrieves a boolean value that indicates whether help should be displayed for the specified control.
setHelpFile | Sets the help file to be displayed for any controls for which this HelpProvider object is providing support.
setHelpString | Associates a help string with a control.
setHelpTopic | Sets the help topic to be displayed when the user invokes help for the specified control.
setShowHelp | Sets a boolean value that determines whether help should be displayed for a specified control.


 HelpProvider.getHelpFile

HelpProvider.getHelpFile

Retrieves the name of the help file that is associated with this HelpProvider object.

Syntax

public String getHelpFile()

Return Value

Returns the name of the help file.

Remarks

The file name returned by this method identifies the file that provides help support for all the controls for which this object is the help provider. This file name can designate either an HTML Help file or a WinHelp file.

See Also setHelpFile


 HelpProvider.getHelpString

HelpProvider.getHelpString

Retrieves the contents of the pop-up help window for the specified control.

Syntax

public String getHelpString( Control ctl )

Parameters

ctl

A Control object for which to retrieve the help string.

Return Value

Returns the help string associated with this control.

Remarks

To display this help string at run time, the user clicks F1 while the specified control has the input focus.

See Also setHelpString


 HelpProvider.getHelpTopic

HelpProvider.getHelpTopic

Retrieves the help topic associated with a specified control.

Syntax

public String getHelpTopic( Control ctl )

Parameters

ctl

A Control object for which to retrieve the help topic.

Return Value

Returns the help topic associated with this control. If the HelpProvider object is currently configured to display the entire help file, this method returns null.

See Also setHelpTopic


 HelpProvider.getShowHelp

HelpProvider.getShowHelp

Retrieves a boolean value that indicates whether help should be displayed for the specified control.

Syntax

public boolean getShowHelp( Control ctl )

Parameters

ctl

A Control object for which help should or should not be displayed.

Return Value

Returns true if help will be displayed for the control; otherwise, returns false.

Remarks

When you use the setHelpTopic or setHelpString method to associate a topic or prompt with a specified control, calling this method automatically returns true. You can override this behavior by passing false to the setShowHelp method.


 HelpProvider.HelpProvider

HelpProvider.HelpProvider

Creates a HelpProvider object.

Syntax

public HelpProvider()


 HelpProvider.setHelpFile

HelpProvider.setHelpFile

Sets the help file to be displayed for any controls for which this HelpProvider object is providing support.

Syntax

public void setHelpFile( String helpFile )

Parameters

helpFile

The help file to display. This file can be either an HTML Help or a WinHelp file.

See Also getHelpFile


 HelpProvider.setHelpString

HelpProvider.setHelpString

Associates a help string with a control.

Syntax

public void setHelpString( Control ctl, String helpString )

Parameters

ctl

A Control object that specifies the control with which to associate the help string.

helpString

The help string to associate with the control.

Remarks

The help string that you specify in the helpString parameter is displayed in a pop-up window when the user clicks F1 while the specified control has the input focus.

See Also getHelpString


 HelpProvider.setHelpTopic

HelpProvider.setHelpTopic

Sets the help topic to be displayed when the user invokes help for the specified control.

Syntax

public void setHelpTopic( Control ctl, String topic )

Parameters

ctl

A Control object that specifies the control for which to set the help topic.

topic

The help topic to associate with the control, or null, if the contents of the entire help file should be displayed.

See Also getHelpTopic


 HelpProvider.setShowHelp

HelpProvider.setShowHelp

Sets a boolean value that determines whether help should be displayed for a specified control.

Syntax

public void setShowHelp( Control ctl, boolean value )

Parameters

ctl

A Control object that specifies the control for which to turn help on or off.

value

Set to true to display help for this control; otherwise, set to false.

Remarks

If you have previously called the setHelpString or setHelpTopic for the control specified in the ctl parameter, the HelpProvider object automatically displays help for that control. To modify this behavior, call the setShowHelp method, specifying false in the value parameter.


HitArea Class

Defines constants that represent areas in a MonthCalendar control.

Enum
  |
  +--HitArea

package com.ms.wfc.ui

public class HitArea
extends Enum

Remarks

A value from this class is returned to the hitArea field of a HitTestInfo object to indicate which part of a month calendar is found at the specified location.


 HitArea Methods

HitArea Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 HitArea.valid

HitArea.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 HitArea Fields

HitArea Fields

Fields | Description
CALENDAR_BACKGROUND | Specifies the calendar's background.
DATE | Specifies a particular date within the calendar.
DAY_OF_WEEK | Specifies a day abbreviation ("Fri", for example).
NEXT_MONTH_BUTTON | Specifies the button at the top right corner of the control.
NEXT_MONTH_DATE | Specifies a date from the next month (partially displayed at the end of the currently displayed month).
NOWHERE | Specifies an area that is not part of the month calendar control or an inactive area of the month calendar control.
PREV_MONTH_BUTTON | Specifies the button at the top left corner of the control.
PREV_MONTH_DATE | Specifies a date from the previous month (partially displayed at the beginning of the currently displayed month).
TITLE_BACKGROUND | Specifies the background of a month's title.
TITLE_MONTH | Specifies a month's title bar, over a month name.
TITLE_YEAR | Specifies a month's title bar, over the year value.
TODAY_LINK | Specifies the "Today" link at the bottom of the month calendar control.
WEEK_NUMBERS | Specifies a week number.


 HitArea.CALENDAR_BACKGROUND

HitArea.CALENDAR_BACKGROUND

Specifies the calendar's background.

Syntax

public static final int CALENDAR_BACKGROUND;


 HitArea.DATE

HitArea.DATE

Specifies a particular date within the calendar.

Syntax

public static final int DATE;

Remarks

If the hitArea field of a HitTestInfo object is set to HitArea.DATE, the time field is set to the date found at the hit-tested point.


 HitArea.DAY_OF_WEEK

HitArea.DAY_OF_WEEK

Specifies a day abbreviation ("Fri", for example).

Syntax

public static final int DAY_OF_WEEK;

Remarks

If the hitArea field of a HitTestInfo object is set to HitArea.DAY_OF_WEEK, the time field is set to the corresponding date in the topmost visible row of the month calendar.


 HitArea.NEXT_MONTH_BUTTON

HitArea.NEXT_MONTH_BUTTON

Specifies the button at the top right corner of the control.

Syntax

public static final int NEXT_MONTH_BUTTON;

Remarks

If the user clicks here, the month calendar scrolls its display to the next month or set of months.


 HitArea.NEXT_MONTH_DATE

HitArea.NEXT_MONTH_DATE

Specifies a date from the next month (partially displayed at the end of the currently displayed month).

Syntax

public static final int NEXT_MONTH_DATE;

Remarks

If the user clicks here, the month calendar scrolls its display to the next month or set of months.


 HitArea.NOWHERE

HitArea.NOWHERE

Specifies an area that is not part of the month calendar control or an inactive area of the month calendar control.

Syntax

public static final int NOWHERE;


 HitArea.PREV_MONTH_BUTTON

HitArea.PREV_MONTH_BUTTON

Specifies the button at the top left corner of the control.

Syntax

public static final int PREV_MONTH_BUTTON;


 HitArea.PREV_MONTH_DATE

HitArea.PREV_MONTH_DATE

Specifies a date from the previous month (partially displayed at the beginning of the currently displayed month).

Syntax

public static final int PREV_MONTH_DATE;

Remarks

If the user clicks here, the month calendar scrolls its display to the previous month or set of months.


 HitArea.TITLE_BACKGROUND

HitArea.TITLE_BACKGROUND

Specifies the background of a month's title.

Syntax

public static final int TITLE_BACKGROUND;


 HitArea.TITLE_MONTH

HitArea.TITLE_MONTH

Specifies a month's title bar, over a month name.

Syntax

public static final int TITLE_MONTH;


 HitArea.TITLE_YEAR

HitArea.TITLE_YEAR

Specifies a month's title bar, over the year value.

Syntax

public static final int TITLE_YEAR;


 HitArea.TODAY_LINK

HitArea.TODAY_LINK

Specifies the "Today" link at the bottom of the month calendar control.

Syntax

public static final int TODAY_LINK;


 HitArea.WEEK_NUMBERS

HitArea.WEEK_NUMBERS

Specifies a week number.

Syntax

public static final int WEEK_NUMBERS;

Remarks

This result can be returned only if the showWeekNumbers property of the month calendar is set to true. If the hitArea field of a HitTestInfo object is set to HitArea.WEEK_NUMBERS, the time field is set to the corresponding date in the leftmost column.


HitTestInfo Class

Contains information specific to hit-testing points for a month calendar control.

package com.ms.wfc.ui

public class HitTestInfo


 HitTestInfo Fields

HitTestInfo Fields

Fields | Description
hitArea | Specifies a value representing the result of the hit-test operation.
point | Specifies a Point object that represents the point that was hit-tested.
time | Specifies a Time object that contains date and time information specific to the location that was hit-tested.


 HitTestInfo.hitArea

HitTestInfo.hitArea

Specifies a value representing the result of the hit-test operation.

Syntax

public int hitArea;

Remarks

Possible values are constants defined in the HitArea class. The default value is HitArea.NOWHERE


 HitTestInfo.point

HitTestInfo.point

Specifies a Point object that represents the point that was hit-tested.

Syntax

public Point point;


 HitTestInfo.time

HitTestInfo.time

Specifies a Time object that contains date and time information specific to the location that was hit-tested.

Syntax

public Time time;


HorizontalAlignment Class

Defines constants that specify how an object or text in a control is horizontally aligned relative to an element of the control.

Enum
  |
  +--HorizontalAlignment

package com.ms.wfc.ui

public class HorizontalAlignment
extends Enum


 HorizontalAlignment Methods

HorizontalAlignment Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 HorizontalAlignment.valid

HorizontalAlignment.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 HorizontalAlignment Fields

HorizontalAlignment Fields

Fields | Description
CENTER | Specifies that the object or text is aligned in the center of the control element.
LEFT | Specifies that the object or text is aligned on the left side of the control element.
RIGHT | Specifies that the object or text is aligned on the right side of the control element.


 HorizontalAlignment.CENTER

HorizontalAlignment.CENTER

Specifies that the object or text is aligned in the center of the control element.

Syntax

public static final int CENTER;


 HorizontalAlignment.LEFT

HorizontalAlignment.LEFT

Specifies that the object or text is aligned on the left side of the control element.

Syntax

public static final int LEFT;


 HorizontalAlignment.RIGHT

HorizontalAlignment.RIGHT

Specifies that the object or text is aligned on the right side of the control element.

Syntax

public static final int RIGHT;


HScrollBar Class

Encapsulates a scroll bar that is always oriented horizontally.

Component
  |
  +--Control
    |
    +--ScrollBar
      |
      +--HScrollBar

package com.ms.wfc.ui

public class HScrollBar
extends ScrollBar

See Also VScrollBar


 HScrollBar Methods

HScrollBar Methods

Constructors | Description
HScrollBar | Creates an HScrollBar control.


 HScrollBar.HScrollBar

HScrollBar.HScrollBar

Creates an HScrollBar control.

Syntax

public HScrollBar()


HTMLControl Class

Encapsulates the HTML control.

WebBrowser
  |
  +--HTMLControl

package com.ms.wfc.ui

public class HTMLControl
extends WebBrowser

Remarks

The HTML control makes it possible to retrieve Web pages and to parse their contents. Typically, after drawing the control on a form, you call the HTMLControl class' setURL method to associate a URL with the control. This URL can be a reference to an HTML page, or it can be the path to a Common Gateway Interface (CGI) script, or Active Server Page (ASP), and can include the arguments to an HTTP post.

For example, the following code sets the URL in the control to Microsoft's Web site:

HTMLControl1.setURL("http://www.microsoft.com");

The following example sets the URL and posts arguments to that URL:

HTMLControl1.setURL("http://www.myguestbook.com/guestbook.asp?FirstName=Joe&LastName=Smith");

Calling the setURL method results in the display of the page within the control. Once the page is loaded, the control's documentReady event is triggered. From within the event handler for this event, you can call HTMLControl.getDocument to retrieve a DhDocument object that represents the control's contents, and you can use the methods supported by the DhDocument object to manipulate the control's contents.


 HTMLControl Methods

HTMLControl Methods

Methods | Description
add | Adds a WFC control to the HTML control.
addOnDocumentReady | Assigns a delegate to the documentReady event.
getDocument | Retrieves the document associated with the HTML control.
getURL | Retrieves the address of the page currently displayed in the HTML control.
onDocumentReady | Triggers the documentReady event.
remove | Removes a control from the HTML control.
removeOnDocumentReady | Removes the delegate that is assigned to the documentReady event.
setBoundElements | Binds the elements of a specified array to their peers.
setNewComponents | Adds the specified components to the HTML control.
setNewHTMLElements | Adds the specified HTML elements to the HTML control.
setURL | Loads the document at the specified URL into the HTML control.


 HTMLControl.add

HTMLControl.add

Adds a WFC control to the HTML control.

Syntax

public final void add( Control c )

public final void add( DhElement e )

Parameters

c

A Control object that specifies the Windows' user interface element to add to the HTML control.

e

A DhElement object that specifies the HTML element to be added to the control.


 HTMLControl.addOnDocumentReady

HTMLControl.addOnDocumentReady

Assigns a delegate to the documentReady event.

Syntax

public void addOnDocumentReady( DocumentReadyEventHandler handler )

Parameters

handler

The DocumentReadyEventHandler to be notified when the event occurs.

Remarks

The documentReady event occurs when the DhDocument object that encapsulates the HTML control's contents is initialized. After this event occurs, you can access the document by calling the HTMLControl object's getDocument method.

See Also onDocumentReady, removeOnDocumentReady


 HTMLControl.getDocument

HTMLControl.getDocument

Retrieves the document associated with the HTML control.

Syntax

public final DhDocument getDocument()

Return Value

Returns a DhDocument object that represents the current document.


 HTMLControl.getURL

HTMLControl.getURL

Retrieves the address of the page currently displayed in the HTML control.

Syntax

public final String getURL()

Return Value

Returns the current address.

See Also setURL


 HTMLControl.onDocumentReady

HTMLControl.onDocumentReady

Triggers the documentReady event.

Syntax

protected void onDocumentReady( DocumentReadyEvent e )

Parameters

e

A DocumentReadyEvent object that provides the event data.

Remarks

The documentReady event occurs when the DhDocument object that encapsulates the HTML control's contents is initialized. After this event occurs, you can access the document by calling the HTMLControl object's getDocument method.

Classes that extend this one should override this method to handle this event and should call super.onDocumentReady to send this event to any delegates.

See Also addOnDocumentReady, removeOnDocumentReady


 HTMLControl.remove

HTMLControl.remove

Removes a control from the HTML control.

Syntax

public final void remove( Control c )

Parameters

c

A Control object that specifies the control to remove.


 HTMLControl.removeOnDocumentReady

HTMLControl.removeOnDocumentReady

Removes the delegate that is assigned to the documentReady event.

Syntax

public void removeOnDocumentReady( DocumentReadyEventHandler handler )

Parameters

handler

The DocumentReadyEventHandler delegate to be removed.

Remarks

The documentReady event occurs when the DhDocument object that encapsulates the HTML control's contents is initialized. After this event occurs, you can access the document by calling the HTMLControl object's getDocument method.

See Also addOnDocumentReady, onDocumentReady


 HTMLControl.setBoundElements

HTMLControl.setBoundElements

Binds the elements of a specified array to their peers.

Syntax

public void setBoundElements( DhElement[] elems )

Parameters

elems

An array of DhElement objects that specifies the elements to be bound.

Exceptions

WFCException thrown if the ID of an element in the elems array does not match the existing elements in the HTML content.

WFCException thrown if an element in the elems array is already bound to another Java object.

WFCException thrown if the class type of the peer and the specified Java object do not match.


 HTMLControl.setNewComponents

HTMLControl.setNewComponents

Adds the specified components to the HTML control.

Syntax

public final void setNewComponents( Component[] comps )

Parameters

comps

An array of Component objects that specify the components to add to the control.

Remarks

Components added using this method must extend either the Control or DhElement classes.


 HTMLControl.setNewHTMLElements

HTMLControl.setNewHTMLElements

Adds the specified HTML elements to the HTML control.

Syntax

public final void setNewHTMLElements( DhElement[] elems )

Parameters

elems

An array of DhElement objects that specifies the HTML elements to add to the control.

Remarks

Items specified in the elems parameter must be DhElement objects or objects that extend the DhElement class.


 HTMLControl.setURL

HTMLControl.setURL

Loads the document at the specified URL into the HTML control.

Syntax

public final void setURL( String url )

Parameters

url

The address of the page to load.

Remarks

Once this document is loaded, the documentReady event is triggered, and you can use the HTMLControl object's getDocument method to retrieve a DhDocument object that represents the control's contents.

See Also getDocument, getURL


IButtonControl Interface

Defines the button interface.

package com.ms.wfc.ui

public interface IButtonControl

Remarks

To behave like a button on a form, a class must implement IButton. Implementing this interface allows a class to behave like a default or accept button (the button that receives a click event when the user presses ENTER to close a dialog box) or like a cancel button (the button that receives a click event when the user presses ESC to dismiss a dialog box).


 IButtonControl Methods

IButtonControl Methods

Methods | Description
notifyDefault | Notifies the button whether it is the default button so that it can adjust its appearance accordingly.
performClick | Generates a click event for the button, simulating a click by a user.


 IButtonControl.notifyDefault

IButtonControl.notifyDefault

Notifies the button whether it is the default button so that it can adjust its appearance accordingly.

Syntax

void notifyDefault( boolean value )

Parameters

value

Set to true to notify the button that it is the default button; otherwise, set to false.

Remarks

This method is called from the parent form to notify the button that it should consider itself the default button and to allow the button to adjust its appearance accordingly. Typically, a Windows command button that is the default button for a form has a thicker border than other buttons on the form.


 IButtonControl.performClick

IButtonControl.performClick

Generates a click event for the button, simulating a click by a user.

Syntax

void performClick()

Remarks

This method is called when the user presses ENTER to close the dialog box that contains the button (if the button is a default button) or ESC to dismiss the dialog box (if the button is a cancel button).


Icon Class

Encapsulates a Windows icon, which is a small, transparent bitmap used to visually represent an object, such as a Windows application.

Image
  |
  +--Icon

package com.ms.wfc.ui

public class Icon
extends Image
implements IPersistable


 Icon Methods

Icon Methods

Constructors | Description
Icon |

Methods | Description
clone | Clones the Icon object and returns a duplicate.
copyHandle | Retrieves a copy of the Win32 handle for this icon.
createSmallIcon | Creates and returns a small icon copy of the specified Icon object.
destroyHandle | Called when this object is going to destroy its Win32 handle.
dispose | Frees the resources allocated by this object.
drawStretchTo | Renders the icon image to a Graphics object, stretching the image to fill the specified dimensions.
drawTo | Renders the icon image (or part of it) to a Graphics object, cropping the image to fit the specified dimensions.
finalize | Frees the resources allocated by the Icon object.
getExtension | Retrieves the recommended file extension for files that persist this object.
getHandle | Retrieves the Win32 handle to this icon.
getPICTDESC | Retrieves a PICTDESC (Picture Descriptor) for this icon.
getSize | Retrieves the size of this Icon object's image.
toString | Retrieves a human-readable string representation of this object.


 Icon.clone

Icon.clone

Clones the Icon object and returns a duplicate.

Syntax

public Object clone()

Return Value

Returns an Object that is a duplicate of this one and that can be cast to an Icon object.


 Icon.copyHandle

Icon.copyHandle

Retrieves a copy of the Win32 handle for this icon.

Syntax

public final int copyHandle()

Return Value

Returns a copy of the Win32 handle for this icon.

Remarks

Because the handle returned by copyHandle is a copy of the icon's underlying Win32 handle, you are responsible for freeing this handle when you are finished using it.

See Also getHandle


 Icon.createSmallIcon

Icon.createSmallIcon

Creates and returns a small icon copy of the specified Icon object.

Syntax

public static Icon createSmallIcon( Icon icon )

Parameters

icon

An Icon object that specifies the icon on which to base the small icon.

Return Value

Returns an Icon object that represents a small version of the specified icon.

Remarks

A small icon is 16 by 16 pixels.


 Icon.destroyHandle

Icon.destroyHandle

Called when this object is going to destroy its Win32 handle.

Syntax

protected void destroyHandle( int handle )

Parameters

handle

The Win32 handle to the bitmap on which this object is based.

Remarks

The Icon class's implementation of destroyHandle frees only handles owned by the Icon object. If you have used the object to retrieve a handle to this icon (using the copyHandle method), or if you have created a Icon object based on a previously allocated handle, this handle is not freed by the object's call to destroyHandle; you are responsible for freeing these handles.

However, you can override this method in your Icon-derived class to define your own custom semantics for handle creation and destruction.


 Icon.dispose

Icon.dispose

Frees the resources allocated by this object.

Syntax

public void dispose()

Remarks

The dispose method frees only those resources allocated by the object. Such resources do not include handle copies that you retrieve using the object's methods; you must free these manually.

Once the dispose method is called, the Icon object is no longer useful.


 Icon.drawStretchTo

Icon.drawStretchTo

Renders the icon image to a Graphics object, stretching the image to fill the specified dimensions.

Syntax

protected void drawStretchTo( Graphics g, Rectangle imageRect, Rectangle targetRect, int rop )

Parameters

g

The Graphics object to which to draw the icon.

imageRect

A Rectangle object that specifies the icon region to draw.

targetRect

A Rectangle object that specifies the area to which to draw the image.

rop

A numerical raster operation (ROP) code that describes how to draw the source image to the target.

Remarks

This method is used by the Graphics object for all image rendering.

If the area specified in imageRect is smaller than the area specified in targetRect, the source image is stretched to fill the specified area. If the area specified in imageRect is larger than that specified in targetRect, the image is shrunk.


 Icon.drawTo

Icon.drawTo

Renders the icon image (or part of it) to a Graphics object, cropping the image to fit the specified dimensions.

Syntax

protected void drawTo( Graphics g, Rectangle imageRect, Rectangle targetRect, int rop )

Parameters

g

The Graphics object to which to draw the image.

imageRect

A Rectangle object that specifies the source rectangle in the image.

targetRect

A Rectangle object that specifies the rectangle to which to draw the image. If this area is smaller than imageRect, the source rectangle is cropped to fit in the target rectangle.

rop

A numerical raster operation (ROP) code that specifies how to draw the image.

See Also drawStretchTo


 Icon.finalize

Icon.finalize

Frees the resources allocated by the Icon object.

Syntax

protected void finalize()


 Icon.getExtension

Icon.getExtension

Retrieves the recommended file extension for files that persist this object.

Syntax

public String getExtension()

Return Value

Returns the recommended file extension for this object, minus the prefixing period. The default implementation of this method always returns "ico".


 Icon.getHandle

Icon.getHandle

Retrieves the Win32 handle to this icon.

Syntax

public int getHandle()

Return Value

Returns the handle to this icon.

Exceptions

WFCException thrown if the Icon object has been disposed through a call to its dispose method.

Remarks

The handle returned by this method is not a copy of the icon handle. Therefore, this handle should not be freed by the caller.


 Icon.getPICTDESC

Icon.getPICTDESC

Retrieves a PICTDESC (Picture Descriptor) for this icon.

Syntax

public final PICTDESC getPICTDESC()

Return Value

Returns a PICTDESC structure that describes this icon's image.

Remarks

The PICTDESC structure is used by OLE functions to create picture objects.


 Icon.getSize

Icon.getSize

Retrieves the size of this Icon object's image.

Syntax

public final Point getSize()

Return Value

Returns a Point object that specifies the height and width of the image.


 Icon.Icon

Icon.Icon

Syntax

public Icon( int handle )

public Icon( String fileName )

public Icon( Class type, String resource )

public Icon( IDataStream stream )

public Icon( IDataStream stream, int width, int height )

public Icon( IStream stream )

public Icon( IStream stream, int width, int height )

public Icon( IPicture picture )

Parameters

handle

A Win32 icon handle (HICON). The Icon object does not claim ownership of this handle; you must free it manually.

fileName

The name of an icon file that stores the icon on which to base this object.

type

The class used to load the icon resource.

resource

The resource to load.

stream

A data stream (IDataStream or com.ms.wfc.ole32.IStream) from which to load the icon.

width

The width of the icon.

height

The height of the icon.

picture

An OLE com.ms.wfc.ole32.IPicture object that contains the icon to load.


 Icon.toString

Icon.toString

Retrieves a human-readable string representation of this object.

Syntax

public String toString()

Return Value

A string that describes this Icon object.


IconArrange Class

Defines a group of constants that specify how icons are arranged within a window.

Enum
  |
  +--IconArrange

package com.ms.wfc.ui

public class IconArrange
extends Enum


 IconArrange Methods

IconArrange Methods

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value designates a valid IconArrange constant.


 <b>IconArrange.valid</b>

IconArrange.valid

Retrieves a boolean value that indicates whether a specified value designates a valid IconArrange constant.

Syntax

public static boolean valid( int value )

Parameters

value

A value to be compared to those defined in this class.

Return Value

Returns true if the value designates a member of this class; otherwise, returns false.


 IconArrange Fields

IconArrange Fields

Fields | Description
DEFAULT | Specifies a default arrangement of icons in which icons remain in the position in which they were last placed by a user.
LEFT | Specifies that icons are arranged along the left of the parent control or window.
SNAP_TO_GRID | Specifies that icons are snapped to an imaginary grid, dividing the parenting control into invisible sections.
TOP | Specifies that icons are arranged along the top of the parent control or window.


 IconArrange.DEFAULT

IconArrange.DEFAULT

Specifies a default arrangement of icons in which icons remain in the position in which they were last placed by a user.

Syntax

public static final int DEFAULT;


 IconArrange.LEFT

IconArrange.LEFT

Specifies that icons are arranged along the left of the parent control or window.

Syntax

public static final int LEFT;


 IconArrange.SNAP_TO_GRID

IconArrange.SNAP_TO_GRID

Specifies that icons are snapped to an imaginary grid, dividing the parenting control into invisible sections.

Syntax

public static final int SNAP_TO_GRID;


 IconArrange.TOP

IconArrange.TOP

Specifies that icons are arranged along the top of the parent control or window.

Syntax

public static final int TOP;


IHandleHook Interface

Defines the interface that provides information about when components create and destroy their handles.

package com.ms.wfc.ui

public interface IHandleHook


 IHandleHook Methods

IHandleHook Methods

Methods | Description
augmentCreateParams | Indicates that the control is about to create its handle.
onCreateHandle | Indicates that the specified window handle has just been created.
onDestroyHandle | Indicates that the specified window handle is about to be destroyed.


 IHandleHook.augmentCreateParams

IHandleHook.augmentCreateParams

Indicates that the control is about to create its handle.

Syntax

public void augmentCreateParams( Control control, CreateParams cp )

Parameters

control

A Control object that represents the control that is about to be created.

cp

A CreateParams object that contains information about the initial state of the control.

Remarks

This method allows the Forms Designer or any other siting object to augment the control's creation information before the control is actually created.


 IHandleHook.onCreateHandle

IHandleHook.onCreateHandle

Indicates that the specified window handle has just been created.

Syntax

public void onCreateHandle( int handle )

Parameters

handle

The window handle for the control.


 IHandleHook.onDestroyHandle

IHandleHook.onDestroyHandle

Indicates that the specified window handle is about to be destroyed.

Syntax

public void onDestroyHandle( int handle )

Parameters

handle

The window handle for the control.

Remarks

You cannot prevent the handle from being destroyed once you call this method.


Image Class

Represents the base class for image classes such as Bitmap, Cursor, Metafile, and Icon.

package com.ms.wfc.ui

public abstract class Image
implements IPersistable

Remarks

The Image class is the base class for all WFC images, including icons, bitmaps, cursors, and metafiles. This object is based on an OLE IPicture object, which makes it possible for the Image object to handle a wider variety of image formats than are natively supported in Win32.


 Image Methods

Image Methods

Constructors | Description
Image | Creates an Image object.

Methods | Description
copyHandle | Retrieves a copy of the Win32 handle for the image on which this object is based.
dispose | Frees all the resources allocated by this object.
drawStretchTo | Renders the image (or part of it) to a Graphics object, stretching the image to fit the specified dimensions.
drawTo | Renders the bitmap image to a Graphics object, cropping the image to fill the specified dimensions.
finalize | Frees all the resources allocated by this object.
getHandle | Retrieves the Win32 handle to this image.
getPICTDESC | Retrieves a PICTDESC (Picture Descriptor) for this image.
getPicture | Retrieves the OLE com.ms.wfc.ole32.IPicture object associated with this image.
getSize | Retrieves the size of the image.
loadImage | Loads an image from a stream.
loadPicture | Loads a picture from the specified stream.
save | Saves the image to the specified output stream.
toString | Retrieves a human-readable string representation of this object.


 Image.copyHandle

Image.copyHandle

Retrieves a copy of the Win32 handle for the image on which this object is based.

Syntax

public abstract int copyHandle()

Return Value

Returns a copy of the Win32 handle to the image that underlies this object.

Remarks

Classes that extend the Image class use the copyHandle method to duplicate their underlying handle.


 Image.dispose

Image.dispose

Frees all the resources allocated by this object.

Syntax

public void dispose()

Remarks

In classes that extend the Image object, a call to this method typically frees only resources allocated by the subclass itself and renders the object unusable.

See Also finalize


 Image.drawStretchTo

Image.drawStretchTo

Renders the image (or part of it) to a Graphics object, stretching the image to fit the specified dimensions.

Syntax

protected abstract void drawStretchTo( Graphics g, Rectangle imageRect, Rectangle targetRect, int rop )

Parameters

g

The Graphics object to which to draw the image.

imageRect

A Rectangle object that specifies the bitmap region to draw.

targetRect

A Rectangle object that specifies the area to which to draw the image.

rop

A numerical raster operation (ROP) code that describes how to draw the source image to the target.

Remarks

The command to draw an image originates with the Graphics object. The Graphics object has no built-in image drawing capability so it generally passes the command to the image's drawTo or drawStretchTo methods.

Users should take advantage the wide variety of image-drawing methods supported by the Graphics object rather than attempting to directly call the image-drawing methods implemented in the classes that extend this one.


 Image.drawTo

Image.drawTo

Renders the bitmap image to a Graphics object, cropping the image to fill the specified dimensions.

Syntax

protected abstract void drawTo( Graphics g, Rectangle imageRect, Rectangle targetRect, int rop )

Parameters

g

The Graphics object to which to draw the image.

imageRect

A Rectangle object that specifies the source rectangle in the image.

targetRect

A Rectangle object that specifies the rectangle to which to draw the image. If this area is smaller than imageRect, the source rectangle is cropped to fit in the target rectangle.

rop

A numerical raster operation (ROP) code that specifies how to draw the image.


 Image.finalize

Image.finalize

Frees all the resources allocated by this object.

Syntax

protected void finalize()

Remarks

A call to this method is equivalent to calling the Image object's dispose method.


 Image.getHandle

Image.getHandle

Retrieves the Win32 handle to this image.

Syntax

public abstract int getHandle()

Return Value

Returns the handle to this image.

Remarks

In classes that extend the Image class, the override of this method is generally not a copy of the icon handle. Therefore, this handle should not be freed by the caller.


 Image.getPICTDESC

Image.getPICTDESC

Retrieves a PICTDESC (Picture Descriptor) for this image.

Syntax

public abstract PICTDESC getPICTDESC()

Return Value

Returns a PICTDESC structure that describes this object's image.

Remarks

The PICTDESC structure is used by OLE functions to create picture objects.


 Image.getPicture

Image.getPicture

Retrieves the OLE com.ms.wfc.ole32.IPicture object associated with this image.

Syntax

protected IPicture getPicture()

Return Value

Returns the OLE IPicture object associated with this image, if there is one; otherwise, returns null.


 Image.getSize

Image.getSize

Retrieves the size of the image.

Syntax

public abstract Point getSize()

Return Value

Returns a Point object that specifies the width and height of the image.


 Image.Image

Image.Image

Creates an Image object.

Syntax

protected Image()

protected Image( IPicture picture )

Parameters

picture

A com.ms.wfc.ole32.IPicture object that specifies the picture to load.


 Image.loadImage

Image.loadImage

Loads an image from a stream.

Syntax

public static Image loadImage( IDataStream stream )

public static Image loadImage( IStream stream )

Parameters

stream

An IDataStream or com.ms.wfc.ole32.IStream object from which to load the image.

Return Value

Returns an Image object for the loaded image. This object represents a bitmap, icon, cursor, or metafile, depending on the type of data stored in the stream.


 Image.loadPicture

Image.loadPicture

Loads a picture from the specified stream.

Syntax

protected static IPicture loadPicture( IStream stream )

protected static IPicture loadPicture( IStream stream, int width, int height )

Parameters

stream

The IStream object from which to load the picture.

width

The requested width of the picture.

height

The requested height of the picture.

Return Value

Returns an OLE IPicture object that represents the image.


 Image.save

Image.save

Saves the image to the specified output stream.

Syntax

public void save( IDataStream outputStream )

Parameters

outputStream

An IDataStream object to which to save the image. This can be a file, object, or other data stream.


 Image.toString

Image.toString

Retrieves a human-readable string representation of this object.

Syntax

public String toString()

Return Value

A string that describes this Image object.


ImageList Class

Contains a collection of images that can be used by other controls, such as the ListView, TreeView, Toolbar, TabStrip, and TabControl controls.

Component
  |
  +--ImageList

package com.ms.wfc.ui

public class ImageList
extends Component

Remarks

You can use an ImageList object to store the images that appear next to nodes in a tree view control. Use the addImage or setImages method to add images to the image list. Use the setImageList method of a control to associate an image list with it. For a list view control, use the setLargeImageList and setSmallImageList methods to specify the images used in Large Icon view and Small Icon view, and use the setStateImageList method to specify the images used to indicate the state of an item.


 ImageList Methods

ImageList Methods

Constructors | Description
ImageList | Creates an ImageList control.

Methods | Description
addImage | Adds one or more images derived from the specified bitmap or icon to the image list.
draw | Draws the specified image.
drawImage | Draws the specified image.
getBitmap | Retrieves the specified image as a bitmap.
getIcon | Creates and retrieves an icon based on the image and mask at the specified index.
getImage | Retrieves the specified image.
getImageCount | Retrieves the number of images in the image list.
getImages | Retrieves all the images in the image list.
getImageSize | Retrieves the size of images in the image list.
getImageStream | Retrieves the stream to persist the image list to and depersist the image list from.
getMaskColor | Retrieves the color used to generate masks for images in the image list.
getUseMask | Retrieves a boolean value indicating whether the image list uses a mask.
removeAll | Removes all images and masks from the image list.
removeImage | Removes the specified image from the image list.
replaceImage | Replaces the specified image with another image.
setImages | Adds images to the the image list.
setImageSize | Sets the size of images in the image list.
setImageStream | Sets the stream to persist the image list to and depersist the image list from.
setMaskColor | Sets the color used to generate masks for images in the image list.
setUseMask | Sets a boolean value indicating whether the image list uses a mask.


 ImageList.addImage

ImageList.addImage

Adds one or more images derived from the specified bitmap or icon to the image list.

Syntax

public int addImage( Image value )

public int addImage( Bitmap image, Color maskColor )

Parameters

value

An Image object that represents the image(s) to add. If you specify an image whose size is greater than the size specified in the imageSize property, multiple images may be added to the image list.

image

The Bitmap object that represents the the image(s) to add. If you specify an image whose size is greater than the size specified in the imageSize property, multiple images may be added to the image list.

maskColor

A Color object that represents the mask color for the image. If the value of the useMask property is false, this parameter is ignored.

Return Value

Returns the zero-based index of the first image added.

Exceptions

WFCInvalidArgumentException thrown if the Image object specified for the value parameter is null. WFCException thrown if the dimensions of the Image object specified for the value parameter are less than the dimensions specified in the imageSize property, if the specified image is not a bitmap or an icon, or if the image cannot be added to the image list.

See Also removeImage


 ImageList.draw

ImageList.draw

Draws the specified image.

Syntax

public void draw( Graphics g, Point pt, int index )

public void draw( Graphics g, int x, int y, int index )

Parameters

g

A Graphics object that is used to draw the image.

pt

A Point object that represents the upper-left corner of the bounding rectangle to draw the image in.

x

The x-coordinate of the upper-left corner of the bounding rectangle to draw the image in.

y

The y-coordinate of the upper-left corner of the bounding rectangle to draw the image in.

index

The zero-based index of the image to draw.


 ImageList.drawImage

ImageList.drawImage

Draws the specified image.

Syntax

public void drawImage( Graphics g, int x, int y, int width, int height, int rop, int index )

Parameters

g

A Graphics object that is used to draw the image.

x

The x-coordinate of the upper-left corner of the bounding rectangle to draw the image in.

y

The y-coordinate of the upper-left corner of the bounding rectangle to draw the image in.

width

The width, in pixels, of the image to draw.

height

The height, in pixels, of the image to draw.

rop

A integer that represents a raster operation code. These codes define how the color data for the source rectangle will be combined with the color data for the destination rectangle to achieve the final color. Possible values are defined in the RasterOp class.

index

The zero-based index of the image to draw.


 ImageList.getBitmap

ImageList.getBitmap

Retrieves the specified image as a bitmap.

Syntax

public Bitmap getBitmap( int index )

Parameters

index

The zero-based index of the image to retrieve.

Return Value

Returns a Bitmap object that represents the image to retrieve. The returned image is a copy of the original image.


 ImageList.getIcon

ImageList.getIcon

Creates and retrieves an icon based on the image and mask at the specified index.

Syntax

public Icon getIcon( int index )

Parameters

index

The zero-based index of the image to retrieve as an icon.

Return Value

Returns an Icon object that represents the specified image.

Remarks

The icon is created using the current drawing mode.


 ImageList.getImage

ImageList.getImage

Retrieves the specified image.

Syntax

public Image getImage( int index )

Parameters

index

The zero-based index of the image to retrieve.

Return Value

Returns an Image object that represents the image to retrieve. The returned Image object contains a reference to the original image in the image list and will reflect changes made to the original image.


 ImageList.getImageCount

ImageList.getImageCount

Retrieves the number of images in the image list.

Syntax

public int getImageCount()

Return Value

Returns the number of images in the image list.


 ImageList.getImages

ImageList.getImages

Retrieves all the images in the image list.

Syntax

public Image[] getImages()

Return Value

Returns an array of Image objects that represent the images in the image list.

See Also setImages


 ImageList.getImageSize

ImageList.getImageSize

Retrieves the size of images in the image list.

Syntax

public Point getImageSize()

Return Value

Returns a Point object that specifies the size of images in the image list.

See Also setImageSize


 ImageList.getImageStream

ImageList.getImageStream

Retrieves the stream to persist the image list to and depersist the image list from.

Syntax

public ImageListStreamer getImageStream()

Return Value

Returns an ImageListStreamer object that represents the stream to persist the image list to and depersist the image list from.

See Also setImageStream


 ImageList.getMaskColor

ImageList.getMaskColor

Retrieves the color used to generate masks for images in the image list.

Syntax

public Color getMaskColor()

Return Value

Returns a Color object that represents the mask color for images in the image list.

See Also setMaskColor


 ImageList.getUseMask

ImageList.getUseMask

Retrieves a boolean value indicating whether the image list uses a mask.

Syntax

public boolean getUseMask()

Return Value

Returns true if the image list uses a mask; otherwise, returns false.

See Also setUseMask


 ImageList.ImageList

ImageList.ImageList

Creates an ImageList control.

Syntax

public ImageList()

public ImageList( Point size )

public ImageList( Point size, Color maskColor )

Parameters

size

A Point object that represents the dimensions, in pixels, of an image in the image list.

maskColor

A Color object that represents the mask color for the images in the image list.

Remarks

If the size parameter is not supplied or is null, this method creates an ImageList control with a default image size of 16 x 16 pixels.


 ImageList.removeAll

ImageList.removeAll

Removes all images and masks from the image list.

Syntax

public void removeAll()


 ImageList.removeImage

ImageList.removeImage

Removes the specified image from the image list.

Syntax

public void removeImage( int index )

Parameters

index

The zero-based index of the image to remove.

See Also addImage


 ImageList.replaceImage

ImageList.replaceImage

Replaces the specified image with another image.

Syntax

public void replaceImage( int index, Image value )

Parameters

index

The zero-based index of the image to remove.

value

An Image object that represents the image to replace the removed image with.


 ImageList.setImages

ImageList.setImages

Adds images to the the image list.

Syntax

public void setImages( Image[] image )

Parameters

image

A zero-based array of Image objects that represent the images you want to add to the image list.

Remarks

This method removes all existing images from the image list while inserting the new ones.

See Also getImages


 ImageList.setImageSize

ImageList.setImageSize

Sets the size of images in the image list.

Syntax

public void setImageSize( Point value )

Parameters

value

A Point object that specifies the size of images in the image list.

See Also getImageSize


 ImageList.setImageStream

ImageList.setImageStream

Sets the stream to persist the image list to and depersist the image list from.

Syntax

public void setImageStream( ImageListStreamer ils )

Parameters

ils

An ImageListStreamer object that represents the stream to persist the image list to and depersist the image list from.

See Also getImageStream


 ImageList.setMaskColor

ImageList.setMaskColor

Sets the color used to generate masks for images in the image list.

Syntax

public void setMaskColor( Color value )

Parameters

value

A Color object that represents the mask color for images in the image list.

See Also getMaskColor


 ImageList.setUseMask

ImageList.setUseMask

Sets a boolean value indicating whether the image list uses a mask.

Syntax

public void setUseMask( boolean value )

Parameters

value

Set to true if the image list uses a mask; otherwise, set to false.

See Also getUseMask


ImageListStreamer Class

Allows an ImageList object to be persisted to a stream and depersisted from a stream.

package com.ms.wfc.ui

public class ImageListStreamer
implements IPersistable


 ImageListStreamer Methods

ImageListStreamer Methods

Constructors | Description
ImageListStreamer | Creates an ImageListStreamer object.

Methods | Description
getExtension | Retrieves the file name extension for the file where this object's persistence data is saved.
save | Saves the images in the ImageList object to the specified data stream.


 ImageListStreamer.getExtension

ImageListStreamer.getExtension

Retrieves the file name extension for the file where this object's persistence data is saved.

Syntax

public String getExtension()

Return Value

Returns a file name extension to use during object persistence.

See Also IPersistable


 ImageListStreamer.ImageListStreamer

ImageListStreamer.ImageListStreamer

Creates an ImageListStreamer object.

Syntax

public ImageListStreamer( IDataStream stream )

Parameters

stream

An IDataStream object to save the image list to.


 ImageListStreamer.save

ImageListStreamer.save

Saves the images in the ImageList object to the specified data stream.

Syntax

public void save( IDataStream stream )

Parameters

stream

An IDataStream object to save the image list to.

See Also IPersistable


InputLangChangeEvent Class

Provides data for the inputLangChange event of the Form control.

Event
  |
  +--InputLangChangeEvent

package com.ms.wfc.ui

public class InputLangChangeEvent
extends Event

Remarks

An InputLangChangeEvent object identifies the locale and the character set of the new input language.


 InputLangChangeEvent Methods

InputLangChangeEvent Methods

Constructors | Description
InputLangChangeEvent | Creates an InputLangChangeEvent object.


 InputLangChangeEvent.InputLangChangeEvent

InputLangChangeEvent.InputLangChangeEvent

Creates an InputLangChangeEvent object.

Syntax

public InputLangChangeEvent( Locale locale, byte charSet )

Parameters

locale

Specifies the locale of the new input language.

charSet

Specifies the character set of the new input language.


 InputLangChangeEvent Fields

InputLangChangeEvent Fields

Fields | Description
charSet | Specifies the character set associated with the new language.
locale | Specifies the locale of the new language.


 InputLangChangeEvent.charSet

InputLangChangeEvent.charSet

Specifies the character set associated with the new language.

Syntax

public final byte charSet;


 InputLangChangeEvent.locale

InputLangChangeEvent.locale

Specifies the locale of the new language.

Syntax

public final Locale locale;


InputLangChangeEventHandler Delegate

Identifies the method that will handle the inputLangChange event of a Form control.

package com.ms.wfc.data.ui

public multicast delegate
void InputLangChangeEventHandler( Object sender, InputLangChangeEvent e );

Remarks

The syntax of the InputLangChangeEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is an InputLangChangeEvent object that provides the event data.

When you create an InputLangChangeEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events.


InputLangChangeRequestEvent Class

Provides data for the inputLangChangeRequest event of the Form control.

Event
  |
  +--InputLangChangeRequestEvent

package com.ms.wfc.ui

public class InputLangChangeRequestEvent
extends Event


 InputLangChangeRequestEvent Methods

InputLangChangeRequestEvent Methods

Constructors | Description
InputLangChangeRequestEvent | Creates an InputLangChangeRequestEvent object.


 InputLangChangeRequestEvent.InputLangChangeRequestEvent

InputLangChangeRequestEvent.InputLangChangeRequestEvent

Creates an InputLangChangeRequestEvent object.

Syntax

public InputLangChangeRequestEvent( Locale locale, boolean sysCharSet, boolean acceptRequest )

Parameters

locale

The locale of the requested input language.

sysCharSet

Specifies whether the system default font supports the character set required for the requested input language. If true, the character set is supported; otherwise, it is not.

acceptRequest

Specifies whether the request to accept the input language change has been accepted. If true, the request has been accepted; otherwise, it has not.


 InputLangChangeRequestEvent Fields

InputLangChangeRequestEvent Fields

Fields | Description
acceptRequest | Specifies whether the request to change the input language should be accepted.
locale | Specifies the locale of the requested input language.
sysCharSet | Specifies whether the system default font supports the character set required for the requested input language.


 InputLangChangeRequestEvent.acceptRequest

InputLangChangeRequestEvent.acceptRequest

Specifies whether the request to change the input language should be accepted.

Syntax

public boolean acceptRequest;

Remarks

If set to false, the input language is not changed.


 InputLangChangeRequestEvent.locale

InputLangChangeRequestEvent.locale

Specifies the locale of the requested input language.

Syntax

public final Locale locale;


 InputLangChangeRequestEvent.sysCharSet

InputLangChangeRequestEvent.sysCharSet

Specifies whether the system default font supports the character set required for the requested input language.

Syntax

public final boolean sysCharSet;

Remarks

If false, the system default font does not support the character set required for the requested input language.


InputLangChangeEventHandler Delegate

InputLangChangeRequestEventHandler Delegate

Identifies the method that will handle the inputLangChangeRequest event of a Form control.

package com.ms.wfc.data.ui

public multicast delegate
void InputLangChangeRequestEventHandler( Object sender, InputLangChangeRequestEvent e );

Remarks

The syntax of the InputLangChangeRequestEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is an InputLangChangeRequestEvent object that provides the event data.

When you create an InputLangChangeRequestEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events.


ISelectionService Interface

Defines the interface for selecting components in the Forms Designer.

package com.ms.wfc.ui

public interface ISelectionService

Remarks

Use the Component.getComponentSite method to return the object that implements the IComponentSite interface for a component, and then use the IComponentSite.getService method to return the object that implements the ISelectionService interface for the component.


 ISelectionService Methods

ISelectionService Methods

Methods | Description
addOnSelectionChanged | Assigns a delegate to the selectionChanged event.
getComponentSelected | Retrieves a boolean value indicating whether this component is selected.
getSelectedComponents | Retrieves an array of all components that are selected in the Forms Designer.
removeOnSelectionChanged | Removes the delegate that is assigned to the selectionChanged event.
setSelectedComponents | Selects a set of components in the Forms Designer.
setSelectionStyle | Sets the style of the selection frame for this component.


 ISelectionService.addOnSelectionChanged

ISelectionService.addOnSelectionChanged

Assigns a delegate to the selectionChanged event.

Syntax

public void addOnSelectionChanged( EventHandler handler )

Parameters

handler

The EventHandler delegate to be notified when the event occurs.

Remarks

The selectionChanged event occurs when the user changes the components that are selected in the Forms Designer. You should keep processing during this event to a minimum to avoid decreasing the overall performance of the Forms Designer.

See Also removeOnSelectionChanged


 ISelectionService.getComponentSelected

ISelectionService.getComponentSelected

Retrieves a boolean value indicating whether this component is selected.

Syntax

public boolean getComponentSelected()

Return Value

Returns true if this component is one of the selected components in the Forms Designer; otherwise, returns false.

Remarks

Calling this method on a specific component is faster than retrieving an array of all selected components. To change the selection in the Forms Designer, use the setSelectedComponents method.


 ISelectionService.getSelectedComponents

ISelectionService.getSelectedComponents

Retrieves an array of all components that are selected in the Forms Designer.

Syntax

public IComponent [] getSelectedComponents()

Return Value

Returns an array of IComponent objects that represent the components that are selected in the Forms Designer.

Remarks

Calling the getComponentSelected method on a specific component is faster than retrieving the array of all selected components.


 ISelectionService.removeOnSelectionChanged

ISelectionService.removeOnSelectionChanged

Removes the delegate that is assigned to the selectionChanged event.

Syntax

public void removeOnSelectionChanged( EventHandler handler )

Parameters

handler

The EventHandler delegate to be removed.

See Also addOnSelectionChanged


 ISelectionService.setSelectedComponents

ISelectionService.setSelectedComponents

Selects a set of components in the Forms Designer.

Syntax

public void setSelectedComponents( IComponent [] components )

Parameters

components

An array of IComponent objects that represent the components to select in the Forms Designer. Either set to null or set to an empty array to indicate that nothing should be selected.

Remarks

Use this method with care. It can change the behavior of the Forms Designer's selection model.


 ISelectionService.setSelectionStyle

ISelectionService.setSelectionStyle

Sets the style of the selection frame for this component.

Syntax

public void setSelectionStyle( int style )

Parameters

style

An integer that represents the selection frame style for the component. Possible values are constants defined in the SelectionStyle class.

Remarks

Setting the selection frame style can be a useful way to help the user distinguish between different selection modes (such as in-place editing mode and static design mode) supported by a component. However, changing the selection border style does not affect the behavior of a component in the Forms Designer. To modify the component's behavior in the Forms Designer, use the design-time hit-testing feature in the ICustomizer interface.


ItemActivation Class

Defines the constants that specify the user action that is required to activate items in a the list view control and the feedback that is given as the user moves the mouse pointer over an item.

Enum
  |
  +--ItemActivation

package com.ms.wfc.ui

public class ItemActivation
extends Enum


 ItemActivation Methods

ItemActivation Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 ItemActivation.valid

ItemActivation.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 ItemActivation Fields

ItemActivation Fields

Fields | Description
ONECLICK | Specifies that the user must single-click to activate items, that the cursor changes to a hand with a pointing index finger, and that the item text changes color as the user moves the mouse pointer over the item.
STANDARD | Specifies that the user must double-click to activate items and that no feedback is given as the user moves the mouse pointer over an item.
TWOCLICK | Specifies that that the user must double-click to activate items and that the item text changes color as the user moves the mouse pointer over the item.


 ItemActivation.ONECLICK

ItemActivation.ONECLICK

Specifies that the user must single-click to activate items, that the cursor changes to a hand with a pointing index finger, and that the item text changes color as the user moves the mouse pointer over the item.

Syntax

public static final int ONECLICK;


 ItemActivation.STANDARD

ItemActivation.STANDARD

Specifies that the user must double-click to activate items and that no feedback is given as the user moves the mouse pointer over an item.

Syntax

public static final int STANDARD;


 ItemActivation.TWOCLICK

ItemActivation.TWOCLICK

Specifies that that the user must double-click to activate items and that the item text changes color as the user moves the mouse pointer over the item.

Syntax

public static final int TWOCLICK;


ItemBoundsPortion Class

Defines the constants that specify a portion of the list view item for which to retrieve the bounding rectangle.

Enum
  |
  +--ItemBoundsPortion

package com.ms.wfc.ui

public class ItemBoundsPortion
extends Enum


 ItemBoundsPortion Methods

ItemBoundsPortion Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 ItemBoundsPortion.valid

ItemBoundsPortion.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 ItemBoundsPortion Fields

ItemBoundsPortion Fields

Fields | Description
ENTIRE | Specifies that the bounding rectangle of the entire item, including the icon, the item text, and the subitem text (in Report view), should be retrieved.
ICON | Specifies that the bounding rectangle of the icon or small icon should be retrieved.
ITEMONLY | Specifies that the bounding rectangle of the icon or small icon and the item text should be retrieved.
LABEL | Specifies that the bounding rectangle of the item text should be retrieved.


 ItemBoundsPortion.ENTIRE

ItemBoundsPortion.ENTIRE

Specifies that the bounding rectangle of the entire item, including the icon, the item text, and the subitem text (in Report view), should be retrieved.

Syntax

public static final int ENTIRE;


 ItemBoundsPortion.ICON

ItemBoundsPortion.ICON

Specifies that the bounding rectangle of the icon or small icon should be retrieved.

Syntax

public static final int ICON;


 ItemBoundsPortion.ITEMONLY

ItemBoundsPortion.ITEMONLY

Specifies that the bounding rectangle of the icon or small icon and the item text should be retrieved.

Syntax

public static final int ITEMONLY;

Remarks

In all views except Report view, the ITEMONLY constant specifies the same bounding rectangle as the ENTIRE constant. In Report view, the ITEMONLY constant specifies the bounding rectangle specified by the ENTIRE constant without the subitems.


 ItemBoundsPortion.LABEL

ItemBoundsPortion.LABEL

Specifies that the bounding rectangle of the item text should be retrieved.

Syntax

public static final int LABEL;


ItemCheckEvent Class

Provides data for the itemCheck event of a CheckedListBox control.

Event
  |
  +--ItemCheckEvent

package com.ms.wfc.ui

public class ItemCheckEvent
extends Event

Remarks

The itemCheck event occurs when the checked state of an item in a checked list box changes. An ItemCheckEvent object specifies the index of the item to change, the current value of the check box for the item, and the new value to set for the check box.

For information about the WFC event model, see Handling Events in WFC.


 ItemCheckEvent Methods

ItemCheckEvent Methods

Constructors | Description
ItemCheckEvent | Creates a ItemCheckEvent object.


 ItemCheckEvent.ItemCheckEvent

ItemCheckEvent.ItemCheckEvent

Creates a ItemCheckEvent object.

Syntax

public ItemCheckEvent( int index, int newCheckValue, int currentValue )

Parameters

index

The zero-based index of the item to change.

newCheckValue

An integer that indicates whether to change the the check box for the item to be checked, unchecked, or indeterminate. Possible values are constants defined in the CheckState class.

currentValue

An integer that indicates whether the check box for the item is currently checked, unchecked, or indeterminate. Possible values are constants defined in the CheckState class.


 ItemCheckEvent Fields

ItemCheckEvent Fields

Fields | Description
currentValue | Specifies whether the check box for the item is currently checked, unchecked, or indeterminate.
index | Specifies the zero-based index of the item to change.
newValue | Specifies whether to set the the check box for the item to be checked, unchecked, or indeterminate.


 ItemCheckEvent.currentValue

ItemCheckEvent.currentValue

Specifies whether the check box for the item is currently checked, unchecked, or indeterminate.

Syntax

public final int currentValue;

Remarks

Possible values are constants defined in the CheckState class.


 ItemCheckEvent.index

ItemCheckEvent.index

Specifies the zero-based index of the item to change.

Syntax

public final int index;


 ItemCheckEvent.newValue

ItemCheckEvent.newValue

Specifies whether to set the the check box for the item to be checked, unchecked, or indeterminate.

Syntax

public int newValue;

Remarks

Possible values are constants defined in the CheckState class.


ItemCheckEventHandler Delegate

Identifies the method that will handle the itemCheck event of a CheckedListBox control.

package com.ms.wfc.ui

public multicast delegate
void ItemCheckEventHandler( Object sender, ItemCheckEvent e );

Remarks

The syntax of the ItemCheckEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a ItemCheckEvent object that provides the event data.

When you create a ItemCheckEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC.


ItemDragEvent Class

Provides data for the itemDrag event of a ListView or a TreeView control.

Event
  |
  +--ItemDragEvent

package com.ms.wfc.ui

public class ItemDragEvent
extends Event

Remarks

The itemDrag event occurs when the user begins dragging an item. An ItemDragEvent object specifies which mouse button was pressed.

For information about the WFC event model, see Handling Events in WFC.


 ItemDragEvent Methods

ItemDragEvent Methods

Constructors | Description
ItemDragEvent | Creates an ItemDragEvent object.


 ItemDragEvent.ItemDragEvent

ItemDragEvent.ItemDragEvent

Creates an ItemDragEvent object.

Syntax

public ItemDragEvent( int button )

Parameters

button

An integer that indicates which mouse button was pressed.


 ItemDragEvent Fields

ItemDragEvent Fields

Fields | Description
button | Specifies which mouse button was pressed.


 ItemDragEvent.button

ItemDragEvent.button

Specifies which mouse button was pressed.

Syntax

public final int button;


ItemDragEventHandler Delegate

Identifies the method that will handle the itemDrag event of a ListView or a TreeView control.

package com.ms.wfc.ui

public multicast delegate
void ItemDragEventHandler( Object sender, ItemDragEvent e );

Remarks

The syntax of the ItemDragEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a ItemDragEvent object that provides the event data.

When you create a ItemDragEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC.


ITopLevelWindow Interface

Defines the interface for a top-level window.

package com.ms.wfc.ui

public interface ITopLevelWindow

Remarks

This interface should be implemented by any visual component that can act as a top-level window.


 ITopLevelWindow Methods

ITopLevelWindow Methods

Methods | Description
getHandle | Retrieves the handle to the window represented by the implementor.


 ITopLevelWindow.getHandle

ITopLevelWindow.getHandle

Retrieves the handle to the window represented by the implementor.

Syntax

public int getHandle()

Return Value

Returns the window handle.

Remarks

This handle can be used as a parent handle for objects derived from the Control class.


Key Class

Defines constants to use for processing keyboard input.

package com.ms.wfc.ui

public class Key

Remarks

Keyboard input is identified by a key value. A key value is an integer containing the key code of the key that was pressed as well as information about any modifier keys (SHIFT, CTRL, and ALT) that were pressed at the same time. The low-order word of a key value contains the key code (which is the same as a Windows virtual key code). The high-order word of a key value contains modifier bits for the SHIFT, CTRL, and ALT keys.


 Key Fields

Key Fields

Fields | Description
A | Specifies the A key.
ADD | Specifies the Add key.
ALT | Specifies the ALT modifier key.
APPS | Specifies the Application key (Microsoft Natural Keyboard).
ATTN | Specifies the ATTN key.
B | Specifies the B key.
BACK | Specifies the BACKSPACE key.
C | Specifies the C key.
CANCEL | Specifies the CANCEL key.
CAPITAL | Specifies the CAPS LOCK key.
CLEAR | Specifies the CLEAR key.
CONTROL | Specifies the CTRL modifier key.
CONTROL_KEY | Specifies the CTRL key.
CRSEL | Specifies the CRSEL key.
D | Specifies the D key.
D0 | Specifies the 0 key.
D1 | Specifies the 1 key.
D2 | Specifies the 2 key.
D3 | Specifies the 3 key.
D4 | Specifies the 4 key.
D5 | Specifies the 5 key.
D6 | Specifies the 6 key.
D7 | Specifies the 7 key.
D8 | Specifies the 8 key.
D9 | Specifies the 9 key.
DECIMAL | Specifies the Decimal key.
DELETE | Specifies the DEL key.
DIVIDE | Specifies the Divide key.
DOWN | Specifies the DOWN ARROW key.
E | Specifies the E key.
END | Specifies the END key.
EREOF | Specifies the ERASE EOF key.
ESCAPE | Specifies the ESC key.
EXECUTE | Specifies the EXECUTE key.
EXSEL | Specifies the EXSEL key.
F | Specifies the F key.
F1 | Specifies the F1 key.
F10 | Specifies the F10 key.
F11 | Specifies the F11 key.
F12 | Specifies the F12 key.
F13 | Specifies the F13 key.
F14 | Specifies the F14 key.
F15 | Specifies the F15 key.
F16 | Specifies the F16 key.
F17 | Specifies the F17 key.
F18 | Specifies the F18 key.
F19 | Specifies the F19 key.
F2 | Specifies the F2 key.
F20 | Specifies the F20 key.
F21 | Specifies the F21 key.
F22 | Specifies the F22 key.
F23 | Specifies the F23 key.
F24 | Specifies the F24 key.
F3 | Specifies the F3 key.
F4 | Specifies the F4 key.
F5 | Specifies the F5 key.
F6 | Specifies the F6 key.
F7 | Specifies the F7 key.
F8 | Specifies the F8 key.
F9 | Specifies the F9 key.
G | Specifies the G key.
H | Specifies the H key.
HELP | Specifies the HELP key.
HOME | Specifies the HOME key.
I | Specifies the I key.
INSERT | Specifies the INS key.
J | Specifies the J key.
K | Specifies the K key.
KEYCODE | Specifies the bit mask to extract the key code for the key that was pressed from a key value.
L | Specifies the L key.
LBUTTON | Specifies the left mouse button.
LCONTROL_KEY | Specifies the left CTRL key.
LEFT | Specifies the LEFT ARROW key.
LMENU | Specifies the left ALT key.
LSHIFT_KEY | Specifies the left SHIFT key.
LWIN | Specifies the left Windows logo key (Microsoft Natural Keyboard).
M | Specifies the M key.
MBUTTON | Specifies the middle mouse button (three-button mouse).
MENU | Specifies the ALT key.
MODIFIERS | Specifies the bit mask to extract information about which modifier keys were pressed from a key value.
MULTIPLY | Specifies the Multiply key.
N | Specifies the N key.
NEXT | Specifies the PAGE DOWN key.
NONAME | Specifies a constant reserved for future use.
NUMLOCK | Specifies the NUM LOCK key.
NUMPAD0 | Specifies the numeric keypad 0 key.
NUMPAD1 | Specifies the numeric keypad 1 key.
NUMPAD2 | Specifies the numeric keypad 2 key.
NUMPAD3 | Specifies the numeric keypad 3 key.
NUMPAD4 | Specifies the numeric keypad 4 key.
NUMPAD5 | Specifies the numeric keypad 5 key.
NUMPAD6 | Specifies the numeric keypad 6 key.
NUMPAD7 | Specifies the numeric keypad 7 key.
NUMPAD8 | Specifies the numeric keypad 8 key.
NUMPAD9 | Specifies the numeric keypad 9 key.
O | Specifies the O key.
OEM_CLEAR | Specifies the CLEAR key.
P | Specifies the P key.
PA1 | Specifies the PA1 key.
PAUSE | Specifies the PAUSE key.
PLAY | Specifies the PLAY key.
PRINT | Specifies the PRINT key.
PRIOR | Specifies the PAGE UP key.
PROCESSKEY | Specifies the PROCESS KEY key.
Q | Specifies the Q key.
R | Specifies the R key.
RBUTTON | Specifies the right mouse button.
RCONTROL_KEY | Specifies the right CTRL key.
RETURN | Specifies the RETURN key.
RIGHT | Specifies the RIGHT ARROW key.
RMENU | Specifies the right ALT key.
RSHIFT_KEY | Specifies the right SHIFT key.
RWIN | Specifies the right Windows logo key (Microsoft Natural Keyboard).
S | Specifies the S key.
SCROLL | Specifies the SCROLL LOCK key.
SELECT | Specifies the SELECT key.
SEPARATOR | Specifies the Separator key.
SHIFT | Specifies the SHIFT modifier key.
SHIFT_KEY | Specifies the SHIFT key.
SNAPSHOT | Specifies the PRINT SCREEN key.
SPACE | Specifies the SPACEBAR key.
SUBTRACT | Specifies the Subtract key.
T | Specifies the T key.
TAB | Specifies the TAB key.
U | Specifies the U key.
UP | Specifies the UP ARROW key.
V | Specifies the V key.
W | Specifies the W key.
X | Specifies the X key.
Y | Specifies the Y key.
Z | Specifies the Z key.
ZOOM | Specifies the ZOOM key.


 Key.A

Key.A

Specifies the A key.

Syntax

public static final int A;


 Key.ADD

Key.ADD

Specifies the Add key.

Syntax

public static final int ADD;


 Key.ALT

Key.ALT

Specifies the ALT modifier key.

Syntax

public static final int ALT;


 Key.APPS

Key.APPS

Specifies the Application key (Microsoft Natural Keyboard).

Syntax

public static final int APPS;


 Key.ATTN

Key.ATTN

Specifies the ATTN key.

Syntax

public static final int ATTN;


 Key.B

Key.B

Specifies the B key.

Syntax

public static final int B;


 Key.BACK

Key.BACK

Specifies the BACKSPACE key.

Syntax

public static final int BACK;


 Key.C

Key.C

Specifies the C key.

Syntax

public static final int C;


 Key.CANCEL

Key.CANCEL

Specifies the CANCEL key.

Syntax

public static final int CANCEL;


 Key.CAPITAL

Key.CAPITAL

Specifies the CAPS LOCK key.

Syntax

public static final int CAPITAL;


 Key.CLEAR

Key.CLEAR

Specifies the CLEAR key.

Syntax

public static final int CLEAR;


 Key.CONTROL

Key.CONTROL

Specifies the CTRL modifier key.

Syntax

public static final int CONTROL;


 Key.CONTROL_KEY

Key.CONTROL_KEY

Specifies the CTRL key.

Syntax

public static final int CONTROL_KEY;


 Key.CRSEL

Key.CRSEL

Specifies the CRSEL key.

Syntax

public static final int CRSEL;


 Key.D

Key.D

Specifies the D key.

Syntax

public static final int D;


 Key.D0

Key.D0

Specifies the 0 key.

Syntax

public static final int D0;


 Key.D1

Key.D1

Specifies the 1 key.

Syntax

public static final int D1;


 Key.D2

Key.D2

Specifies the 2 key.

Syntax

public static final int D2;


 Key.D3

Key.D3

Specifies the 3 key.

Syntax

public static final int D3;


 Key.D4

Key.D4

Specifies the 4 key.

Syntax

public static final int D4;


 Key.D5

Key.D5

Specifies the 5 key.

Syntax

public static final int D5;


 Key.D6

Key.D6

Specifies the 6 key.

Syntax

public static final int D6;


 Key.D7

Key.D7

Specifies the 7 key.

Syntax

public static final int D7;


 Key.D8

Key.D8

Specifies the 8 key.

Syntax

public static final int D8;


 Key.D9

Key.D9

Specifies the 9 key.

Syntax

public static final int D9;


 Key.DECIMAL

Key.DECIMAL

Specifies the Decimal key.

Syntax

public static final int DECIMAL;


 Key.DELETE

Key.DELETE

Specifies the DEL key.

Syntax

public static final int DELETE;


 Key.DIVIDE

Key.DIVIDE

Specifies the Divide key.

Syntax

public static final int DIVIDE;


 Key.DOWN

Key.DOWN

Specifies the DOWN ARROW key.

Syntax

public static final int DOWN;


 Key.E

Key.E

Specifies the E key.

Syntax

public static final int E;


 Key.END

Key.END

Specifies the END key.

Syntax

public static final int END;


 Key.EREOF

Key.EREOF

Specifies the ERASE EOF key.

Syntax

public static final int EREOF;


 Key.ESCAPE

Key.ESCAPE

Specifies the ESC key.

Syntax

public static final int ESCAPE;


 Key.EXECUTE

Key.EXECUTE

Specifies the EXECUTE key.

Syntax

public static final int EXECUTE;


 Key.EXSEL

Key.EXSEL

Specifies the EXSEL key.

Syntax

public static final int EXSEL;


 Key.F

Key.F

Specifies the F key.

Syntax

public static final int F;


 Key.F1

Key.F1

Specifies the F1 key.

Syntax

public static final int F1;


 Key.F10

Key.F10

Specifies the F10 key.

Syntax

public static final int F10;


 Key.F11

Key.F11

Specifies the F11 key.

Syntax

public static final int F11;


 Key.F12

Key.F12

Specifies the F12 key.

Syntax

public static final int F12;


 Key.F13

Key.F13

Specifies the F13 key.

Syntax

public static final int F13;


 Key.F14

Key.F14

Specifies the F14 key.

Syntax

public static final int F14;


 Key.F15

Key.F15

Specifies the F15 key.

Syntax

public static final int F15;


 Key.F16

Key.F16

Specifies the F16 key.

Syntax

public static final int F16;


 Key.F17

Key.F17

Specifies the F17 key.

Syntax

public static final int F17;


 Key.F18

Key.F18

Specifies the F18 key.

Syntax

public static final int F18;


 Key.F19

Key.F19

Specifies the F19 key.

Syntax

public static final int F19;


 Key.F2

Key.F2

Specifies the F2 key.

Syntax

public static final int F2;


 Key.F20

Key.F20

Specifies the F20 key.

Syntax

public static final int F20;


 Key.F21

Key.F21

Specifies the F21 key.

Syntax

public static final int F21;


 Key.F22

Key.F22

Specifies the F22 key.

Syntax

public static final int F22;


 Key.F23

Key.F23

Specifies the F23 key.

Syntax

public static final int F23;


 Key.F24

Key.F24

Specifies the F24 key.

Syntax

public static final int F24;


 Key.F3

Key.F3

Specifies the F3 key.

Syntax

public static final int F3;


 Key.F4

Key.F4

Specifies the F4 key.

Syntax

public static final int F4;


 Key.F5

Key.F5

Specifies the F5 key.

Syntax

public static final int F5;


 Key.F6

Key.F6

Specifies the F6 key.

Syntax

public static final int F6;


 Key.F7

Key.F7

Specifies the F7 key.

Syntax

public static final int F7;


 Key.F8

Key.F8

Specifies the F8 key.

Syntax

public static final int F8;


 Key.F9

Key.F9

Specifies the F9 key.

Syntax

public static final int F9;


 Key.G

Key.G

Specifies the G key.

Syntax

public static final int G;


 Key.H

Key.H

Specifies the H key.

Syntax

public static final int H;


 Key.HELP

Key.HELP

Specifies the HELP key.

Syntax

public static final int HELP;


 Key.HOME

Key.HOME

Specifies the HOME key.

Syntax

public static final int HOME;


 Key.I

Key.I

Specifies the I key.

Syntax

public static final int I;


 Key.INSERT

Key.INSERT

Specifies the INS key.

Syntax

public static final int INSERT;


 Key.J

Key.J

Specifies the J key.

Syntax

public static final int J;


 Key.K

Key.K

Specifies the K key.

Syntax

public static final int K;


 Key.KEYCODE

Key.KEYCODE

Specifies the bit mask to extract the key code for the key that was pressed from a key value.

Syntax

public static final int KEYCODE;


 Key.L

Key.L

Specifies the L key.

Syntax

public static final int L;


 Key.LBUTTON

Key.LBUTTON

Specifies the left mouse button.

Syntax

public static final int LBUTTON;


 Key.LCONTROL_KEY

Key.LCONTROL_KEY

Specifies the left CTRL key.

Syntax

public static final int LCONTROL_KEY;


 Key.LEFT

Key.LEFT

Specifies the LEFT ARROW key.

Syntax

public static final int LEFT;


 Key.LMENU

Key.LMENU

Specifies the left ALT key.

Syntax

public static final int LMENU;


 Key.LSHIFT_KEY

Key.LSHIFT_KEY

Specifies the left SHIFT key.

Syntax

public static final int LSHIFT_KEY;


 Key.LWIN

Key.LWIN

Specifies the left Windows logo key (Microsoft Natural Keyboard).

Syntax

public static final int LWIN;


 Key.M

Key.M

Specifies the M key.

Syntax

public static final int M;


 Key.MBUTTON

Key.MBUTTON

Specifies the middle mouse button (three-button mouse).

Syntax

public static final int MBUTTON;


 Key.MENU

Key.MENU

Specifies the ALT key.

Syntax

public static final int MENU;


 Key.MODIFIERS

Key.MODIFIERS

Specifies the bit mask to extract information about which modifier keys were pressed from a key value.

Syntax

public static final int MODIFIERS;


 Key.MULTIPLY

Key.MULTIPLY

Specifies the Multiply key.

Syntax

public static final int MULTIPLY;


 Key.N

Key.N

Specifies the N key.

Syntax

public static final int N;


 Key.NEXT

Key.NEXT

Specifies the PAGE DOWN key.

Syntax

public static final int NEXT;


 Key.NONAME

Key.NONAME

Specifies a constant reserved for future use.

Syntax

public static final int NONAME;


 Key.NUMLOCK

Key.NUMLOCK

Specifies the NUM LOCK key.

Syntax

public static final int NUMLOCK;


 Key.NUMPAD0

Key.NUMPAD0

Specifies the numeric keypad 0 key.

Syntax

public static final int NUMPAD0;


 Key.NUMPAD1

Key.NUMPAD1

Specifies the numeric keypad 1 key.

Syntax

public static final int NUMPAD1;


 Key.NUMPAD2

Key.NUMPAD2

Specifies the numeric keypad 2 key.

Syntax

public static final int NUMPAD2;


 Key.NUMPAD3

Key.NUMPAD3

Specifies the numeric keypad 3 key.

Syntax

public static final int NUMPAD3;


 Key.NUMPAD4

Key.NUMPAD4

Specifies the numeric keypad 4 key.

Syntax

public static final int NUMPAD4;


 Key.NUMPAD5

Key.NUMPAD5

Specifies the numeric keypad 5 key.

Syntax

public static final int NUMPAD5;


 Key.NUMPAD6

Key.NUMPAD6

Specifies the numeric keypad 6 key.

Syntax

public static final int NUMPAD6;


 Key.NUMPAD7

Key.NUMPAD7

Specifies the numeric keypad 7 key.

Syntax

public static final int NUMPAD7;


 Key.NUMPAD8

Key.NUMPAD8

Specifies the numeric keypad 8 key.

Syntax

public static final int NUMPAD8;


 Key.NUMPAD9

Key.NUMPAD9

Specifies the numeric keypad 9 key.

Syntax

public static final int NUMPAD9;


 Key.O

Key.O

Specifies the O key.

Syntax

public static final int O;


 Key.OEM_CLEAR

Key.OEM_CLEAR

Specifies the CLEAR key.

Syntax

public static final int OEM_CLEAR;


 Key.P

Key.P

Specifies the P key.

Syntax

public static final int P;


 Key.PA1

Key.PA1

Specifies the PA1 key.

Syntax

public static final int PA1;


 Key.PAUSE

Key.PAUSE

Specifies the PAUSE key.

Syntax

public static final int PAUSE;


 Key.PLAY

Key.PLAY

Specifies the PLAY key.

Syntax

public static final int PLAY;


 Key.PRINT

Key.PRINT

Specifies the PRINT key.

Syntax

public static final int PRINT;


 Key.PRIOR

Key.PRIOR

Specifies the PAGE UP key.

Syntax

public static final int PRIOR;


 Key.PROCESSKEY

Key.PROCESSKEY

Specifies the PROCESS KEY key.

Syntax

public static final int PROCESSKEY;


 Key.Q

Key.Q

Specifies the Q key.

Syntax

public static final int Q;


 Key.R

Key.R

Specifies the R key.

Syntax

public static final int R;


 Key.RBUTTON

Key.RBUTTON

Specifies the right mouse button.

Syntax

public static final int RBUTTON;


 Key.RCONTROL_KEY

Key.RCONTROL_KEY

Specifies the right CTRL key.

Syntax

public static final int RCONTROL_KEY;


 Key.RETURN

Key.RETURN

Specifies the RETURN key.

Syntax

public static final int RETURN;


 Key.RIGHT

Key.RIGHT

Specifies the RIGHT ARROW key.

Syntax

public static final int RIGHT;


 Key.RMENU

Key.RMENU

Specifies the right ALT key.

Syntax

public static final int RMENU;


 Key.RSHIFT_KEY

Key.RSHIFT_KEY

Specifies the right SHIFT key.

Syntax

public static final int RSHIFT_KEY;


 Key.RWIN

Key.RWIN

Specifies the right Windows logo key (Microsoft Natural Keyboard).

Syntax

public static final int RWIN;


 Key.S

Key.S

Specifies the S key.

Syntax

public static final int S;


 Key.SCROLL

Key.SCROLL

Specifies the SCROLL LOCK key.

Syntax

public static final int SCROLL;


 Key.SELECT

Key.SELECT

Specifies the SELECT key.

Syntax

public static final int SELECT;


 Key.SEPARATOR

Key.SEPARATOR

Specifies the Separator key.

Syntax

public static final int SEPARATOR;


 Key.SHIFT

Key.SHIFT

Specifies the SHIFT modifier key.

Syntax

public static final int SHIFT;


 Key.SHIFT_KEY

Key.SHIFT_KEY

Specifies the SHIFT key.

Syntax

public static final int SHIFT_KEY;


 Key.SNAPSHOT

Key.SNAPSHOT

Specifies the PRINT SCREEN key.

Syntax

public static final int SNAPSHOT;


 Key.SPACE

Key.SPACE

Specifies the SPACEBAR key.

Syntax

public static final int SPACE;


 Key.SUBTRACT

Key.SUBTRACT

Specifies the Subtract key.

Syntax

public static final int SUBTRACT;


 Key.T

Key.T

Specifies the T key.

Syntax

public static final int T;


 Key.TAB

Key.TAB

Specifies the TAB key.

Syntax

public static final int TAB;


 Key.U

Key.U

Specifies the U key.

Syntax

public static final int U;


 Key.UP

Key.UP

Specifies the UP ARROW key.

Syntax

public static final int UP;


 Key.V

Key.V

Specifies the V key.

Syntax

public static final int V;


 Key.W

Key.W

Specifies the W key.

Syntax

public static final int W;


 Key.X

Key.X

Specifies the X key.

Syntax

public static final int X;


 Key.Y

Key.Y

Specifies the Y key.

Syntax

public static final int Y;


 Key.Z

Key.Z

Specifies the Z key.

Syntax

public static final int Z;


 Key.ZOOM

Key.ZOOM

Specifies the ZOOM key.

Syntax

public static final int ZOOM;


KeyEvent Class

Provides data for the keyDown or keyUp event of a Control object.

Event
  |
  +--KeyEvent

package com.ms.wfc.ui

public class KeyEvent
extends Event

Remarks

When the user presses a key on the keyboard, three events can be generated: The keyDown, keyUp, and keyPress events. The keyDown event occurs when the user presses a key while this control has the focus. The keyUp event occurs when the user releases a key while this control has the focus. The keyPress event occurs when the user presses a key while this control has the focus. Duplicate keyDown and keyPress events occur each time the key repeats; only one keyUp event is generated when the user releases the key.

A KeyEvent object, which specifies the key the user pressed and whether any modifier keys (CTRL, ALT, and SHIFT) were pressed at the same time, is passed with each keyDown and keyUp event. A KeyPressEvent, which specifies the character the user composed, is passed with each keyPress event.

Use the KeyEvent object when you want information about the keys the user pressed. Use the KeyPressEvent object when you want information about the character that was composed by the keys the user pressed.

You can use the logical OR (|) operator to compare data in the KeyEvent object with the constants in the Key class to extract information about modifier keys the user pressed.

For example, the following code checks if the user pressed the SHIFT+K keys:

private void Form1_keyDown(Object source, KeyEvent e)
{
   if(e.keyData == (Key.SHIFT | Key.K))
      System.out.println("The KeyEvent object knows you pressed SHIFT+K.");
}

Another way to approach this would be to check the character the user composed, rather than checking the keys the user pressed. The following example checks if the user composed an uppercase K character:

private void Form1_keyPress(Object source, KeyPressEvent e)
{
   if(e.keyChar == 'K')
      System.out.println("The KeyPressEvent object knows you pressed keys that composed an uppercase K.");
}

For information about the WFC event model, see Handling Events in WFC.


 KeyEvent Methods

KeyEvent Methods

Constructors | Description
KeyEvent | Creates a KeyEvent object.

Methods | Description
getAlt | Retrieves a boolean value indicating whether the ALT key was pressed when the event occurred.
getControl | Retrieves a boolean value indicating whether the CTRL key was pressed when the event occurred.
getKeyCode | Retrieves the key code for the key the user pressed.
getModifiers | Retrieves a value indicating which, if any, of the CTRL, SHIFT, and ALT keys were pressed when the event occurred.
getShift | Retrieves a boolean value indicating whether the SHIFT key was pressed when the event occurred.


 KeyEvent.getAlt

KeyEvent.getAlt

Retrieves a boolean value indicating whether the ALT key was pressed when the event occurred.

Syntax

public boolean getAlt()

Return Value

Returns true if the ALT key was pressed when the event occurred; otherwise, returns false.


 KeyEvent.getControl

KeyEvent.getControl

Retrieves a boolean value indicating whether the CTRL key was pressed when the event occurred.

Syntax

public boolean getControl()

Return Value

Returns true if the CTRL key was pressed when the event occurred; otherwise, returns false.


 KeyEvent.getKeyCode

KeyEvent.getKeyCode

Retrieves the key code for the key the user pressed.

Syntax

public int getKeyCode()

Return Value

Returns the key code for the key the user pressed.

Remarks

Key code constants are defined in the Key class.


 KeyEvent.getModifiers

KeyEvent.getModifiers

Retrieves a value indicating which, if any, of the CTRL, SHIFT, and ALT keys were pressed when the event occurred.

Syntax

public int getModifiers()

Return Value

Returns an integer that indicates which modifier keys were pressed.

Remarks

To determine whether a specific modifier key was pressed when a key event occurred, use the getAlt, getControl, or getShift method.


 KeyEvent.getShift

KeyEvent.getShift

Retrieves a boolean value indicating whether the SHIFT key was pressed when the event occurred.

Syntax

public boolean getShift()

Return Value

Returns true if the SHIFT key was pressed when the event occurred; otherwise, returns false.


 KeyEvent.KeyEvent

KeyEvent.KeyEvent

Creates a KeyEvent object.

Syntax

public KeyEvent( int keyData )

public KeyEvent( Object extendedInfo, int keyData )

Parameters

keyData

An integer that specifies the key constant for the key the user pressed and indicates which, if any, of the CTRL, SHIFT, and ALT keys were pressed at the same time. Possible values are obtained by applying the bitwise OR operation (|) to constants from the Key class.

extendedInfo

Additional information supplied by com.ms.wfc.html events. You should not pass a value for this parameter outside the context of the com.ms.wfc.html package. For more information, see Event.extendedInfo and DhEventInfo.


 KeyEvent Fields

KeyEvent Fields

Fields | Description
handled | Specifies whether the event is handled.
keyData | Specifies the key constant for the key the user pressed and indicates which, if any, of the CTRL, SHIFT, and ALT keys were pressed at the same time.


 KeyEvent.handled

KeyEvent.handled

Specifies whether the event is handled.

Syntax

public boolean handled;

Remarks

If the event is not handled, the message is passed on for default Windows processing. If you do not want the message to be passed on for default processing, set handled to true.


 KeyEvent.keyData

KeyEvent.keyData

Specifies the key constant for the key the user pressed and indicates which, if any, of the CTRL, SHIFT, and ALT keys were pressed at the same time.

Syntax

public final int keyData;

Remarks

You can use constants from the Key class to extract information from the keyData field. Use the logical AND (&) operator to compare data in the keyData field with constants in the Key class to extract information about which keys the user pressed. To determine whether a specific modifier key was pressed when a key event occurred, use the getAlt, getControl, or getShift method.


KeyEventHandler Delegate

Identifies the method handling the keyDown or keyUp event of a Control control.

package com.ms.wfc.ui

public multicast delegate
void KeyEventHandler( Object sender, KeyEvent e );

Remarks

The syntax of the KeyEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a KeyEvent object that provides the event data.

When you create a KeyEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC.


KeyPressEvent Class

Provides data for the keyPress event of a Control object.

Event
  |
  +--KeyPressEvent

package com.ms.wfc.ui

public class KeyPressEvent
extends Event

Remarks

When the user presses a key on the keyboard, three events can be generated: keyDown, keyUp, and keyPress. The keyDown event occurs when the user presses a key while this control has the focus. The keyUp event occurs when the user releases a key while this control has the focus. The keyPress event occurs when the user presses a key while this control has the focus. Duplicate keyDown and keyPress events occur each time the key repeats; only one keyUp event is generated when the user releases the key.

A KeyEvent object, which specifies the key the user pressed and whether any modifier keys (CTRL, ALT, and SHIFT) were pressed at the time, is passed with each keyDown and keyUp event. A KeyPressEvent, which specifies the character the user composed, is passed with each keyPress event.

Use the KeyEvent object when you want information about the keys the user pressed. Use the KeyPressEvent object when you want information about the character that was composed by the keys the user pressed.

For example, the following code checks if the user pressed the keys SHIFT+K:

private void Form1_keyDown(Object source, KeyEvent e)
{
   if(e.keyData == (Key.SHIFT | Key.K))
     System.out.println("The KeyEvent object knows you pressed SHIFT+K.");
}

Another way to approach this would be to check the character the user composed, rather than checking the keys the user pressed. The following example checks if the user composed an uppercase K character:

private void Form1_keyPress(Object source, KeyPressEvent e)
{
   if(e.keyChar == 'K')
      System.out.println("The KeyPressEvent object knows you pressed keys that composed an uppercase K.");
}

For information about the WFC event model, see Handling Events in WFC.


 KeyPressEvent Methods

KeyPressEvent Methods

Constructors | Description
KeyPressEvent | Creates KeyPressEvent object.

Methods | Description
getKeyChar | Retrieves the character the user composed.


 KeyPressEvent.getKeyChar

KeyPressEvent.getKeyChar

Retrieves the character the user composed.

Syntax

public final char getKeyChar()

Return Value

Returns the character the user composed to trigger this event.


 KeyPressEvent.KeyPressEvent

KeyPressEvent.KeyPressEvent

Creates KeyPressEvent object.

Syntax

public KeyPressEvent( char keyChar )

public KeyPressEvent( Object extendedInfo, char keyChar )

Parameters

keyChar

The character the user composed.

extendedInfo

Additional information supplied by com.ms.wfc.html events. You should not pass a value for this parameter outside the context of the com.ms.wfc.html package. For more information, see Event.extendedInfo and DhEventInfo.


 KeyPressEvent Fields

KeyPressEvent Fields

Fields | Description
handled | Specifies whether the event is handled.
keyChar | Specifies the character the user composed.


 KeyPressEvent.handled

KeyPressEvent.handled

Specifies whether the event is handled.

Syntax

public boolean handled;

Remarks

If the event is not handled, the message is passed on for default Windows processing. If you do not want the message to be passed on for default processing, set handled to true.


 KeyPressEvent.keyChar

KeyPressEvent.keyChar

Specifies the character the user composed.

Syntax

public final char keyChar;


KeyPressEventHandler Delegate

Identifies the method that will handle the keyPress event of a Control control.

package com.ms.wfc.ui

public multicast delegate
void KeyPressEventHandler( Object sender, KeyPressEvent e );

Remarks

The syntax of the KeyPressEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a KeyPressEvent object that provides the event data.

When you create a KeyPressEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered. For more information about delegates, see Handling Events in WFC.


Label Class

Encapsulates the Windows label control, which displays a string of text that the user cannot edit.

Component
  |
  +--Control
    |
    +--Label

package com.ms.wfc.ui

public class Label
extends Control

Remarks

You can use a label to display status information or to identify a control that doesn't have a built-in label. When a label control gets the focus, it passes that focus to the next control in the tab order. This allows you to specify a mnemonic key for the label that sets the focus to another control.


 Label Methods

Label Methods

Constructors | Description
Label | Creates a Label control.

Methods | Description
getAutoSize | Retrieves a boolean value indicating whether the size of the control automatically adjusts when the font is changed.
getBorderStyle | Retrieves a value indicating the kind of border the label has.
getPreferredHeight | Retrieves the preferred height for the label.
getTextAlign | Retrieves a value indicating how text is aligned in a label.
getUseMnemonic | Retrieves a value indicating whether the label interprets an ampersand (&) character in the label's text to be an access key prefix character.
setAutoSize | Sets a boolean value indicating whether the size of the control automatically adjusts when the font is changed.
setBorderStyle | Sets a value indicating the kind of border the label has.
setTextAlign | Sets a value indicating how text is aligned in a label.
setUseMnemonic | Sets a value indicating whether the label interprets an ampersand character in the label's text to be an access key prefix character.


 Label.getAutoSize

Label.getAutoSize

Retrieves a boolean value indicating whether the size of the control automatically adjusts when the font is changed.

Syntax

public final boolean getAutoSize()

Return Value

Returns true if the size of the control automatically adjusts when the font is changed; otherwise, returns false.

See Also setAutoSize


 Label.getBorderStyle

Label.getBorderStyle

Retrieves a value indicating the kind of border the label has.

Syntax

public final int getBorderStyle()

Return Value

Returns an integer that specifies the kind of border the label has. Possible return values are constants defined in the BorderStyle class. If the value is BorderStyle.FIXED_3D, the label has a three-dimensional border.

See Also setBorderStyle


 Label.getPreferredHeight

Label.getPreferredHeight

Retrieves the preferred height for the label.

Syntax

public final int getPreferredHeight()

Return Value

Returns the height, in pixels, of a single line of text displayed in the current font.


 Label.getTextAlign

Label.getTextAlign

Retrieves a value indicating how text is aligned in a label.

Syntax

public final int getTextAlign()

Return Value

Returns an integer that specifies how text is aligned in a label. Possible return values are constants defined in the HorizontalAlignment class.

See Also setTextAlign


 Label.getUseMnemonic

Label.getUseMnemonic

Retrieves a value indicating whether the label interprets an ampersand (&) character in the label's text to be an access key prefix character.

Syntax

public final boolean getUseMnemonic()

Return Value

Returns true if the label removes the ampersand character and underlines the character after the ampersand in its displayed text and treats the underlined character as an access key; returns false if the label displays any ampersand characters included in its text.

Remarks

Use the setText property to set the text for the label.

See Also setUseMnemonic


 Label.Label

Label.Label

Creates a Label control.

Syntax

public Label()


 Label.setAutoSize

Label.setAutoSize

Sets a boolean value indicating whether the size of the control automatically adjusts when the font is changed.

Syntax

public final void setAutoSize( boolean value )

Parameters

value

Set to true if the size of the control automatically adjusts when the font is changed; otherwise, set to false. The default value is true.

See Also getAutoSize


 Label.setBorderStyle

Label.setBorderStyle

Sets a value indicating the kind of border the label has.

Syntax

public final void setBorderStyle( int value )

Parameters

value

An integer that specifies the kind of border the label has. Possible return values are constants defined in the BorderStyle class. If the value is BorderStyle.FIXED_3D, the label has a three-dimensional border. The default value is BorderStyle.NONE.

Exceptions

WFCInvalidEnumException thrown if the specified value is not a valid BorderStyle constant.

See Also getBorderStyle


 Label.setTextAlign

Label.setTextAlign

Sets a value indicating how text is aligned in a label.

Syntax

public void setTextAlign( int value )

Parameters

value

An integer that specifies how text is aligned in a label. Possible values are constants defined in the HorizontalAlignment class. The default value is HorizontalAlignment.LEFT.

Exceptions

WFCInvalidEnumException thrown if the specified value is not a valid HorizontalAlignment constant.

See Also getTextAlign


 Label.setUseMnemonic

Label.setUseMnemonic

Sets a value indicating whether the label interprets an ampersand character in the label's text to be an access key prefix character.

Syntax

public final void setUseMnemonic( boolean useMnemonic )

Parameters

useMnemonic

Set to true if the label removes the ampersand character and underlines the character after the ampersand in its displayed text and treats the underlined character as an access key; set to false if the label displays any ampersand characters included in its text. The default value is true.

Remarks

If the useMnemonic property is set to true and a mnemonic character (a character preceded by the ampersand) is defined in the label text, pressing ALT+ the mnemonic character sets the focus to the control that follows the label in the tab order. Use the setText property to set the text for the label.

See Also getUseMnemonic


LabelEditEvent Class

Provides data for the afterLabelEdit event and the beforeLabelEdit event of a ListView control.

Event
  |
  +--LabelEditEvent

package com.ms.wfc.ui

public class LabelEditEvent
extends Event

Remarks

The afterLabelEdit event occurs when the user finishes editing the text for a list view item. The beforeLabelEdit event occurs when the user begins editing the text for a list view item. A LabelEditEvent object specifies the new text to associate with the list view item, the zero-based index of the list view item that contains the text to edit, and whether the edit operation has been canceled.

For information about the WFC event model, see Handling Events in WFC.


 LabelEditEvent Methods

LabelEditEvent Methods

Constructors | Description
LabelEditEvent | Creates a LabelEditEvent object.

Methods | Description
cancelEdit | Cancels the edit operation on the text of the list view item.


 LabelEditEvent.cancelEdit

LabelEditEvent.cancelEdit

Cancels the edit operation on the text of the list view item.

Syntax

public void cancelEdit()


 LabelEditEvent.LabelEditEvent

LabelEditEvent.LabelEditEvent

Creates a LabelEditEvent object.

Syntax

public LabelEditEvent( int item )

public LabelEditEvent( int item, String label )

Parameters

item

The zero-based index of the list view item containing the text to edit.

label

The new text to associate with the list view item.


 LabelEditEvent Fields

LabelEditEvent Fields

Fields | Description
cancelEdit | Specifies whether the edit has been canceled.
item | Specifies the zero-based index of the list view item containing the text to edit.
label | Specifies the new text to associate with the list view item.


 LabelEditEvent.item

LabelEditEvent.item

Specifies the zero-based index of the list view item containing the text to edit.

Syntax

public final int item;


 LabelEditEvent.label

LabelEditEvent.label

Specifies the new text to associate with the list view item.

Syntax

public final String label;


LabelEditEventHandler Delegate

Identifies the method that will handle the afterLabelEdit event and the beforeLabelEdit event of a ListView control.

package com.ms.wfc.ui

public multicast delegate
void LabelEditEventHandler( Object sender, LabelEditEvent e );

Remarks

The syntax of the LabelEditEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a LabelEditEvent object that provides the event data.

When you create a LabelEditEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC.


LayoutEvent Class

Provides data for the layout event of the Control object.

Event
  |
  +--LayoutEvent

package com.ms.wfc.ui

public final class LayoutEvent
extends Event

Remarks

The layout event occurs when a control has to lay out its child controls. Actions that make it necessary for a control to lay out its child controls include resizing, showing or hiding child controls, and adding or removing child controls. A LayoutEvent object specifies the child control that has been shown, hidden, added, or removed since the last layout operation and has made a new layout operation necessary.

For information about the WFC event model, see Handling Events in WFC.


 LayoutEvent Methods

LayoutEvent Methods

Constructors | Description
LayoutEvent | Creates a LayoutEvent object.


 LayoutEvent.LayoutEvent

LayoutEvent.LayoutEvent

Creates a LayoutEvent object.

Syntax

public LayoutEvent( Control affectedControl )

Parameters

affectedControl

The child control that has been shown, hidden, added, or removed since the last layout operation and has made a new layout operation necessary.


 LayoutEvent Fields

LayoutEvent Fields

Fields | Description
affectedControl | Specifies the child control that has been shown, hidden, added, or removed since the last layout operation and has made a new layout operation necessary.


 LayoutEvent.affectedControl

LayoutEvent.affectedControl

Specifies the child control that has been shown, hidden, added, or removed since the last layout operation and has made a new layout operation necessary.

Syntax

public final Control affectedControl;


LayoutEventHandler Delegate

Identifies the method handling the layout event of a Control control.

package com.ms.wfc.ui

public multicast delegate
void LayoutEventHandler( Object sender, LayoutEvent e );

Remarks

The syntax of the LayoutEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a LayoutEvent object that provides the event data.

When you create a LayoutEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC.


LeftRightAlignment Class

Defines constants that specify whether an object or text is aligned to the left or to the right of a reference point.

Enum
  |
  +--LeftRightAlignment

package com.ms.wfc.ui

public class LeftRightAlignment
extends Enum


 LeftRightAlignment Methods

LeftRightAlignment Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 LeftRightAlignment.valid

LeftRightAlignment.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 LeftRightAlignment Fields

LeftRightAlignment Fields

Fields | Description
LEFT | Specifies that the object or text is aligned to the left of the reference point.
RIGHT | Specifies that the object or text is aligned to the right of the reference point.


 LeftRightAlignment.LEFT

LeftRightAlignment.LEFT

Specifies that the object or text is aligned to the left of the reference point.

Syntax

public static final int LEFT;


 LeftRightAlignment.RIGHT

LeftRightAlignment.RIGHT

Specifies that the object or text is aligned to the right of the reference point.

Syntax

public static final int RIGHT;


ListBox Class

Encapsulates the Windows list box control, which displays a list from which the user can select one or more items.

Component
  |
  +--Control
    |
    +--ListBox

package com.ms.wfc.ui

public class ListBox
extends Control

Remarks

Use the addItem method to add a single item to the end of the list or to its sorted position in the list, or use the insertItem method to add a single item to a specific location in the list. If you want to add a set of items to a list box at one time, the most efficient way is to use the setItems method. Use the getSelected method to determine if a specific item in the list is selected; use the getSelectedIndex, getSelectedIndices, getSelectedItem, and getSelectedItems methods to determine which item or items in the list box are selected.


 ListBox Methods

ListBox Methods

Constructors | Description
ListBox | Creates a ListBox control.

Methods | Description
addItem | Adds an item to the list box, and returns the index of the new item.
addOnDrawItem | Assigns a delegate to the drawItem event.
addOnMeasureItem | Assigns a delegate to the measureItem event.
addOnSelectedIndexChanged | Assigns a delegate to the selectedIndexChanged event.
beginUpdate | Maintains performance while items are added to the list box one at a time by preventing the ListBox control from painting until the endUpdate method is called.
endUpdate | Resumes painting the ListBox control after painting is suspended by the beginUpdate method.
findString | Finds the first item in the list box that starts with the specified string.
findStringExact | Finds the first item in the list that exactly matches the string specified in the s parameter.
getBorderStyle | Retrieves a value indicating if the list box has a three-dimensional border, a flat single-line border, or no border.
getColumnWidth | Retrieves a value indicating the current width of each column in a multicolumn list box.
getDrawMode | Retrieves a value indicating whether the system draws the list box, whether the list box owner draws the list box with all items of equal height, or whether the list box owner draws the list box with items of variable height.
getIntegralHeight | Retrieves a boolean value indicating whether the list box should resize to avoid showing partial items.
getItem | Retrieves the item at the specified zero-based index.
getItemCount | Retrieves the number of items in the list box.
getItemHeight | Retrieves the height, in pixels, of an item in the list box.
getItemRect | Retrieves the bounding rectangle for an item in the list.
getItems | Retrieves an Object array containing all the items in the list box.
getMultiColumn | Retrieves a boolean value indicating whether the list box supports multiple columns.
getPreferredHeight | Retrieves the combined height, in pixels, of all the items in the list box.
getScrollAlwaysVisible | For single-column list boxes, retrieves a boolean value indicating whether the scroll bar always appears on the right side of the list, even when all items are visible in the list box without scrolling.
getSelected | Retrieves a boolean value indicating whether the specified item is selected.
getSelectedIndex | Retrieves the zero-based index of the currently selected item in a single-selection list box.
getSelectedIndices | Retrieves an array that contains the zero-based indices of all currently selected items.
getSelectedItem | Retrieves the currently selected item in the list.
getSelectedItems | Retrieves an array containing all selected items in a list box.
getSelectionMode | Retrieves a value indicating how many items in the list box a user can select at one time and how the user can make multiple selections.
getSorted | Retrieves a boolean value indicating whether the items in the list box are sorted alphabetically.
getTopIndex | Retrieves the zero-based index of the first visible item in a list box.
getUseTabStops | Retrieves a boolean value indicating whether a list box can recognize and expand tab characters when drawing its strings.
indexFromPoint | Retrieves the zero-based index of the item at the specified coordinates.
insertItem | Adds an item to the list box at the specified position.
onDrawItem | Triggers the drawItem event.
onMeasureItem | Triggers the measureItem event.
onSelectedIndexChanged | Triggers the selectedIndexChanged event.
removeAll | Removes all items from the list box.
removeItem | Removes the specified item from the list box.
removeOnDrawItem | Removes the delegate that is assigned to the drawItem event.
removeOnMeasureItem | Removes the delegate that is assigned to the measureItem event.
removeOnSelectedIndexChanged | Removes the delegate that is assigned to the selectedIndexChanged event.
setBorderStyle | Sets a value indicating if the list box has three-dimensional border, a flat single-line border, or no border.
setColumnWidth | Sets a value indicating the current width of each column in a multicolumn list box.
setDrawMode | Sets a value indicating whether the system draws the list box, whether the list box owner draws the list box with all items of equal height, or whether the list box owner draws the list box with items of variable height.
setIntegralHeight | Sets a boolean value indicating whether the list box should resize to avoid showing partial items.
setItem | Allows you to replace the item at the specified position in the list box.
setItemHeight | Sets the height, in pixels, of an item in the list box.
setItems | Adds a set of items to the list box.
setMultiColumn | Sets a boolean value indicating whether the list box supports multiple columns.
setScrollAlwaysVisible | For single-column list boxes, sets a boolean value indicating whether the scroll bar always appears on right side of the list, even when all items are visible in the list box without scrolling.
setSelected | Selects or clears the selection for the specified item in a multiple selection list box.
setSelectedIndex | Selects an item in a single-selection list box.
setSelectedItem | Selects the first occurrence of the specified item in a single-selection list box, and returns the zero-based index of the item.
setSelectionMode | Sets a value indicating how many items in the list box a user can select at one time and how the user can make multiple selections.
setSorted | Sets a boolean value indicating whether the items in the list box are sorted alphabetically.
setUseTabStops | Sets a boolean value indicating whether a list box can recognize and expand tab characters when drawing its strings.


 ListBox.addItem

ListBox.addItem

Adds an item to the list box, and returns the index of the new item.

Syntax

public final int addItem( Object item )

Parameters

item

An object (generally a String object) whose toString method returns the string you want to display in the list box.

Return Value

Returns index of where the item was inserted.

Remarks

If the sorted property of the list box is set to true, the item is inserted into the list alphabetically. Otherwise, the item is inserted at the end of the list. To insert an item into the list box at a specific position, use the insertItem method. To add a set of items to the list box at one time, use the setItems method.

See Also removeItem


 ListBox.addOnDrawItem

ListBox.addOnDrawItem

Assigns a delegate to the drawItem event.

Syntax

public final void addOnDrawItem( DrawItemEventHandler value )

Parameters

value

The DrawItemEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the drawItem event to that method in the Properties window. The drawItem event occurs when a visual aspect of an owner-drawn list box changes. For a list box to be owner-drawn, its drawMode property must be set to DrawMode.OWNERDRAWFIXED or DrawMode.OWNERDRAWVARIABLE. It must also contain a Graphics object in which to paint the item.

See Also removeOnDrawItem


 ListBox.addOnMeasureItem

ListBox.addOnMeasureItem

Assigns a delegate to the measureItem event.

Syntax

public final void addOnMeasureItem( MeasureItemEventHandler value )

Parameters

value

The MeasureItemEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the measureItem event to that method in the Properties window. The measureItem event occurs when an owner-drawn list box is created and the sizes of the list items are determined. For a list box to be owner-drawn, its drawMode property must be set to DrawMode.OWNERDRAWFIXED or DrawMode.OWNERDRAWVARIABLE. It must also contain a Graphics object in which to paint the item.

See Also removeOnMeasureItem


 ListBox.addOnSelectedIndexChanged

ListBox.addOnSelectedIndexChanged

Assigns a delegate to the selectedIndexChanged event.

Syntax

public final void addOnSelectedIndexChanged( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the selectedIndexChanged event to that method in the Properties window. The selectedIndexChanged event occurs when the selection in the list box changes.

See Also removeOnSelectedIndexChanged


 ListBox.beginUpdate

ListBox.beginUpdate

Maintains performance while items are added to the list box one at a time by preventing the ListBox control from painting until the endUpdate method is called.

Syntax

public final void beginUpdate()

Remarks

The preferred way to insert items is to use the setItems method to add an array of items to a list box at once. However, if you want to add items one at a time, use this method to prevent the ListBox control from painting during these operations. Call the endUpdate method when all the items have been added to the list box so that the control can resume painting.


 ListBox.endUpdate

ListBox.endUpdate

Resumes painting the ListBox control after painting is suspended by the beginUpdate method.

Syntax

public final void endUpdate()


 ListBox.findString

ListBox.findString

Finds the first item in the list box that starts with the specified string.

Syntax

public final int findString( String s )

public final int findString( String s, int startIndex )

Parameters

s

The string to match. Any string that begins with the specified characters is considered a match.

startIndex

The zero-based index of the item before the first item to be searched. Set to -1 to search from the beginning of the list box.

Return Value

Returns the zero-based index of the item found; returns ListBox.NOMATCHES if no match is found

Remarks

The search is not case sensitive.


 ListBox.findStringExact

ListBox.findStringExact

Finds the first item in the list that exactly matches the string specified in the s parameter.

Syntax

public final int findStringExact( String s )

public final int findStringExact( String s, int startIndex )

Parameters

s

The string to match exactly. Only strings that match this string in its entirety are considered matches.

startIndex

The zero-based index of the item before the first item to be searched. Set to -1 to search from the beginning of the list box.

Return Value

Returns the zero-based index of the item found; returns ListBox.NOMATCHES if no match is found.

Remarks

The search is not case sensitive.


 ListBox.getBorderStyle

ListBox.getBorderStyle

Retrieves a value indicating if the list box has a three-dimensional border, a flat single-line border, or no border.

Syntax

public final int getBorderStyle()

Return Value

Returns an integer that specifies the type of border the list box has. Possible return values are constants defined in the BorderStyle class. If the value is BorderStyle.FIXED_3D, the list box has a three-dimensional border.

See Also setBorderStyle


 ListBox.getColumnWidth

ListBox.getColumnWidth

Retrieves a value indicating the current width of each column in a multicolumn list box.

Syntax

public final int getColumnWidth()

Return Value

Returns the width, in pixels, of each column in the list box.

Remarks

A return value of zero (0) indicates that Windows assigns a default width to each column.

See Also setColumnWidth


 ListBox.getDrawMode

ListBox.getDrawMode

Retrieves a value indicating whether the system draws the list box, whether the list box owner draws the list box with all items of equal height, or whether the list box owner draws the list box with items of variable height.

Syntax

public final int getDrawMode()

Return Value

Returns an integer that specifies how the current list box is drawn. Possible return values are constants defined in the DrawMode class.

See Also setDrawMode


 ListBox.getIntegralHeight

ListBox.getIntegralHeight

Retrieves a boolean value indicating whether the list box should resize to avoid showing partial items.

Syntax

public final boolean getIntegralHeight()

Return Value

Returns true if Windows resizes the list box so that it does not display partial items; returns false if the size of the list box remains exactly the size specified by the application when it creates the list box, allowing partial items to be shown.

See Also setIntegralHeight


 ListBox.getItem

ListBox.getItem

Retrieves the item at the specified zero-based index.

Syntax

public final Object getItem( int index )

Parameters

index

The index of the item to retrieve.

Return Value

Returns an object that represents the retrieved list-box item.

Exceptions

WFCInvalidArgumentException thrown if the specified index is not valid.

See Also setItem


 ListBox.getItemCount

ListBox.getItemCount

Retrieves the number of items in the list box.

Syntax

public final int getItemCount()

Return Value

Returns the number of items in the list box.

Remarks

Because the index for a list box is zero-based, the returned count is one greater than the index value of the last item in the list.


 ListBox.getItemHeight

ListBox.getItemHeight

Retrieves the height, in pixels, of an item in the list box.

Syntax

public final int getItemHeight()

public final int getItemHeight( int index )

Parameters

index

The zero-based index of the item to return the height for.

Return Value

Returns the height, in pixels, of an item in the list.

Exceptions

WFCInvalidArgumentException thrown if the specified index is not valid. WFCWin32Exception thrown if the item height cannot be retrieved.

Remarks

For list boxes with items of variable height (list boxes whose drawMode property is set to DrawMode.OWNERDRAWVARIABLE), use the index parameter to indicate the item for which you want a height returned. If you call this method on a list box with items of variable height without supplying the index parameter, this method returns the height of the first item in the list box.

See Also setItemHeight


 ListBox.getItemRect

ListBox.getItemRect

Retrieves the bounding rectangle for an item in the list.

Syntax

public final Rectangle getItemRect( int index )

Parameters

index

The zero-based index of item whose bounding rectangle you want to return.

Return Value

Returns a Rectangle object that represents the bounding rectangle for the specified list box item.


 ListBox.getItems

ListBox.getItems

Retrieves an Object array containing all the items in the list box.

Syntax

public final Object[] getItems()

Return Value

Returns a zero-based array of objects. Items in the array are in the order they appear in the list box. If the list box contains no items, returns an empty array.

See Also setItems


 ListBox.getMultiColumn

ListBox.getMultiColumn

Retrieves a boolean value indicating whether the list box supports multiple columns.

Syntax

public final boolean getMultiColumn()

Return Value

Returns true if the list box supports multiple columns; otherwise, returns false.

Remarks

A multicolumn list box places items into as many columns as are needed to make vertical scrolling unnecessary. The user can use the keyboard to navigate to columns that are not currently visible. Use the setScrollAlwaysVisible property to display a horizontal scroll bar that allows the user to scroll to columns that are not currently shown in the list box area. The value of the columnWidth property determines the width of each column.

See Also setMultiColumn


 ListBox.getPreferredHeight

ListBox.getPreferredHeight

Retrieves the combined height, in pixels, of all the items in the list box.

Syntax

public final int getPreferredHeight()

Return Value

Returns the combined height, in pixels, of all items in the list box.


 ListBox.getScrollAlwaysVisible

ListBox.getScrollAlwaysVisible

For single-column list boxes, retrieves a boolean value indicating whether the scroll bar always appears on the right side of the list, even when all items are visible in the list box without scrolling.

Syntax

public final boolean getScrollAlwaysVisible()

Return Value

Returns a boolean value indicating whether the scroll bar should always be visible.

Remarks

By default, a scroll bar appears only when there are enough items to warrant it. For multicolumn list boxes, this method retrieves a boolean value indicating whether a horizontal scroll bar should appear at the bottom of the list box. By default, no horizontal scroll bar appears with a multicolumn list box. A multicolumn list box never has a vertical scroll bar.

See Also setScrollAlwaysVisible


 ListBox.getSelected

ListBox.getSelected

Retrieves a boolean value indicating whether the specified item is selected.

Syntax

public final boolean getSelected( int index )

Parameters

index

The zero-based index of the item you want selection information for.

Return Value

Returns true if the specified item is selected; otherwise, returns false.

Exceptions

WFCWin32Exception thrown if the selection information cannot be retrieved.

See Also setSelected


 ListBox.getSelectedIndex

ListBox.getSelectedIndex

Retrieves the zero-based index of the currently selected item in a single-selection list box.

Syntax

public final int getSelectedIndex()

Return Value

Returns the zero-based index of the currently selected item in a single-selection list box. Returns the zero-based index of the first selected item in a multiple-selection list box. If no item is currently selected, the return value is -1.

Remarks

To retrieve an array containing the indices of all selected items in a multiple-selection list box, use the getSelectedIndices method.

See Also setSelectedIndex


 ListBox.getSelectedIndices

ListBox.getSelectedIndices

Retrieves an array that contains the zero-based indices of all currently selected items.

Syntax

public final int [] getSelectedIndices()

Return Value

Returns an integer array containing the zero-based indices of all currently selected items. In a single-selection list box, returns an array containing a single element. If there are no selected items in the list box, returns an empty array.


 ListBox.getSelectedItem

ListBox.getSelectedItem

Retrieves the currently selected item in the list.

Syntax

public final Object getSelectedItem()

Return Value

Returns an object that represents the current selection in a single-selection list box. Returns an object that represents the first selected item in a multiple-selection list box. If no item is currently selected, returns null. To retrieve an array containing the all the selected items in a multiple-selection list box, use the getSelectedItems method.

See Also setSelectedItem


 ListBox.getSelectedItems

ListBox.getSelectedItems

Retrieves an array containing all selected items in a list box.

Syntax

public final Object[] getSelectedItems()

Return Value

Returns an object array containing all the currently selected items. In a single-selection list box, returns an array containing a single element. If there are no selected items in the list box, returns an empty array.


 ListBox.getSelectionMode

ListBox.getSelectionMode

Retrieves a value indicating how many items in the list box a user can select at one time and how the user can make multiple selections.

Syntax

public final int getSelectionMode()

Return Value

Returns a value that indicates the kinds of selections the user can make in the list box. Possible return values are constants defined in the SelectionMode class.

See Also setSelectionMode


 ListBox.getSorted

ListBox.getSorted

Retrieves a boolean value indicating whether the items in the list box are sorted alphabetically.

Syntax

public final boolean getSorted()

Return Value

Returns true if the list is sorted alphabetically; otherwise, returns false.

Remarks

Retrieves a boolean value indicating whether the items in the list box are sorted alphabetically.

See Also setSorted


 ListBox.getTopIndex

ListBox.getTopIndex

Retrieves the zero-based index of the first visible item in a list box.

Syntax

public final int getTopIndex()

Return Value

Returns the zero-based index of the first visible item in a list box.

Remarks

Initially, the item with the index zero (0) is at the top of the list box; if the list box contents have been scrolled, a different item can be at the top.


 ListBox.getUseTabStops

ListBox.getUseTabStops

Retrieves a boolean value indicating whether a list box can recognize and expand tab characters when drawing its strings.

Syntax

public final boolean getUseTabStops()

Return Value

Returns true if the list box can expand tab characters; otherwise, returns false.


 ListBox.indexFromPoint

ListBox.indexFromPoint

Retrieves the zero-based index of the item at the specified coordinates.

Syntax

public final int indexFromPoint( Point p )

public final int indexFromPoint( int x, int y )

Parameters

point

A Point object containing the coordinates for the point.

x

The x-coordinate of the point.

y

The y-coordinate of the point.

Return Value

Returns the zero-based index of item at the specified point; if there is no item at the specified point, returns ListBox.NOMATCHES.


 ListBox.insertItem

ListBox.insertItem

Adds an item to the list box at the specified position.

Syntax

public final void insertItem( int index, Object item )

Parameters

index

The zero-based position where you want to insert the item into the list box.

item

The object (generally a String object) whose toString property returns the string you want to display in the list box.

Exceptions

WFCInvalidArgumentException thrown if the specified index is not valid.

Remarks

Items inserted into a list box using this method are not sorted, even if the sorted property is set to true. To add an item that is inserted into the list alphabetically when the sorted property is set to true, use the addItem method.


 ListBox.ListBox

ListBox.ListBox

Creates a ListBox control.

Syntax

public ListBox()

Remarks

By default, the list box is empty. To add items to the list box, use the setItems or addItem method.


 ListBox.onDrawItem

ListBox.onDrawItem

Triggers the drawItem event.

Syntax

protected void onDrawItem( DrawItemEvent e )

Parameters

e

A DrawItemEvent object that provides notification for the event.

Remarks

When overriding this method, call super.onDrawItem.

See Also addOnDrawItem


 ListBox.onMeasureItem

ListBox.onMeasureItem

Triggers the measureItem event.

Syntax

protected void onMeasureItem( MeasureItemEvent e )

Parameters

e

A MeasureItemEvent object that provides notification for the event.

Remarks

When overriding this method, call super.onMeasureItem.

See Also addOnMeasureItem


 ListBox.onSelectedIndexChanged

ListBox.onSelectedIndexChanged

Triggers the selectedIndexChanged event.

Syntax

protected void onSelectedIndexChanged( Event e )

Parameters

e

An Event object that provides notification for the event.

Remarks

When overriding this method, call super.onSelectedIndexChanged.

See Also addOnSelectedIndexChanged


 ListBox.removeAll

ListBox.removeAll

Removes all items from the list box.

Syntax

public void removeAll()

Remarks

When you remove items from the list, all information about the deleted items is lost.


 ListBox.removeItem

ListBox.removeItem

Removes the specified item from the list box.

Syntax

public final void removeItem( int index )

public final int removeItem( Object value )

Parameters

index

The zero-based index of the item to remove.

value

The item to remove.

Exceptions

WFCInvalidArgumentException thrown if the specified index is not valid.

Return Value

The second syntax returns the zero-based index of the removed item; if the item is not found in the list, returns -1.

Remarks

When you remove an item from the list, the indices change for subsequent items in the list. All information about the deleted item is lost.

See Also addItem


 ListBox.removeOnDrawItem

ListBox.removeOnDrawItem

Removes the delegate that is assigned to the drawItem event.

Syntax

public final void removeOnDrawItem( DrawItemEventHandler value )

Parameters

value

The DrawItemEventHandler delegate to be removed.

See Also addOnDrawItem


 ListBox.removeOnMeasureItem

ListBox.removeOnMeasureItem

Removes the delegate that is assigned to the measureItem event.

Syntax

public final void removeOnMeasureItem( MeasureItemEventHandler value )

Parameters

value

The MeasureItemEventHandler delegate to be removed.

See Also addOnMeasureItem


 ListBox.removeOnSelectedIndexChanged

ListBox.removeOnSelectedIndexChanged

Removes the delegate that is assigned to the selectedIndexChanged event.

Syntax

public final void removeOnSelectedIndexChanged( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnSelectedIndexChanged


 ListBox.setBorderStyle

ListBox.setBorderStyle

Sets a value indicating if the list box has three-dimensional border, a flat single-line border, or no border.

Syntax

public final void setBorderStyle( int value )

Parameters

value

An integer that specifies the type of border the list box has. Possible values are constants defined in the BorderStyle class. If the value is BorderStyle.FIXED_3D, the list box has a three-dimensional border. The default value is BorderStyle.FIXED_3D.

Exceptions

WFCInvalidEnumException thrown if the specified value is not a valid BorderStyle constant.

See Also getBorderStyle


 ListBox.setColumnWidth

ListBox.setColumnWidth

Sets a value indicating the current width of each column in a multicolumn list box.

Syntax

public final void setColumnWidth( int value )

Parameters

value

The width, in pixels, of each column in the list box.

Exceptions

WFCInvalidArgumentException thrown if the width is less than or equal to zero.

Remarks

If you set the value to zero (0), Windows assigns a default width to each column.

See Also getColumnWidth


 ListBox.setDrawMode

ListBox.setDrawMode

Sets a value indicating whether the system draws the list box, whether the list box owner draws the list box with all items of equal height, or whether the list box owner draws the list box with items of variable height.

Syntax

public final void setDrawMode( int value )

Parameters

value

An integer that specifies how the current list box is drawn. Possible return values are constants defined in the DrawMode class. The default value is DrawMode.NORMAL.

Exceptions

WFCInvalidEnumException thrown if the specified value is not a valid DrawMode constant.

See Also getDrawMode


 ListBox.setIntegralHeight

ListBox.setIntegralHeight

Sets a boolean value indicating whether the list box should resize to avoid showing partial items.

Syntax

public final void setIntegralHeight( boolean value )

Parameters

value

Set to true if Windows resizes the list box so that it does not display partial items; set to false if the size of the list box remains the exact size specified by the application when it creates the list box, allowing partial items to be shown. The default value is true.

See Also getIntegralHeight


 ListBox.setItem

ListBox.setItem

Allows you to replace the item at the specified position in the list box.

Syntax

public final void setItem( int index, Object item )

Parameters

index

The zero-based index of the item you want to replace.

item

The new item that you want insert in the place of the item currently at the specified position.

Exceptions

WFCInvalidArgumentException thrown if the specified index is not valid.

See Also getItem


 ListBox.setItemHeight

ListBox.setItemHeight

Sets the height, in pixels, of an item in the list box.

Syntax

public final void setItemHeight( int value )

Parameters

value

The height, in pixels, of an item in the list. The default value is 15.

Exceptions

WFCInvalidArgumentException thrown if the specified value is less than one (1).

Remarks

Use this method to set the height of items in an owner-drawn list box with items of fixed height. To set the height of items in an owner-drawn list boxes with items of variable height, use the measureItem event. For list boxes that are drawn by the system, calls to this method are ignored.

See Also getItemHeight


 ListBox.setItems

ListBox.setItems

Adds a set of items to the list box.

Syntax

public final void setItems( Object[] value )

Parameters

value

A zero-based array of objects (generally String objects) whose toString methods return the strings you want to display in the list box. If the sorted property of the list box is set to true, the items are inserted into the list alphabetically. Otherwise, the items are inserted in the order they occur the array.

Remarks

This method removes all existing items from the list box before inserting the new items.

See Also getItems


 ListBox.setMultiColumn

ListBox.setMultiColumn

Sets a boolean value indicating whether the list box supports multiple columns.

Syntax

public final void setMultiColumn( boolean value )

Parameters

value

Set to true if the list box supports multiple columns; otherwise, set to false. The default value is false.

Remarks

A multicolumn list box places items into as many columns as are needed to make vertical scrolling unnecessary. The user can use the keyboard to navigate to columns that are not currently visible. Use the setScrollAlwaysVisible property to display a horizontal scroll bar that allows the user to scroll to columns that are not currently shown in the list box area. The value of the columnWidth property determines the width of each column.

See Also getMultiColumn


 ListBox.setScrollAlwaysVisible

ListBox.setScrollAlwaysVisible

For single-column list boxes, sets a boolean value indicating whether the scroll bar always appears on right side of the list, even when all items are visible in the list box without scrolling.

Syntax

public final void setScrollAlwaysVisible( boolean value )

Parameters

value

Set to true if the scroll bar should always be visible; otherwise, set to false. The default value is false.

Remarks

By default, a scroll bar appears only when there are enough items to warrant it. For multicolumn list boxes, this method sets a boolean value indicating whether a horizontal scroll bar should appear at the bottom of the list box. By default, no horizontal scroll bar appears with a multicolumn list box. A multicolumn list box never has a vertical scroll bar.

See Also getScrollAlwaysVisible


 ListBox.setSelected

ListBox.setSelected

Selects or clears the selection for the specified item in a multiple selection list box.

Syntax

public final void setSelected( int index, boolean value )

Parameters

index

The zero-based index of the item in a multiple selection list box that you want to select or clear the selection for.

value

Set to true to select the specified item; set to false to clear the selection for the specified item.

Remarks

To select an item in a single-selection list box, use the setSelectedIndex method.

Exceptions

WFCInvalidArgumentException thrown if the specified index is not valid. WFCException thrown if the selectionMode property of the list box is set to SelectionMode.NONE.

See Also getSelected


 ListBox.setSelectedIndex

ListBox.setSelectedIndex

Selects an item in a single-selection list box.

Syntax

public final void setSelectedIndex( int index )

Parameters

index

The zero-based index of the item you want to select. Set to -1 if you want no item to be selected.

Remarks

To select an item in a multiple-selection list box, use the setSelected method.

Exceptions

WFCInvalidArgumentException thrown if the specified index is not valid. WFCException thrown if the selectionMode property of the list box is set to SelectionMode.NONE.

See Also getSelectedIndex


 ListBox.setSelectedItem

ListBox.setSelectedItem

Selects the first occurrence of the specified item in a single-selection list box, and returns the zero-based index of the item.

Syntax

public final int setSelectedItem( Object value )

Parameters

value

The object (generally a String object) to select.

Return Value

Returns the zero-based index of the selected item if it exists in the list box; returns -1 if the item is not in the list box.

See Also getSelectedItem


 ListBox.setSelectionMode

ListBox.setSelectionMode

Sets a value indicating how many items in the list box a user can select at one time and how the user can make multiple selections.

Syntax

public void setSelectionMode( int value )

Parameters

value

A value that indicates the kinds of selections the user can make in the list box. Possible values are constants defined in the SelectionMode class. The default value is SelectionMode.ONE.

Exceptions

WFCInvalidEnumException thrown if the specified value is not a valid SelectionMode constant.

See Also getSelectionMode


 ListBox.setSorted

ListBox.setSorted

Sets a boolean value indicating whether the items in the list box are sorted alphabetically.

Syntax

public final void setSorted( boolean value )

Parameters

value

Set to true if the list is sorted alphabetically; otherwise, set to false. The default value is false.

See Also getSorted


 ListBox.setUseTabStops

ListBox.setUseTabStops

Sets a boolean value indicating whether a list box can recognize and expand tab characters when drawing its strings.

Syntax

public final void setUseTabStops( boolean value )

Parameters

value

Set to true if the list box can expand tab characters; otherwise, set to false. The default value is true.


 ListBox Fields

ListBox Fields

Fields | Description
NOMATCHES | Specifies that no matches are found during a search.


 ListBox.NOMATCHES

ListBox.NOMATCHES

Specifies that no matches are found during a search.

Syntax

public static final int NOMATCHES;


ListItem Class

Represents an item in a list view control.

package com.ms.wfc.ui

public class ListItem
implements Cloneable, IConstructable, IPersistable


 ListItem Methods

ListItem Methods

Constructors | Description
ListItem | Creates a ListItem object.

Methods | Description
clone | Creates an identical copy of this item.
ensureVisible | Ensures that the list item is visible, scrolling the list view control if necessary.
equals | Retrieves a boolean value indicating whether the specified object is equivalent to this ListItem object.
getBounds | Retrieves the specified portion of the bounding rectangle for a list view item.
getChecked | Retrieves a boolean value that indicates whether the check box for the list view item is checked.
getConstructorArgs | Retrieves an array of ConstructorArg objects that describe the data types and values needed to persist this object.
getExtension | Retrieves the file name extension for the file to store the item's persistent data in.
getFocused | Retrieves a boolean value indicating whether this item has the focus.
getImageIndex | Retrieves the index of the image that appears next to this item.
getIndex | Retrieves the zero-based index of the item within the list view control.
getSelected | Retrieves a boolean value indicating whether this item is selected.
getStateImageIndex | Retrieves the index of the state image (an image such as a checked or cleared check box that indicates the state of the item) that appears next to this item.
getSubItem | Retrieves the specified subitem for this item.
getSubItemCount | Retrieves the number of subitems associated with this list item.
getSubItems | Retrieves all the subitems associated with this list item.
getText | Retrieves the text for this list item.
remove | Removes this item from the list view control.
save | Saves this ListItem object to the specified data stream.
setChecked | Sets a boolean value that indicates whether the check box for the list view item is checked.
setFocused | Sets a boolean value indicating whether this item has the focus.
setImageIndex | Sets the index of the image that appears next to this item.
setSelected | Sets a boolean value indicating whether this item is selected.
setStateImageIndex | Sets the index of the state image (an image such as a checked or cleared check box that indicates the state of the item) that appears next to this item.
setSubItem | Sets the text for the specified subitem.
setSubItems | Sets the subitems for the item.
setText | Sets the text for this list item.
toString | Retrieves a String object that contains the text associated with this list item.


 ListItem.clone

ListItem.clone

Creates an identical copy of this item.

Syntax

public Object clone()

Return Value

Returns a list item that has the same text, image, and subitems associated with it as the cloned item.


 ListItem.ensureVisible

ListItem.ensureVisible

Ensures that the list item is visible, scrolling the list view control if necessary.

Syntax

public void ensureVisible()


 ListItem.equals

ListItem.equals

Retrieves a boolean value indicating whether the specified object is equivalent to this ListItem object.

Syntax

public boolean equals( Object obj )

Parameters

obj

The object to compare to this ListItem object.

Return Value

Returns true if the specified object is equivalent to this ListItem object; otherwise, returns false.


 ListItem.getBounds

ListItem.getBounds

Retrieves the specified portion of the bounding rectangle for a list view item.

Syntax

public final Rectangle getBounds()

public final Rectangle getBounds( int portion )

Parameters

portion

An integer that indicates a portion of the list view item for which to retrieve the bounding rectangle. Possible values are constants defined in the ItemBoundsPortion class.

Return Value

Returns a Rectangle object that represents the bounding rectangle for the specified portion of the designated list view item.

Remarks

The bounding rectangle is measured in client coordinates. If the portion parameter is not supplied, the bounding rectangle for the entire item, including the icon, the item text, and the subitem text, is retrieved.


 ListItem.getChecked

ListItem.getChecked

Retrieves a boolean value that indicates whether the check box for the list view item is checked.

Syntax

public boolean getChecked()

Return Value

Returns true if the check box for the list view item is checked; otherwise, returns false.

See Also setChecked


 ListItem.getConstructorArgs

ListItem.getConstructorArgs

Retrieves an array of ConstructorArg objects that describe the data types and values needed to persist this object.

Syntax

public ConstructorArg[] getConstructorArgs()


 ListItem.getExtension

ListItem.getExtension

Retrieves the file name extension for the file to store the item's persistent data in.

Syntax

public String getExtension()

Return Value

Returns null.

Remarks

Because the ListItem object does not store its persistent data in a file with a file name extension, this method always returns null.

See Also IPersistable.getExtension


 ListItem.getFocused

ListItem.getFocused

Retrieves a boolean value indicating whether this item has the focus.

Syntax

public boolean getFocused()

Return Value

Returns true if this item has the focus; otherwise, returns false.

Exceptions

WFCException thrown if this item is not contained in a ListView control.

See Also setFocused


 ListItem.getImageIndex

ListItem.getImageIndex

Retrieves the index of the image that appears next to this item.

Syntax

public int getImageIndex()

Return Value

Returns the zero-based index within an ImageList object of the image that appears next to this item. The smallImageList and largeImageList properties of the ListView control that contains this item determine which image lists are associated with the list view control. Returns -1 if the imageIndex property of the item has never been set.

See Also setImageIndex


 ListItem.getIndex

ListItem.getIndex

Retrieves the zero-based index of the item within the list view control.

Syntax

public int getIndex()

Return Value

Returns the zero-based index of the item within the list view control. If the item is not contained in a list view control, returns -1.


 ListItem.getSelected

ListItem.getSelected

Retrieves a boolean value indicating whether this item is selected.

Syntax

public boolean getSelected()

Return Value

Returns true if this item is selected; otherwise, returns false.

See Also setSelected


 ListItem.getStateImageIndex

ListItem.getStateImageIndex

Retrieves the index of the state image (an image such as a checked or cleared check box that indicates the state of the item) that appears next to this item.

Syntax

public int getStateImageIndex()

Return Value

Returns the zero-based index within an ImageList object of the state image that appears next to this item.

See Also setStateImageIndex


 ListItem.getSubItem

ListItem.getSubItem

Retrieves the specified subitem for this item.

Syntax

public String getSubItem( int index )

Parameters

index

The zero-based index of the subitem whose text you want to retrieve.

Return Value

Returns the text for the specified subitem.

Exceptions

WFCInvalidArgumentException thrown if the specified index is not valid.

Remarks

For a subitem to be visible, the list view control must be in Report view, and a column must exist to display the subitem. To add a column to a list view control, use the addColumn, insertColumn, or setColumns method of the ListView control.

See Also setSubItem


 ListItem.getSubItemCount

ListItem.getSubItemCount

Retrieves the number of subitems associated with this list item.

Syntax

public int getSubItemCount()

Return Value

Returns the number of subitems associated with this list item.


 ListItem.getSubItems

ListItem.getSubItems

Retrieves all the subitems associated with this list item.

Syntax

public String[] getSubItems()

Return Value

Returns an array of strings containing the text for all the subitems associated with this list item.

Remarks

For a subitem to be visible, the list view control must be in Report view, and a column must exist to display the subitem. To add a column to a list view control, use the addColumn, insertColumn, or setColumns method of the ListView control.

See Also setSubItems


 ListItem.getText

ListItem.getText

Retrieves the text for this list item.

Syntax

public String getText()

Return Value

Returns the text for this list item.

See Also setText


 ListItem.ListItem

ListItem.ListItem

Creates a ListItem object.

Syntax

public ListItem()

public ListItem( IDataStream stream )

public ListItem( String text )

public ListItem( String text, int image )

public ListItem( String text, String[] subItems )

public ListItem( String text, int image, String[] subItems )

Parameters

stream

The IDataStream object to use to create the item.

text

The string to display for the list item.

image

The zero-based index of the image within the ImageList object associated with the ListView control that contains this item.

subItems

An array of strings that represent the subitems of the new item.


 ListItem.remove

ListItem.remove

Removes this item from the list view control.

Syntax

public void remove()


 ListItem.save

ListItem.save

Saves this ListItem object to the specified data stream.

Syntax

public void save( IDataStream stream )

Parameters

stream

The IDataStream object to write to.

See Also IPersistable


 ListItem.setChecked

ListItem.setChecked

Sets a boolean value that indicates whether the check box for the list view item is checked.

Syntax

public void setChecked( boolean value )

Parameters

value

Set to true to check the check box for the list view item; set to false to clear the check box.

Remarks

If the ListView.checkBoxes property of the list view control that contains this list view item is set to false, the effect of this method is not visible.

See Also getChecked


 ListItem.setFocused

ListItem.setFocused

Sets a boolean value indicating whether this item has the focus.

Syntax

public void setFocused( boolean value )

Parameters

value

Set to true to set the focus to this item; set to false to remove the focus from this item. Because only one item can have the focus at a time, setting the focused property to true for one item automatically sets it to false for all other items in the list view control.

See Also getFocused


 ListItem.setImageIndex

ListItem.setImageIndex

Sets the index of the image that appears next to this item.

Syntax

public void setImageIndex( int value )

Parameters

value

The zero-based index within an ImageList object of the image that appears next to this item. The smallImageList and largeImageList properties of the ListView control that contains this item determine which image lists are associated with the list view control.

See Also getImageIndex


 ListItem.setSelected

ListItem.setSelected

Sets a boolean value indicating whether this item is selected.

Syntax

public void setSelected( boolean value )

Parameters

value

Set to true to select this item; set to false to cancel the selection for this item. If the multiSelect property for the list view control is set to true, using this method adds or removes the current item from the set of selected items; if the multiSelect property is set to false, using this method to select an item automatically cancels the selection for any other items in the list view control.

See Also getSelected


 ListItem.setStateImageIndex

ListItem.setStateImageIndex

Sets the index of the state image (an image such as a checked or cleared check box that indicates the state of the item) that appears next to this item.

Syntax

public void setStateImageIndex( int imageIndex )

Parameters

imageIndex

The zero-based index within an ImageList object of the state image that appears next to this item.

Exceptions

WFCInvalidArgumentException thrown if the specified index is not valid.

Remarks

Either the stateImageList must be set to an ImageList object or the checkBoxes property must be set to true for the state images to appear next to the items.

See Also getStateImageIndex


 ListItem.setSubItem

ListItem.setSubItem

Sets the text for the specified subitem.

Syntax

public void setSubItem( int index, String text )

Parameters

index

The zero-based index of the subitem whose text you want to set.

text

The text for the specified subitem.

Exceptions

WFCInvalidArgumentException thrown if the specified index is less than zero (0).

Remarks

For a subitem to be visible, the list view control must be in Report view, and a column must exist to display the subitem. To add a column to a list view control, use the addColumn, insertColumn, or setColumns method of the ListView control.

See Also getSubItem


 ListItem.setSubItems

ListItem.setSubItems

Sets the subitems for the item.

Syntax

public void setSubItems( String[] subItems )

Parameters

subItems

An array of strings that represent the text for the subitems.

Remarks

For a subitem to be visible, the list view control must be in Report view, and a column must exist to display the subitem. To add a column to a list view control, use the addColumn, insertColumn, or setColumns method of the ListView control.

See Also getSubItems


 ListItem.setText

ListItem.setText

Sets the text for this list item.

Syntax

public void setText( String text )

Parameters

text

The text for this list item.

See Also getText


 ListItem.toString

ListItem.toString

Retrieves a String object that contains the text associated with this list item.

Syntax

public String toString()

Return Value

Returns a String object that contains the text associated with this list item.


ListView Class

Encapsulates the Windows list view control, which displays a collection of items, each consisting of an icon (from an image list) and a label.

Control
  |
  +--ListView

package com.ms.wfc.ui

public class ListView
extends Control

Remarks

List view controls can display their contents in four different ways: Large Icon view, Small Icon view, List view, or Report view. In Report view, each item can have information displayed in columns to the right of the icon and label.


 ListView Methods

ListView Methods

Constructors | Description
ListView | Creates a ListView control.

Methods | Description
addColumn | Adds a column to the list view control and returns the column header that appears at the top of the column.
addItem | Adds an item to the list view control and returns the new item.
addOnAfterLabelEdit | Assigns a delegate to the afterLabelEdit event.
addOnBeforeLabelEdit | Assigns a delegate to the beforeLabelEdit event.
addOnColumnClick | Assigns a delegate to the columnClick event.
addOnItemActivate | Assigns a delegate to the itemActivate event.
addOnItemCheck | Assigns a delegate to the itemCheck event.
addOnItemDrag | Assigns a delegate to the itemDrag event.
arrangeIcons | Arranges items in Large Icon or Small Icon view.
beginUpdate | Maintains performance while items are added to the list view control one at a time by preventing the ListView control from painting until the endUpdate method is called.
clear | Removes all items and columns from the list view control.
endUpdate | Resumes painting the ListView control after painting is suspended by the beginUpdate method.
ensureVisible | Ensures that the specified list item is visible, scrolling the list view control if necessary.
getActivation | Retrieves a value indicating what kind of action the user must take to activate an item and what sort of feedback is given to the user to show which item the mouse pointer is over.
getAlignment | Retrieves a value indicating whether items are aligned to the top or to the left of the list view control by default.
getAllowColumnReorder | Retrieves a boolean value indicating whether the user can drag and drop column headers to reorder columns in the list view control.
getAutoArrange | Retrieves a boolean value indicating whether icons are automatically kept arranged.
getBorderStyle | Retrieves a value indicating the kind of border the list view control has.
getCheckBoxes | Retrieves a boolean value indicating whether a check box appears next to each item in the list view control.
getColumn | Retrieves the column header for the specified column.
getColumnCount | Retrieves a value indicating the number of columns that appear in the list view control in Report view.
getColumns | Retrieves an array of all the column headers that appear in the list view control in Report view.
getFocusedItem | Retrieves the item in the list view control that currently has the focus.
getFullRowSelect | Retrieves a boolean value indicating whether clicking an item selects the item and all its subitems rather than just the item itself.
getGridLines | Retrieves a boolean value indicating whether gridlines appear between the rows and columns containing the items and subitems in a list view control.
getHeaderStyle | Retrieves a value indicating whether column headers are visible in Report view and, if they are visible, whether they act like buttons, allowing users to click them to carry out actions.
getHideSelection | Retrieves a boolean value indicating whether the selected item in the list view control remains highlighted when the control loses the focus.
getHoverSelection | Retrieves a boolean value indicating whether a list control item is automatically selected when the mouse pointer remains over the item for a few seconds.
getItem | Retrieves the specified item in the list view control.
getItemAt | Retrieves the item at the specified location.
getItemCount | Retrieves the number of items contained in the list view control.
getItemRect | Retrieves the specified portion of the bounding rectangle for a list view item.
getItems | Retrieves an array containing all the items in the list view control.
getItemText | Retrieves the text for the specified list view item.
getLabelEdit | Retrieves a boolean value indicating whether the user can edit the labels of list view items.
getLabelWrap | Retrieves a boolean value indicating whether item labels wrap in icon view.
getLargeImageList | Retrieves the image list control associated with Large Icon view in the list view control.
getMultiSelect | Retrieves a boolean value indicating whether multiple items in the list view control can be selected at one time.
getScrollable | Retrieves a boolean value indicating whether a scroll bar is added to the list view control when there is not enough room to display all the list view items in the control client area.
getSelectedItems | Retrieves an array containing all selected items in a list view control.
getSmallImageList | Retrieves the image list control associated with all views other than Large Icon view in the list view control.
getSorting | Retrieves a value indicating whether list items are sorted based on item text in ascending or descending order or whether items are not sorted.
getStateImageList | Retrieves the image list control associated with application-defined states in the list view control.
getTopItem | Retrieves the first visible item in a list view control.
getView | Retrieves a value that indicates how data is displayed in the list view control.
insertColumn | Inserts a column into the list view control at the specified position and returns the column header that appears at the top of the new column.
insertItem | Inserts an item into the list view control.
onAfterLabelEdit | Triggers the afterLabelEdit event.
onBeforeLabelEdit | Triggers the beforeLabelEdit event.
onColumnClick | Triggers the columnClick event.
onItemActivate | Triggers the itemActivate event.
onItemDrag | Triggers the itemDrag event.
removeAllColumns | Removes all columns from the list view control.
removeAllItems | Removes all items from the list view control.
removeColumn | Removes the specified column from the list view control.
removeItem | Removes the specified item from the list view control.
removeOnAfterLabelEdit | Removes the delegate that is assigned to the afterLabelEdit event.
removeOnBeforeLabelEdit | Removes the delegate that is assigned to the beforeLabelEdit event.
removeOnColumnClick | Removes the delegate that is assigned to the columnClick event.
removeOnItemActivate | Removes the delegate that is assigned to the itemActivate event.
removeOnItemCheck | Removes the delegate that is assigned to the itemCheck event.
removeOnItemDrag | Removes the delegate that is assigned to the itemDrag event.
setActivation | Sets a value indicating the kind of action the user must take to activate an item and the kind of feedback that is given to the user to show which item the mouse pointer is over.
setAlignment | Sets a value indicating whether items are aligned to the top or to the left of the list view control by default.
setAllowColumnReorder | Sets a boolean value indicating whether the user can drag and drop column headers to reorder columns in the list view control.
setAutoArrange | Sets a boolean value indicating whether icons are automatically kept arranged.
setBackColor | Sets the background color for the list view control.
setBorderStyle | Sets a value indicating the kind of border the list view control has.
setCheckBoxes | Sets a boolean value indicating whether a check box appears next to each item in the list view control.
setColumns | Adds a set of columns to the list view control.
setEnabled | Sets a boolean value indicating whether this control is enabled.
setForeColor | Sets the current foreground color for this control, which is the color the control uses to draw its text.
setFullRowSelect | Sets a boolean value indicating whether clicking an item selects the item and all its subitems instead of selecting just the item itself.
setGridLines | Sets a boolean value indicating whether gridlines appear around items and subitems.
setHeaderStyle | Sets a value indicating whether column headers are visible in Report view and, if they are visible, whether they act like buttons, allowing users to click them to carry out actions.
setHideSelection | Sets a boolean value indicating whether the selected item in the list view control remains highlighted when the control loses the focus.
setHoverSelection | Sets a boolean value indicating whether a list control item is automatically selected when the mouse pointer remains over the item for a few seconds.
setItems | Adds a set of items to the list view control.
setLabelEdit | Sets a boolean value indicating whether the user can edit the labels of list view items.
setLabelWrap | Sets a boolean value indicating whether item labels wrap in icon view.
setLargeImageList | Sets the image list control associated with Large Icon view in the list view control.
setMultiSelect | Sets a boolean value indicating whether multiple items can be selected at one time in the list view control.
setScrollable | Sets a boolean value indicating whether a scroll bar is added to the list view control when there is not enough room to display all of the list view items in the control client area.
setSmallImageList | Sets the image list control associated with all views other than Large Icon view in the list view control.
setSorting | Sets a value indicating whether list items are sorted based on item text in ascending or descending order or whether items are not sorted.
setStateImageList | Sets the image list control associated with application-defined states in the list view control.
setView | Sets a value that indicates how data is displayed in the list view control.


 ListView.addColumn

ListView.addColumn

Adds a column to the list view control and returns the column header that appears at the top of the column.

Syntax

public ColumnHeader addColumn( String str, int width, int textAlign )

Parameters

str

The text that appears in the header for the new column.

width

The width, in pixels, of the new column.

textAlign

The text alignment setting for the new column. Possible return values are constants defined in the HorizontalAlignment class.

Return Value

Returns a ColumnHeader object representing the header for the new column.

Remarks

The new column is inserted to the right of existing columns. To insert a column into the list view control at a specific position, use the insertColumn method. Columns are visible only in Report view.

See Also removeColumn


 ListView.addItem

ListView.addItem

Adds an item to the list view control and returns the new item.

Syntax

public ListItem addItem( ListItem listItem )

public ListItem addItem( String text )

public ListItem addItem( String text, int imageIndex )

public ListItem addItem( String text, int imageIndex, String[] subItems )

Parameters

listItem

A ListItem object containing the data for the item you want to add to the list view control.

text

The string to display for the list item.

imageIndex

The zero-based index of image within the ImageList object associated with this ListView control.

subItems

An array of strings that represent the subitems of the new item.

Return Value

Returns the ListItem object that represents the item you added to the list view control.

Remarks

If the sorting property of the list view control is set to SortOrder.ASCENDING or SortOrder.DESCENDING, the item is inserted into the list in sorted order. Otherwise, the item is inserted at the end of the list. To insert an item into the list view control at a specific position, use the insertItem method. To add a set of items to the list view control at one time, use the setItems method.

If you add a list item without specifying an image or subitems, the item is created without associated image or subitems.

See Also removeItem


 ListView.addOnAfterLabelEdit

ListView.addOnAfterLabelEdit

Assigns a delegate to the afterLabelEdit event.

Syntax

public final void addOnAfterLabelEdit( LabelEditEventHandler value )

Parameters

value

The LabelEditEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the afterLabelEdit event to that method in the Properties window. The afterLabelEdit event occurs when the user finishes modifying the text for a list view item. The new string that the user types for the item is passed to the event, and the event handler can reject the change. If the handler rejects the change, the text reverts to what it was before the user began editing the item.

See Also removeOnAfterLabelEdit


 ListView.addOnBeforeLabelEdit

ListView.addOnBeforeLabelEdit

Assigns a delegate to the beforeLabelEdit event.

Syntax

public final void addOnBeforeLabelEdit( LabelEditEventHandler value )

Parameters

value

The LabelEditEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the beforeLabelEdit event to that method in the Properties window. The beforeLabelEdit event occurs when the user begins modifying the text for a list view item. The event handler can cancel this event, and the user cannot edit the text. Use this event to prevent the user from editing specific items in the list view control. If the labelEdit property of the ListView control is set to false, the beforeLabelEdit event is not triggered. All user attempts to edit item labels are automatically rejected.

See Also removeOnBeforeLabelEdit


 ListView.addOnColumnClick

ListView.addOnColumnClick

Assigns a delegate to the columnClick event.

Syntax

public final void addOnColumnClick( ColumnClickEventHandler value )

Parameters

value

The ColumnClickEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the columnClick event to that method in the Properties window. The columnClick event occurs when the user clicks one of the column headers that are visible in Report view. A common response to clicking a column header is to sort the list view items using the clicked column as the key.

See Also removeOnColumnClick


 ListView.addOnItemActivate

ListView.addOnItemActivate

Assigns a delegate to the itemActivate event.

Syntax

public final void addOnItemActivate( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the itemActivate event to that method in the Properties window. The itemActivate event occurs when the user activates one or more items in the list view control. The user can activate an item with either a single-click or double-click, depending on the value of the activation property, or with the keyboard. The event handler should call the getSelectedItems method to determine which items are being activated.

See Also removeOnItemActivate


 ListView.addOnItemCheck

ListView.addOnItemCheck

Assigns a delegate to the itemCheck event.

Syntax

public final void addOnItemCheck( ItemCheckEventHandler value )

Parameters

value

The ItemCheckEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the itemCheck event to that method in the Properties window. The itemCheck event occurs when the check state of an item changes.

See Also removeOnItemCheck


 ListView.addOnItemDrag

ListView.addOnItemDrag

Assigns a delegate to the itemDrag event.

Syntax

public final void addOnItemDrag( ItemDragEventHandler value )

Parameters

value

The ItemDragEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the itemDrag event to that method in the Properties window. The itemDrag event occurs when the user begins dragging an item. A common response to this event is to call the doDragDrop method.

See Also removeOnItemDrag


 ListView.arrangeIcons

ListView.arrangeIcons

Arranges items in Large Icon or Small Icon view.

Syntax

public void arrangeIcons()

public void arrangeIcons( int value )

Parameters

value

An integer that indicates how to arrange the icons in Large Icon or Small Icon view. The following constants are possible values: com.ms.win32.LVA_DEFAULT aligns items according to the current value of the list view's current alignment property. com.ms.win32.LVA_ALIGNLEFT aligns items along the left edge of the control. com.ms.win32.LVA_ALIGNTOP aligns items along the top edge of the control. com.ms.win32.LVA_SNAPTOGRID snaps all icons to the nearest grid position.

Exceptions

WFCInvalidArgumentException thrown if the specified value is not one of the supported icon arrangement constants.

Remarks

Using this method with no parameters arranges the items according to the current value of the list view's alignment property.


 ListView.beginUpdate

ListView.beginUpdate

Maintains performance while items are added to the list view control one at a time by preventing the ListView control from painting until the endUpdate method is called.

Syntax

public final void beginUpdate()

Remarks

Call the endUpdate method when all the items have been added to the list view control so that the control can resume painting.


 ListView.clear

ListView.clear

Removes all items and columns from the list view control.

Syntax

public void clear()


 ListView.endUpdate

ListView.endUpdate

Resumes painting the ListView control after painting is suspended by the beginUpdate method.

Syntax

public final void endUpdate()


 ListView.ensureVisible

ListView.ensureVisible

Ensures that the specified list item is visible, scrolling the list view control if necessary.

Syntax

public void ensureVisible( int index )

Parameters

index

The zero-based index of the item to scroll into view if necessary.


 ListView.getActivation

ListView.getActivation

Retrieves a value indicating what kind of action the user must take to activate an item and what sort of feedback is given to the user to show which item the mouse pointer is over.

Syntax

public final int getActivation()

Return Value

Returns an integer that indicates what the user must do to activate an item and what sort of visual feedback helps the user determine what item the mouse pointer is currently over. Possible values are constants defined in the ItemActivation class.

See Also setActivation


 ListView.getAlignment

ListView.getAlignment

Retrieves a value indicating whether items are aligned to the top or to the left of the list view control by default.

Syntax

public final int getAlignment()

Return Value

Returns an integer that indicates whether items are aligned to the top or to the left of the list view control by default. Possible return values are constants defined in the ListViewAlignment class.

See Also setAlignment


 ListView.getAllowColumnReorder

ListView.getAllowColumnReorder

Retrieves a boolean value indicating whether the user can drag and drop column headers to reorder columns in the list view control.

Syntax

public final boolean getAllowColumnReorder()

Return Value

Returns true if drag-and-drop column reordering is allowed; otherwise, returns false.

See Also setAllowColumnReorder


 ListView.getAutoArrange

ListView.getAutoArrange

Retrieves a boolean value indicating whether icons are automatically kept arranged.

Syntax

public final boolean getAutoArrange()

Return Value

Returns true if icons are are automatically kept arranged and snapped to the grid; otherwise, returns false.

Remarks

The way the icons are arranged is determined by the current value of the alignment property.

See Also setAutoArrange


 ListView.getBorderStyle

ListView.getBorderStyle

Retrieves a value indicating the kind of border the list view control has.

Syntax

public int getBorderStyle()

Return Value

Returns an integer that specifies the kind of border the list view control has. Possible return values are constants defined in the BorderStyle class. If the value is BorderStyle.FIXED_3D, the list view control has a three-dimensional border.

See Also setBorderStyle


 ListView.getCheckBoxes

ListView.getCheckBoxes

Retrieves a boolean value indicating whether a check box appears next to each item in the list view control.

Syntax

public final boolean getCheckBoxes()

Return Value

Returns true if a check box appears next to each item in the list view control; otherwise, returns false.

See Also setCheckBoxes


 ListView.getColumn

ListView.getColumn

Retrieves the column header for the specified column.

Syntax

public final ColumnHeader getColumn( int index )

Parameters

index

The zero-based index for the column whose column header you want to retrieve.

Return Value

Returns a ColumnHeader object that represents the header for the specified column.

Exceptions

WFCInvalidArgumentException thrown if the specified index is not valid.

Remarks

To retrieve an array containing all the column headers in the list view control, use the getColumns method.


 ListView.getColumnCount

ListView.getColumnCount

Retrieves a value indicating the number of columns that appear in the list view control in Report view.

Syntax

public final int getColumnCount()

Return Value

Returns an integer that represents the number of columns that appear in the control in Report view. This number is equal to the number of column headers that have been defined for the control.


 ListView.getColumns

ListView.getColumns

Retrieves an array of all the column headers that appear in the list view control in Report view.

Syntax

public final ColumnHeader[] getColumns()

Return Value

Returns an array of ColumnHeader objects that represents the column headers that appear in the control in Report view.

Remarks

To retrieve a single column header in the list view control, use the getColumn method.

See Also setColumns


 ListView.getFocusedItem

ListView.getFocusedItem

Retrieves the item in the list view control that currently has the focus.

Syntax

public ListItem getFocusedItem()

Return Value

Returns a ListItem object that represents the item that has the focus.

Exceptions

WFCException thrown if no item has the focus.


 ListView.getFullRowSelect

ListView.getFullRowSelect

Retrieves a boolean value indicating whether clicking an item selects the item and all its subitems rather than just the item itself.

Syntax

public final boolean getFullRowSelect()

Return Value

Returns true if clicking an item selects the item and all of its subitems; returns false if clicking an item selects only the item itself.

See Also setFullRowSelect


 ListView.getGridLines

ListView.getGridLines

Retrieves a boolean value indicating whether gridlines appear between the rows and columns containing the items and subitems in a list view control.

Syntax

public final boolean getGridLines()

Return Value

Returns true if gridlines are drawn around items and subitems; otherwise, returns false.

See Also setGridLines


 ListView.getHeaderStyle

ListView.getHeaderStyle

Retrieves a value indicating whether column headers are visible in Report view and, if they are visible, whether they act like buttons, allowing users to click them to carry out actions.

Syntax

public final int getHeaderStyle()

Return Value

Returns an integer that indicates whether column headers are visible in Report view and, if they are visible, whether they act like buttons. If column headers act like buttons, users can click them to carry out an action, such as sorting the items in the list view control using the items in the clicked column as a key. Possible return values are constants defined in the ColumnHeaderStyle class.

See Also setHeaderStyle


 ListView.getHideSelection

ListView.getHideSelection

Retrieves a boolean value indicating whether the selected item in the list view control remains highlighted when the control loses the focus.

Syntax

public final boolean getHideSelection()

Return Value

Returns true if the selected item does not appear highlighted when the list view control loses the focus; returns false if the selected item still appears highlighted when the list view control loses the focus.

See Also setHideSelection


 ListView.getHoverSelection

ListView.getHoverSelection

Retrieves a boolean value indicating whether a list control item is automatically selected when the mouse pointer remains over the item for a few seconds.

Syntax

public boolean getHoverSelection()

Return Value

Returns true if an item is automatically selected when the mouse pointer hovers over it; otherwise, returns false.

See Also setHoverSelection


 ListView.getItem

ListView.getItem

Retrieves the specified item in the list view control.

Syntax

public final ListItem getItem( int index )

Parameters

index

The zero-based index of an item in the list view control.

Return Value

Returns the ListItem object that represents the item at the specified zero-based index.

Exceptions

WFCInvalidArgumentException thrown if the specified index is not valid.


 ListView.getItemAt

ListView.getItemAt

Retrieves the item at the specified location.

Syntax

public ListItem getItemAt( int x, int y )

Parameters

x

The x-coordinate of the location to test (expressed in client coordinates).

y

The y-coordinate of the location to test (expressed in client coordinates).

Return Value

Returns a ListItem object that represents the item at the specified location. If there is no item at the specified location, returns null.


 ListView.getItemCount

ListView.getItemCount

Retrieves the number of items contained in the list view control.

Syntax

public final int getItemCount()

Return Value

Returns an integer that represents the number of items the list view control contains.


 ListView.getItemRect

ListView.getItemRect

Retrieves the specified portion of the bounding rectangle for a list view item.

Syntax

public final Rectangle getItemRect( int index )

public final Rectangle getItemRect( int index, int portion )

Parameters

index

The zero-based index of item whose bounding rectangle you want to return.

portion

An integer that indicates a portion of the list view item for which to retrieve the bounding rectangle. Possible values are constants defined in the ItemBoundsPortion class.

Return Value

Returns a Rectangle object that represents the bounding rectangle for the specified portion of the specified list view item.

Remarks

If the portion parameter is not supplied, the bounding rectangle for the entire item, including the icon, item text, and subitem text, is retrieved.


 ListView.getItems

ListView.getItems

Retrieves an array containing all the items in the list view control.

Syntax

public final ListItem[] getItems()

Return Value

Returns a zero-based array of ListItem objects that represent the items in the list view control.

See Also setItems


 ListView.getItemText

ListView.getItemText

Retrieves the text for the specified list view item.

Syntax

public final String getItemText( int index )

Parameters

index

The zero-based index of the item whose text you want to retrieve.

Return Value

Returns a string that represents the label of the specified list view item.

Exceptions

WFCInvalidArgumentException thrown if the specified index is not valid.


 ListView.getLabelEdit

ListView.getLabelEdit

Retrieves a boolean value indicating whether the user can edit the labels of list view items.

Syntax

public boolean getLabelEdit()

Return Value

Returns true if the user can edit the labels of list view items at run time; otherwise, returns false.

See Also setLabelEdit


 ListView.getLabelWrap

ListView.getLabelWrap

Retrieves a boolean value indicating whether item labels wrap in icon view.

Syntax

public boolean getLabelWrap()

Return Value

Returns true if item labels wrap in icon view; returns false item labels are displayed on a single line.

See Also setLabelWrap


 ListView.getLargeImageList

ListView.getLargeImageList

Retrieves the image list control associated with Large Icon view in the list view control.

Syntax

public final ImageList getLargeImageList()

Return Value

Returns an ImageList object that contains a set of images that can be displayed next to items in Large Icon view.

See Also setLargeImageList


 ListView.getMultiSelect

ListView.getMultiSelect

Retrieves a boolean value indicating whether multiple items in the list view control can be selected at one time.

Syntax

public boolean getMultiSelect()

Return Value

Returns true if multiple items in the list view control can be selected at one time; otherwise, returns false.

See Also setMultiSelect


 ListView.getScrollable

ListView.getScrollable

Retrieves a boolean value indicating whether a scroll bar is added to the list view control when there is not enough room to display all the list view items in the control client area.

Syntax

public boolean getScrollable()

Return Value

Returns true if scroll bars are added to the control when necessary to allow the user to see all the items; otherwise, returns false.

See Also setScrollable


 ListView.getSelectedItems

ListView.getSelectedItems

Retrieves an array containing all selected items in a list view control.

Syntax

public ListItem[] getSelectedItems()

Return Value

Returns an array of ListItem objects that represents all the currently selected items. In a single-selection list view control, returns an array containing a single element. If there are no selected items in the list view control, returns an empty array.


 ListView.getSmallImageList

ListView.getSmallImageList

Retrieves the image list control associated with all views other than Large Icon view in the list view control.

Syntax

public ImageList getSmallImageList()

Return Value

Returns an ImageList object that contains a set of images that can be displayed next to items in all views other than Large Icon view.

See Also setSmallImageList


 ListView.getSorting

ListView.getSorting

Retrieves a value indicating whether list items are sorted based on item text in ascending or descending order or whether items are not sorted.

Syntax

public int getSorting()

Return Value

Returns an integer that indicates how items in the list are sorted. Possible values are constants defined in the SortOrder class.

See Also setSorting


 ListView.getStateImageList

ListView.getStateImageList

Retrieves the image list control associated with application-defined states in the list view control.

Syntax

public final ImageList getStateImageList()

Return Value

Returns an ImageList object that contains a set of state images that can be used to indicate an application-defined state of a list view item.

Remarks

State images are displayed to the left of the small or large icon for the item. You can use state images, such as selected and cleared check boxes, to indicate application-defined item states. State images are visible in all views.

See Also setStateImageList


 ListView.getTopItem

ListView.getTopItem

Retrieves the first visible item in a list view control.

Syntax

public final ListItem getTopItem()

Return Value

Returns a ListItem object that represents the first visible item in a list view control.

Exceptions

WFCException thrown if the list view control is in Large Icon or Small Icon view.

Remarks

Initially, the item with the index zero (0) is at the top of the list view control; if the list view control contents have been scrolled, a different item can be at the top.


 ListView.getView

ListView.getView

Retrieves a value that indicates how data is displayed in the list view control.

Syntax

public int getView()

Return Value

Returns an integer that represents the way displayed in the list view control. Possible return values are constants defined in the ViewEnum class.

See Also setView


 ListView.insertColumn

ListView.insertColumn

Inserts a column into the list view control at the specified position and returns the column header that appears at the top of the new column.

Syntax

public ColumnHeader insertColumn( int index, ColumnHeader ch )

public ColumnHeader insertColumn( int index, String str, int width, int textAlign )

Parameters

index

The zero-based index of the new column.

ch

A ColumnHeader object representing the header for the new column.

str

The text that appears in the header for the new column.

width

The width, in pixels, of the new column.

textAlign

The text alignment setting for the new column. Possible return values are constants defined in the HorizontalAlignment class.

Return Value

Returns a ColumnHeader object representing the header for the new column.

Exceptions

WFCInvalidArgumentException thrown if the ColumnHeader object passed as the ch parameter is equal to null or if its textAlign property is not set to a valid HorizontalAlignment constant.

WFCException thrown if the column header is already contained in another list view control or there is a problem creating the new column header.

Remarks

You can either pass an existing ColumnHeader object as the ch parameter to this method or create a ColumnHeader object based on the values of the other parameters. To insert a column into the list view control to the right of existing columns, you can use the addColumn method. Columns are visible only in Report view.


 ListView.insertItem

ListView.insertItem

Inserts an item into the list view control.

Syntax

public ListItem insertItem( int index, ListItem li )

public ListItem insertItem( int index, String text )

public ListItem insertItem( int index, String text, int imageIndex )

public ListItem insertItem( int index, String text, int imageIndex, String[] subItems )

Parameters

index

The zero-based position where you want to insert the item into the list view control.

li

The ListItem object that represents the item to insert into the list view control.

text

The string to display for the list item.

imageIndex

The zero-based index of image within the ImageList object associated with this ListView control.

subItems

An array of strings that represent the subitems of the new item.

Return Value

Returns the ListItem object that represents the item you added to the list view control.

Exceptions

WFCException thrown if the item is already contained in another list view control.

Remarks

If the sorting property of the list view control is set to SortOrder.ASCENDING or SortOrder.DESCENDING, the item is inserted into the list in sorted order. Otherwise, the item is inserted at the specified position.

If you add a list item without specifying an image or subitems, the item is created without associated image or subitems.


 ListView.ListView

ListView.ListView

Creates a ListView control.

Syntax

public ListView()


 ListView.onAfterLabelEdit

ListView.onAfterLabelEdit

Triggers the afterLabelEdit event.

Syntax

protected void onAfterLabelEdit( LabelEditEvent e )

Parameters

e

A LabelEditEvent object that provides the event data.

Remarks

When overriding this method, be sure to call super.onAfterLabelEdit.

See Also addOnAfterLabelEdit


 ListView.onBeforeLabelEdit

ListView.onBeforeLabelEdit

Triggers the beforeLabelEdit event.

Syntax

protected void onBeforeLabelEdit( LabelEditEvent e )

Parameters

e

A LabelEditEvent object that provides the event data.

Remarks

When overriding this method, be sure to call super.onBeforeLabelEdit.

See Also addOnBeforeLabelEdit


 ListView.onColumnClick

ListView.onColumnClick

Triggers the columnClick event.

Syntax

protected void onColumnClick( ColumnClickEvent e )

Parameters

e

A ColumnClickEvent object that provides the event data.

Remarks

When overriding this method, be sure to call super.onColumnClick.

See Also addOnColumnClick


 ListView.onItemActivate

ListView.onItemActivate

Triggers the itemActivate event.

Syntax

protected void onItemActivate( Event e )

Parameters

e

An Event object that provides the event data.

Remarks

When overriding this method, be sure to call super.onItemActivate.

See Also addOnItemActivate


 ListView.onItemDrag

ListView.onItemDrag

Triggers the itemDrag event.

Syntax

protected void onItemDrag( ItemDragEvent e )

Parameters

e

An ItemDragEvent object that provides the event data.

Remarks

When overriding this method, be sure to call super.onItemDrag.

See Also addOnItemDrag


 ListView.removeAllColumns

ListView.removeAllColumns

Removes all columns from the list view control.

Syntax

public void removeAllColumns()


 ListView.removeAllItems

ListView.removeAllItems

Removes all items from the list view control.

Syntax

public void removeAllItems()


 ListView.removeColumn

ListView.removeColumn

Removes the specified column from the list view control.

Syntax

public void removeColumn( int index )

Parameters

index

The zero-based index of the column to remove.

Exceptions

WFCInvalidArgumentException thrown if the specified index is not valid.

See Also addColumn


 ListView.removeItem

ListView.removeItem

Removes the specified item from the list view control.

Syntax

public void removeItem( int index )

public void removeItem( ListItem item )

Parameters

index

The zero-based index of the item to remove.

item

The ListItem object that represents the item to remove.

Exceptions

WFCInvalidArgumentException thrown if the specified index is not valid or if the specified ListItem object is null.

See Also addItem


 ListView.removeOnAfterLabelEdit

ListView.removeOnAfterLabelEdit

Removes the delegate that is assigned to the afterLabelEdit event.

Syntax

public final void removeOnAfterLabelEdit( LabelEditEventHandler value )

Parameters

value

The LabelEditEventHandler delegate to be removed.

See Also addOnAfterLabelEdit


 ListView.removeOnBeforeLabelEdit

ListView.removeOnBeforeLabelEdit

Removes the delegate that is assigned to the beforeLabelEdit event.

Syntax

public final void removeOnBeforeLabelEdit( LabelEditEventHandler value )

Parameters

value

The LabelEditEventHandler delegate to be removed.

See Also addOnBeforeLabelEdit


 ListView.removeOnColumnClick

ListView.removeOnColumnClick

Removes the delegate that is assigned to the columnClick event.

Syntax

public final void removeOnColumnClick( ColumnClickEventHandler value )

Parameters

value

The ColumnClickEventHandler delegate to be removed.

See Also addOnColumnClick


 ListView.removeOnItemActivate

ListView.removeOnItemActivate

Removes the delegate that is assigned to the itemActivate event.

Syntax

public final void removeOnItemActivate( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnItemActivate


 ListView.removeOnItemCheck

ListView.removeOnItemCheck

Removes the delegate that is assigned to the itemCheck event.

Syntax

public final void removeOnItemCheck( ItemCheckEventHandler value )

Parameters

value

The ItemCheckEventHandler delegate to be removed.

See Also addOnItemCheck


 ListView.removeOnItemDrag

ListView.removeOnItemDrag

Removes the delegate that is assigned to the itemDrag event.

Syntax

public final void removeOnItemDrag( ItemDragEventHandler value )

Parameters

value

The ItemDragEventHandler delegate to be removed.

See Also addOnItemDrag


 ListView.setActivation

ListView.setActivation

Sets a value indicating the kind of action the user must take to activate an item and the kind of feedback that is given to the user to show which item the mouse pointer is over.

Syntax

public void setActivation( int value )

Parameters

value

An integer that indicates what the user must do to activate an item and what sort of visual feedback helps the user see which item the mouse pointer is currently over. Possible values are constants defined in the ItemActivation class. The default value is ItemActivation.STANDARD.

See Also getActivation


 ListView.setAlignment

ListView.setAlignment

Sets a value indicating whether items are aligned to the top or to the left of the list view control by default.

Syntax

public void setAlignment( int value )

Parameters

value

An integer that indicates whether items are aligned to the top or to the left of the list view control by default. Possible values are constants defined in the ListViewAlignment class. The default value is ListViewAlignment.TOP.

Exceptions

WFCInvalidEnumException thrown if the specified value is not a valid ListViewAlignment constant.

See Also getAlignment


 ListView.setAllowColumnReorder

ListView.setAllowColumnReorder

Sets a boolean value indicating whether the user can drag and drop column headers to reorder columns in the list view control.

Syntax

public void setAllowColumnReorder( boolean flag )

Parameters

flag

Set to true if drag-and-drop column reordering is allowed; otherwise, set to false. The default value is false.

Remarks

Setting the value of the allowColumnReorder property has no effect unless the control is in Report view.

See Also getAllowColumnReorder


 ListView.setAutoArrange

ListView.setAutoArrange

Sets a boolean value indicating whether icons are automatically kept arranged.

Syntax

public void setAutoArrange( boolean flag )

Parameters

flag

Set to true if icons are are automatically kept arranged and snapped to the grid; otherwise, set to false. The default value is false.

Remarks

The way the icons are arranged is determined by the current value of the alignment property. Setting the value of the autoArrange property has no effect unless the control is in Large Icon or Small Icon view.

See Also getAutoArrange


 ListView.setBackColor

ListView.setBackColor

Sets the background color for the list view control.

Syntax

public void setBackColor( Color value )

Parameters

value

A Color object that represents the background color for the list view control. The default value is the system window color.


 ListView.setBorderStyle

ListView.setBorderStyle

Sets a value indicating the kind of border the list view control has.

Syntax

public void setBorderStyle( int value )

Parameters

value

An integer that specifies the kind of border the list view control has. Possible values are constants defined in the BorderStyle class. If the value is BorderStyle.FIXED_3D, the list view control has a three-dimensional border. The default value is BorderStyle.FIXED_3D.

Exceptions

WFCInvalidEnumException thrown if the specified value is not a valid BorderStyle constant.

See Also getBorderStyle


 ListView.setCheckBoxes

ListView.setCheckBoxes

Sets a boolean value indicating whether a check box appears next to each item in the list view control.

Syntax

public void setCheckBoxes( boolean flag )

Parameters

flag

Set to true if a check box appears next to each item in the list view control; otherwise, set to false. The default value is false.

See Also getCheckBoxes


 ListView.setColumns

ListView.setColumns

Adds a set of columns to the list view control.

Syntax

public void setColumns( ColumnHeader[] columns )

Parameters

columns

A zero-based array of ColumnHeader objects that represent the columns you want to add to the list view control.

Remarks

This method removes all existing columns from the list view control before inserting new columns.

See Also getColumns


 ListView.setEnabled

ListView.setEnabled

Sets a boolean value indicating whether this control is enabled.

Syntax

public void setEnabled( boolean enabled )

Parameters

enabled

Set to true to enable the control; otherwise, set to false. The default value is true.


 ListView.setForeColor

ListView.setForeColor

Sets the current foreground color for this control, which is the color the control uses to draw its text.

Syntax

public void setForeColor( Color value )

Parameters

value

A Color object that represents the color used to draw text in this control. The default value is the system window text color.


 ListView.setFullRowSelect

ListView.setFullRowSelect

Sets a boolean value indicating whether clicking an item selects the item and all its subitems instead of selecting just the item itself.

Syntax

public void setFullRowSelect( boolean flag )

Parameters

flag

Set to true if clicking an item selects the item and all its subitems; returns false if clicking an item selects only the item itself. The default value is false.

Remarks

Setting the value of the fullRowSelect property has no effect unless the control is in Report view.

See Also getFullRowSelect


 ListView.setGridLines

ListView.setGridLines

Sets a boolean value indicating whether gridlines appear around items and subitems.

Syntax

public void setGridLines( boolean flag )

Parameters

flag

Set to true if gridlines are drawn around items and subitems; otherwise, set to false. The default value is false. Setting the value of the gridLines property has no effect unless the control is in Report view.

See Also getGridLines


 ListView.setHeaderStyle

ListView.setHeaderStyle

Sets a value indicating whether column headers are visible in Report view and, if they are visible, whether they act like buttons, allowing users to click them to carry out actions.

Syntax

public void setHeaderStyle( int value )

Parameters

value

An integer that indicates whether column headers are visible in Report view and, if they are visible, whether they act like buttons. If column headers act like buttons, users can click them to carry out an action, such as sorting the items in the list view control using the items in the clicked column as a key. Possible values are constants defined in the ColumnHeaderStyle class. The default value is ColumnHeaderStyle.CLICKABLE.

Remarks

Setting the value of the allowColumnReorder property has no effect unless the control is in Report view.

See Also getHeaderStyle


 ListView.setHideSelection

ListView.setHideSelection

Sets a boolean value indicating whether the selected item in the list view control remains highlighted when the control loses the focus.

Syntax

public void setHideSelection ( boolean flag )

Parameters

final

Set to true if the selected item does not appear highlighted when the list view control loses the focus; set to false if the selected item still appears highlighted when the list view control loses the focus. The default value is true.

See Also getHideSelection


 ListView.setHoverSelection

ListView.setHoverSelection

Sets a boolean value indicating whether a list control item is automatically selected when the mouse pointer remains over the item for a few seconds.

Syntax

public void setHoverSelection( boolean flag )

Parameters

flag

Set to true if an item is automatically selected when the mouse pointer hovers over it; otherwise, set to false. The default value is false.

See Also getHoverSelection


 ListView.setItems

ListView.setItems

Adds a set of items to the list view control.

Syntax

public void setItems( ListItem[] items )

Parameters

items

A zero-based array of ListItem objects that represent the items you want to add to the list view control.

Remarks

This method removes all existing items from the list view control before inserting the new items.

See Also getItems


 ListView.setLabelEdit

ListView.setLabelEdit

Sets a boolean value indicating whether the user can edit the labels of list view items.

Syntax

public void setLabelEdit ( boolean flag )

Parameters

boolean

Set to true if the user can edit the labels of list view items at run time; otherwise, set to false. The default value is false.

See Also getLabelEdit


 ListView.setLabelWrap

ListView.setLabelWrap

Sets a boolean value indicating whether item labels wrap in icon view.

Syntax

public void setLabelWrap( boolean flag )

Parameters

flag

Set to true if item labels wrap in icon view; returns false item labels are displayed on a single line. The default value is true.

See Also getLabelWrap


 ListView.setLargeImageList

ListView.setLargeImageList

Sets the image list control associated with Large Icon view in the list view control.

Syntax

public void setLargeImageList( ImageList value )

Parameters

value

An ImageList object that contains a set of images that can be displayed next to items in Large Icon view.

See Also getLargeImageList


 ListView.setMultiSelect

ListView.setMultiSelect

Sets a boolean value indicating whether multiple items can be selected at one time in the list view control.

Syntax

public void setMultiSelect( boolean flag )

Parameters

flag

Set to true if multiple items can be selected at one time in the list view control; otherwise, set to false. The default value is true.

See Also getMultiSelect


 ListView.setScrollable

ListView.setScrollable

Sets a boolean value indicating whether a scroll bar is added to the list view control when there is not enough room to display all of the list view items in the control client area.

Syntax

public void setScrollable( boolean flag )

Parameters

flag

Set to true if scroll bars are added to the control when necessary to allow the user to see all the items; otherwise, set to false. The default value is true.

See Also getScrollable


 ListView.setSmallImageList

ListView.setSmallImageList

Sets the image list control associated with all views other than Large Icon view in the list view control.

Syntax

public void setSmallImageList( ImageList value )

Parameters

value

An ImageList object that contains a set of images that can be displayed next to items in all views other than Large Icon view.

See Also getSmallImageList


 ListView.setSorting

ListView.setSorting

Sets a value indicating whether list items are sorted based on item text in ascending or descending order or whether items are not sorted.

Syntax

public void setSorting( int value )

Parameters

value

An integer that indicates how items in the list are sorted. Possible values are constants defined in the SortOrder class. The default value is SortOrder.NONE.

See Also getSorting


 ListView.setStateImageList

ListView.setStateImageList

Sets the image list control associated with application-defined states in the list view control.

Syntax

public void setStateImageList( ImageList value )

Parameters

value

An ImageList object that contains a set of state images that can be used to indicate an application-defined state of a list view item.

Remarks

State images are displayed to the left of the small or large icon for the item. You can use state images, such as selected and cleared check boxes, to indicate application-defined item states. State images are visible in all views.

See Also getStateImageList


 ListView.setView

ListView.setView

Sets a value that indicates how data is displayed in the list view control.

Syntax

public void setView( int value )

Parameters

value

An integer that represents the way data is displayed in the list view control. Possible values are constants defined in the ViewEnum class. The default value is ViewEnum.LARGEICON.

See Also getView


ListViewAlignment Class

Defines the constants that specify how items are aligned in a list view control.

Enum
  |
  +--ListViewAlignment

package com.ms.wfc.ui

public class ListViewAlignment
extends Enum


 ListViewAlignment Methods

ListViewAlignment Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 ListViewAlignment.valid

ListViewAlignment.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 ListViewAlignment Fields

ListViewAlignment Fields

Fields | Description
LEFT | Specifies that items are aligned to the left of the list view control.
TOP | Specifies that items are aligned to the top of the list view control.


 ListViewAlignment.LEFT

ListViewAlignment.LEFT

Specifies that items are aligned to the left of the list view control.

Syntax

public static final int LEFT;


 ListViewAlignment.TOP

ListViewAlignment.TOP

Specifies that items are aligned to the top of the list view control.

Syntax

public static final int TOP;


MainMenu Class

Encapsulates the MainMenu control.

Menu
  |
  +--MainMenu

package com.ms.wfc.ui

public class MainMenu
extends Menu

Remarks

The MainMenu object enables you to programmatically take advantage of the functionality defined in the MainMenu control. Typically, to add a menu to a form you draw a MainMenu control on the form, and then use the visual editing capabilities built into the control to determine its appearance and behavior.

Generally the MainMenu control consists of one or more menus. The capabilities of each of these menus is encapsulated in the Menu class. The individual items on a menu and the operations that you can perform on these items are embodied in the MenuItem class.


 MainMenu Methods

MainMenu Methods

Constructors | Description
MainMenu | Creates a MainMenu object.

Methods | Description
cloneMenu | Creates a duplicate of this object.
dispose | Frees all the resources allocated by this object.
getForm | Retrieves a Form object that identifies the form that currently hosts the MainMenu control.


 MainMenu.cloneMenu

MainMenu.cloneMenu

Creates a duplicate of this object.

Syntax

public MainMenu cloneMenu()

Return Value

Returns a MainMenu object that is a duplicate of this one.


 MainMenu.dispose

MainMenu.dispose

Frees all the resources allocated by this object.

Syntax

public void dispose()

Remarks

If the MainMenu control is the child of a form or control, this method disconnects the main menu from its parent.


 MainMenu.getForm

MainMenu.getForm

Retrieves a Form object that identifies the form that currently hosts the MainMenu control.

Syntax

public Form getForm()

Return Value

Returns a Form object that identifies the form that currently hosts the MainMenu control. If the MainMenu control is not currently hosted on any form, this method returns null.


 MainMenu.MainMenu

MainMenu.MainMenu

Creates a MainMenu object.

Syntax

public MainMenu()

public MainMenu( MenuItem[] items )

Parameters

items

An array of MenuItem objects that specifies the initial items on the main menu.


MDIClient Class

Encapsulates an MDI container.

Control
  |
  +--MDIClient

package com.ms.wfc.ui

public class MDIClient
extends Control

Remarks

An MDI container is an MDI window that contains child windows.

You should not create instances of the MDIClient object directly; this object is used by the Form class for MDI window management.


 MDIClient Methods

MDIClient Methods

Methods | Description
add | Adds a child form to the MDI container.
getMDIChildren | Retrieves a list of the MDI child forms.
layoutMDI | Arranges the MDI child forms according to the specified layout value.
remove | Removes a child form from the MDI container.


 MDIClient.add

MDIClient.add

Adds a child form to the MDI container.

Syntax

public void add( Control ctl )

Parameters

ctl

A Control object that specifies the MDI child form to add.

Remarks

The child form specified in the ctl parameter must be a Form object that is marked as an MDI child. You should not call this method directly. Instead, you should set the child form's MDIParent property from within the Properties window or call the Form object's setMDIParent method:

// Incorrect.
Form child = new ChildForm();
this.getMDIClient().add(child);

// Correct.
Form child = new ChildForm();
child.setMDIParent(this);

See Also remove


 MDIClient.getMDIChildren

MDIClient.getMDIChildren

Retrieves a list of the MDI child forms.

Syntax

public Form[] getMDIChildren()

Return Value

Returns an array of Form objects that represent the MDI children.

Remarks

The items in the array returned by this method are sorted in the order in which the children were added to the form, not by the current z-order.


 MDIClient.layoutMDI

MDIClient.layoutMDI

Arranges the MDI child forms according to the specified layout value.

Syntax

public final void layoutMDI( int value )

Parameters

value

One of the values defined in the MDILayout class.


 MDIClient.remove

MDIClient.remove

Removes a child form from the MDI container.

Syntax

public void remove( Control ctl )

Parameters

ctl

A Control object that specifies the MDI child form to remove.

See Also add


MDILayout Class

Defines constants that specify the layout of MDI child windows.

Enum
  |
  +--MDILayout

package com.ms.wfc.ui

public class MDILayout
extends Enum


 MDILayout Methods

MDILayout Methods

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value is a valid member of this class.


 MDILayout.valid

MDILayout.valid

Retrieves a boolean value that indicates whether a specified value is a valid member of this class.

Syntax

public static boolean valid( int value )

Parameters

value

A value to compare to the constants defined in this class.

Return Value

Returns true if value is a valid member of this class; otherwise, returns false.


 MDILayout Fields

MDILayout Fields

Fields | Description
ARRANGE_ICONS | Specifies that all minimized MDI child icons should be arranged within the parent window.
CASCADE | Specifies that all MDI child windows should be cascaded in the available MDIClient region.
TILE_HORIZONTAL | Specifies that all the MDI child windows should be tiled horizontally horizontally in the available MDIClient region.
TILE_VERTICAL | Specifies that all MDI child windows should be tiled vertically in the available MDIClient region.


 MDILayout.ARRANGE_ICONS

MDILayout.ARRANGE_ICONS

Specifies that all minimized MDI child icons should be arranged within the parent window.

Syntax

public static final int ARRANGE_ICONS;


 MDILayout.CASCADE

MDILayout.CASCADE

Specifies that all MDI child windows should be cascaded in the available MDIClient region.

Syntax

public static final int CASCADE;


 MDILayout.TILE_HORIZONTAL

MDILayout.TILE_HORIZONTAL

Specifies that all the MDI child windows should be tiled horizontally horizontally in the available MDIClient region.

Syntax

public static final int TILE_HORIZONTAL;


 MDILayout.TILE_VERTICAL

MDILayout.TILE_VERTICAL

Specifies that all MDI child windows should be tiled vertically in the available MDIClient region.

Syntax

public static final int TILE_VERTICAL;


MeasureItemEvent Class

Provides data for the measureItem event of a ComboBox or ListBox control.

Event
  |
  +--MeasureItemEvent

package com.ms.wfc.ui

public class MeasureItemEvent
extends Event

Remarks

The measureItem event occurs when an owner-drawn combo box or list box is created and the sizes of the list items are determined. A MeasureItemEvent object specifies the index of the item whose height must be determined and the height of the item.

For information about the WFC event model, see Handling Events in WFC.


 MeasureItemEvent Methods

MeasureItemEvent Methods

Constructors | Description
MeasureItemEvent | Creates a MeasureItemEvent object.


 MeasureItemEvent.MeasureItemEvent

MeasureItemEvent.MeasureItemEvent

Creates a MeasureItemEvent object.

Syntax

public MeasureItemEvent( int index, int itemHeight )

Parameters

index

The zero-based index of the item whose height must be determined.

itemHeight

The height of the item at the specified index.


 MeasureItemEvent Fields

MeasureItemEvent Fields

Fields | Description
index | Specifies the zero-based index of the item whose height must be determined.
itemHeight | Specifies the height of the item at the specified index.


 MeasureItemEvent.index

MeasureItemEvent.index

Specifies the zero-based index of the item whose height must be determined.

Syntax

public final int index;


 MeasureItemEvent.itemHeight

MeasureItemEvent.itemHeight

Specifies the height of the item at the specified index.

Syntax

public int itemHeight;


MeasureItemEventHandler Delegate

Identifies the method that will handle the measureItem event of a ComboBox or a ListBox control.

package com.ms.wfc.ui

public multicast delegate
void MeasureItemEventHandler( Object sender, MeasureItemEvent e );

Remarks

The syntax of the MeasureItemEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a MeasureItemEvent object that provides the event data.

When you create a MeasureItemEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC.


Menu Class

Encapsulates a WFC menu.

Component
  |
  +--Menu

package com.ms.wfc.ui

public abstract class Menu
extends Component

Remarks

The Menu class is the base class for all WFC menu components, which includes MainMenu, MenuItem, and ContextMenu.


 Menu Methods

Menu Methods

Constructors | Description
Menu | Creates a new Menu object.

Methods | Description
add | Adds a menu item to the end of this menu.
clear | Removes all existing items from this menu.
cloneMenu | Sets this menu to be an identical copy of another menu.
dispose | Frees the resources allocated by this component.
getHandle | Returns the Win32 menu handle (HMENU) handle for this menu.
getIsParent | Retrieves a boolean value that indicates whether this menu contains items.
getMainMenu | Returns the MainMenu object that contains this menu.
getMDIListItem | Retrieves the the MDI list from this menu.
getMenuItem | Retrieves the menu item at the specified index.
getMenuItemCount | Retrieves the number of items that this menu contains.
getMenuItems | Retrieves the items in this menu.
insert | Adds a menu item to this menu at the specified index.
mergeMenu | Merges the specified menu with this one.
remove | Removes the specified menu item.
setMenuItems | Initializes this menu to contain the specified list of menu items.


 Menu.add

Menu.add

Adds a menu item to the end of this menu.

Syntax

public void add( MenuItem item )

Parameters

item

A MenuItem object that specifies the item to add.

Remarks

A menu item can be inserted into one menu at a time, and the same menu item may not be added more than once to the same menu.

See Also clear


 Menu.clear

Menu.clear

Removes all existing items from this menu.

Syntax

public void clear()

See Also add


 Menu.cloneMenu

Menu.cloneMenu

Sets this menu to be an identical copy of another menu.

Syntax

protected void cloneMenu( Menu menuSrc )

Parameters

menuSrc

A Menu object that specifies the menu to copy.


 Menu.dispose

Menu.dispose

Frees the resources allocated by this component.

Syntax

public void dispose()

Remarks

A call to this method removes the component from its container (if the component has a site) and triggers the dispose event.


 Menu.getHandle

Menu.getHandle

Returns the Win32 menu handle (HMENU) handle for this menu.

Syntax

public int getHandle()

Return Value

Returns the handle to this menu.

Remarks

Because the handle returned by this method is the underlying handle to the menu on which this object is based, callers should not attempt to free this handle.


 Menu.getIsParent

Menu.getIsParent

Retrieves a boolean value that indicates whether this menu contains items.

Syntax

public boolean getIsParent()

Return Value

Returns true if the menu contains items; otherwise, returns false.


 Menu.getMainMenu

Menu.getMainMenu

Returns the MainMenu object that contains this menu.

Syntax

public MainMenu getMainMenu()

Return Value

Returns a MainMenu object if this menu is contained by a main menu; otherwise, returns null.

Remarks

The main menu is the menu at the top of this menu's parent chain.

This method returns null if this menu is not the child of another, or if this menu is contained in a context menu.


 Menu.getMDIListItem

Menu.getMDIListItem

Retrieves the the MDI list from this menu.

Syntax

public MenuItem getMDIListItem()

Return Value

Returns a MenuItem object that specifies the MDI list, if such a list exists; otherwise, returns null.


 Menu.getMenuItem

Menu.getMenuItem

Retrieves the menu item at the specified index.

Syntax

public MenuItem getMenuItem( int index )

Parameters

index

The index of the menu item to retrieve.

Return Value

Returns a MenuItem object that specifies the requested item.

Exceptions

WFCInvalidArgumentException thrown if the value specified by the index parameter is out of range.


 Menu.getMenuItemCount

Menu.getMenuItemCount

Retrieves the number of items that this menu contains.

Syntax

public int getMenuItemCount()

Return Value

Returns the number of items in this menu.


 Menu.getMenuItems

Menu.getMenuItems

Retrieves the items in this menu.

Syntax

public MenuItem[] getMenuItems()

Return Value

Returns an array of MenuItem objects, in which each member of the array specifies one of the items in the menu.


 Menu.insert

Menu.insert

Adds a menu item to this menu at the specified index.

Syntax

public void insert( int index, MenuItem item )

Parameters

index

The zero-based index of the position at which to insert the menu.

item

A MenuItem object that specifies the item to add.

Exceptions

WFCException thrown if the item specified in the item parameter is already in another menu.

Remarks

If a menu item currently occupies the slot designated by the index parameter, the item and all items after it are moved out one slot to make room for the new item.

A menu item can be contained in one menu at a time and may not be added more than once to the same menu.


 Menu.Menu

Menu.Menu

Creates a new Menu object.

Syntax

protected Menu( MenuItem[] items )

Parameters

items

An array of MenuItem objects that specify the items to insert into the menu.

Remarks

This method is protected, and cannot be called directly, except from within a class that extends the Menu class.


 Menu.mergeMenu

Menu.mergeMenu

Merges the specified menu with this one.

Syntax

public void mergeMenu( Menu menuSrc )

Parameters

menuSrc

A Menu object that specifies the menu to merge with this one.


 Menu.remove

Menu.remove

Removes the specified menu item.

Syntax

public MenuItem remove( int index )

public void remove( MenuItem item )

Parameters

index

The zero-based index of the menu item to remove.

item

A MenuItem object that specifies the item to remove.

Return Value

Returns a MenuItem object that specifies the item that was removed.

Remarks

When a menu item is removed, all items following the removed item are moved up one position.

See Also add, clear, insert


 Menu.setMenuItems

Menu.setMenuItems

Initializes this menu to contain the specified list of menu items.

Syntax

public void setMenuItems( MenuItem[] value )

Parameters

value

An array of MenuItem objects, in which each element in the array specifies an item to add to the menu.

Remarks

A call to this method replaces all of the menu's current items.


MenuGlyph Class

Defines a group of constants that determine how a menu glyph should be drawn.

Enum
  |
  +--MenuGlyph

package com.ms.wfc.ui

public final class MenuGlyph
extends Enum

To draw a menu glyph, use the Graphics object's drawMenuGlyph method.


 MenuGlyph Methods

MenuGlyph Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 MenuGlyph.valid

MenuGlyph.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 MenuGlyph Fields

MenuGlyph Fields

Fields | Description
ARROW | Indicates that a submenu arrow should be drawn.
BULLET | Indicates that a menu bullet should be drawn.
CHECKMARK | Indicates that a menu checkmark should be drawn.


 MenuGlyph.ARROW

MenuGlyph.ARROW

Indicates that a submenu arrow should be drawn.

Syntax

public static final int ARROW;


 MenuGlyph.BULLET

MenuGlyph.BULLET

Indicates that a menu bullet should be drawn.

Syntax

public static final int BULLET;


 MenuGlyph.CHECKMARK

MenuGlyph.CHECKMARK

Indicates that a menu checkmark should be drawn.

Syntax

public static final int CHECKMARK;


MenuItem Class

Encapsulates a menu item.

Menu
  |
  +--MenuItem

package com.ms.wfc.ui

public class MenuItem
extends Menu


 MenuItem Methods

MenuItem Methods

Constructors | Description
MenuItem | Creates a MenuItem object.

Methods | Description
addOnClick | Assigns a delegate to the click event.
addOnPopup | Assigns a delegate to the popup event.
addOnSelect | Assigns a delegate to the select event.
cloneMenu | Creates a copy of this menu item.
dispose | Frees all the resources allocated by this object.
getBarBreak | Retrieves a boolean value that indicates whether this menu item has been placed on a new line (if the item is part of a menu bar) or in a new column (if the item is part of a drop-down menu, submenu, or shortcut menu).
getBreak | Retrieves a boolean value that indicates whether this menu item has been placed on a new line (if the item is part of a menu bar) or in a new column (if the item is part of a drop-down menu, submenu, or shortcut menu).
getChecked | Retrieves a boolean value that indicates whether this menu item is checked.
getDefault | Retrieves a boolean value that indicates whether this menu item is the default menu item.
getEnabled | Retrieves a boolean value that indicates whether this menu item is enabled.
getIndex | Retrieves the zero-based index of this menu item.
getIsParent | Retrieves a boolean value that indicates whether this menu item contains child items.
getMDIList | Retrieves a boolean value that indicates whether this menu item is part of a Multiple Document Interface (MDI) list.
getMenu | Retrieves the menu in which this item appears.
getMergeOrder | Retrieves the merge order for this menu item.
getMergeType | Retrieves a constant that indicates how this menu item behaves when the menu of which it is a part is merged with another menu.
getRadioCheck | Retrieves a boolean value that indicates whether a radio button is used instead of a check mark to display checked menu items.
getShortcut | Retrieves the shortcut key that is associated with this menu item.
getShowShortcut | Retrieves a boolean value that indicates whether the shortcut associated with this menu item should be displayed.
getText | Retrieves the text of this menu item.
getVisible | Retrieves a boolean value that indicates whether this menu item is visible.
mergeMenu | Merges this menu item with another menu item.
onClick | Triggers the click event.
onPopup | Triggers the popup event.
onSelect | Triggers the select event.
performSelect | Selects this menu item.
removeOnClick | Removes the delegate that is assigned to the click event.
removeOnPopup | Removes the delegate that is assigned to the popup event.
removeOnSelect | Removes the delegate that is assigned to the select event.
setBarBreak | Sets a boolean value that determines whether this menu item should be placed on a new line (if the item is part of a menu bar) or in a new column (if the item is part of a drop-down menu, submenu, or shortcut menu).
setBreak | Sets a boolean value that determines whether this menu item should be placed on a new line (if the item is part of a menu bar) or in a new column (if the item is part of a drop-down menu, submenu, or shortcut menu).
setChecked | Sets a boolean value that determines whether this menu item is checked.
setDefault | Sets a boolean value that determines whether this menu item is the default item for the submenu in which it appears.
setEnabled | Sets a boolean value that indicates whether this item is enabled.
setIndex | Sets this menu item's zero-based index.
setMDIList | Sets a boolean value that indicates whether this menu item should be populated with a list of the MDI children that appear on the form with which this menu is associated.
setMergeOrder | Sets the merge order for this menu item.
setMergeType | Specifies the merge type of this menu item.
setRadioCheck | Sets a boolean value that determines whether a radio button is used instead of a check mark to display checked menu items.
setShortcut | Associates a shortcut key with this menu item.
setShowShortcut | Sets a boolean value that indicates whether the shortcut associated with this menu item should be displayed.
setText | Sets the text for this menu item.
setVisible | Sets a boolean value that determines whether this menu item is visible.


 MenuItem.addOnClick

MenuItem.addOnClick

Assigns a delegate to the click event.

Syntax

public void addOnClick( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

The click event occurs when this menu item is clicked by the user, using either the mouse, mnemonic keys, or shortcut keys.

This event is fired only for menu items that are not submenus.


 MenuItem.addOnPopup

MenuItem.addOnPopup

Assigns a delegate to the popup event.

Syntax

public void addOnPopup( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

The popup event occurs when this item is about to be expanded to display its subitems. This event affects only menu items that are submenus.


 MenuItem.addOnSelect

MenuItem.addOnSelect

Assigns a delegate to the select event.

Syntax

public void addOnSelect( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

The select event occurs when a menu item has been selected but not yet activated.

See Also onSelect, removeOnSelect


 MenuItem.cloneMenu

MenuItem.cloneMenu

Creates a copy of this menu item.

Syntax

public MenuItem cloneMenu()

protected void cloneMenu( MenuItem itemSrc )

Parameters

itemSrc

A MenuItem object that specifies the item to copy.

Return Value

Returns a MenuItem object that is a duplicate of this object.

Remarks

The first version of this method returns a copy of this MenuItem object. The second version of this method initializes this object to be a copy of the specified MenuItem object.


 MenuItem.dispose

MenuItem.dispose

Frees all the resources allocated by this object.

Syntax

public void dispose()

Remarks

A call to this method removes the component from its container (if the component has a site) and triggers the dispose event.


 MenuItem.getBarBreak

MenuItem.getBarBreak

Retrieves a boolean value that indicates whether this menu item has been placed on a new line (if the item is part of a menu bar) or in a new column (if the item is part of a drop-down menu, submenu, or shortcut menu).

Syntax

public boolean getBarBreak()

Return Value

Returns true if this menu item has been placed on a new line or in a new column; otherwise, returns false.

See Also setBarBreak


 MenuItem.getBreak

MenuItem.getBreak

Retrieves a boolean value that indicates whether this menu item has been placed on a new line (if the item is part of a menu bar) or in a new column (if the item is part of a drop-down menu, submenu, or shortcut menu).

Syntax

public boolean getBreak()

Return Value

Returns true if the menu item has been placed on a new line or column; otherwise, returns false.

See Also setBreak


 MenuItem.getChecked

MenuItem.getChecked

Retrieves a boolean value that indicates whether this menu item is checked.

Syntax

public boolean getChecked()

Return Value

Returns true if this menu item is checked; otherwise, returns false.

See Also setChecked


 MenuItem.getDefault

MenuItem.getDefault

Retrieves a boolean value that indicates whether this menu item is the default menu item.

Syntax

public boolean getDefault()

Return Value

Returns true if this menu item is the default menu item; otherwise, returns false.

Remarks

The default menu item for a menu is boldfaced. When the user double-clicks on a submenu that contains a default item, the default item is selected, and the submenu is closed.

See Also setDefault


 MenuItem.getEnabled

MenuItem.getEnabled

Retrieves a boolean value that indicates whether this menu item is enabled.

Syntax

public boolean getEnabled()

Return Value

Returns true if this menu item is enabled; otherwise, returns false.

See Also setEnabled


 MenuItem.getIndex

MenuItem.getIndex

Retrieves the zero-based index of this menu item.

Syntax

public int getIndex()

Return Value

Returns the index of this menu item.

See Also setIndex


 MenuItem.getIsParent

MenuItem.getIsParent

Retrieves a boolean value that indicates whether this menu item contains child items.

Syntax

public boolean getIsParent()

Return Value

Returns true if this menu item contains child items; otherwise, returns false.


 MenuItem.getMDIList

MenuItem.getMDIList

Retrieves a boolean value that indicates whether this menu item is part of a Multiple Document Interface (MDI) list.

Syntax

public boolean getMDIList()

Return Value

Returns true if this menu item is part of an MDI list; otherwise, returns false.

See Also setMDIList


 MenuItem.getMenu

MenuItem.getMenu

Retrieves the menu in which this item appears.

Syntax

public Menu getMenu()

Return Value

Returns a Menu object that specifies the menu in which this item is included.


 MenuItem.getMergeOrder

MenuItem.getMergeOrder

Retrieves the merge order for this menu item.

Syntax

public int getMergeOrder()

Return Value

Returns the zero-based merge order for this menu item.


 MenuItem.getMergeType

MenuItem.getMergeType

Retrieves a constant that indicates how this menu item behaves when the menu of which it is a part is merged with another menu.

Syntax

public int getMergeType()

Return Value

Returns one of the enumeration constants defined in the MenuMerge class.

See Also setMergeType


 MenuItem.getRadioCheck

MenuItem.getRadioCheck

Retrieves a boolean value that indicates whether a radio button is used instead of a check mark to display checked menu items.

Syntax

public boolean getRadioCheck()

Return Value

Returns true if a radio button is used to indicate that the item is checked; otherwise, returns false.

See Also setRadioCheck


 MenuItem.getShortcut

MenuItem.getShortcut

Retrieves the shortcut key that is associated with this menu item.

Syntax

public int getShortcut()

Return Value

Returns the shortcut key. This value is one of the enumeration constants defined in the Shortcut class.

See Also setShortcut


 MenuItem.getShowShortcut

MenuItem.getShowShortcut

Retrieves a boolean value that indicates whether the shortcut associated with this menu item should be displayed.

Syntax

public boolean getShowShortcut()

Return Value

Returns true if the shortcut will be displayed; otherwise, returns false. The default value is true.

See Also setShowShortcut


 MenuItem.getText

MenuItem.getText

Retrieves the text of this menu item.

Syntax

public String getText()

Return Value

Returns the text that is associated with this menu item.

See Also setText


 MenuItem.getVisible

MenuItem.getVisible

Retrieves a boolean value that indicates whether this menu item is visible.

Syntax

public boolean getVisible()

Return Value

Returns true if this menu item is visible; otherwise, returns false.

See Also setVisible


 MenuItem.MenuItem

MenuItem.MenuItem

Creates a MenuItem object.

Syntax

public MenuItem()

public MenuItem( String text )

public MenuItem( String text, EventHandler onClick )

public MenuItem( String text, EventHandler onClick, MenuItem[] items )

public MenuItem( int mergeType, int mergeOrder, int shortcut, String text, EventHandler onClick, EventHandler onPopup, EventHandler onSelect, MenuItem[] items )

Parameters

text

The text of the menu item.

onClick

The EventHandler object that handles the click event for this menu item.

items

An array of MenuItem objects that specifies the items that this menu item will contain. Unless this parameter is empty or null, this menu item is a submenu.

mergeType

A constant that specifies how this menu item behaves if the menu that it contains is merged with another menu. This value must be one of the enumeration constants specified in the MenuMerge class.

mergeOrder

The relative position that this item assumes to other items in a merged menu.

shortcut

The shortcut key that corresponds to this menu item. This value must be one of the enumeration constants defined in the Key class.

onPopup

The EventHandler object that handles this menu item's popup event. This event is fired only for menu items that are submenus.

onSelect

The EventHandler object that handles the menu item's select event. This event is fired only for menu items that are submenus.


 MenuItem.mergeMenu

MenuItem.mergeMenu

Merges this menu item with another menu item.

Syntax

public MenuItem mergeMenu()

public void mergeMenu( MenuItem itemSrc )

Parameters

itemSrc

A MenuItem object that specifies the menu item to merge with this one.

Return Value

Returns a MenuItem object. This object is a copy of this menu item that can be merged with another menu item without affecting the functionality of this item.

Remarks

Typically, the version of this method that returns a MenuItem object is called by a Menu object when an MDI child window is activated.


 MenuItem.onClick

MenuItem.onClick

Triggers the click event.

Syntax

protected void onClick( Event e )

Parameters

e

The Event object to be notified when the event occurs.

Remarks

The click event occurs when this menu item is clicked by the user, using either the mouse, mnemonic keys, or shortcut keys.

This event is fired only for menu items that are not submenus.

See Also addOnClick, removeOnClick


 MenuItem.onPopup

MenuItem.onPopup

Triggers the popup event.

Syntax

protected void onPopup( Event e )

Parameters

e

The Event object to be notified when the event occurs.

Remarks

The popup event occurs when this item is about to be expanded to display its subitems. This event affects only menu items that are submenus.

See Also addOnPopup, removeOnPopup


 MenuItem.onSelect

MenuItem.onSelect

Triggers the select event.

Syntax

protected void onSelect( Event e )

Parameters

e

The Event object to be notified when the event occurs.

Remarks

The select event occurs when a menu item has been selected but not yet activated.

See Also addOnSelect, removeOnSelect


 MenuItem.performSelect

MenuItem.performSelect

Selects this menu item.

Syntax

public void performSelect()

Remarks

A call to this method triggers the select event.

See Also onSelect


 MenuItem.removeOnClick

MenuItem.removeOnClick

Removes the delegate that is assigned to the click event.

Syntax

public void removeOnClick( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

Remarks

The click event occurs when this menu item is clicked by the user, using the mouse or shortcut keys.

See Also addOnClick, onClick


 MenuItem.removeOnPopup

MenuItem.removeOnPopup

Removes the delegate that is assigned to the popup event.

Syntax

public void removeOnPopup( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

Remarks

The popup event occurs when this item is about to be expanded to display its subitems. This event affects only menu items that are submenus.

See Also addOnPopup, onPopup


 MenuItem.removeOnSelect

MenuItem.removeOnSelect

Removes the delegate that is assigned to the select event.

Syntax

public void removeOnSelect( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

Remarks

The select event occurs when a menu item has been selected but not yet activated.

See Also addOnSelect, onSelect


 MenuItem.setBarBreak

MenuItem.setBarBreak

Sets a boolean value that determines whether this menu item should be placed on a new line (if the item is part of a menu bar) or in a new column (if the item is part of a drop-down menu, submenu, or shortcut menu).

Syntax

public void setBarBreak( boolean value )

Parameters

value

Set to true to place the menu item on a new line or in a new column; otherwise, set to false.

Remarks

For a drop-down menu, submenu, or a shortcut menu, a vertical line separates the new column from the old.

See Also getBarBreak, setBreak


 MenuItem.setBreak

MenuItem.setBreak

Sets a boolean value that determines whether this menu item should be placed on a new line (if the item is part of a menu bar) or in a new column (if the item is part of a drop-down menu, submenu, or shortcut menu).

Syntax

public void setBreak( boolean value )

Parameters

value

Set to true to place the menu item on a new line or in a new column; otherwise, set to false.

Remarks

For a drop-down menu, submenu, or shortcut menu, no vertical line separates the columns.

See Also getBarBreak, setBarBreak


 MenuItem.setChecked

MenuItem.setChecked

Sets a boolean value that determines whether this menu item is checked.

Syntax

public void setChecked( boolean value )

Parameters

value

Set to true if this menu item is to be checked; otherwise, set to false.

See Also getChecked


 MenuItem.setDefault

MenuItem.setDefault

Sets a boolean value that determines whether this menu item is the default item for the submenu in which it appears.

Syntax

public void setDefault( boolean value )

Parameters

value

Set to true to make this menu item the default; otherwise, set to false.

Remarks

The default menu item for a menu is boldfaced. When the user double-clicks on a submenu that contains a default item, the default item is selected and the submenu is closed.

See Also getDefault


 MenuItem.setEnabled

MenuItem.setEnabled

Sets a boolean value that indicates whether this item is enabled.

Syntax

public void setEnabled( boolean value )

Parameters

value

Set to true to enable this menu item; otherwise, set to false.

See Also getEnabled


 MenuItem.setIndex

MenuItem.setIndex

Sets this menu item's zero-based index.

Syntax

public void setIndex( int value )

Parameters

value

The zero-based index of this menu item.

See Also getIndex


 MenuItem.setMDIList

MenuItem.setMDIList

Sets a boolean value that indicates whether this menu item should be populated with a list of the MDI children that appear on the form with which this menu is associated.

Syntax

public void setMDIList( boolean value )

Parameters

value

Set to true to display the form's MDI children in this menu item; otherwise, set to false.

See Also getMDIList


 MenuItem.setMergeOrder

MenuItem.setMergeOrder

Sets the merge order for this menu item.

Syntax

public void setMergeOrder( int value )

Parameters

value

The zero-based merge order of this item.

Remarks

The merge order of a menu item specifies the relative position that this menu item will assume if the menu of which it is a member is merged with another.

See Also getMergeOrder


 MenuItem.setMergeType

MenuItem.setMergeType

Specifies the merge type of this menu item.

Syntax

public void setMergeType( int value )

Parameters

value

The menu item's merge type. This value must be one of the enumeration constants defined in the MenuMerge class.

Remarks

The merge type of a menu item indicates how the item behaves when it has the same merge order as an item in a menu with which this item's menu is merged.

See Also getMergeType


 MenuItem.setRadioCheck

MenuItem.setRadioCheck

Sets a boolean value that determines whether a radio button is used instead of a check mark to display checked menu items.

Syntax

public void setRadioCheck( boolean value )

Parameters

value

Set to true to use a radio button with checked menu items; otherwise, set to false.

See Also getRadioCheck


 MenuItem.setShortcut

MenuItem.setShortcut

Associates a shortcut key with this menu item.

Syntax

public void setShortcut( int value )

Parameters

value

The shortcut to associate with this menu item. This value must be one of the enumeration values defined in the Shortcut class.


 MenuItem.setShowShortcut

MenuItem.setShowShortcut

Sets a boolean value that indicates whether the shortcut associated with this menu item should be displayed.

Syntax

public void setShowShortcut( boolean value )

Parameters

value

Set to true to display the shortcut; otherwise, set to false. The default value is true.

See Also getShowShortcut


 MenuItem.setText

MenuItem.setText

Sets the text for this menu item.

Syntax

public void setText( String value )

Parameters

value

The text to display on this menu item.

See Also getText


 MenuItem.setVisible

MenuItem.setVisible

Sets a boolean value that determines whether this menu item is visible.

Syntax

public void setVisible( boolean value )

Parameters

value

Set to true to make the menu item visible; otherwise, set to false.

See Also getVisible


MenuMerge Class

Defines constants that specify how menus behave when they are merged together.

Enum
  |
  +--MenuMerge

package com.ms.wfc.ui

public class MenuMerge
extends Enum

Remarks

Two elements come into play when two menus are merged: the merge order and merge type of the items in the menu.

The merge order is a zero-based index. If, for example, one menu item has a merge order of 2 and an item from a different menu has a merge order of 1, the item with the lower merge order precedes the item with the higher order.

The merge type determines how two items are placed relative to each other when they have the same merge order. If, for example, a menu item has a merge order of MenuMerge.REPLACE, it replaces a menu item that has the same merge order on a merged menu.

To set the merge order for a menu item, call the MenuItem object's setMergeOrder method. To set the merge type, call the setMergeType method.


 MenuMerge Methods

MenuMerge Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 <b>MenuMerge.valid</b>

MenuMerge.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 MenuMerge Fields

MenuMerge Fields

Fields | Description
ADD | Specifies that the menu item should be added alongside an existing item in the merged menu.
MERGEITEMS | Specifies that the subitems of this item should be merged with those of the existing item at the same position in the merged menu.
REMOVE | Specifies that the menu item should not be included in the merged menu.
REPLACE | Indicates that the menu item should replace the existing item at the same position in the merged menu.


 MenuMerge.ADD

MenuMerge.ADD

Specifies that the menu item should be added alongside an existing item in the merged menu.

Syntax

public static final int ADD;


 MenuMerge.MERGEITEMS

MenuMerge.MERGEITEMS

Specifies that the subitems of this item should be merged with those of the existing item at the same position in the merged menu.

Syntax

public static final int MERGEITEMS;


 MenuMerge.REMOVE

MenuMerge.REMOVE

Specifies that the menu item should not be included in the merged menu.

Syntax

public static final int REMOVE;


 MenuMerge.REPLACE

MenuMerge.REPLACE

Indicates that the menu item should replace the existing item at the same position in the merged menu.

Syntax

public static final int REPLACE;


MessageBox Class

Allows the user to display a message box that can contain various buttons and icons.

package com.ms.wfc.ui

public class MessageBox

Remarks

The title, message, and icons displayed on the message box are determined by parameters that you pass to the MessageBox class' show method.

The following example shows the correct usage of this class:

MessageBox.show("This is my message", "Title!", MessageBox.OK);


 MessageBox Methods

MessageBox Methods

Methods | Description
show | Displays a message box with the specified text, caption, and style.


 MessageBox.show

MessageBox.show

Displays a message box with the specified text, caption, and style.

Syntax

public static int show( String text )

public static int show( String text, String caption )

public static int show( String text, String caption, int style )

Parameters

text

The text to display on the message box.

caption

The text to display in the title bar of the message box.

style

The style of the message box. This value represents one or more of the constants defined in this class, combined with a bitwise OR operator.

Return Value

Returns an integer that contains the value returned by the message box. Typically, this value identifies the button that the user clicked. These values are defined in the DialogResult class.


 MessageBox Fields

MessageBox Fields

Fields | Description
ABORTRETRYIGNORE | Indicates that the message box should display Abort, Retry, and Ignore buttons.
DEFBUTTON1 | Indicates that the first button on the message box should be the default button.
DEFBUTTON2 | Indicates that the second button on the message box should be the default button.
DEFBUTTON3 | Indicates that the third button on the message box should be the default button.
ICONASTERISK | Indicates that the message box should display an asterisk icon.
ICONERROR | Indicates that the message box should display an error icon.
ICONEXCLAMATION | Indicates that the message box should display an exclamation icon.
ICONHAND | Indicates that a hand icon should be displayed on the message box.
ICONINFORMATION | Indicates that the message box should display a question mark.
ICONQUESTION | Indicates that the message box should display a question mark.
ICONSTOP | Indicates that the message box should display a stop icon.
ICONWARNING | Indicates that the message box should display a warning icon.
OK | Indicates that the message box should display an OK button.
OKCANCEL | Indicates that the message box should display OK and Cancel buttons.
RETRYCANCEL | Indicates that the message box should display Retry and Cancel buttons.
YESNO | Indicates that the message box should display Yes and No buttons.
YESNOCANCEL | Indicates that the message box should display Yes, No, and Cancel buttons.


 MessageBox.ABORTRETRYIGNORE

MessageBox.ABORTRETRYIGNORE

Indicates that the message box should display Abort, Retry, and Ignore buttons.

Syntax

public static final int ABORTRETRYIGNORE;


 MessageBox.DEFBUTTON1

MessageBox.DEFBUTTON1

Indicates that the first button on the message box should be the default button.

Syntax

public static final int DEFBUTTON1;


 MessageBox.DEFBUTTON2

MessageBox.DEFBUTTON2

Indicates that the second button on the message box should be the default button.

Syntax

public static final int DEFBUTTON2;


 MessageBox.DEFBUTTON3

MessageBox.DEFBUTTON3

Indicates that the third button on the message box should be the default button.

Syntax

public static final int DEFBUTTON3;


 MessageBox.ICONASTERISK

MessageBox.ICONASTERISK

Indicates that the message box should display an asterisk icon.

Syntax

public static final int ICONASTERISK;


 MessageBox.ICONERROR

MessageBox.ICONERROR

Indicates that the message box should display an error icon.

Syntax

public static final int ICONERROR;

Remarks

An error icon consists of a red circle that contains a white X.


 MessageBox.ICONEXCLAMATION

MessageBox.ICONEXCLAMATION

Indicates that the message box should display an exclamation icon.

Syntax

public static final int ICONEXCLAMATION;

Remarks

The exclamation icon consists of a yellow triangle that contains an exclamation mark.


 MessageBox.ICONHAND

MessageBox.ICONHAND

Indicates that a hand icon should be displayed on the message box.

Syntax

public static final int ICONHAND;


 MessageBox.ICONINFORMATION

MessageBox.ICONINFORMATION

Indicates that the message box should display a question mark.

Syntax

public static final int ICONINFORMATION;


 MessageBox.ICONQUESTION

MessageBox.ICONQUESTION

Indicates that the message box should display a question mark.

Syntax

public static final int ICONQUESTION;


 MessageBox.ICONSTOP

MessageBox.ICONSTOP

Indicates that the message box should display a stop icon.

Syntax

public static final int ICONSTOP;

Remarks

A stop icon consists of a red circle that contains a white X.


 MessageBox.ICONWARNING

MessageBox.ICONWARNING

Indicates that the message box should display a warning icon.

Syntax

public static final int ICONWARNING;

Remarks

A warning icon consists of a yellow triangle that contains an exclamation point.


 MessageBox.OK

MessageBox.OK

Indicates that the message box should display an OK button.

Syntax

public static final int OK;


 MessageBox.OKCANCEL

MessageBox.OKCANCEL

Indicates that the message box should display OK and Cancel buttons.

Syntax

public static final int OKCANCEL;


 MessageBox.RETRYCANCEL

MessageBox.RETRYCANCEL

Indicates that the message box should display Retry and Cancel buttons.

Syntax

public static final int RETRYCANCEL;


 MessageBox.YESNO

MessageBox.YESNO

Indicates that the message box should display Yes and No buttons.

Syntax

public static final int YESNO;


 MessageBox.YESNOCANCEL

MessageBox.YESNOCANCEL

Indicates that the message box should display Yes, No, and Cancel buttons.

Syntax

public static final int YESNOCANCEL;


Metafile Class

Encapsulates a Windows metafile.

Image
  |
  +--Metafile

package com.ms.wfc.ui

public class Metafile
extends Image
implements IPersistable

Remarks

You can think of a metafile as a graphics macro. A metafile consists of graphics function calls that have been stored in a file. The ability to store such information in a file enables you to reproduce the graphics commands that originally created the metafile image on any screen resolution with any scale, resulting in smoothly scaled images.


 Metafile Methods

Metafile Methods

Constructors | Description
Metafile | Creates a Metafile object.

Methods | Description
clone | Clones the Metafile object and returns a duplicate.
copyHandle | Retrieves a copy of the Win32 handle for the metafile on which this object is based.
destroyHandle | Called when this object is going to destroy its Win32 handle.
dispose | Frees all the resources allocated by this object.
drawStretchTo | Renders the metafile image to a Graphics object, stretching the image to fill the specified dimensions.
drawTo | Renders the metafile image (or part of it) to a Graphics object, cropping the image to fit the specified dimensions.
finalize | Frees the resources allocated by the Metafile object.
getExtension | Retrieves the recommended file extension for files that persist this object.
getGraphics | Retrieves a Graphics object that you can use to paint to this image.
getHandle | Retrieves the Win32 handle (HMETAFILE) to this metafile.
getPICTDESC | Retrieves a PICTDESC (Picture Descriptor) for this metafile.
getRenderedSize | Retrieves the size of the image, in logical units, for the specified Graphics object.
getSize | Retrieves the size of the metafile in .01 millimeter units.
toString | Retrieves a human-readable string representation of this object.


 Metafile.clone

Metafile.clone

Clones the Metafile object and returns a duplicate.

Syntax

public Object clone()

Return Value

Returns an Object that can be cast to a Metafile object.


 Metafile.copyHandle

Metafile.copyHandle

Retrieves a copy of the Win32 handle for the metafile on which this object is based.

Syntax

public final int copyHandle()

Return Value

Returns a copy of the Win32 handle (HMETAFILE) to the metafile that underlies this object.

Remarks

When you copy a metafile handle, you own the handle and are responsible for freeing it.

See Also getHandle


 Metafile.destroyHandle

Metafile.destroyHandle

Called when this object is going to destroy its Win32 handle.

Syntax

protected void destroyHandle( int handle )

Parameters

handle

The Win32 handle (HMETAFILE) to the metafile on which this object is based.

Remarks

The Metafile class' implementation of destroyHandle frees only handles owned by the Metafile object. If you have used the object to retrieve a copy of the handle to this metafile (using the copyHandle method), or if you have created a Metafile object based on a previously allocated handle, this handle is not freed by the object's call to destroyHandle; you are responsible for freeing these handles.

However, you can override this method in your Metafile-derived class to define your own custom semantics for handle creation and destruction.

If the Metafile object does not own the handle to this metafile, this method does nothing.


 Metafile.dispose

Metafile.dispose

Frees all the resources allocated by this object.

Syntax

public void dispose()

Remarks

The dispose method frees only those resources allocated by the object. Such resources do not include handle copies that you retrieve using the object's methods; you must free these manually.

Once the dispose method is called, the Metafile object is no longer useful.


 Metafile.drawStretchTo

Metafile.drawStretchTo

Renders the metafile image to a Graphics object, stretching the image to fill the specified dimensions.

Syntax

protected void drawStretchTo( Graphics g, Rectangle imageRect, Rectangle targetRect, int rop )

Parameters

g

The Graphics object to which to draw the image.

imageRect

A Rectangle object that specifies the metafile region to draw.

targetRect

A Rectangle object that specifies the area to which to draw the image.

rop

A numerical raster operation (ROP) code that describes how to draw the source image to the target.

Remarks

This method is used by the Graphics object for all image rendering.

If the area specified in imageRect is smaller than the area specified in targetRect, the source image is stretched to fill the specified area. If the area specified in imageRect is larger than that specified in targetRect, the image is shrunk.

See Also drawTo


 Metafile.drawTo

Metafile.drawTo

Renders the metafile image (or part of it) to a Graphics object, cropping the image to fit the specified dimensions.

Syntax

protected void drawTo( Graphics g, Rectangle imageRect, Rectangle targetRect, int rop )

Parameters

g

The Graphics object to which to draw the image.

imageRect

A Rectangle object that specifies the source rectangle in the image.

targetRect

A Rectangle object that specifies the rectangle to which to draw the image. If this area is smaller than imageRect, the source rectangle is cropped to fit in the target rectangle.

rop

A numerical raster operation (ROP) code that specifies how to draw the image.

See Also drawStretchTo


 Metafile.finalize

Metafile.finalize

Frees the resources allocated by the Metafile object.

Syntax

protected void finalize()


 Metafile.getExtension

Metafile.getExtension

Retrieves the recommended file extension for files that persist this object.

Syntax

public String getExtension()

Return Value

Returns the recommended file extension for this object, minus the prefixing period. The default implementation of this method always returns "emf".


 Metafile.getGraphics

Metafile.getGraphics

Retrieves a Graphics object that you can use to paint to this image.

Syntax

public Graphics getGraphics()

Return Value

Returns a Graphics object for the Metafile object. If a Graphics object does not already exist for this object, one is created. If you have created a Graphics object through a previous call to getGraphics, the existing Graphics object is returned.

Remarks

When you create a Graphics object instance using the Metafile object's getGraphics method, the Graphics object's drawing methods draw to the surface of the Metafile object itself.


 Metafile.getHandle

Metafile.getHandle

Retrieves the Win32 handle (HMETAFILE) to this metafile.

Syntax

public int getHandle()

Return Value

Returns the handle to this metafile.

Exceptions

WFCException thrown if the Metafile object has been disposed through a call to its dispose method.

Remarks

The handle returned by this method is not a copy of the metafile handle. Therefore, this handle should not be freed by the caller.

See Also copyHandle


 Metafile.getPICTDESC

Metafile.getPICTDESC

Retrieves a PICTDESC (Picture Descriptor) for this metafile.

Syntax

public PICTDESC getPICTDESC()

Return Value

Returns a PICTDESC structure that describes this object's image.

Remarks

The PICTDESC structure is used by OLE functions to create picture objects.


 Metafile.getRenderedSize

Metafile.getRenderedSize

Retrieves the size of the image, in logical units, for the specified Graphics object.

Syntax

public final Point getRenderedSize( Graphics g )

Parameters

g

The Graphics object to use when converting the size of the metafile to logical units.

Return Value

Returns a Point object that specifies, in logical units, the dimensions of the metafile for the specified Graphics object.


 Metafile.getSize

Metafile.getSize

Retrieves the size of the metafile in .01 millimeter units.

Syntax

public final Point getSize()

Return Value

Returns a Point object that specifies the dimensions of the metafile.

See Also getRenderedSize


 Metafile.Metafile

Metafile.Metafile

Creates a Metafile object.

Syntax

public Metafile()

public Metafile( Rectangle bounds )

public Metafile( String fileName )

public Metafile( int handle )

public Metafile( Class type, String resource )

public Metafile( IDataStream stream )

public Metafile( Stream stream )

public Metafile( IPicture picture )

Parameters

bounds

A Rectangle object that specifies the dimensions of the metafile in .01 millimeter units.

fileName

The name of the file from which to load the metafile.

handle

A Win32 handle (HMETAFILE) to the metafile on which to base this object. This handle is not owned by the Metafile object; you are responsible for freeing it.

type

The class used to load the metafile resource.

resource

The resource to load.

stream

A data stream (IDataStream or com.ms.wfc.ole32.IStream) from which to load the metafile.

picture

The OLE com.ms.wfc.ole32.IPicture object from which to load the metafile.


 Metafile.toString

Metafile.toString

Retrieves a human-readable string representation of this object.

Syntax

public String toString()

Return Value

A string that describes this Metafile object.


MonthCalendar Class

Encapsulates a Windows month calendar control, which provides a simple calendar interface from which the user can select a date.

Component
  |
  +--Control
    |
    +--MonthCalendar

package com.ms.wfc.ui

public class MonthCalendar
extends Control

Remarks

Use the getSelectionRange method to return the date range the user selected in the month calendar.

The following examples use the setBoldedDates method to set which dates appear bold in the month calendar, and use the removeBoldedDate and removeAllBoldedDates method to remove bold formatting from date. You use similar code to add and remove monthly and annually bolded dates.

private void btnBoldDates_click(Object source, Event e)
{
    Time time[] = new Time[3];
    time[0] = new Time();
    time[1] = time[0].addDays(2);
    time[2] = time[1].addDays(2);
    mcVacation.setBoldedDates(time);
}

private void btnUnboldToday_click(Object source, Event e)
{
    Time time1 = new Time();
    mcVacation.removeBoldedDate(time1);
    mcVacation.updateBoldedDates();
}

private void btnUnboldAllDates_click(Object source, Event e)
{
    mcVacation.removeAllBoldedDates();
    mcVacation.updateBoldedDates();
}


 MonthCalendar Methods

MonthCalendar Methods

Constructors | Description
MonthCalendar | Creates a MonthCalendar control.

Methods | Description
addAnnuallyBoldedDate | Specifies that a date will be displayed in bold every year in the month calendar.
addBoldedDate | Specifies that a date will be displayed in bold in the month calendar.
addMonthlyBoldedDate | Specifies that a date will be displayed in bold every month in the month calendar.
addOnDateChanged | Assigns a delegate to the dateRange event.
addOnDateSelected | Assigns a delegate to the dateSelected event.
dispose | Releases windowing system resources used by the month calendar control.
getAnnuallyBoldedDates | Retrieves an array of Time objects that represent dates that are displayed in bold every year in the month calendar.
getBoldedDates | Retrieves an array of Time objects that represent dates that are displayed in bold in the month calendar.
getDimensions | Retrieves the number of columns and rows of months that the control displays.
getDisplayRange | Retrieves the starting and ending dates of the date range displayed in the control.
getFirstDayOfWeek | Retrieves the first day of the week for the month calendar control.
getMaxDate | Retrieves a value indicating the last date that the control allows the user to select.
getMaxSelectionCount | Retrieves the maximum number of days that can be selected in a month calendar control.
getMinDate | Retrieves a value indicating the first date that the control allows the user to select.
getMonthlyBoldedDates | Retrieves an array of Time objects that represent dates that are displayed in bold every month in the month calendar.
getScrollChange | Retrieves the scroll rate for a month calendar control.
getSelectionEnd | Retrieves the end of the date range currently selected in the control.
getSelectionRange | Retrieves the selected date range for a month calendar control.
getSelectionStart | Retrieves the start of the date range currently selected in the control.
getShowToday | Retrieves a boolean value indicating whether the month calendar control will display the "today" date at the bottom of the control.
getShowTodayCircle | Retrieves a boolean value indicating whether the month calendar control will circle the "today" date.
getShowWeekNumbers | Retrieves a boolean value indicating whether the month calendar control displays week numbers (1 through 52) to the left of each row of days.
getSingleMonthSize | Retrieves the minimum dimensions required to display a full month in a month calendar control.
getTitleBackColor | Retrieves the background color displayed in the month calendar's title.
getTitleForeColor | Retrieves the color used to display text within the month calendar's title.
getTodayDate | Retrieves the date information for the date specified as "today" for a month calendar control.
getTrailingForeColor | Retrieves the color used to display text for header and trailing-day days (days from the previous and following month that appear on the current calendar).
hitTest | Determines which portion of a month calendar control is at at the specified point on the screen.
onDateChanged | Triggers the dateChanged event.
onDateSelected | Triggers the dateSelected event.
removeAllAnnuallyBoldedDates | Specifies that no dates are displayed every year in bold in the month calendar.
removeAllBoldedDates | Specifies that no dates are displayed in bold in the month calendar.
removeAllMonthlyBoldedDates | Specifies that no dates are displayed every month in bold in the month calendar.
removeAnnuallyBoldedDate | Specifies that a date will not be displayed in bold every year in the month calendar.
removeBoldedDate | Specifies that a date will not be displayed in bold in the month calendar.
removeMonthlyBoldedDate | Specifies that a date will not be displayed in bold every month in the month calendar.
removeOnDateChanged | Removes the delegate that is assigned to the dateChanged event.
removeOnDateSelected | Removes the delegate that is assigned to the dateSelected event.
resetMaxDate | Resets the calendar so that there is no upper limit to the selectable range of dates.
resetMinDate | Resets the calendar so that there is no lower limit to the selectable range of dates.
resetSelectionRange | Resets the selected range of the control to the current date.
resetTodayDate | Resets the "today" date to the current date.
setAnnuallyBoldedDates | Sets an array of Time objects that represent dates that are displayed in bold every year in the month calendar.
setBoldedDates | Sets an array of Time objects that represent dates that are displayed in bold in the month calendar.
setDate | Selects the specified date in the calendar.
setDimensions | Sets the number of columns and rows of months that the control will display.
setFirstDayOfWeek | Sets the first day of the week for the month calendar control.
setMaxDate | Sets a value indicating the last date that the control allows the user to select.
setMaxSelectionCount | Sets the maximum number of days that can be selected in a month calendar control.
setMinDate | Sets a value indicating the first date that the control allows the user to select.
setMonthlyBoldedDates | Sets an array of Time objects that represent dates that are displayed in bold every month in the month calendar.
setScrollChange | Sets the scroll rate for a month calendar control.
setSelectionEnd | Sets the end of the date range currently selected in the control.
setSelectionRange | Sets the selection for a month calendar control to a specified date range.
setSelectionStart | Sets the start date of the selection range.
setShowToday | Sets a boolean value indicating whether the month calendar control will display the "today" date at the bottom of the control.
setShowTodayCircle | Sets a boolean value indicating whether the month calendar control will circle the "today" date.
setShowWeekNumbers | Sets a boolean value indicating whether the month calendar control displays week numbers (1 through 52) to the left of each row of days.
setTitleBackColor | Sets the background color displayed in the month calendar's title.
setTitleForeColor | Sets the color used to display text within the month calendar's title.
setTodayDate | Sets the "today" selection for a month calendar control.
setTrailingForeColor | Sets the color used to display text for header and trailing-day days (days from the previous and following month that appear on the current calendar).
shouldPersistMaxDate | Retrieves a boolean value indicating whether the value of the maxDate property has been explicitly set.
shouldPersistMinDate | Retrieves a boolean value indicating whether the value of the minDate property has been explicitly set.
shouldPersistSelectionRange | Retrieves a boolean value indicating whether the value of the selectionRange property has been explicitly set.
shouldPersistTodayDate | Retrieves a boolean value indicating whether the value of the todayDate property has been explicitly set.
updateBoldedDates | Updates the list of dates that are displayed in bold in the month calendar and repaints the calendar.


 MonthCalendar.addAnnuallyBoldedDate

MonthCalendar.addAnnuallyBoldedDate

Specifies that a date will be displayed in bold every year in the month calendar.

Syntax

public void addAnnuallyBoldedDate( Time date )

Parameters

date

A Time object that represents the date to display in bold every year.

Exceptions

WFCException thrown if the value specified for the date parameter evaluates to null.

Remarks

Call the updateBoldedDates method after calling this method.

See Also removeAnnuallyBoldedDate


 MonthCalendar.addBoldedDate

MonthCalendar.addBoldedDate

Specifies that a date will be displayed in bold in the month calendar.

Syntax

public void addBoldedDate( Time date )

Parameters

date

A Time object that represents the date to display in bold.

Exceptions

WFCException thrown if the value specified for the date parameter evaluates to null.

Remarks

Call the updateBoldedDates method after calling this method.

See Also removeBoldedDate


 MonthCalendar.addMonthlyBoldedDate

MonthCalendar.addMonthlyBoldedDate

Specifies that a date will be displayed in bold every month in the month calendar.

Syntax

public void addMonthlyBoldedDate( Time date )

Parameters

date

A Time object that represents the date to display in bold every month.

Exceptions

WFCException thrown if the value specified for the date parameter evaluates to null.

Remarks

Call the updateBoldedDates method after calling this method.


 MonthCalendar.addOnDateChanged

MonthCalendar.addOnDateChanged

Assigns a delegate to the dateRange event.

Syntax

public void addOnDateChanged( DateRangeEventHandler value )

Parameters

value

The DateRangeEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the dateRange event to that method in the Properties window. The dateRange event occurs when the currently selected date or range of dates changes. This occurs, for example, when the user explicitly changes a selection within the current month or when a selection is implicitly changed in response to next/previous month navigation.

See Also removeOnDateChanged


 MonthCalendar.addOnDateSelected

MonthCalendar.addOnDateSelected

Assigns a delegate to the dateSelected event.

Syntax

public void addOnDateSelected( DateRangeEventHandler value )

Parameters

value

The DateRangeEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the dateSelected event to that method in the Properties window. The dateSelected event occurs when user explicitly changes his or her selection.

See Also removeOnDateSelected


 MonthCalendar.dispose

MonthCalendar.dispose

Releases windowing system resources used by the month calendar control.

Syntax

public void dispose()

Remarks

Call this method when you want to release resources immediately instead of waiting for garbage collection.

Overrides

Control.dispose.


 MonthCalendar.getAnnuallyBoldedDates

MonthCalendar.getAnnuallyBoldedDates

Retrieves an array of Time objects that represent dates that are displayed in bold every year in the month calendar.

Syntax

public Time[] getAnnuallyBoldedDates()

Return Value

Returns an array of Time objects that represent the dates that are displayed in bold every year in the month calendar.

See Also setAnnuallyBoldedDates


 MonthCalendar.getBoldedDates

MonthCalendar.getBoldedDates

Retrieves an array of Time objects that represent dates that are displayed in bold in the month calendar.

Syntax

public Time[] getBoldedDates()

Return Value

Returns an array of Time objects that represent the dates that are displayed in bold in the month calendar.

See Also setBoldedDates


 MonthCalendar.getDimensions

MonthCalendar.getDimensions

Retrieves the number of columns and rows of months that the control displays.

Syntax

public Dimensions getDimensions()

Return Value

Returns a Dimensions object that contains the current dimensions of the control.

See Also setDimensions


 MonthCalendar.getDisplayRange

MonthCalendar.getDisplayRange

Retrieves the starting and ending dates of the date range displayed in the control.

Syntax

public SelectionRange getDisplayRange( boolean visible )

Parameters

visible

Set to true to include only the dates in fully displayed months in the returned date range. Set to false to include dates from the partially displayed months at the beginning and end of the visible range in the returned date range.

Return Value

Returns a SelectionRange object that contains the starting and ending dates in the displayed range.


 MonthCalendar.getFirstDayOfWeek

MonthCalendar.getFirstDayOfWeek

Retrieves the first day of the week for the month calendar control.

Syntax

public int getFirstDayOfWeek()

Return Value

Returns an integer that represents a day of the week. Possible return values are constants defined in the Days class.

See Also setFirstDayOfWeek


 MonthCalendar.getMaxDate

MonthCalendar.getMaxDate

Retrieves a value indicating the last date that the control allows the user to select.

Syntax

public Time getMaxDate()

Return Value

Returns a Time object that represents the last date that is available for selection in the control. Returns null if there is no upper limit to allowable dates.

See Also setMaxDate


 MonthCalendar.getMaxSelectionCount

MonthCalendar.getMaxSelectionCount

Retrieves the maximum number of days that can be selected in a month calendar control.

Syntax

public int getMaxSelectionCount()

Return Value

Returns an integer that represents the maximum number of days that can be selected at one time in the control.

See Also setMaxSelectionCount


 MonthCalendar.getMinDate

MonthCalendar.getMinDate

Retrieves a value indicating the first date that the control allows the user to select.

Syntax

public Time getMinDate()

Return Value

Returns a Time object that represents the first date that is available for selection in the control. Returns null if there is no lower limit to allowable dates.

See Also setMinDate


 MonthCalendar.getMonthlyBoldedDates

MonthCalendar.getMonthlyBoldedDates

Retrieves an array of Time objects that represent dates that are displayed in bold every month in the month calendar.

Syntax

public Time[] getMonthlyBoldedDates()

Return Value

Returns an array of Time objects that represent the dates that are displayed in bold every month in the month calendar.

See Also setMonthlyBoldedDates


 MonthCalendar.getScrollChange

MonthCalendar.getScrollChange

Retrieves the scroll rate for a month calendar control.

Syntax

public int getScrollChange()

Return Value

Returns an integer that represents the current scroll rate.

Remarks

The scroll rate is the number of months that the control moves its display when the user clicks a scroll button.

See Also setScrollChange


 MonthCalendar.getSelectionEnd

MonthCalendar.getSelectionEnd

Retrieves the end of the date range currently selected in the control.

Syntax

public Time getSelectionEnd()

Return Value

Returns a Time object that represents the end of the selected date range.

See Also setSelectionEnd


 MonthCalendar.getSelectionRange

MonthCalendar.getSelectionRange

Retrieves the selected date range for a month calendar control.

Syntax

public SelectionRange getSelectionRange()

Return Value

Returns a SelectionRange object that represents the currently selected date range in the month calendar control.

See Also setSelectionRange


 MonthCalendar.getSelectionStart

MonthCalendar.getSelectionStart

Retrieves the start of the date range currently selected in the control.

Syntax

public Time getSelectionStart()

Return Value

Returns a Time object that represents the start of the selected date range.

See Also setSelectionStart


 MonthCalendar.getShowToday

MonthCalendar.getShowToday

Retrieves a boolean value indicating whether the month calendar control will display the "today" date at the bottom of the control.

Syntax

public boolean getShowToday()

Return Value

Returns true if the "today" date will appear on the control; otherwise, returns false.

See Also setShowToday


 MonthCalendar.getShowTodayCircle

MonthCalendar.getShowTodayCircle

Retrieves a boolean value indicating whether the month calendar control will circle the "today" date.

Syntax

public boolean getShowTodayCircle()

Return Value

Returns true if the control will circle the "today" date; otherwise, returns false.

See Also setShowTodayCircle


 MonthCalendar.getShowWeekNumbers

MonthCalendar.getShowWeekNumbers

Retrieves a boolean value indicating whether the month calendar control displays week numbers (1 through 52) to the left of each row of days.

Syntax

public boolean getShowWeekNumbers()

Return Value

Returns true if the week numbers are displayed; otherwise, returns false.

See Also setShowWeekNumbers


 MonthCalendar.getSingleMonthSize

MonthCalendar.getSingleMonthSize

Retrieves the minimum dimensions required to display a full month in a month calendar control.

Syntax

public Point getSingleMonthSize()

Return Value

Returns a Point object whose x property represents the minimum width required to display a month in the control and whose y property represents the height required.

Exceptions

WFCWin32Exception thrown if the applicable bounding information cannot be returned.

Remarks

The minimum required window size for a month calendar control depends on the currently selected font.


 MonthCalendar.getTitleBackColor

MonthCalendar.getTitleBackColor

Retrieves the background color displayed in the month calendar's title.

Syntax

public Color getTitleBackColor()

Return Value

Returns a Color object that represents background color displayed in the month calendar's title.

See Also setTitleBackColor


 MonthCalendar.getTitleForeColor

MonthCalendar.getTitleForeColor

Retrieves the color used to display text within the month calendar's title.

Syntax

public Color getTitleForeColor()

Return Value

Returns a Color object that represents the text color for the month calendar's title.

See Also setTitleForeColor


 MonthCalendar.getTodayDate

MonthCalendar.getTodayDate

Retrieves the date information for the date specified as "today" for a month calendar control.

Syntax

public Time getTodayDate()

Return Value

Returns a Time object that represents the date value of the date specified as "today" in the control.

See Also setTodayDate


 MonthCalendar.getTrailingForeColor

MonthCalendar.getTrailingForeColor

Retrieves the color used to display text for header and trailing-day days (days from the previous and following month that appear on the current calendar).

Syntax

public Color getTrailingForeColor()

Return Value

Returns a Color object that represents the color used to display text for header and trailing-day days

See Also setTrailingForeColor


 MonthCalendar.hitTest

MonthCalendar.hitTest

Determines which portion of a month calendar control is at at the specified point on the screen.

Syntax

public HitTestInfo hitTest( int x, int y )

public HitTestInfo hitTest( Point point )

Parameters

x

The x-coordinate of the point to hit test.

y

The y-coordinate of the point to hit test.

point

A Point object that contains the coordinates of the point to be hit tested.

Return Value

Returns a HitTestInfo object that carries information specific to hit-testing points for a month calendar control.


 MonthCalendar.MonthCalendar

MonthCalendar.MonthCalendar

Creates a MonthCalendar control.

Syntax

public MonthCalendar()


 MonthCalendar.onDateChanged

MonthCalendar.onDateChanged

Triggers the dateChanged event.

Syntax

protected void onDateChanged( DateRangeEvent event )

Parameters

event

A DateRangeEvent object that provides the event data.

Remarks

When overriding this method, call super.onDateChanged.

See Also addOnDateChanged


 MonthCalendar.onDateSelected

MonthCalendar.onDateSelected

Triggers the dateSelected event.

Syntax

protected void onDateSelected( DateRangeEvent event )

Parameters

event

A DateRangeEvent object that provides the event data.

Remarks

When overriding this method, call super.onDateSelected.

See Also addOnDateSelected


 MonthCalendar.removeAllAnnuallyBoldedDates

MonthCalendar.removeAllAnnuallyBoldedDates

Specifies that no dates are displayed every year in bold in the month calendar.

Syntax

public void removeAllAnnuallyBoldedDates()

Remarks

Call the updateBoldedDates method after calling this method.


 MonthCalendar.removeAllBoldedDates

MonthCalendar.removeAllBoldedDates

Specifies that no dates are displayed in bold in the month calendar.

Syntax

public void removeAllBoldedDates()

Remarks

Call the updateBoldedDates method after calling this method.


 MonthCalendar.removeAllMonthlyBoldedDates

MonthCalendar.removeAllMonthlyBoldedDates

Specifies that no dates are displayed every month in bold in the month calendar.

Syntax

public void removeAllMonthlyBoldedDates()

Remarks

Call the updateBoldedDates method after calling this method.


 MonthCalendar.removeAnnuallyBoldedDate

MonthCalendar.removeAnnuallyBoldedDate

Specifies that a date will not be displayed in bold every year in the month calendar.

Syntax

public void removeAnnuallyBoldedDate( Time date )

Parameters

date

A Time object that represents the date to display in with no emphasis every year. If the specified date is not found in the list of dates to display in bold, this method has no effect. If the specified date occurs more than once in the bolded date list, only the first occurrence is removed.

Remarks

Call the updateBoldedDates method after calling this method.

See Also addAnnuallyBoldedDate


 MonthCalendar.removeBoldedDate

MonthCalendar.removeBoldedDate

Specifies that a date will not be displayed in bold in the month calendar.

Syntax

public void removeBoldedDate( Time date )

Parameters

date

A Time object that represents the date to display with no emphasis. If the specified date is not found in the list of dates to display in bold, this method has no effect. If the specified date occurs more than once in the bolded date list, only the first occurrence is removed.

Remarks

Call the updateBoldedDates method after calling this method.

See Also addBoldedDate


 MonthCalendar.removeMonthlyBoldedDate

MonthCalendar.removeMonthlyBoldedDate

Specifies that a date will not be displayed in bold every month in the month calendar.

Syntax

public void removeMonthlyBoldedDate( Time date )

Parameters

date

A Time object that represents the date to display in with no emphasis every month. If the specified date is not found in the list of dates to display in bold, this method has no effect. If the specified date occurs more than once in the bolded date list, only the first occurrence is removed.

Remarks

Call the updateBoldedDates method after calling this method.


 MonthCalendar.removeOnDateChanged

MonthCalendar.removeOnDateChanged

Removes the delegate that is assigned to the dateChanged event.

Syntax

public void removeOnDateChanged( DateRangeEventHandler value )

Parameters

value

The DateRangeEventHandler delegate to be removed.

See Also addOnDateChanged


 MonthCalendar.removeOnDateSelected

MonthCalendar.removeOnDateSelected

Removes the delegate that is assigned to the dateSelected event.

Syntax

public void removeOnDateSelected( DateRangeEventHandler value )

Parameters

value

The DateRangeEventHandler delegate to be removed.

See Also addOnDateSelected


 MonthCalendar.resetMaxDate

MonthCalendar.resetMaxDate

Resets the calendar so that there is no upper limit to the selectable range of dates.

Syntax

public void resetMaxDate()

See Also getMaxDate


 MonthCalendar.resetMinDate

MonthCalendar.resetMinDate

Resets the calendar so that there is no lower limit to the selectable range of dates.

Syntax

public void resetMinDate()

See Also getMinDate


 MonthCalendar.resetSelectionRange

MonthCalendar.resetSelectionRange

Resets the selected range of the control to the current date.

Syntax

public void resetSelectionRange()

See Also getSelectionRange


 MonthCalendar.resetTodayDate

MonthCalendar.resetTodayDate

Resets the "today" date to the current date.

Syntax

public void resetTodayDate()

See Also getTodayDate


 MonthCalendar.setAnnuallyBoldedDates

MonthCalendar.setAnnuallyBoldedDates

Sets an array of Time objects that represent dates that are displayed in bold every year in the month calendar.

Syntax

public void setAnnuallyBoldedDates( Time[] dates )

Parameters

dates

An array of Time objects that represent the dates to display in bold every year in the month calendar.

Remarks

Calling this method removes existing information about which dates to display in bold.

See Also getAnnuallyBoldedDates


 MonthCalendar.setBoldedDates

MonthCalendar.setBoldedDates

Sets an array of Time objects that represent dates that are displayed in bold in the month calendar.

Syntax

public void setBoldedDates( Time[] dates )

Parameters

dates

An array of Time objects that represent the dates to display in bold in the month calendar.

Remarks

Calling this method removes existing information about which dates to display in bold.

See Also getBoldedDates


 MonthCalendar.setDate

MonthCalendar.setDate

Selects the specified date in the calendar.

Syntax

public void setDate( Time date )

Parameters

date

A Time object that represents the selected date.


 MonthCalendar.setDimensions

MonthCalendar.setDimensions

Sets the number of columns and rows of months that the control will display.

Syntax

public void setDimensions( Dimensions dimensions )

public void setDimensions( int rows, int columns )

Parameters

dimensions

A Dimensions object that contains the dimensions of the control. By default, the control displays one row and one column of months.

rows

An integer that represents the number of rows to display.

columns

An integer that represents the number of columns to display.

Remarks

Sets the number of columns and rows of months that the control will display. By default, the control will display one row and one column of months.

See Also getDimensions


 MonthCalendar.setFirstDayOfWeek

MonthCalendar.setFirstDayOfWeek

Sets the first day of the week for the month calendar control.

Syntax

public void setFirstDayOfWeek( int value )

Parameters

value

An integer that represents a day of the week. Possible return values are constants defined in the Days class. The default value is Days.DEFAULT.

Exceptions

WFCInvalidArgumentException thrown if the specified value is not a valid Days constant.

See Also getFirstDayOfWeek


 MonthCalendar.setMaxDate

MonthCalendar.setMaxDate

Sets a value indicating the last date that the control allows the user to select.

Syntax

public void setMaxDate( Time max )

Parameters

max

A Time object that represents the last date that is available for selection in the control. Set to null to remove any upper limit for allowable dates. The default value is null.

Exceptions

WFCSystemException thrown if the method cannot set the value.

See Also getMaxDate


 MonthCalendar.setMaxSelectionCount

MonthCalendar.setMaxSelectionCount

Sets the maximum number of days that can be selected in a month calendar control.

Syntax

public void setMaxSelectionCount( int max )

Parameters

max

An integer that represents the maximum number of days that can be selected at one time in the control. The default value is 7.

Exceptions

WFCSystemException thrown if this method cannot set the value.

Remarks

Calling this method does not affect the current selection range.

See Also getMaxSelectionCount


 MonthCalendar.setMinDate

MonthCalendar.setMinDate

Sets a value indicating the first date that the control allows the user to select.

Syntax

public void setMinDate( Time min )

Parameters

min

A Time object that represents the first date that is available for selection in the control. Set to null to remove any lower limit for allowable dates. The default value is null.

Exceptions

WFCSystemException thrown if this method is unable to set the value.

Remarks

The month calendar control does not support dates earlier than 1601.

See Also getMinDate


 MonthCalendar.setMonthlyBoldedDates

MonthCalendar.setMonthlyBoldedDates

Sets an array of Time objects that represent dates that are displayed in bold every month in the month calendar.

Syntax

public void setMonthlyBoldedDates( Time[] dates )

Parameters

dates

An array of Time objects that represent the dates to display in bold every month in the month calendar.

Remarks

Calling this method removes existing information about which dates to display in bold.

See Also getMonthlyBoldedDates


 MonthCalendar.setScrollChange

MonthCalendar.setScrollChange

Sets the scroll rate for a month calendar control.

Syntax

public void setScrollChange( int rate )

Parameters

rate

An integer that indicates the number of months the control should offset its display when the user clicks a scroll button. If you specify zero (0) for this parameter, the scroll rate is reset to the default, which is the number of months displayed in the control. The default value is one (1).

Remarks

The scroll rate is the number of months that the control moves its display when the user clicks a scroll button.

See Also getScrollChange


 MonthCalendar.setSelectionEnd

MonthCalendar.setSelectionEnd

Sets the end of the date range currently selected in the control.

Syntax

public void setSelectionEnd( Time date )

Parameters

date

A Time object that represents the last date in the selection range. If this value is before the first date in the current selection, or if selecting this date would cause the selection range to exceed the maximum selection count, the end date will not be set.

See Also getSelectionEnd


 MonthCalendar.setSelectionRange

MonthCalendar.setSelectionRange

Sets the selection for a month calendar control to a specified date range.

Syntax

public void setSelectionRange( Time date1, Time date2 )

public void setSelectionRange( SelectionRange range )

Parameters

date1

A Time object that represents the first date in the selection range.

date2

A Time object that represents the last date in the selection range.

range

A SelectionRange object that represents the new selection range. The selection range will not be set if it exceeds the maximum selection count, or if either element in the range array is less than 0.

Remarks

The selection range will not be set if it exceeds the maximum selection count.

See Also setSelectionStart, setSelectionEnd , getSelectionRange


 MonthCalendar.setSelectionStart

MonthCalendar.setSelectionStart

Sets the start date of the selection range.

Syntax

public void setSelectionStart( Time date )

Parameters

date

A Time object that represents the first date in the selection range. If this value is after the last date in the current selection, or if selecting this date would cause the selection range to exceed the maximum selection count, the starting date will not be set.

See Also getSelectionStart, setSelectionEnd, setSelectionStart, setSelectionRange


 MonthCalendar.setShowToday

MonthCalendar.setShowToday

Sets a boolean value indicating whether the month calendar control will display the "today" date at the bottom of the control.

Syntax

public void setShowToday( boolean value )

Parameters

value

Set to true if the "today" date will appear on the control; otherwise, set to false. The default value is true.

See Also getShowToday


 MonthCalendar.setShowTodayCircle

MonthCalendar.setShowTodayCircle

Sets a boolean value indicating whether the month calendar control will circle the "today" date.

Syntax

public void setShowTodayCircle( boolean value )

Parameters

value

Set to true if the control will circle the "today" date; otherwise, set to false. The default value is true.

See Also getShowTodayCircle


 MonthCalendar.setShowWeekNumbers

MonthCalendar.setShowWeekNumbers

Sets a boolean value indicating whether the month calendar control displays week numbers (1 through 52) to the left of each row of days.

Syntax

public void setShowWeekNumbers( boolean value )

Parameters

value

Set to true to display the week numbers; otherwise, set to false. The default value is false.

See Also getShowWeekNumbers


 MonthCalendar.setTitleBackColor

MonthCalendar.setTitleBackColor

Sets the background color displayed in the month calendar's title.

Syntax

public void setTitleBackColor( Color value )

Parameters

value

Set to a Color object that represents the background color displayed in the month calendar's title. The default value is the default active window caption background color.

Exceptions

WFCInvalidArgumentException thrown if the specified parameter evaluates to null.

See Also getTitleBackColor


 MonthCalendar.setTitleForeColor

MonthCalendar.setTitleForeColor

Sets the color used to display text within the month calendar's title.

Syntax

public void setTitleForeColor( Color value )

Parameters

value

Set to a Color object that represents the text color for the month calendar's title. The default value is the default active window caption text color.

Exceptions

WFCInvalidArgumentException thrown if the specified parameter evaluates to null.

See Also getTitleForeColor


 MonthCalendar.setTodayDate

MonthCalendar.setTodayDate

Sets the "today" selection for a month calendar control.

Syntax

public void setTodayDate( Time date )

Parameters

date

A Time object that represents the "today" date value. Set to -1 to reset the "today" date value to the default setting (the current system date).

Exceptions

WFCSystemException thrown if this method is unable to change the date value.

See Also getTodayDate


 MonthCalendar.setTrailingForeColor

MonthCalendar.setTrailingForeColor

Sets the color used to display text for header and trailing-day days (days from the previous and following month that appear on the current calendar).

Syntax

public void setTrailingForeColor( Color value )

Parameters

value

Set to a Color object that represents the color used to display text for header and trailing-day days. The default value is the default window gray text value.

Exceptions

WFCInvalidArgumentException thrown if the specified parameter evaluates to null.

See Also getTrailingForeColor


 MonthCalendar.shouldPersistMaxDate

MonthCalendar.shouldPersistMaxDate

Retrieves a boolean value indicating whether the value of the maxDate property has been explicitly set.

Syntax

public boolean shouldPersistMaxDate()

Return Value

Returns true if the property has been explicitly set; returns false if it still has the default value null.


 MonthCalendar.shouldPersistMinDate

MonthCalendar.shouldPersistMinDate

Retrieves a boolean value indicating whether the value of the minDate property has been explicitly set.

Syntax

public boolean shouldPersistMinDate()

Return Value

Returns true if the property has been explicitly set; returns false if it still has the default value of null.


 MonthCalendar.shouldPersistSelectionRange

MonthCalendar.shouldPersistSelectionRange

Retrieves a boolean value indicating whether the value of the selectionRange property has been explicitly set.

Syntax

public boolean shouldPersistSelectionRange()

Return Value

Returns true if the property has been explicitly set; returns false if it still has the default value of null.


 MonthCalendar.shouldPersistTodayDate

MonthCalendar.shouldPersistTodayDate

Retrieves a boolean value indicating whether the value of the todayDate property has been explicitly set.

Syntax

public boolean shouldPersistTodayDate()

Return Value

Returns true if the property has been explicitly set; returns false if it still has the default value of null.


 MonthCalendar.updateBoldedDates

MonthCalendar.updateBoldedDates

Updates the list of dates that are displayed in bold in the month calendar and repaints the calendar.

Syntax

public void updateBoldedDates()


MouseButton Class

Defines constants that specify which mouse button was pressed.

Enum
  |
  +--MouseButton

package com.ms.wfc.ui

public class MouseButton
extends Enum


 MouseButton Methods

MouseButton Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 MouseButton.valid

MouseButton.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 MouseButton Fields

MouseButton Fields

Fields | Description
LEFT | Specifies that the left mouse button was pressed.
MIDDLE | Specifies that the middle mouse button was pressed.
NONE | Specifies that no mouse button was pressed.
RIGHT | Specifies that the right mouse button was pressed.


 MouseButton.LEFT

MouseButton.LEFT

Specifies that the left mouse button was pressed.

Syntax

public static final int LEFT;


 MouseButton.MIDDLE

MouseButton.MIDDLE

Specifies that the middle mouse button was pressed.

Syntax

public static final int MIDDLE;


 MouseButton.NONE

MouseButton.NONE

Specifies that no mouse button was pressed.

Syntax

public static final int NONE;


 MouseButton.RIGHT

MouseButton.RIGHT

Specifies that the right mouse button was pressed.

Syntax

public static final int RIGHT;


MouseEvent Class

Provides data for the the mouseDown, mouseEnter, mouseLeave, mouseMove, or mouseUp event of a Control object.

Event
  |
  +--MouseEvent

package com.ms.wfc.ui

public class MouseEvent
extends Event

Remarks

The mouseDown event occurs when the user presses the mouse down over this control. The mouseEnter event occurs when the mouse first moves over this control. The mouseLeave event occurs when the mouse first moves out of this control. The mouseMove event occurs when the user moves the mouse over this control. The mouseUp event occurs when the user releases a mouse button inside the control. A MouseEvent object specifies which mouse button was pressed, how many times the mouse button was pressed, the coordinates of the location of the mouse click, and the amount the mouse wheel moved.

For information about the WFC event model, see Handling Events in WFC.


 MouseEvent Methods

MouseEvent Methods

Constructors | Description
MouseEvent | Creates a MouseEvent object.


 MouseEvent.MouseEvent

MouseEvent.MouseEvent

Creates a MouseEvent object.

Syntax

public MouseEvent( int button, int clicks, int x, int y, int delta )

public MouseEvent( Object extendedInfo, int button, int clicks, int x, int y, int delta )

Parameters

extendedInfo

Additional information supplied by com.ms.wfc.html events. You should not pass a value for this parameter outside the context of the com.ms.wfc.html package. For more information, see Event.extendedInfo and DhEventInfo.

button

An integer that indicates which mouse button was pressed. Possible values are constants defined in the MouseButton class. This value is MouseButton.NONE if no mouse button was pressed when the event was generated.

clicks

An integer that indicates how many times the mouse button was pressed.

x

An integer that represents the x-coordinate of the mouse click (in client coordinates).

y

An integer that represents the y-coordinate of the mouse click (in client coordinates).

delta

An integer that represents the amount that the mouse wheel has moved.


 MouseEvent Fields

MouseEvent Fields

Fields | Description
button | Specifies which mouse button was pressed.
clicks | Specifies how many times the mouse button was pressed.
delta | Specifies the amount that the mouse wheel has moved.
x | Specifies the x-coordinate of the mouse click (in client coordinates).
y | Specifies the y-coordinate of the mouse click (in client coordinates).


 MouseEvent.button

MouseEvent.button

Specifies which mouse button was pressed.

Syntax

public final int button;

Remarks

Possible values are constants defined in the MouseButton class. This value is MouseButton.NONE if no mouse button was pressed when the event was generated.


 MouseEvent.clicks

MouseEvent.clicks

Specifies how many times the mouse button was pressed.

Syntax

public final int clicks;


 MouseEvent.delta

MouseEvent.delta

Specifies the amount that the mouse wheel has moved.

Syntax

public final int delta;

Remarks

Microsoft standards specify that the view should scroll by the number of lines returned by com.ms.wfc.app.SystemInformation.getMouseWheelScrollLines when the delta value has reached the value specified in win.WHEEL_DELTA. If a mouseWheel event occurs with a value less than WHEEL_DELTA, the control should either increment a stored value and wait until the total delta is an increment of WHEEL_DELTA or scroll the view a percentage of MouseWheelScrollLines.


 MouseEvent.x

MouseEvent.x

Specifies the x-coordinate of the mouse click (in client coordinates).

Syntax

public final int x;


 MouseEvent.y

MouseEvent.y

Specifies the y-coordinate of the mouse click (in client coordinates).

Syntax

public final int y;


MouseEventHandler Delegate

Identifies the method handling the mouseDown, mouseEnter, mouseLeave, mouseMove, or mouseUp event of a Control control.

package com.ms.wfc.ui

public multicast delegate
void MouseEventHandler( Object sender, MouseEvent e );

Remarks

The syntax of the MouseEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a MouseEvent object that provides the event data.

When you create a MouseEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC.


NodeLabelEditEvent Class

Provides data for the afterLabelEdit event and the beforeLabelEdit event of a TreeView control.

Event
  |
  +--NodeLabelEditEvent

package com.ms.wfc.ui

public class NodeLabelEditEvent
extends Event

Remarks

The afterLabelEdit event occurs when the user finishes editing the text for a tree node. The beforeLabelEdit event occurs when the user begins editing the text for a tree node. A NodeLabelEditEvent object specifies the new text to associate with the tree node, the tree node that contains the text to edit, and whether the edit operation has been canceled.

For information about the WFC event model, see Handling Events in WFC.


 NodeLabelEditEvent Methods

NodeLabelEditEvent Methods

Constructors | Description
NodeLabelEditEvent | Creates a NodeLabelEditEvent object.

Methods | Description
cancelEdit | Cancels the edit operation on the text of the tree node.


 NodeLabelEditEvent.cancelEdit

NodeLabelEditEvent.cancelEdit

Cancels the edit operation on the text of the tree node.

Syntax

public void cancelEdit()


 NodeLabelEditEvent.NodeLabelEditEvent

NodeLabelEditEvent.NodeLabelEditEvent

Creates a NodeLabelEditEvent object.

Syntax

public NodeLabelEditEvent( TreeNode node )

public NodeLabelEditEvent( TreeNode node, String label )

Parameters

node

The tree node containing the text to edit.

label

The new text to associate with the tree node.


 NodeLabelEditEvent Fields

NodeLabelEditEvent Fields

Fields | Description
cancelEdit | Specifies whether the edit has been canceled.
label | Specifies the new text to associate with the tree node.
node | Specifies the tree node containing the text to edit.


 NodeLabelEditEvent.label

NodeLabelEditEvent.label

Specifies the new text to associate with the tree node.

Syntax

public final String label;


 NodeLabelEditEvent.node

NodeLabelEditEvent.node

Specifies the tree node containing the text to edit.

Syntax

public final TreeNode node;


NodeLabelEditEventHandler Delegate

Identifies the method that will handle the afterLabelEdit event and the beforeLabelEdit event of a TreeView control.

package com.ms.wfc.ui

public multicast delegate
void NodeLabelEditEventHandler( Object sender, NodeLabelEditEvent e );

Remarks

The syntax of the NodeLabelEditEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a NodeLabelEditEvent object that provides the event data.

When you create a NodeLabelEditEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC.


OpenFileDialog Class

Encapsulates the Save As common dialog box control that allows the user to open a file.

Component
  |
  +--CommonDialog
    |
    +--FileDialog
      |
      +--OpenFileDialog

package com.ms.wfc.ui

public class OpenFileDialog
extends FileDialog

Remarks

The following example sets options for an Open dialog box, displays the dialog box, and saves the names of the files the user selects in a string array:

private void btnOpen_click(Object source, Event e)
{
    OpenFileDialog ofd = new OpenFileDialog();
    ofd.setDefaultExt("java");	//sets the default extension
    ofd.setFilter("Java files (*.java)|*.java|All files (*.*)|*.*"); //sets the file filter
    ofd.setFilterIndex(1);  //sets the filter that will be initially selected
    ofd.setInitialDir("c:\\program files");  //sets the initial directory
    int dlgResult = ofd.showDialog();
    if (dlgResult == DialogResult.OK) {
        String[] fnames = ofd.getFileNames(); //gets the names of the files the user chose
    }
}


 OpenFileDialog Methods

OpenFileDialog Methods

Methods | Description
getMultiselect | Retrieves a boolean value indicating whether the dialog box allows multiple files to be selected.
getReadOnlyChecked | Retrieves a boolean value indicating whether the Open as read-only check box is currently selected.
getShowReadOnly | Retrieves a boolean value indicating whether the dialog box contains an Open as read-only check box that the user can select to open a file in read-only mode.
reset | Resets all dialog box options to their default values.
setMultiselect | Sets a boolean value indicating whether the dialog box allows multiple files to be selected.
setReadOnlyChecked | Sets a boolean value indicating whether the Open as read-only check box is initially selected when the dialog box opens.
setShowReadOnly | Sets a boolean value indicating whether the dialog box contains an Open as read-only check box that the user can select to open a file in read-only mode.


 OpenFileDialog.getMultiselect

OpenFileDialog.getMultiselect

Retrieves a boolean value indicating whether the dialog box allows multiple files to be selected.

Syntax

public final boolean getMultiselect()

Return Value

Returns true if the dialog allows multiple files to be selected at one time; returns false if only one file can be selected at one time.

See Also setMultiselect


 OpenFileDialog.getReadOnlyChecked

OpenFileDialog.getReadOnlyChecked

Retrieves a boolean value indicating whether the Open as read-only check box is currently selected.

Syntax

public final boolean getReadOnlyChecked()

Return Value

Returns true if the Open as read-only check box is selected; returns false if it is cleared.

Remarks

To display the Open as read-only check box in the dialog box, use the setShowReadOnly method.

See Also setReadOnlyChecked


 OpenFileDialog.getShowReadOnly

OpenFileDialog.getShowReadOnly

Retrieves a boolean value indicating whether the dialog box contains an Open as read-only check box that the user can select to open a file in read-only mode.

Syntax

public final boolean getShowReadOnly()

Return Value

Returns true if the dialog contains an Open as read-only check box; otherwise, returns false.

See Also setShowReadOnly


 OpenFileDialog.reset

OpenFileDialog.reset

Resets all dialog box options to their default values.

Syntax

public final void reset()


 OpenFileDialog.setMultiselect

OpenFileDialog.setMultiselect

Sets a boolean value indicating whether the dialog box allows multiple files to be selected.

Syntax

public final void setMultiselect( boolean value )

Parameters

value

Set to true to specify that the dialog allows multiple files to be selected at one time; set to false to specify that only one file can be selected at one time. The default value is false.

See Also getMultiselect


 OpenFileDialog.setReadOnlyChecked

OpenFileDialog.setReadOnlyChecked

Sets a boolean value indicating whether the Open as read-only check box is initially selected when the dialog box opens.

Syntax

public final void setReadOnlyChecked( boolean value )

Parameters

value

Set to true to specify that the Open as read-only check box be selected when the dialog box opens; set to false to specify that it be cleared. The default value is false.

Remarks

To display the Open as read-only check box in the dialog box, use the setShowReadOnly method.

See Also getReadOnlyChecked


 OpenFileDialog.setShowReadOnly

OpenFileDialog.setShowReadOnly

Sets a boolean value indicating whether the dialog box contains an Open as read-only check box that the user can select to open a file in read-only mode.

Syntax

public final void setShowReadOnly( boolean value )

Parameters

value

Set to true if to include an Open as read-only check box in the dialog box; otherwise, set to false. The default value is false.

See Also getShowReadOnly


Orientation Class

Defines a group of constants that represent the orientation of a control or of an element of the control.

Enum
  |
  +--Orientation

package com.ms.wfc.ui

public class Orientation
extends Enum

Remarks

The TrackBar and the Rebar controls are examples of objects that support orientation settings. For example, the TrackBar control can be displayed either horizontally or vertically, and the Rebar control supports the horizontal or vertical stacking of its child controls.


 Orientation Methods

Orientation Methods

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value designates a valid Orientation constant.


 Orientation.valid

Orientation.valid

Retrieves a boolean value that indicates whether a specified value designates a valid Orientation constant.

Syntax

public static boolean valid( int value )

Parameters

value

A value to be compared to those defined in this class.

Return Value

Returns true if value designates a member of this class; otherwise, returns false.


 Orientation Fields

Orientation Fields

Fields | Description
HORIZONTAL | Indicates that the control is oriented horizontally.
VERTICAL | Indicates that the control is oriented vertically.


 Orientation.HORIZONTAL

Orientation.HORIZONTAL

Indicates that the control is oriented horizontally.

Syntax

public static final int HORIZONTAL;


 Orientation.VERTICAL

Orientation.VERTICAL

Indicates that the control is oriented vertically.

Syntax

public static final int VERTICAL;


PaintEvent Class

Provides data for the paint event of the Control object.

Event
  |
  +--PaintEvent

package ms.com.wfc.ui

public class PaintEvent
extends Event

Remarks

The paint event occurs when a control needs to be painted. A PaintEvent object specifies the Graphics object to use to paint the control and the rectangle in which to paint.

For information about the WFC event model, see Handling Events in WFC.


 PaintEvent Methods

PaintEvent Methods

Constructors | Description
PaintEvent | Creates a PaintEvent object.


 PaintEvent.PaintEvent

PaintEvent.PaintEvent

Creates a PaintEvent object.

Syntax

public PaintEvent( Graphics graphics, RECT rect )

Parameters

graphics

The Graphics object used to paint the item.

rect

The com.ms.win32.RECT structure that represents the rectangle in which to paint.


 PaintEvent Fields

PaintEvent Fields

Fields | Description
clipRect | Specifies the Rectangle object that represents the rectangle in which to paint.
graphics | Specifies the Graphics object used to paint the item.


 PaintEvent.clipRect

PaintEvent.clipRect

Specifies the Rectangle object that represents the rectangle in which to paint.

Syntax

public final Rectangle clipRect;


 PaintEvent.graphics

PaintEvent.graphics

Specifies the Graphics object used to paint the item.

Syntax

public final Graphics graphics;


PaintEventHandler Delegate

Identifies the method handling the paint event of a Control control.

package com.ms.wfc.ui

public multicast delegate
void PaintEventHandler( Object sender, PaintEvent e );

Remarks

The syntax of the PaintEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a PaintEvent object that provides the event data.

When you create a PaintEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC.


Palette Class

Encapsulates a Windows logical palette.

package com.ms.wfc.ui

public class Palette

Remarks

A logical palette is a group of colors. Windows uses palettes for various operations. For example, Windows may associate a palette with a bitmap to define the set of colors the bitmap uses. Associating a palette with the bitmap conserves memory, since each pixel in the bitmap needs only to reference an entry in the palette, rather than completely specifying its color.

When a system is using a 256-color video driver, Windows uses the driver's palette information to control the display's hardware palette. Windows can display bitmaps using near true color quality in this way, because it optimizes all the colors of a display device to a bitmap.

Typically, WFC handles all palette interactions for you. However, you can use this object to exercise finer control over palette operations.


 Palette Methods

Palette Methods

Constructors | Description
Palette | Creates a Palette object.

Methods | Description
clone | Clones the Palette object and returns a duplicate.
copyHandle | Retrieves a copy of the Win32 handle (HPALETTE) for the palette.
destroyHandle | Called when this object is going to destroy its Win32 handle.
dispose | Frees all the resources allocated by this object.
equals | Retrieves a boolean value that indicates whether the specified object is equivalent to this Palette object.
finalize | Frees the resources allocated by this object.
getHalftonePalette | Retrieves a stock Windows halftone palette.
getHandle | Retrieves the Win32 handle to this palette.
getPaletteSupported | Retrieves a boolean value that indicates whether the display driver supports palettes.


 Palette.clone

Palette.clone

Clones the Palette object and returns a duplicate.

Syntax

public Object clone()

Return Value

Returns an Object that can be cast to a Palette object.


 Palette.copyHandle

Palette.copyHandle

Retrieves a copy of the Win32 handle (HPALETTE) for the palette.

Syntax

public final int copyHandle()

Return Value

Returns a copy of the Win32 handle to the palette that underlies this object.

Remarks

When you copy a palette handle, you own the handle and are responsible for freeing it.


 Palette.destroyHandle

Palette.destroyHandle

Called when this object is going to destroy its Win32 handle.

Syntax

protected void destroyHandle()

Remarks

The Palette class' implementation of the destroyHandle method frees only handles owned by the Palette object. If you have created this object based on a previously allocated handle, this method does nothing; you are responsible for freeing the handle. Additionally, if you have used the Palette object's copyHandle method to duplicate its handle, a call to destroyHandle does not free this handle; you are responsible for freeing it.

However, you can override this method in your Palette-derived class to define your own custom semantics for handle destruction.


 Palette.dispose

Palette.dispose

Frees all the resources allocated by this object.

Syntax

public void dispose()

Remarks

The dispose method frees only those resources allocated by the object. Such resources do not include handle copies that you retrieve using the object's methods; you must free these manually.

Once the dispose method is called, the Palette object is no longer useful.


 Palette.equals

Palette.equals

Retrieves a boolean value that indicates whether the specified object is equivalent to this Palette object.

Syntax

public boolean equals( Object pal )

Parameters

pal

The object to compare to this one.

Return Value

Returns true if the given object is equivalent to this object; otherwise, returns false. For this method to return true, the specified object must be a Palette object and must be equal to this one.


 Palette.finalize

Palette.finalize

Frees the resources allocated by this object.

Syntax

protected void finalize()

Remarks

A call to finalize is equivalent to a call to the Palette object's dispose method.


 Palette.getHalftonePalette

Palette.getHalftonePalette

Retrieves a stock Windows halftone palette.

Syntax

public static final Palette getHalftonePalette()

Return Value

Returns a Palette object that specifies a stock halftone palette.

Remarks

A halftone palette consists of a broad variety of colors and is not tuned to any specific bitmap.


 Palette.getHandle

Palette.getHandle

Retrieves the Win32 handle to this palette.

Syntax

public int getHandle()

Return Value

Returns a handle to the palette.

Exceptions

WFCException thrown if the Palette object has been disposed through a call to its dispose method.

Remarks

The handle returned by this method is not a copy of the palette handle. Therefore, this handle should not be freed by the caller.

See Also copyHandle


 Palette.getPaletteSupported

Palette.getPaletteSupported

Retrieves a boolean value that indicates whether the display driver supports palettes.

Syntax

public static final boolean getPaletteSupported()

Return Value

Returns true if palettes are supported; otherwise, returns false.


 Palette.Palette

Palette.Palette

Creates a Palette object.

Syntax

public Palette( int handle )

Parameters

handle

The handle (HPALETTE) on which to base the palette.

Remarks

When you create a palette based on a previously allocated Windows handle, the Palette object does not take ownership of that handle; you are responsible for freeing the handle when you are finished.


Panel Class

Represents a container you can use to parent other controls visually.

Component
  |
  +--Control
    |
    +--Panel

package com.ms.wfc.ui

public class Panel
extends Control


 Panel Methods

Panel Methods

Constructors | Description
Panel | Creates a Panel control.

Methods | Description
getBorderStyle | Retrieves a value indicating the kind of border the panel has.
onPaint | Triggers the paint event.
onResize | Triggers the resize event.
setBorderStyle | Sets a value indicating the kind of border the panel has.


 Panel.getBorderStyle

Panel.getBorderStyle

Retrieves a value indicating the kind of border the panel has.

Syntax

public final int getBorderStyle()

Return Value

Returns an integer that specifies the kind of border the panel has. Possible return values are constants defined in the BorderStyle class.


 Panel.onPaint

Panel.onPaint

Triggers the paint event.

Syntax

protected void onPaint( PaintEvent event )

Parameters

event

A PaintEvent object that provides the event data.

Remarks

When overriding onPaint, be sure to call super.onPaint.


 Panel.onResize

Panel.onResize

Triggers the resize event.

Syntax

protected void onResize( Event event )

Parameters

event

An Event object that provides the event data.

Remarks

When overriding onResize, be sure to call super.onResize.


 Panel.Panel

Panel.Panel

Creates a Panel control.

Syntax

public Panel()


 Panel.setBorderStyle

Panel.setBorderStyle

Sets a value indicating the kind of border the panel has.

Syntax

public final void setBorderStyle( int value )

Parameters

value

An integer that specifies the kind of border the panel has. Possible values are constants defined in the BorderStyle class. The default value is BorderStyle.NONE_3D.

Exceptions

WFCInvalidEnumException thrown if the specified value is not a valid BorderStyle constant.


Pen Class

Encapsulates a Windows pen that applications use to draw lines, curves, and shapes.

package com.ms.wfc.ui

public final class Pen

Remarks

An application associates a Pen object with a Graphics object using the Graphics object's setPen method. After this association is established, all lines drawn using that object use the associated pen.


 Pen Methods

Pen Methods

Constructors | Description
Pen | Creates a Pen object.

Methods | Description
clone | Creates a duplicate of this Pen object.
copyHandle | Retrieves a copy of this pen's handle (HPEN).
destroyHandle | Called when this object is about to destroy its handle.
dispose | Frees all resources allocated by this object.
equals | Retrieves a boolean value that indicates whether the specified object is equivalent to this Pen object.
finalize | Frees the resources allocated by this object.
getColor | Retrieves the color of this pen.
getHandle | Retrieves the Win32 handle for this pen.
getStyle | Retrieves the style of this pen.
getWidth | Retrieves the width of this pen in logical units.
hashCode | Computes the hash code for this object.


 Pen.clone

Pen.clone

Creates a duplicate of this Pen object.

Syntax

public Object clone()

Return Value

Returns a Pen object that is a duplicate of this one.


 Pen.copyHandle

Pen.copyHandle

Retrieves a copy of this pen's handle (HPEN).

Syntax

public final int copyHandle()

Return Value

Returns the Win32 handle to the pen.

Remarks

When you use copyHandle to retrieve the handle to a pen, you assume ownership of the handle and are responsible for freeing it.


 Pen.destroyHandle

Pen.destroyHandle

Called when this object is about to destroy its handle.

Syntax

protected void destroyHandle()

Remarks

If you create a Pen object based on a Win32 handle, this handle is not freed in the default implementation of this method. However, in classes that extend the Pen class, you can override this function to free handles that the object does not own.


 Pen.dispose

Pen.dispose

Frees all resources allocated by this object.

Syntax

public void dispose()

Remarks

The resources freed by this object are limited to those allocated by it. If you construct a Pen object based on a previously-allocated Win32 handle, the call to the dispose method does not free this object.


 Pen.equals

Pen.equals

Retrieves a boolean value that indicates whether the specified object is equivalent to this Pen object.

Syntax

public boolean equals( Object obj )

Parameters

obj

The object to compare to this one.

Return Value

Returns true if the given object is equivalent to this object; otherwise, returns false. The specified object must be a Pen object.


 Pen.finalize

Pen.finalize

Frees the resources allocated by this object.

Syntax

protected void finalize() throws Throwable

Exceptions

Throwable thrown if this object's resources could not be freed.

Remarks

A call to finalize is equivalent to a call to the Pen object's dispose method.


 Pen.getColor

Pen.getColor

Retrieves the color of this pen.

Syntax

public final Color getColor()

Return Value

Returns a Color object that specifies the color of this pen.


 Pen.getHandle

Pen.getHandle

Retrieves the Win32 handle for this pen.

Syntax

public int getHandle()

Return Value

Returns a Win32 pen handle (HPEN).


 Pen.getStyle

Pen.getStyle

Retrieves the style of this pen.

Syntax

public final int getStyle()

Return Value

Returns the pen style, which is one of the enumeration constants defined in the PenStyle class.


 Pen.getWidth

Pen.getWidth

Retrieves the width of this pen in logical units.

Syntax

public final int getWidth()

Return Value

Returns the width of the pen in logical units. If the width of the pen is zero, this method returns 1, regardless of the current transformation.


 Pen.hashCode

Pen.hashCode

Computes the hash code for this object.

Syntax

public int hashCode()

Return Value

Returns an integer hash code value.


 Pen.Pen

Pen.Pen

Creates a Pen object.

Syntax

public Pen( Color color )

public Pen( Color color, int style )

public Pen( Color color, int style, int width )

public Pen( int handle )

Parameters

color

A Color object specifying the color of the pen.

style

The style of the pen to create. This value must be one of the enumeration constants defined in the PenStyle class.

width

The width of the pen in logical units. If this value is zero, the pen is one pixel wide, regardless of the current transformation.

handle

A Win32 pen handle (HPEN).

Exceptions

WFCInvalidArgumentException thrown if there is an illegal argument.

Remarks

If you create a Pen object specifying only a color, the style of the pen will be PenStyle.SOLID, and the pen will be one pixel wide.

If you create a Pen object based on a Win32 pen handle, the Pen object does not assume ownership of that pen. You are responsible for freeing the handle when you are finished using the object. For more information on handle destruction, see destroyHandle.


 Pen Fields

Pen Fields

Fields | Description
ACTIVECAPTIONTEXT | Specifies a Pen object that is the color of the active window's caption text.
CONTROLTEXT | Specifies a Pen object that is the color of the text on a button or other control.
GRAYTEXT | Specifies a Pen object that is the color of disabled text.
HIGHLIGHTTEXT | Specifies a Pen object that is the color of highlighted text.
INACTIVECAPTIONTEXT | Specifies a Pen object that is the color of an inactive window's caption text.
INFOTEXT | Specifies a Pen object that is the color of the information ToolTip's text.
MENUTEXT | Specifies a Pen object that is the color of the menu text.
NULL | Specifies a Pen object that does nothing in Graphics operations that require a pen.
WINDOWFRAME | Specifies a Pen object that is the color of the window frame.
WINDOWTEXT | Specifies a Pen object that is the color of a window's text.


 Pen.ACTIVECAPTIONTEXT

Pen.ACTIVECAPTIONTEXT

Specifies a Pen object that is the color of the active window's caption text.

Syntax

public static final Pen ACTIVECAPTIONTEXT;

Remarks

The color represented by this setting is based on the current system settings. If the system setting for active caption text is modified, this object automatically reflects the new setting.


 Pen.CONTROLTEXT

Pen.CONTROLTEXT

Specifies a Pen object that is the color of the text on a button or other control.

Syntax

public static final Pen CONTROLTEXT;

Remarks

The color represented by this setting is based on the current system settings. If the system setting for control text is modified, this object automatically reflects the new setting.


 Pen.GRAYTEXT

Pen.GRAYTEXT

Specifies a Pen object that is the color of disabled text.

Syntax

public static final Pen GRAYTEXT;

Remarks

The color represented by this setting is based on the current system settings. If the system setting for disabled text is modified, this object automatically reflects the new setting.


 Pen.HIGHLIGHTTEXT

Pen.HIGHLIGHTTEXT

Specifies a Pen object that is the color of highlighted text.

Syntax

public static final Pen HIGHLIGHTTEXT;

Remarks

The color represented by this setting is based on the current system settings. If the system setting for highlighted text is modified, this object automatically reflects the new setting.


 Pen.INACTIVECAPTIONTEXT

Pen.INACTIVECAPTIONTEXT

Specifies a Pen object that is the color of an inactive window's caption text.

Syntax

public static final Pen INACTIVECAPTIONTEXT;

Remarks

The color represented by this setting is based on the current system settings. If the system setting for the caption text of inactive windows is modified, this object automatically reflects the new setting.


 Pen.INFOTEXT

Pen.INFOTEXT

Specifies a Pen object that is the color of the information ToolTip's text.

Syntax

public static final Pen INFOTEXT;

Remarks

The color represented by this setting is based on the current system settings. If the system setting for the display of ToolTip text is modified, this object automatically reflects the new setting.


 Pen.MENUTEXT

Pen.MENUTEXT

Specifies a Pen object that is the color of the menu text.

Syntax

public static final Pen MENUTEXT;

Remarks

The color represented by this setting is based on the current system settings. If the system setting for the display of menu text is modified, this object automatically reflects the new setting.


 Pen.NULL

Pen.NULL

Specifies a Pen object that does nothing in Graphics operations that require a pen.

Syntax

public static final Pen NULL;

Remarks

When you use the Graphics object's drawing methods, the methods draw using the current Pen object and fill the drawn area using the current Brush object. If you call one of these methods, and the Pen object associated with the Graphics object is null, only the fill occurs.


 Pen.WINDOWFRAME

Pen.WINDOWFRAME

Specifies a Pen object that is the color of the window frame.

Syntax

public static final Pen WINDOWFRAME;

Remarks

The color represented by this setting is based on the current system settings. If the system setting for the color of window frames is modified, this object automatically reflects the new setting.


 Pen.WINDOWTEXT

Pen.WINDOWTEXT

Specifies a Pen object that is the color of a window's text.

Syntax

public static final Pen WINDOWTEXT;


PenStyle Class

Defines constants for the seven built-in pen styles supported by the Windows operating system.

Enum
|
+--PenStyle

package com.ms.wfc.ui

public class PenStyle
extends Enum

Remarks

When you create a Pen object, you can associate one of the styles that this class defines with that pen. The following example illustrates how to create a Pen object, specifying a DASH style. When a Pen based on this style is used to draw lines, the lines consist of an evenly spaced series of dashes.

Pen p = new Pen(new Color(0,0,0), PenStyle.DASH);


 PenStyle Methods

PenStyle Methods

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value designates a valid PenStyle constant.


 PenStyle.valid

PenStyle.valid

Retrieves a boolean value that indicates whether a specified value designates a valid PenStyle constant.

Syntax

public static boolean valid( int value )

Parameters

value

A value to be compared to those defined in this class.

Return Value

Returns true if value designates a member of this class; otherwise, returns false.


 PenStyle Fields

PenStyle Fields

Fields | Description
DASH | Represents a pen style that consists of a series of dashed lines.
DASHDOT | Represents a pen style that consists of a dash, followed by a dot.
DASHDOTDOT | Represents a pen style that consists of a dash, followed by two dots.
DOT | Represents a pen style that consists of a dotted line.
INSIDEFRAME | Represents a pen style that consists of a solid pen that is drawn from within any given bounding rectangle.
NULL | Represents a null pen. A null pen is one that results in no drawing.
SOLID | Represents a pen style that consists of a solid line.


 PenStyle.DASH

PenStyle.DASH

Represents a pen style that consists of a series of dashed lines.

Syntax

public static final int DASH;


 PenStyle.DASHDOT

PenStyle.DASHDOT

Represents a pen style that consists of a dash, followed by a dot.

Syntax

public static final int DASHDOT;


 PenStyle.DASHDOTDOT

PenStyle.DASHDOTDOT

Represents a pen style that consists of a dash, followed by two dots.

Syntax

public static final int DASHDOTDOT;


 PenStyle.DOT

PenStyle.DOT

Represents a pen style that consists of a dotted line.

Syntax

public static final int DOT;


 PenStyle.INSIDEFRAME

PenStyle.INSIDEFRAME

Represents a pen style that consists of a solid pen that is drawn from within any given bounding rectangle.

Syntax

public static final int INSIDEFRAME;

Remarks

Using this style allows you to have a wide pen that automatically conforms to the interior of a rectangle.


 PenStyle.NULL

PenStyle.NULL

Represents a null pen. A null pen is one that results in no drawing.

Syntax

public static final int NULL;

Remarks

A null pen is useful when you have a function that always draws a border, but you do not want to include the border.


 PenStyle.SOLID

PenStyle.SOLID

Represents a pen style that consists of a solid line.

Syntax

public static final int SOLID;


PictureBox Class

Encapsulates a PictureBox control.

Component
  |
  +--Control
    |
    +--PictureBox

package com.ms.wfc.ui

public class PictureBox
extends Control

Remarks

A PictureBox control can display a graphic from a bitmap, icon, or metafile, as well as from an enhanced metafile, JPEG, or GIF files. It clips the graphic if the control isn't large enough to display the entire image.


 PictureBox Methods

PictureBox Methods

Constructors | Description
PictureBox | Creates a PictureBox control.

Methods | Description
getBorderStyle | Retrieves the border type for the PictureBox control.
getImage | Retrieves the image currently displayed by the PictureBox control.
getPalette | Retrieves the palette for the image that is currently displayed by the PictureBox control.
getSizeMode | Retrieves a value that indicates how the PictureBox control will render the image.
setBorderStyle | Sets the border style for the PictureBox control.
setImage | Associates an image with the PictureBox control.
setSizeMode | Sets the sizing mode for the PictureBox control.


 PictureBox.getBorderStyle

PictureBox.getBorderStyle

Retrieves the border type for the PictureBox control.

Syntax

public final int getBorderStyle()

Return Value

Returns one of the enumeration constants defined in the BorderStyle class.

See Also setBorderStyle


 PictureBox.getImage

PictureBox.getImage

Retrieves the image currently displayed by the PictureBox control.

Syntax

public final Image getImage()

Return Value

Returns an Image object that specifies the currently displayed image. If no image is displayed, this method returns null.


 PictureBox.getPalette

PictureBox.getPalette

Retrieves the palette for the image that is currently displayed by the PictureBox control.

Syntax

public final Palette getPalette()

Return Value

Returns a Palette object that specifies the image's palette if an image is displayed; otherwise, returns null.


 PictureBox.getSizeMode

PictureBox.getSizeMode

Retrieves a value that indicates how the PictureBox control will render the image.

Syntax

public final int getSizeMode()

Return Value

Returns one of the enumeration constants defined in the PictureBoxSizeMode class.

Remarks

By default, the PictureBox control has a sizing mode of PictureBoxSizeMode.NORMAL, which means that the image is placed in the upper-left corner of the control's client area, and that any part of the image that will not fit into this area is clipped.

See Also setSizeMode


 PictureBox.PictureBox

PictureBox.PictureBox

Creates a PictureBox control.

Syntax

public PictureBox()

Remarks

Upon creation, the PictureBox control has a default size of 100 by 50 points and a sizing mode of PictureBoxSizeMode.NORMAL.


 PictureBox.setBorderStyle

PictureBox.setBorderStyle

Sets the border style for the PictureBox control.

Syntax

public final void setBorderStyle( int value )

Parameters

value

The border style for the control. This value must be one of the enumeration constants defined in the BorderStyle class.

Exceptions

WFCInvalidEnumException thrown if the value specified is not a valid member of the BorderStyle class.

See Also getBorderStyle


 PictureBox.setImage

PictureBox.setImage

Associates an image with the PictureBox control.

Syntax

public final void setImage( Image value )

Parameters

value

An Image object that specifies the image to display in this control.

See Also getImage


 PictureBox.setSizeMode

PictureBox.setSizeMode

Sets the sizing mode for the PictureBox control.

Syntax

public final void setSizeMode( int value )

Parameters

value

The sizing mode for the PictureBox control. This value must be one of the enumeration constants defined in the PictureBoxSizeMode class.

Exceptions

WFCInvalidEnumException thrown if the value specified is not a valid member of the PictureBoxSizeMode class.

See Also getSizeMode


PictureBoxSizeMode Class

Defines the constants that determine the sizing mode of the PictureBox control.

Enum
  |
  +--PictureBoxSizeMode

package com.ms.wfc.ui

public class PictureBoxSizeMode
extends Enum

Remarks

The sizing mode specifies how the control is sized to fit the image that is displayed in it.

To retrieve or set the sizing mode on a PictureBox control, use the PictureBox class' getSizeMode and setSizeMode methods.


 PictureBoxSizeMode Methods

PictureBoxSizeMode Methods

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value is a valid member of this class.


 PictureBoxSizeMode.valid

PictureBoxSizeMode.valid

Retrieves a boolean value that indicates whether a specified value is a valid member of this class.

Syntax

public static boolean valid( int value )

Parameters

value

A value to compare to the constants defined in this class.

Return Value

Returns true if the value is valid; otherwise, returns false.


 PictureBoxSizeMode Fields

PictureBoxSizeMode Fields

Fields | Description
AUTO_SIZE | Specifies that the PictureBox control should size itself to fit the image that it displays.
CENTER_IMAGE | Specifies that if the PictureBox control is larger than the image it displays, the image should be centered in the space available in the control.
NORMAL | Specifies that the image should be placed in the upper-left corner of the PictureBox control's client area, that the image should be clipped if the image is larger than the control, and that no other special processing should occur.
STRETCH_IMAGE | Specifies that the image should be stretched or shrunk to correspond to the size of the PictureBox control.


 PictureBoxSizeMode.AUTO_SIZE

PictureBoxSizeMode.AUTO_SIZE

Specifies that the PictureBox control should size itself to fit the image that it displays.

Syntax

public static final int AUTO_SIZE;


 PictureBoxSizeMode.CENTER_IMAGE

PictureBoxSizeMode.CENTER_IMAGE

Specifies that if the PictureBox control is larger than the image it displays, the image should be centered in the space available in the control.

Syntax

public static final int CENTER_IMAGE;

Remarks

If the image is larger than the PictureBox control, the image is placed in the upper-left corner of the control's client area and is clipped as necessary.


 PictureBoxSizeMode.NORMAL

PictureBoxSizeMode.NORMAL

Specifies that the image should be placed in the upper-left corner of the PictureBox control's client area, that the image should be clipped if the image is larger than the control, and that no other special processing should occur.

Syntax

public static final int NORMAL;


 PictureBoxSizeMode.STRETCH_IMAGE

PictureBoxSizeMode.STRETCH_IMAGE

Specifies that the image should be stretched or shrunk to correspond to the size of the PictureBox control.

Syntax

public static final int STRETCH_IMAGE;


Point Class

Encapsulates a single (x,y) coordinate and the operations that you can perform on such a coordinate.

package com.ms.wfc.ui

public class Point
implements IConstructable, IPersistable


 Point Methods

Point Methods

Constructors | Description
Point | Creates a Point object.

Methods | Description
equals | Retrieves a boolean value that indicates whether the specified object is equivalent to this one.
getConstructorArgs | Retrieves the ConstructorArgs needed to persist this object.
getExtension | Returns the recommended extension for files that persist this object.
hashCode | Retrieves an integer hash code for this object.
save | Saves this object's data to a specified data stream.
toPOINT | Retrieves a Win32 POINT structure representing this object.
toSIZE | Retrieves a Win32 SIZE structure representing this object.
toString | Retrieves a string representation of this object.


 Point.equals

Point.equals

Retrieves a boolean value that indicates whether the specified object is equivalent to this one.

Syntax

public boolean equals( Object obj )

Parameters

obj

An object to compare to this one.

Return Value

Returns true if the specified object is equivalent to this one; otherwise, returns false.

Remarks

If the object specified in the obj parameter is not a Point object, this method returns false.


 Point.getConstructorArgs

Point.getConstructorArgs

Retrieves the ConstructorArgs needed to persist this object.

Syntax

public ConstructorArg[] getConstructorArgs()

Return Value

Returns an array of ConstructorArg objects.


 Point.getExtension

Point.getExtension

Returns the recommended extension for files that persist this object.

Syntax

public String getExtension()

Return Value

Returns a String that identifies the recommended file extensions. Because the Point object is not a persisted object, this method always returns null.


 Point.hashCode

Point.hashCode

Retrieves an integer hash code for this object.

Syntax

public int hashCode()

Return Value

Returns an integer hash code for this object.


 Point.Point

Point.Point

Creates a Point object.

Syntax

public Point()

public Point( int x, int y )

public Point( Point pt )

public Point( POINT pt )

public Point( SIZE size )

public Point( int dw )

public Point( IDataStream stream )

Parameters

x

The horizontal coordinate for this point.

y

The vertical coordinate for this point.

pt

A Point object or a Win32 POINT structure on which to base this Point object.

size

A Win32 SIZE structure on which to base this Point object.

dw

An integer that stores the horizontal and vertical coordinates for the point in its high and low words.

stream

A data stream from which to load the point settings.

See Also toPOINT, toSIZE


 Point.save

Point.save

Saves this object's data to a specified data stream.

Syntax

public void save( IDataStream stream )

Parameters

stream

An IDataStream to which to save the data.


 Point.toPOINT

Point.toPOINT

Retrieves a Win32 POINT structure representing this object.

Syntax

public POINT toPOINT()

Return Value

Returns a Win32 POINT structure that contains this object's current settings.


 Point.toSIZE

Point.toSIZE

Retrieves a Win32 SIZE structure representing this object.

Syntax

public SIZE toSIZE()

Return Value

Returns a Win32 SIZE structure that contains this object's current settings.

See Also toPoint


 Point.toString

Point.toString

Retrieves a string representation of this object.

Syntax

public String toString()

Return Value

Returns a String that contains this object's settings.


 Point Fields

Point Fields

Fields | Description
x | Specifies the horizontal position of the coordinate.
y | Specifies the vertical position of the coordinate.


 Point.x

Point.x

Specifies the horizontal position of the coordinate.

Syntax

public int x;


 Point.y

Point.y

Specifies the vertical position of the coordinate.

Syntax

public int y;


PolyFillMode Class

Defines a group of constants that describe the approaches to filling areas in a polygon.

package com.ms.wfc.ui

public class PolyFillMode
extends Enum

Remarks

This class defines a group of constants that define how the Graphics object's drawPolygon method fills the enclosed areas of a polygon.


 PolyFillMode Methods

PolyFillMode Methods

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value is a valid member of the PolyFillMode class.


 PolyFillMode.valid

PolyFillMode.valid

Retrieves a boolean value that indicates whether a specified value is a valid member of the PolyFillMode class.

Syntax

public static boolean valid( int value )

Parameters

value

A value to be compared to those defined in this class.

Return Value

Returns true if the value designates a member of this class; otherwise, returns false.


 PolyFillMode Fields

PolyFillMode Fields

Fields | Description
ALTERNATE | Represents a fill mode in which the system fills the area between odd-numbered and even-numbered polygon sides on each scan line.
WINDING | Represents a fill mode in which the system uses the direction in which a figure was drawn to determine whether to fill the area.


 PolyFillMode.ALTERNATE

PolyFillMode.ALTERNATE

Represents a fill mode in which the system fills the area between odd-numbered and even-numbered polygon sides on each scan line.

Syntax

public static final int ALTERNATE;


 <b>PolyFillMode.WINDING</b>

PolyFillMode.WINDING

Represents a fill mode in which the system uses the direction in which a figure was drawn to determine whether to fill the area.

Syntax

public static final int WINDING;


ProgressBar Class

Encapsulates the ProgressBar control.

Component
  |
  +--Control
    |
    +--ProgressBar

package com.ms.wfc.ui

public final class ProgressBar
extends Control

Remarks

A progress bar is a window that an application uses to indicate visually the progress of a lengthy operation.

The ProgressBar control consists of a window that is filled, from left to right, with the system highlight color as an operation progresses. A ProgressBar control has a range and a current position.

The range represents the entire duration of the operation. For example, to map the progress of a file copy, the range of the operation might be 100 percent. The current position represents the progress that the application has made toward completing the operation. The control itself uses the range and the current position to determine the percentage of the ProgressBar control to fill, and to determine what text, if any, to display on the ProgressBar.

Because the range and current position on a ProgressBar control are expressed as unsigned integers, the highest possible range and current position value is 65,535.


 ProgressBar Methods

ProgressBar Methods

Constructors | Description
ProgressBar | Creates a ProgressBar control.

Methods | Description
getMaximum | Retrieves the upper limit of the ProgressBar control's range.
getMinimum | Retrieves the lower limit of the ProgressBar control's range.
getStep | Retrieves the step increment for the ProgressBar control.
getValue | Retrieves the current position for the ProgressBar control.
increment | Advances the current position for the ProgressBar control by the specified step increment and redraws the control to reflect the new position.
setMaximum | Sets the upper limit of the ProgressBar control's range and redraws the control to reflect the new value.
setMinimum | Sets the lower limit of the ProgressBar control's range and redraws the control to reflect the new value.
setStep | Specifies the step increment for a progress bar.
setValue | Sets the ProgressBar control's current position and redraws the control to reflect the new position.
step | Advances the current position for a progress bar by the step increment and redraws the control to reflect the new position.


 ProgressBar.getMaximum

ProgressBar.getMaximum

Retrieves the upper limit of the ProgressBar control's range.

Syntax

public final int getMaximum()

Return Value

Returns the upper limit of the range.

See Also setMaximum


 ProgressBar.getMinimum

ProgressBar.getMinimum

Retrieves the lower limit of the ProgressBar control's range.

Syntax

public final int getMinimum()

Return Value

Returns the lower limit of the range.

See Also setMinimum


 ProgressBar.getStep

ProgressBar.getStep

Retrieves the step increment for the ProgressBar control.

Syntax

public final int getStep()

Return Value

Returns an integer that identifies the current step increment.

Remarks

The step increment is the amount by which a call to increment increases the progress bar's current position.

See Also setStep


 ProgressBar.getValue

ProgressBar.getValue

Retrieves the current position for the ProgressBar control.

Syntax

public final int getValue()

Return Value

Returns the current position for the control. The current position indicates the amount of the ProgressBar control that is filled with the system color.

See Also setValue


 ProgressBar.increment

ProgressBar.increment

Advances the current position for the ProgressBar control by the specified step increment and redraws the control to reflect the new position.

Syntax

public final void increment( int value )

Parameters

value

The amount by which to increment the control's current position.


 ProgressBar.ProgressBar

ProgressBar.ProgressBar

Creates a ProgressBar control.

Syntax

public ProgressBar()

Remarks

By default, the range of a ProgressBar control is 0 to 100 and the step is 10.


 ProgressBar.setMax

ProgressBar.setMaximum

Sets the upper limit of the ProgressBar control's range and redraws the control to reflect the new value.

Syntax

public final void setMaximum( int value )

Parameters

value

The new upper limit of the range.

See Also getMaximum


 ProgressBar.setMinimum

ProgressBar.setMinimum

Sets the lower limit of the ProgressBar control's range and redraws the control to reflect the new value.

Syntax

public final void setMinimum( int value )

Parameters

value

The new lower limit of the range.

See Also getMinimum


 ProgressBar.setStep

ProgressBar.setStep

Specifies the step increment for a progress bar.

Syntax

public final void setStep( int stepNew )

Parameters

stepNew

The step increment.

Remarks

The step increment is the amount by which the progress bar increases its current position whenever the step method is called. By default, the step increment is set to 10.


 ProgressBar.setValue

ProgressBar.setValue

Sets the ProgressBar control's current position and redraws the control to reflect the new position.

Syntax

public final void setValue( int value )

Parameters

value

The new position on the ProgressBar control.

See Also getValue


 ProgressBar.step

ProgressBar.step

Advances the current position for a progress bar by the step increment and redraws the control to reflect the new position.

Syntax

public final void step()

Remarks

An application sets the step increment by calling the setStep method.

See Also increment


QueryContinueDragEvent Class

Provides data for the queryContinueDrag event of the Control object.

Event
  |
  +--QueryContinueDragEvent

package com.ms.wfc.ui

public class QueryContinueDragEvent
extends Event

Remarks

The queryContinueDrag event occurs during a drag-and-drop operation and allows the drag source to determine whether the drag-and-drop operation should be canceled. A QueryContinueDragEvent object specifies whether and how the drag-and-drop operation should proceed, whether any modifier keys are pressed, and whether the user has pressed the ESC key.

For information about the WFC event model, see Handling Events in WFC.

See Also DragAction


 QueryContinueDragEvent Methods

QueryContinueDragEvent Methods

Constructors | Description
QueryContinueDragEvent | Creates a QueryContinueDragEvent object.


 QueryContinueDragEvent.QueryContinueDragEvent

QueryContinueDragEvent.QueryContinueDragEvent

Creates a QueryContinueDragEvent object.

Syntax

public QueryContinueDragEvent( int keyState, boolean escapePressed, int action )

Parameters

keyState

The current state of the SHIFT, CTRL, and ALT keys.

escapePressed

Set to true if the user has pressed the ESC key.

action

Set to ACTION_CONTINUE to continue the drag operation.


 QueryContinueDragEvent Fields

QueryContinueDragEvent Fields

Fields | Description
action | This will be used as the response to the query.
escapePressed | Set to true if the user has pressed the ESC key.
keyState | Specifies the current state of the SHIFT, CTRL, and ALT keys.


 QueryContinueDragEvent.action

QueryContinueDragEvent.action

This will be used as the response to the query.

Syntax

public int action;

Remarks

Set to a constant in the DragAction class. Set to DragAction.ACTION_CONTINUE to continue the drag operation.

See Also DragAction


 QueryContinueDragEvent.escapePressed

QueryContinueDragEvent.escapePressed

Set to true if the user has pressed the ESC key.

Syntax

public final boolean escapePressed;


 QueryContinueDragEvent.keyState

QueryContinueDragEvent.keyState

Specifies the current state of the SHIFT, CTRL, and ALT keys.

Syntax

public final int keyState;


QueryContinueDragEventHandler Delegate

Identifies the method handling the queryContinueDrag event of a Control control.

package com.ms.wfc.ui

public multicast delegate
void QueryContinueDragEventHandler( Object sender, QueryContinueDragEvent e );

Remarks

The syntax of the QueryContinueDragEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a QueryContinueDragEvent object that provides the event data.

When you create a QueryContinueDragEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC.


RadioButton Class

Encapsulates a radio button (or option button) control, which displays an option that can be turned on or off.

Component
  |
  +--Control
    |
    +--RadioButton

package com.ms.wfc.ui

public class RadioButton
extends Control

Remarks

Radio buttons differ from check box controls because radio buttons in a container are mutually exclusive: turning one option on automatically turns all the other options off. To create several groups of mutually exclusive radio buttons on the same form, place each set of radio buttons in a container, such as a group box.


 RadioButton Methods

RadioButton Methods

Constructors | Description
RadioButton | Creates a RadioButton control.

Methods | Description
addOnCheckedChanged | Assigns a delegate to the checkedChanged event.
getAppearance | Retrieves a value that indicates whether the radio button will have the appearance of a command button rather than the usual appearance of a radio button.
getAutoCheck | Retrieves a boolean value that indicates whether the user can change the value of the radio button by clicking it or whether the value can only be changed programmatically.
getChecked | Retrieves a boolean value that indicates whether the radio button is turned on or off.
getTextAlign | Retrieves a value that indicates where the text for the RadioButton control is positioned relative to the circle that shows whether the option is turned on or off.
onCheckedChanged | Triggers the checkedChanged event.
onClick | Triggers the click event.
performClick | Generates a click event for the button, simulating a click by a user.
removeOnCheckedChanged | Removes the delegate that is assigned to the checkedChanged event.
setAppearance | Sets a value that indicates whether the radio button will have the appearance of a command button rather than the usual appearance of a radio button.
setAutoCheck | Sets a boolean value that indicates whether the user can change the value of the check box by clicking it or whether the value can only be changed programmatically.
setChecked | Sets a boolean value that indicates whether the radio button is turned on.
setTextAlign | Sets a value that indicates where the text for the RadioButton control is positioned relative to the circle that shows whether the option is turned on or off.


 RadioButton.addOnCheckedChanged

RadioButton.addOnCheckedChanged

Assigns a delegate to the checkedChanged event.

Syntax

public final void addOnCheckedChanged( EventHandler handler )

Parameters

handler

The EventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the checkedChanged event to that method in the Properties window. The checkedChanged event occurs when the value of the radio button changes. The change can be made by the user or programmatically.

See Also removeOnCheckedChanged


 RadioButton.getAppearance

RadioButton.getAppearance

Retrieves a value that indicates whether the radio button will have the appearance of a command button rather than the usual appearance of a radio button.

Syntax

public final int getAppearance()

Return Value

Returns an integer that specifies the current appearance of the radio button. Possible return values are constants defined in the Appearance class. If the value is Appearance.NORMAL, the radio button has the usual appearance of a radio button. If the value is Appearance.BUTTON, the radio button has the appearance of a command button.

Remarks

For a radio button that looks like a command button, a pushed-in appearance is equivalent to being turned on, and a popped-up appearance is equivalent to being turned off.

See Also setAppearance


 RadioButton.getAutoCheck

RadioButton.getAutoCheck

Retrieves a boolean value that indicates whether the user can change the value of the radio button by clicking it or whether the value can only be changed programmatically.

Syntax

public final boolean getAutoCheck()

Return Value

Returns true if the user can change the value of the radio button by clicking it; returns false if the value of the control can only be changed programmatically.

See Also setAutoCheck


 RadioButton.getChecked

RadioButton.getChecked

Retrieves a boolean value that indicates whether the radio button is turned on or off.

Syntax

public final boolean getChecked()

Return Value

Returns true if the radio button is turned on; returns false if the radio button is turned off.

See Also setChecked


 RadioButton.getTextAlign

RadioButton.getTextAlign

Retrieves a value that indicates where the text for the RadioButton control is positioned relative to the circle that shows whether the option is turned on or off.

Syntax

public final int getTextAlign()

Return Value

Returns an integer that specifies the current position of the text relative to the circle. Possible return values are constants defined in the LeftRightAlignment class. If the value is LeftRightAlignment.RIGHT (default), the text appears to the right of the circle. If the value is LeftRightAlignment.LEFT, the text appears to the left of the circle.

See Also setTextAlign


 RadioButton.onCheckedChanged

RadioButton.onCheckedChanged

Triggers the checkedChanged event.

Syntax

protected void onCheckedChanged( Event e )

Parameters

e

An Event object that provides the event data.

Remarks

When overriding this method, call super.onCheckedChanged.

See Also addOnCheckedChanged


 RadioButton.onClick

RadioButton.onClick

Triggers the click event.

Syntax

protected void onClick( Event e )

Parameters

e

An Event object that provides the event data.

Remarks

When overriding this method, call super.onClick.


 RadioButton.performClick

RadioButton.performClick

Generates a click event for the button, simulating a click by a user.

Syntax

public final void performClick()


 RadioButton.RadioButton

RadioButton.RadioButton

Creates a RadioButton control.

Syntax

public RadioButton()


 RadioButton.removeOnCheckedChanged

RadioButton.removeOnCheckedChanged

Removes the delegate that is assigned to the checkedChanged event.

Syntax

public final void removeOnCheckedChanged( EventHandler handler )

Parameters

handler

The EventHandler delegate to be removed.

See Also addOnCheckedChanged


 RadioButton.setAppearance

RadioButton.setAppearance

Sets a value that indicates whether the radio button will have the appearance of a command button rather than the usual appearance of a radio button.

Syntax

public final void setAppearance( int value )

Parameters

value

An integer that specifies the current appearance of the radio button. Possible values are constants defined in the Appearance class. If the value is set to Appearance.NORMAL, the radio button has the usual appearance of a radio button. If the value is set to Appearance.BUTTON, the radio button has the appearance of a command button. The default value is Appearance.NORMAL.

Remarks

For a radio button that looks like a command button, a pushed-in appearance is equivalent to being turned on, and a popped-up appearance is equivalent to being turned off.

See Also getAppearance


 RadioButton.setAutoCheck

RadioButton.setAutoCheck

Sets a boolean value that indicates whether the user can change the value of the check box by clicking it or whether the value can only be changed programmatically.

Syntax

public final void setAutoCheck( boolean value )

Parameters

value

Set to true if the user can change the value of the check box by clicking it; set to false if the value of the control can only be changed programmatically. The default value is true.

See Also getAutoCheck


 RadioButton.setChecked

RadioButton.setChecked

Sets a boolean value that indicates whether the radio button is turned on.

Syntax

public final void setChecked( boolean value )

Parameters

value

Set to true to turn the radio button on; set to false to turn the the radio button off. The default value is false.

See Also getChecked


 RadioButton.setTextAlign

RadioButton.setTextAlign

Sets a value that indicates where the text for the RadioButton control is positioned relative to the circle that shows whether the option is turned on or off.

Syntax

public final void setTextAlign( int value )

Parameters

value

An integer that specifies the current position of the text relative to the circle. Possible values are constants defined in the LeftRightAlignment class. If the value is LeftRightAlignment.RIGHT (default), the text appears to the right of the circle. If the value is LeftRightAlignment.LEFT, the text appears to the left of the circle. The default value is LeftRightAlignment.RIGHT.

Exceptions

WFCInvalidEnumException thrown if the specified value is not a valid LeftRightAlignment constant.

See Also getTextAlign


Radix Class

Defines constants that specify the supported base values for the up-down control.

Enum
  |
  +--Radix

package com.ms.wfc.ui

public class Radix
extends Enum

Remarks

The base value determines whether the buddy control for the up-down control displays numbers in decimal or hexadecimal digits.


 Radix Methods

Radix Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 Radix.valid

Radix.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 Radix Fields

Radix Fields

Fields | Description
DECIMAL | Specifies that the buddy control for the up-down control displays numbers in decimal digits.
HEXADECIMAL | Specifies that the buddy control for the up-down control displays numbers in hexadecimal digits.


 Radix.DECIMAL

Radix.DECIMAL

Specifies that the buddy control for the up-down control displays numbers in decimal digits.

Syntax

public static final int DECIMAL;

Remarks

Decimal numbers are signed.


 Radix.HEXADECIMAL

Radix.HEXADECIMAL

Specifies that the buddy control for the up-down control displays numbers in hexadecimal digits.

Syntax

public static final int HEXADECIMAL;


RasterOp Class

Encapsulates a Win32 raster operation.

package com.ms.wfc.ui

public class RasterOp

Remarks

A raster operation refers to a series of boolean operations that you can apply to bitmaps, brushes, and pens.

Suppose, for example, that you have two identical images, one of which is black and white (monochrome), and the other in color. Suppose further that you want to write the monochrome image to the colored one, but do not want the white pixels in the source image to overwrite their counterparts in the destination. Raster operations enable you to use boolean logic to make such changes.

Generally, you build a raster operation using a combination of a series of simple operations and boolean logic.


 RasterOp Methods

RasterOp Methods

Methods | Description
andWith | Performs a binary AND operation that combines this RasterOp object with another.
getRop | Retrieves the ternary ROP code for this raster operation.
getRop2 | Retrieves the binary ROP2 code for this raster operation.
invert | Retrieves a RasterOp object that represents an inversion of this one.
orWith | Performs a binary OR operation that combines this RasterOp object with another.
xorWith | Performs a binary XOR operation that combines this RasterOp object with another.


 RasterOp.andWith

RasterOp.andWith

Performs a binary AND operation that combines this RasterOp object with another.

Syntax

public final RasterOp andWith( RasterOp op )

Parameters

op

The RasterOp that participates with this one in the operation.

Return Value

Returns a RasterOp object that represents the result of the binary AND operation.

See Also orWith, xorWith


 RasterOp.getRop

RasterOp.getRop

Retrieves the ternary ROP code for this raster operation.

Syntax

public int getRop()

Return Value

Returns the ternary ROP code for this raster operation.

Remarks

Raster operation codes define how the Windows graphics device interface (GDI) combines the bits from one object with those of another.

A ternary raster operation involves three operands: a source bitmap, a brush, and a destination bitmap. Both binary and ternary raster operations use boolean logical operators.


 RasterOp.getRop2

RasterOp.getRop2

Retrieves the binary ROP2 code for this raster operation.

Syntax

public int getRop2()

Return Value

Returns the binary ROP2 code for this raster operation.

Remarks

A ROP2 code is defined as a binary raster operation code.


 RasterOp.invert

RasterOp.invert

Retrieves a RasterOp object that represents an inversion of this one.

Syntax

public final RasterOp invert()

Return Value

Returns a RasterOp object that represents an inversion of this one.


 RasterOp.orWith

RasterOp.orWith

Performs a binary OR operation that combines this RasterOp object with another.

Syntax

public final RasterOp orWith( RasterOp op )

Parameters

op

A RasterOp object that participates with this one in the operation.

Return Value

Returns a RasterOp object that represents the result of the binary OR operation.

See Also andWith, xorWith


 RasterOp.xorWith

RasterOp.xorWith

Performs a binary XOR operation that combines this RasterOp object with another.

Syntax

public final RasterOp xorWith( RasterOp op )

Parameters

op

A RasterOp that participates with this one in the logical XOR operation.

Return Value

Returns a RasterOp object that represents the result of the binary XOR operation.

See Also andWith, orWith


 RasterOp Fields

RasterOp Fields

Fields | Description
BLACK | Represents a raster operation in which the resulting pixels will be black.
BRUSH | Represents a raster operation in which the resulting pixels will be the color of the current brush.
PEN | Represents a raster operation in which the resulting pixels will be the color of the current pen.
SOURCE | Represents a raster operation in which the resulting pixels will be the color of the source image pixels.
TARGET | Represents a raster operation in which the resulting pixels will be the color of the target image pixels.
WHITE | Represents a raster operation in which the resulting pixels will be white.


 RasterOp.BLACK

RasterOp.BLACK

Represents a raster operation in which the resulting pixels will be black.

Syntax

public static final RasterOp BLACK;


 RasterOp.BRUSH

RasterOp.BRUSH

Represents a raster operation in which the resulting pixels will be the color of the current brush.

Syntax

public static final RasterOp BRUSH;


 RasterOp.PEN

RasterOp.PEN

Represents a raster operation in which the resulting pixels will be the color of the current pen.

Syntax

public static final RasterOp PEN;


 RasterOp.SOURCE

RasterOp.SOURCE

Represents a raster operation in which the resulting pixels will be the color of the source image pixels.

Syntax

public static final RasterOp SOURCE;


 RasterOp.TARGET

RasterOp.TARGET

Represents a raster operation in which the resulting pixels will be the color of the target image pixels.

Syntax

public static final RasterOp TARGET;


 RasterOp.WHITE

RasterOp.WHITE

Represents a raster operation in which the resulting pixels will be white.

Syntax

public static final RasterOp WHITE;


ReadyStateEvent Class

Provides data for the readyState event of the DhTable, DhImage, DhDocument, DhInlineFrame, or DhObjectFactory object.

Event
  |
  +--ReadyStateEvent

package com.ms.wfc.ui

public class ReadyStateEvent
extends Event

Remarks

The readyState event occurs when an object being downloaded needs to communicate its current state. A ReadyStateEvent object specifies the state of the object triggering the event.

For information about the WFC event model, see Handling Events in WFC.


 ReadyStateEvent Methods

ReadyStateEvent Methods

Constructors | Description
ReadyStateEvent | Creates a new ReadyStateEvent object.


 ReadyStateEvent.ReadyStateEvent

ReadyStateEvent.ReadyStateEvent

Creates a new ReadyStateEvent object.

Syntax

public ReadyStateEvent( String state )

public ReadyStateEvent( Object extendedInfo, String state )

Parameters

extendedInfo

Additional information supplied by com.ms.wfc.html events. You should not pass a value for this parameter outside the context of the com.ms.wfc.html package. For more information, see Event.extendedInfo and DhEventInfo.

state

A string indicating the current state of the object being downloaded.


 ReadyStateEvent Fields

ReadyStateEvent Fields

Fields | Description
state | Specifies the state of the object triggering the event.


 ReadyStateEvent.state

ReadyStateEvent.state

Specifies the state of the object triggering the event.

Syntax

public final String state;

Remarks

The following table shows possible values:

Value | Description
uninitialized | The object is not initialized with data.
loading | The object is currently loading its data.
interactive | The object can be interacted with even though it is not fully loaded.
complete | The control is completely loaded.
unloading | The object is currently unloading its data.


ReadyStateEventHandler Delegate

Identifies the method that will handle the readyState event of the DhTable, DhImage, DhDocument, DhInlineFrame, or DhObjectFactory object.

package com.ms.wfc.ui

public multicast delegate
void ReadyStateEventHandler( Object sender, ReadyStateEvent e );

Remarks

The syntax of the ReadyStateEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a ReadyStateEvent object that provides the event data.

When you create a ReadyStateEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered. For more information about delegates, see Handling Events in WFC.


Rebar Class

Encapsulates a rebar control, which contains other controls within moveable, resizable bands.

Component
  |
  +--Control
    |
    +--Rebar

package com.ms.wfc.ui

public class Rebar
extends Control

Remarks

In addition to containing a control, each rebar band can contain a gripper bar, a bitmap, and a text label. Rebar controls are commonly used to contain toolbar controls. Use the addBand method to add a rebar band to the rebar control, and use the RebarBand.setChildControl method to add a control to the rebar band.


 Rebar Methods

Rebar Methods

Constructors | Description
Rebar | Creates a Rebar control.

Methods | Description
add | Adds a control, along with a rebar band to contain it, to the rebar control.
addBand | Adds a rebar band to the rebar control.
addOnAutoSize | Assigns a delegate to the autoSize event.
addOnHeightChange | Assigns a delegate to the heightChange event.
addOnLayoutChange | Assigns a delegate to the layoutChange event.
getAutoSize | Retrieves a boolean value indicating whether the rebar will automatically adjust its size when the bands it contains are moved or resized.
getBandBorders | Retrieves a boolean value indicating whether narrow lines separate adjacent bands in the rebar control.
getBands | Retrieves the all the bands in the rebar.
getBorderStyle | Retrieves a value indicating the kind of border the rebar control has.
getDoubleClickToggle | Retrieves a boolean value indicating whether the user double-clicks or single-clicks to toggle the size of the rebar band.
getFixedOrder | Retrieves a boolean value indicating whether the user can change the order of the bands in the rebar control.
getImageList | Retrieves the image list control associated with the rebar control.
getOrientation | Retrieves a value indicating whether the rebar control is oriented horizontally or vertically.
onAutoSize | Triggers the autoSize event.
onHeightChange | Triggers the heightChange event.
onLayoutChange | Triggers the layoutChange event.
onResize | Triggers the resize event.
remove | Removes a control, along with the band that contains it, from the rebar control.
removeAllBands | Removes all bands from the rebar control.
removeBand | Removes the specified band from the rebar control.
removeOnAutoSize | Removes the delegate that is assigned to the autoSize event.
removeOnHeightChange | Removes the delegate that is assigned to the heightChange event.
removeOnLayoutChange | Removes the delegate that is assigned to the layoutChange event.
setAutoSize | Sets a boolean value indicating whether the rebar will automatically adjust its size when the bands it contains are moved or resized.
setBandBorders | Sets a boolean value indicating whether narrow lines separate adjacent bands in the rebar control.
setBands | Adds a set of bands to the rebar control.
setBorderStyle | Sets a value indicating the kind of border the rebar control has.
setDock | Sets a value indicating which edge of its container this control is docked to.
setDoubleClickToggle | Sets a boolean value indicating whether the user double-clicks or single-clicks to toggle the size of the rebar band.
setFixedOrder | Sets a boolean value indicating whether the user can change the order of the bands in the rebar control.
setImageList | Sets the image list control associated with the rebar control.
setNewControls | Adds controls, along with bands to contain them, to the rebar control.
setOrientation | Sets a value indicating whether the rebar control is oriented horizontally or vertically.


 Rebar.add

Rebar.add

Adds a control, along with a rebar band to contain it, to the rebar control.

Syntax

public void add( Control control )

Parameters

control

A Control object that represents the control to be added. If the specified control already exists on another rebar band, calling this method has no effect.

Exceptions

WFCException thrown if the specified control is a top-level control or if adding the new control as a child would result in a circular control reference.


 Rebar.addBand

Rebar.addBand

Adds a rebar band to the rebar control.

Syntax

public void addBand( RebarBand band )

Parameters

band

The RebarBand object that represents the band to add to the rebar control.

Remarks

To add a control to the rebar band, use the RebarBand.setChildControl method. To add a control and rebar band at the same time, use the add method.


 Rebar.addOnAutoSize

Rebar.addOnAutoSize

Assigns a delegate to the autoSize event.

Syntax

public void addOnAutoSize( AutoSizeEventHandler handler )

Parameters

handler

The AutoSizeEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the autoSize event to that method in the Properties window. The autoSize event occurs when the rebar automatically resizes itself in response to a change in the size or position of the bands it contains. The autoSize event occurs only if the autoSize property for the rebar band is set to true.

See Also removeOnAutoSize


 Rebar.addOnHeightChange

Rebar.addOnHeightChange

Assigns a delegate to the heightChange event.

Syntax

public void addOnHeightChange( EventHandler handler )

Parameters

handler

The EventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the heightChange event to that method in the Properties window. The heightChange event occurs when the bands in a rebar are moved in a way that changes the height of the rebar control. If the orientation property of the rebar is set to Orientation.VERTICAL, this event occurs when the width of the control changes.

See Also removeOnHeightChange


 Rebar.addOnLayoutChange

Rebar.addOnLayoutChange

Assigns a delegate to the layoutChange event.

Syntax

public void addOnLayoutChange( EventHandler handler )

Parameters

handler

The EventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the layoutChange event to that method in the Properties window. The layoutChange event occurs when the layout of the rebar bands changes.

See Also removeOnLayoutChange


 Rebar.getAutoSize

Rebar.getAutoSize

Retrieves a boolean value indicating whether the rebar will automatically adjust its size when the bands it contains are moved or resized.

Syntax

public boolean getAutoSize()

Return Value

Returns true if the rebar will automatically resize itself to fit its bands; otherwise, returns false.

See Also setAutoSize


 Rebar.getBandBorders

Rebar.getBandBorders

Retrieves a boolean value indicating whether narrow lines separate adjacent bands in the rebar control.

Syntax

public boolean getBandBorders()

Return Value

Returns true if narrow lines separate adjacent rebar bands; otherwise, returns false.

See Also setBandBorders


 Rebar.getBands

Rebar.getBands

Retrieves the all the bands in the rebar.

Syntax

public RebarBand[] getBands()

Return Value

Returns a zero-based array of RebarBand objects that represent the bands in this rebar control.

See Also setBands


 Rebar.getBorderStyle

Rebar.getBorderStyle

Retrieves a value indicating the kind of border the rebar control has.

Syntax

public int getBorderStyle()

Return Value

Returns an integer that specifies the kind of border the rebar control has. Possible return values are constants defined in the BorderStyle class. If the value is BorderStyle.FIXED_3D, the rebar control has a three-dimensional border.

See Also setBorderStyle


 Rebar.getDoubleClickToggle

Rebar.getDoubleClickToggle

Retrieves a boolean value indicating whether the user double-clicks or single-clicks to toggle the size of the rebar band.

Syntax

public boolean getDoubleClickToggle()

Return Value

Returns true if the user double-clicks to toggle the size of the rebar band; returns false if the user single-clicks to toggle the size of the rebar band.

Remarks

When the user clicks to toggle the size of the rebar band, the size alternates between the maximum size, the minimum size, and the ideal size.

See Also setDoubleClickToggle


 Rebar.getFixedOrder

Rebar.getFixedOrder

Retrieves a boolean value indicating whether the user can change the order of the bands in the rebar control.

Syntax

public boolean getFixedOrder()

Return Value

Returns true if the user can resize the bands and move them to different rows in the rebar control but cannot change the display order of the bands in the rebar control; returns false if the user can change the display order of the rebar bands.

See Also setFixedOrder


 Rebar.getImageList

Rebar.getImageList

Retrieves the image list control associated with the rebar control.

Syntax

public ImageList getImageList()

Return Value

Returns an ImageList object that contains a set of images from which you can choose the images to display in the rebar bands.

See Also setImageList


 Rebar.getOrientation

Rebar.getOrientation

Retrieves a value indicating whether the rebar control is oriented horizontally or vertically.

Syntax

public int getOrientation()

Return Value

Returns Orientation.HORIZONTAL if the rebar control is oriented horizontally; returns Orientation.VERTICAL if the rebar control is oriented vertically.

See Also setOrientation


 Rebar.onAutoSize

Rebar.onAutoSize

Triggers the autoSize event.

Syntax

protected void onAutoSize( AutoSizeEvent event )

Parameters

event

An AutoSizeEvent object that provides the event data.

Remarks

When overriding this method, call super.onAutoSize.

See Also addOnAutoSize, removeOnAutoSize


 Rebar.onHeightChange

Rebar.onHeightChange

Triggers the heightChange event.

Syntax

protected void onHeightChange( Event event )

Parameters

event

An Event object that provides the event data.

Remarks

When overriding this method, call super.onHeightChange.

See Also addOnHeightChange, removeOnHeightChange


 Rebar.onLayoutChange

Rebar.onLayoutChange

Triggers the layoutChange event.

Syntax

protected void onLayoutChange( Event event )

Parameters

event

An Event object that provides the event data.

Remarks

When overriding this method, call super.onLayoutChange.

See Also addOnLayoutChange, removeOnLayoutChange


 Rebar.onResize

Rebar.onResize

Triggers the resize event.

Syntax

protected void onResize( Event event )

Parameters

event

An Event object that provides the event data.

Remarks

When overriding this method, call super.onResize.


 Rebar.Rebar

Rebar.Rebar

Creates a Rebar control.

Syntax

public Rebar()


 Rebar.remove

Rebar.remove

Removes a control, along with the band that contains it, from the rebar control.

Syntax

public void remove( Control ctl )

Parameters

ctl

A Control object that represents the control to remove.


 Rebar.removeAllBands

Rebar.removeAllBands

Removes all bands from the rebar control.

Syntax

public void removeAllBands()


 Rebar.removeBand

Rebar.removeBand

Removes the specified band from the rebar control.

Syntax

public void removeBand( RebarBand band )

Parameters

band

A RebarBand object that represents the band to remove.


 Rebar.removeOnAutoSize

Rebar.removeOnAutoSize

Removes the delegate that is assigned to the autoSize event.

Syntax

public void removeOnAutoSize( AutoSizeEventHandler handler )

Parameters

handler

The AutoSizeEventHandler delegate to be removed.

See Also addOnAutoSize


 Rebar.removeOnHeightChange

Rebar.removeOnHeightChange

Removes the delegate that is assigned to the heightChange event.

Syntax

public void removeOnHeightChange( EventHandler handler )

Parameters

handler

The EventHandler delegate to be removed.

See Also addOnHeightChange


 Rebar.removeOnLayoutChange

Rebar.removeOnLayoutChange

Removes the delegate that is assigned to the layoutChange event.

Syntax

public void removeOnLayoutChange( EventHandler handler )

Parameters

handler

The EventHandler delegate to be removed.

See Also addOnLayoutChange


 Rebar.setAutoSize

Rebar.setAutoSize

Sets a boolean value indicating whether the rebar will automatically adjust its size when the bands it contains are moved or resized.

Syntax

public void setAutoSize( boolean value )

Parameters

value

Set to true if the rebar will automatically resize itself to fit its bands; otherwise, set to false. The default value is true.

See Also getAutoSize


 Rebar.setBandBorders

Rebar.setBandBorders

Sets a boolean value indicating whether narrow lines separate adjacent bands in the rebar control.

Syntax

public void setBandBorders( boolean value )

Parameters

value

Set to true if narrow lines separate adjacent rebar bands; otherwise, set to false. The default value is true.

See Also getBandBorders


 Rebar.setBands

Rebar.setBands

Adds a set of bands to the rebar control.

Syntax

public void setBands( RebarBand[] bands )

Parameters

bands

A zero-based array of RebarBand objects that represent the bands you want to add to the rebar control.

Remarks

This method removes all existing bands from the rebar control before inserting the new bands. To add a control to the rebar band, use the RebarBand.setChildControl method. To add a single band to the rebar control, use the addBand method. To add a control and rebar band at the same time, use the add method.

See Also getBands


 Rebar.setBorderStyle

Rebar.setBorderStyle

Sets a value indicating the kind of border the rebar control has.

Syntax

public void setBorderStyle( int value )

Parameters

value

An integer that specifies the kind of border the rebar control has. Possible values are constants defined in the BorderStyle class. The default value is BorderStyle.FIXED_SINGLE.


 Rebar.setDock

Rebar.setDock

Sets a value indicating which edge of its container this control is docked to.

Syntax

public void setDock( int dock )

Parameters

dock

An integer that represents which edge of its container this control is docked to. Possible values are constants defined in the ControlDock class. The default value is ControlDock.TOP.

Exceptions

WFCInvalidEnumException thrown if the specified value is not a valid ControlDock constant.


 Rebar.setDoubleClickToggle

Rebar.setDoubleClickToggle

Sets a boolean value indicating whether the user double-clicks or single-clicks to toggle the size of the rebar band.

Syntax

public void setDoubleClickToggle( boolean value )

Parameters

value

Set to true if the user double-clicks to toggle the size of the rebar band; set to false if the user single-clicks to toggle the size of the rebar band. The default value is true.

Remarks

When the user clicks to toggle the size of the rebar band, the size alternates between the maximum size, the minimum size, and the ideal size.

See Also getDoubleClickToggle


 Rebar.setFixedOrder

Rebar.setFixedOrder

Sets a boolean value indicating whether the user can change the order of the bands in the rebar control.

Syntax

public void setFixedOrder( boolean value )

Parameters

value

Set to true if the user can resize the bands and move them to different rows in the rebar control but cannot change the display order of the bands in the rebar control; set to false if the user can change the display order of the rebar bands. The default value is false.

See Also getFixedOrder


 Rebar.setImageList

Rebar.setImageList

Sets the image list control associated with the rebar control.

Syntax

public void setImageList( ImageList value )

Parameters

value

An ImageList object that contains a set of images from which you can choose the images to display in the rebar bands.

See Also getImageList


 Rebar.setNewControls

Rebar.setNewControls

Adds controls, along with bands to contain them, to the rebar control.

Syntax

public void setNewControls( Control[] ctls )

Parameters

ctls

An array of Control objects that represents the controls to add to the rebar control.

Remarks

To add a single control to the rebar control, use the add method.

See Also Control.setNewControls


 Rebar.setOrientation

Rebar.setOrientation

Sets a value indicating whether the rebar control is oriented horizontally or vertically.

Syntax

public void setOrientation( int value )

Parameters

value

Set to Orientation.HORIZONTAL if the rebar control is oriented horizontally; set to Orientation.VERTICAL if the rebar control is oriented vertically. The default value is Orientation.HORIZONTAL.

See Also getOrientation


RebarBand Class

Encapsulates a band on a Rebar control.

Component
  |
  +--RebarBand

package com.ms.wfc.ui

public class RebarBand
extends Component

Remarks


 RebarBand Methods

RebarBand Methods

Constructors | Description
RebarBand | Creates a RebarBand object.

Methods | Description
equals | Retrieves a boolean value indicating whether the specified object is equivalent to this RebarBand object.
getAllowVariableHeight | Retrieves a boolean value indicating whether the rebar control can adjust the height of this band.
getAllowVertical | Retrieves a boolean value indicating whether this rebar band is displayed when the orientation property of the rebar control is set to Orientation.VERTICAL.
getBackgroundImage | Retrieves the background image associated with this rebar band.
getBandBreak | Retrieves a boolean value indicating whether the rebar band begins a new row in the rebar control or whether it can continue a row started by another rebar band.
getChildControl | Retrieves the child control contained by this rebar band.
getChildEdge | Retrieves a boolean value indicating whether the rebar band displays an edge at the top and bottom of the child control.
getFixedBitmap | Retrieves a boolean value indicating whether the background bitmap moves when the rebar band is resized.
getGrowBy | Retrieves the step value, in pixels, by which a variable-height rebar band can grow or shrink during resizing.
getHeaderWidth | Retrieves the width, in pixels, of the rebar band's header.
getIdealWidth | Retrieves the ideal width of the rebar band, in pixels.
getImageIndex | Retrieves the index of the image that appears next to this rebar band.
getIndex | Retrieves the zero-based index of the rebar band within the rebar control.
getInitialHeight | Retrieves the initial height of the rebar band, in pixels.
getMaxInitialHeight | Retrieves the maximum height of the rebar band, in pixels.
getMinChildHeight | Retrieves the minimum height of the rebar band, in pixels.
getMinChildWidth | Retrieves the minimum width of the rebar band, in pixels.
getText | Retrieves the header text for the rebar band.
getVisibleGripper | Retrieves a boolean value indicating whether the rebar band has a sizing grip.
getWidth | Retrieves the width of the rebar band, in pixels.
maximize | Maximizes this rebar band within the rebar control.
minimize | Minimizes this rebar band within the rebar control.
setAllowVariableHeight | Sets a boolean value indicating whether the rebar control can adjust the height of this band.
setAllowVertical | Sets a boolean value indicating whether this rebar band is displayed when the orientation property of the rebar control is set to Orientation.VERTICAL.
setBackgroundImage | Sets the background image associated with this rebar band.
setBandBreak | Sets a boolean value indicating whether the rebar band begins a new row in the rebar control or whether it can continue a row started by another rebar band.
setChildControl | Sets the child control contained by this rebar band.
setChildEdge | Sets a boolean value indicating whether the rebar band displays an edge at the top and bottom of the child control.
setFixedBitmap | Sets a boolean value indicating whether the background bitmap moves when the rebar band is resized.
setGrowBy | Sets the step value, in pixels, by which a variable-height rebar band can increase or decrease during resizing.
setHeaderWidth | Sets the width, in pixels, of the rebar band's header.
setIdealWidth | Sets the ideal width of the rebar band, in pixels.
setImageIndex | Sets the index of the image that appears next to this rebar band.
setIndex | Sets the zero-based index of the band within the rebar control.
setInitialHeight | Sets the initial height of the band, in pixels.
setMaxInitialHeight | Sets the maximum height of the rebar band, in pixels.
setMinChildHeight | Sets the minimum height of the rebar band, in pixels.
setMinChildWidth | Sets the minimum width of the rebar band, in pixels.
setText | Sets the header text for the rebar band.
setVisibleGripper | Sets a boolean value indicating whether the rebar band has a sizing grip.
setWidth | Sets the width of the rebar band, in pixels.
toString | Retrieves a String object that contains information about this rebar band.


 RebarBand.equals

RebarBand.equals

Retrieves a boolean value indicating whether the specified object is equivalent to this RebarBand object.

Syntax

public boolean equals( Object obj )

Parameters

obj

The object to compare to this RebarBand object.

Return Value

Returns true if the specified object is equivalent to this RebarBand object; otherwise, returns false.


 RebarBand.getAllowVariableHeight

RebarBand.getAllowVariableHeight

Retrieves a boolean value indicating whether the rebar control can adjust the height of this band.

Syntax

public boolean getAllowVariableHeight()

Return Value

Returns true if the rebar control can adjust the height of this rebar band; otherwise, returns false.

See Also setAllowVariableHeight


 RebarBand.getAllowVertical

RebarBand.getAllowVertical

Retrieves a boolean value indicating whether this rebar band is displayed when the orientation property of the rebar control is set to Orientation.VERTICAL.

Syntax

public boolean getAllowVertical()

Return Value

Returns true if the rebar band can be displayed vertically; otherwise, returns false.

See Also setAllowVertical


 RebarBand.getBackgroundImage

RebarBand.getBackgroundImage

Retrieves the background image associated with this rebar band.

Syntax

public Bitmap getBackgroundImage()

Return Value

Returns a Bitmap object that represents the image shown in the background of this rebar band.

See Also setBackgroundImage


 RebarBand.getBandBreak

RebarBand.getBandBreak

Retrieves a boolean value indicating whether the rebar band begins a new row in the rebar control or whether it can continue a row started by another rebar band.

Syntax

public boolean getBandBreak()

Return Value

Returns true if the rebar band begins a new row in the rebar control; returns false if the rebar band can continue a row started by another rebar band.

See Also setBandBreak


 RebarBand.getChildControl

RebarBand.getChildControl

Retrieves the child control contained by this rebar band.

Syntax

public Control getChildControl()

Return Value

Returns a Control object that represents the child control for this rebar band.

Remarks

Each rebar band can have only one child control.

See Also setChildControl


 RebarBand.getChildEdge

RebarBand.getChildEdge

Retrieves a boolean value indicating whether the rebar band displays an edge at the top and bottom of the child control.

Syntax

public boolean getChildEdge()

Return Value

Returns true if the rebar band displays an edge at the top and bottom of the child control; otherwise, returns false.

See Also setChildEdge


 RebarBand.getFixedBitmap

RebarBand.getFixedBitmap

Retrieves a boolean value indicating whether the background bitmap moves when the rebar band is resized.

Syntax

public boolean getFixedBitmap()

Return Value

Returns true if the background bitmap does not move when the rebar band is resized; returns false if the background bitmap moves when the rebar band is resized.

See Also setFixedBitmap


 RebarBand.getGrowBy

RebarBand.getGrowBy

Retrieves the step value, in pixels, by which a variable-height rebar band can grow or shrink during resizing.

Syntax

public int getGrowBy()

Return Value

Returns the step value, in pixels, by which a variable-height rebar band can grow or shrink during resizing.

Remarks

When the rebar band is resized, it will be resized in steps specified by this value. The value of this property is ignored if the allowVariableHeight property is set to false.

See Also setGrowBy


 RebarBand.getHeaderWidth

RebarBand.getHeaderWidth

Retrieves the width, in pixels, of the rebar band's header.

Syntax

public int getHeaderWidth()

Return Value

Returns the header width, in pixels, for this rebar band.

Remarks

The band header is the area between the edge of the band and the edge of the child control where rebar band text and images are displayed.

See Also setHeaderWidth


 RebarBand.getIdealWidth

RebarBand.getIdealWidth

Retrieves the ideal width of the rebar band, in pixels.

Syntax

public int getIdealWidth()

Return Value

Returns the ideal width of the rebar band, in pixels.

Remarks

When the user clicks to toggle the size of the rebar band, the size alternates between the maximum size, the minimum size, and the ideal size. This value is used as the ideal height if the rebar band is vertical.

See Also setIdealWidth


 RebarBand.getImageIndex

RebarBand.getImageIndex

Retrieves the index of the image that appears next to this rebar band.

Syntax

public int getImageIndex()

Return Value

Returns the zero-based index within an ImageList object of the image that appears next to this rebar band. The smallImageList property of the Rebar control that contains this rebar band determines which image list is associated with the rebar control. Returns -1 if the imageIndex property of the rebar band has never been set.

See Also setImageIndex


 RebarBand.getIndex

RebarBand.getIndex

Retrieves the zero-based index of the rebar band within the rebar control.

Syntax

public int getIndex()

Return Value

Returns the zero-based index of the rebar band within the rebar control.

See Also setIndex


 RebarBand.getInitialHeight

RebarBand.getInitialHeight

Retrieves the initial height of the rebar band, in pixels.

Syntax

public int getInitialHeight()

Return Value

Returns the initial height of the rebar band, in pixels.

Remarks

The value of this property is ignored if the allowVariableHeight property is set to false.

See Also setInitialHeight


 RebarBand.getMaxInitialHeight

RebarBand.getMaxInitialHeight

Retrieves the maximum height of the rebar band, in pixels.

Syntax

public int getMaxInitialHeight()

Return Value

Returns the maximum height of the rebar band, in pixels.

Remarks

The value of this property is ignored if the allowVariableHeight property is set to false.

See Also setMaxInitialHeight


 RebarBand.getMinChildHeight

RebarBand.getMinChildHeight

Retrieves the minimum height of the rebar band, in pixels.

Syntax

public int getMinChildHeight()

Return Value

Returns the minimum height of the rebar band, in pixels.

See Also setMinChildHeight


 RebarBand.getMinChildWidth

RebarBand.getMinChildWidth

Retrieves the minimum width of the rebar band, in pixels.

Syntax

public int getMinChildWidth()

Return Value

Returns the minimum width of the rebar band, in pixels.

See Also setMinChildWidth


 RebarBand.getText

RebarBand.getText

Retrieves the header text for the rebar band.

Syntax

public String getText()

Return Value

Returns the header text for the rebar band.

See Also setText


 RebarBand.getVisibleGripper

RebarBand.getVisibleGripper

Retrieves a boolean value indicating whether the rebar band has a sizing grip.

Syntax

public boolean getVisibleGripper()

Return Value

Returns true if the rebar band has a sizing grip, even if it is the only band in the rebar control; returns false if the rebar band never has a sizing grip, even if there are multiple bands in the rebar control.

See Also setVisibleGripper


 RebarBand.getWidth

RebarBand.getWidth

Retrieves the width of the rebar band, in pixels.

Syntax

public int getWidth()

Return Value

Returns the width of the rebar band, in pixels.

See Also setWidth


 RebarBand.maximize

RebarBand.maximize

Maximizes this rebar band within the rebar control.

Syntax

public void maximize()

Remarks

The maximum size is determined by the size of the rebar control and the size and position of other rebar bands in the control.


 RebarBand.minimize

RebarBand.minimize

Minimizes this rebar band within the rebar control.

Syntax

public void minimize()

Remarks

The minimum size is determined by the value of the minChildWidth property.


 RebarBand.RebarBand

RebarBand.RebarBand

Creates a RebarBand object.

Syntax

public RebarBand()


 RebarBand.setAllowVariableHeight

RebarBand.setAllowVariableHeight

Sets a boolean value indicating whether the rebar control can adjust the height of this band.

Syntax

public void setAllowVariableHeight( boolean flag )

Parameters

flag

Set to true if the rebar control can adjust the height of this rebar band; otherwise, set to false. The default value is false.

See Also getAllowVariableHeight


 RebarBand.setAllowVertical

RebarBand.setAllowVertical

Sets a boolean value indicating whether this rebar band is displayed when the orientation property of the rebar control is set to Orientation.VERTICAL.

Syntax

public void setAllowVertical( boolean flag )

Parameters

flag

Set to true if the rebar band can be displayed vertically; otherwise, set to false. The default value is false.

See Also getAllowVertical


 RebarBand.setBackgroundImage

RebarBand.setBackgroundImage

Sets the background image associated with this rebar band.

Syntax

public void setBackgroundImage( Bitmap backgroundImage )

Parameters

backgroundImage

A Bitmap object that represents the image shown in the background of this rebar band.

See Also getBackgroundImage


 RebarBand.setBandBreak

RebarBand.setBandBreak

Sets a boolean value indicating whether the rebar band begins a new row in the rebar control or whether it can continue a row started by another rebar band.

Syntax

public void setBandBreak( boolean value )

Parameters

value

Set to true if the rebar band begins a new row in the rebar control; set to false if the rebar band can continue a row started by another rebar band. The default value is true.

See Also getBandBreak


 RebarBand.setChildControl

RebarBand.setChildControl

Sets the child control contained by this rebar band.

Syntax

public void setChildControl( Control childControl )

Parameters

childControl

A Control object that represents the child control for this rebar band.

Remarks

Each rebar band can have only one child control.

See Also getChildControl


 RebarBand.setChildEdge

RebarBand.setChildEdge

Sets a boolean value indicating whether the rebar band displays an edge at the top and bottom of the child control.

Syntax

public void setChildEdge( boolean flag )

Parameters

flag

Set to true if the rebar band displays an edge at the top and bottom of the child control; otherwise, set to false. The default value is false.

See Also getChildEdge


 RebarBand.setFixedBitmap

RebarBand.setFixedBitmap

Sets a boolean value indicating whether the background bitmap moves when the rebar band is resized.

Syntax

public void setFixedBitmap( boolean flag )

Parameters

flag

Set to true if the background bitmap does not move when the rebar band is resized; set to false if the background bitmap moves when the rebar band is resized. The default value is true.

See Also getFixedBitmap


 RebarBand.setGrowBy

RebarBand.setGrowBy

Sets the step value, in pixels, by which a variable-height rebar band can increase or decrease during resizing.

Syntax

public void setGrowBy( int growby )

Parameters

growby

Set to the step value, in pixels, by which a variable-height rebar band can increase or decrease during resizing. The default value is 10.

Remarks

When the rebar band is resized, it will be resized in steps specified by this value. The value of the growBy property is ignored if the allowVariableHeight property is set to false.

See Also getGrowBy


 RebarBand.setHeaderWidth

RebarBand.setHeaderWidth

Sets the width, in pixels, of the rebar band's header.

Syntax

public void setHeaderWidth( int headerWidth )

Parameters

headerWidth

Set to the header width, in pixels, for this rebar band. The default value is zero (0).

Remarks

The rebar band header is the area between the edge of the band and the edge of the child control where band text and images are displayed.

See Also getHeaderWidth


 RebarBand.setIdealWidth

RebarBand.setIdealWidth

Sets the ideal width of the rebar band, in pixels.

Syntax

public void setIdealWidth( int idealWidth )

Parameters

idealWidth

Set to the ideal width of the rebar band, in pixels. The default value is 200.

Remarks

When the user clicks to toggle the size of the rebar band, the size alternates between the maximum size, the minimum size, and the ideal size.

See Also getIdealWidth


 RebarBand.setImageIndex

RebarBand.setImageIndex

Sets the index of the image that appears next to this rebar band.

Syntax

public void setImageIndex( int imageIndex )

Parameters

imageIndex

Set to the zero-based index within an ImageList object of the image that appears next to this rebar band. The smallImageList property of the Rebar control that contains this rebar band determines which image list is associated with the rebar control. Returns -1 if the imageIndex property of the rebar band has never been set.

See Also getImageIndex


 RebarBand.setIndex

RebarBand.setIndex

Sets the zero-based index of the band within the rebar control.

Syntax

public void setIndex( int index )

Parameters

index

The zero-based index of the band within the rebar control.

See Also getIndex


 RebarBand.setInitialHeight

RebarBand.setInitialHeight

Sets the initial height of the band, in pixels.

Syntax

public void setInitialHeight( int initHeight )

Parameters

initHeight

Set to the initial height of the band, in pixels. The default value is 20.

Remarks

The value of this property is ignored if the allowVariableHeight property is set to false.

See Also getInitialHeight


 RebarBand.setMaxInitialHeight

RebarBand.setMaxInitialHeight

Sets the maximum height of the rebar band, in pixels.

Syntax

public void setMaxInitialHeight( int maxInitHeight )

Parameters

maxInitHeight

Set to the maximum height of the rebar band, in pixels. The default value is 100.

Remarks

The value of this property is ignored if the allowVariableHeight property is set to false.

See Also getMaxInitialHeight


 RebarBand.setMinChildHeight

RebarBand.setMinChildHeight

Sets the minimum height of the rebar band, in pixels.

Syntax

public void setMinChildHeight( int minChildHeight )

Parameters

minChildHeight

Set to the minimum height of the rebar band, in pixels. The default value is 20.

See Also getMinChildHeight


 RebarBand.setMinChildWidth

RebarBand.setMinChildWidth

Sets the minimum width of the rebar band, in pixels.

Syntax

public void setMinChildWidth( int minChildWidth )

Parameters

minChildWidth

Set to the minimum width of the rebar band, in pixels. The default value is 50.

See Also getMinChildWidth


 RebarBand.setText

RebarBand.setText

Sets the header text for the rebar band.

Syntax

public void setText( String text )

Parameters

text

The text to display in the header of this rebar band.

See Also getText


 RebarBand.setVisibleGripper

RebarBand.setVisibleGripper

Sets a boolean value indicating whether the rebar band has a sizing grip.

Syntax

public void setVisibleGripper( boolean flag )

Parameters

flag

Set to true if the rebar band has a sizing grip, even if it is the only band in the rebar control; set to false if the rebar band never has a sizing grip, even if there are multiple bands in the rebar control. The default value is true.

See Also getVisibleGripper


 RebarBand.setWidth

RebarBand.setWidth

Sets the width of the rebar band, in pixels.

Syntax

public void setWidth( int width )

Parameters

width

The width of the rebar band, in pixels. The default value is 200.

See Also getWidth


 RebarBand.toString

RebarBand.toString

Retrieves a String object that contains information about this rebar band.

Syntax

public String toString()

Return Value

Returns a String object that contains information about this rebar band.


Rectangle Class

Encapsulates a rectangular area defined by its top-left (x, y) coordinate and its width and height.

package com.ms.wfc.ui

public final class Rectangle
implements IPersistable, IConstructable


 Rectangle Methods

Rectangle Methods

Constructors | Description
Rectangle | Creates a Rectangle object.

Methods | Description
contains | Retrieves a boolean value that indicates whether this rectangle contains the specified rectangle or points.
equals | Retrieves a boolean value that indicates whether the specified object is identical to this rectangle.
getBottom | Retrieves the lowest point in the rectangle's y-axis.
getConstructorArgs | Retrieves the ConstructorArgs needed to persist this object.
getExtension | Retrieves the recommended file extension for files that persist this object.
getRight | Retrieves the rightmost point on the rectangle's x-axis.
hashCode | Retrieves a hash code value for this object.
inflate | Inflates this rectangle by the specified amount.
intersect | Retrieves a Rectangle object that represents the intersecting area of two specified rectangles.
intersectsWith | Retrieves a boolean value that indicates whether the specified rectangle intersects with this one.
offset | Adjusts the location of the rectangle by the specified amount.
save | Saves this object's settings to a data stream.
setBounds | Sets the size and location of this object.
toRECT | Retrieves a Win32 RECT structure that contains the settings of a Rectangle object.
toString | Retrieves a String representation of this object.
union | Retrieves a Rectangle object that represents the smallest rectangle that contains two specified rectangular areas.


 Rectangle.contains

Rectangle.contains

Retrieves a boolean value that indicates whether this rectangle contains the specified rectangle or points.

Syntax

public boolean contains( Point pt )

public boolean contains( int x, int y )

public boolean contains( Rectangle rect )

Parameters

pt

A Point object that specifies the x and y values to be compared to this rectangle's coordinates.

x

The x-coordinate to be compared to this rectangle's coordinates.

y

The y-coordinate to be compared to this rectangle's coordinates.

rect

A Rectangle object that specifies the rectangle to be compared to this one.

Return Value

Returns true if this rectangle contains the specified coordinates; otherwise, returns false.

Remarks

For the contains method to return true when a Point object is specified as a parameter, the following must be true: The x and y fields of the pt parameter must be greater than or equal to the x and y fields in the rectangle; the Point object's x member must be less than or equal to the sum of this rectangle's x and width members; and the Point object's y member must be less than or equal to the sum of this rectangle's y and height members.

For the contains method to return true when a Rectangle object is specified as a parameter, the entire rectangle specified by the rect parameter must be contained in this rectangle.


 Rectangle.equals

Rectangle.equals

Retrieves a boolean value that indicates whether the specified object is identical to this rectangle.

Syntax

public boolean equals( Object obj )

Parameters

obj

The object to compare. This object must be a Rectangle object.

Return Value

Returns true if the objects are equivalent; otherwise, returns false.

Remarks

The specified object must be a Rectangle object instance.


 Rectangle.getBottom

Rectangle.getBottom

Retrieves the lowest point in the rectangle's y-axis.

Syntax

public final int getBottom()

Return Value

Returns the lowest point in the rectangle's y-axis. This value equates to the sum of the rectangle's y-coordinate and its height.


 Rectangle.getConstructorArgs

Rectangle.getConstructorArgs

Retrieves the ConstructorArgs needed to persist this object.

Syntax

public ConstructorArg[] getConstructorArgs()

Return Value

Returns a ConstructorArg array.


 Rectangle.getExtension

Rectangle.getExtension

Retrieves the recommended file extension for files that persist this object.

Syntax

public String getExtension()

Return Value

Returns null since the Rectangle object is not a file-based object.


 Rectangle.getRight

Rectangle.getRight

Retrieves the rightmost point on the rectangle's x-axis.

Syntax

public final int getRight()

Return Value

Returns the rightmost point on the rectangle's x-axis. This value equates to the sum of the rectangle's x-coordinate and its width.


 Rectangle.hashCode

Rectangle.hashCode

Retrieves a hash code value for this object.

Syntax

public int hashCode()

Return Value

Returns a hash code value for this object.


 Rectangle.inflate

Rectangle.inflate

Inflates this rectangle by the specified amount.

Syntax

public void inflate( int x, int y )

public void inflate( Point pt )

public static Rectangle inflate( Rectangle rect, int x, int y )

Parameters

x

The x value to use to formulate the rectangle's new x-coordinate and width. If this value is negative, the size of the rectangle is decreased.

y

The y value to use to formulate the rectangle's new y-coordinate and height. If this value is negative, the size of the rectangle is decreased.

pt

A Point object that specifies the x and y values by which to inflate the rectangle.

rect

A Rectangle object that specifies the rectangle to inflate.

Return Value

Returns a Rectangle object that describes the inflated rectangle.

Remarks

If you call the version of the inflateRect method that takes x, y, or pt parameters, the method formulates the new coordinates by subtracting the x and y coordinates from the current value of the rectangle's x and y coordinates. The new width of the rectangle is formulated by adding the product of x and 2 to the current width. The new height is formulated by adding the product of y and 2 to the current height.

The non-static versions of this method operate on this rectangle. The static version of the member creates and returns a new Rectangle object that is an inflated version of this one.


 Rectangle.intersect

Rectangle.intersect

Retrieves a Rectangle object that represents the intersecting area of two specified rectangles.

Syntax

public static Rectangle intersect( Rectangle lpRect1, Rectangle lpRect2 )

Parameters

lpRect1

A Rectangle object that specifies the rectangle to be compared to lpRect2.

lpRect2

A Rectangle object that specifies the rectangle to be compared to lpRect1.

Return Value

Returns a Rectangle object that represents the intersecting area of lpRect1 and lpRect2.


 Rectangle.intersectsWith

Rectangle.intersectsWith

Retrieves a boolean value that indicates whether the specified rectangle intersects with this one.

Syntax

public boolean intersectsWith( Rectangle rect )

Parameters

rect

A Rectangle object that specifies the rectangle to compare to this one.

Return Value

Returns true if the rectangles intersect; otherwise, returns false.


 Rectangle.offset

Rectangle.offset

Adjusts the location of the rectangle by the specified amount.

Syntax

public void offset( Point pos )

public void offset( int x, int y )

Parameters

pos

A Point object that specifies the amount of vertical and horizontal space to move the rectangle.

x

The amount of space, in logical coordinates, to move the rectangle horizontally.

y

The amount of space, in logical coordinates, to move the rectangle vertically.

See Also setBounds


 Rectangle.Rectangle

Rectangle.Rectangle

Creates a Rectangle object.

Syntax

public Rectangle()

public Rectangle( IDataStream stream )

public Rectangle( Rectangle r )

public Rectangle( int x, int y, int width, int height )

public Rectangle( RECT rect )

Parameters

stream

The data stream (IDataStream) from which to initialize the Rectangle object.

r

A Rectangle object on which to base this object.

x

The x-coordinate of the rectangle.

y

The y-coordinate of the rectangle.

width

The width of the rectangle.

height

The height of the rectangle.

rect

A Win32 RECT structure on which to base this object.


 Rectangle.save

Rectangle.save

Saves this object's settings to a data stream.

Syntax

public void save( IDataStream stream )

Parameters

stream

The data stream (IDataStream) to which to save the settings.


 Rectangle.setBounds

Rectangle.setBounds

Sets the size and location of this object.

Syntax

public void setBounds( int x, int y, int width, int height )

public void setBounds( RECT r )

public void setBounds( Rectangle r )

Parameters

x

The x-coordinate for the rectangle.

y

The y-coordinate for the rectangle.

width

The width of the rectangle.

height

The height of the rectangle.

r

The Win32 RECT structure or a Rectangle object that contains the values with which to initialize this rectangle.


 Rectangle.toRECT

Rectangle.toRECT

Retrieves a Win32 RECT structure that contains the settings of a Rectangle object.

Syntax

public final RECT toRECT()

public final RECT toRect( Rectangle r )

Parameters

r

A Rectangle object that specifies the rectangle to convert to a RECT structure. If no parameter is specified, the current settings on this Rectangle object are converted.

Return Value

Returns a Win32 RECT structure that contains the rectangle's current values.


 Rectangle.toString

Rectangle.toString

Retrieves a String representation of this object.

Syntax

public String toString()

Return Value

Returns a String representation of this Rectangle object.


 Rectangle.union

Rectangle.union

Retrieves a Rectangle object that represents the smallest rectangle that contains two specified rectangular areas.

Syntax

public static Rectangle union( Rectangle a, Rectangle b)

Parameters

a

A Rectangle object that specifies the first rectangle in the union.

b

A Rectangle object that specifies the second rectangle in the union.

Return Value

Returns a Rectangle object that represents the union of the two specified rectangles.


 Rectangle Fields

Rectangle Fields

Fields | Description
height | Specifies the height of the rectangle.
width | Specifies the width of the rectangle.
x | Specifies the x-position (or horizontal origin) of the rectangle.
y | Specifies the y-position (or vertical origin) of the rectangle.


 Rectangle.height

Rectangle.height

Specifies the height of the rectangle.

Syntax

public int height;


 Rectangle.width

Rectangle.width

Specifies the width of the rectangle.

Syntax

public int width;


 Rectangle.x

Rectangle.x

Specifies the x-position (or horizontal origin) of the rectangle.

Syntax

public int x;


 Rectangle.y

Rectangle.y

Specifies the y-position (or vertical origin) of the rectangle.

Syntax

public int y;


Region Class

Encapsulates a Windows region and the logical operations that you can perform on regions.

package com.ms.wfc.ui

public class Region

Remarks

A Windows region designates a complex shape, which can consist of rectangles, ellipses, polygons, or all three.


 Region Methods

Region Methods

Constructors | Description
Region | Creates a Region object.

Methods | Description
andWith | Creates a Region object that contains the elements common to a specified region and this one.
clone | Creates a duplicate of this Region object.
contains | Retrieves a boolean value that indicates whether a specified point or rectangle exists in the region.
copyHandle | Retrieves a copy of the Win32 handle for the region on which this object is based.
createElliptical | Creates an elliptical region based on a specified bounding rectangle.
createPolygonal | Creates a region based on an array of points.
createRectangular | Creates a rectangular region based on a specified bounding rectangle.
createRoundedRectangular | Creates a rounded rectangular region based on a specified bounding rectangle.
destroyHandle | Called when this object is about to destroy its handle.
diffWith | Creates a new region that consists of all areas of this region that are not included in the specified one.
dispose | Frees all resources allocated by this object.
equals | Retrieves a boolean value that indicates whether the specified object is equivalent to this Region object.
finalize | Frees the resources allocated by this object.
getBounds | Retrieves the bounding rectangle for this region.
getHandle | Retrieves the Win32 handle (HREGION) for this region.
hashCode | Retrieves a hash code for this object.
offset | Creates a new Region object which consists of this region, relocated by the specified offset.
orWith | Creates and returns a new region that represents a union between a specified region and this one.
xorWith | Creates a new Region object that contains all non-duplicate elements of this region and a specified one.


 Region.andWith

Region.andWith

Creates a Region object that contains the elements common to a specified region and this one.

Syntax

public final Region andWith( Region region )

Parameters

region

A Region object that specifies the region to combine with this one.

Return Value

Returns a Region object that represents the intersecting area of the specified region and this one.


 Region.clone

Region.clone

Creates a duplicate of this Region object.

Syntax

public Object clone()

Return Value

Returns a Region object that is a duplicate of this one.


 Region.contains

Region.contains

Retrieves a boolean value that indicates whether a specified point or rectangle exists in the region.

Syntax

public final boolean contains( Point pt )

public final boolean contains( int x, int y )

public final boolean contains( Rectangle rect )

public final boolean contains( int x, int y, int width, int height )

Parameters

pt

A Point object that specifies the coordinates to test against the region.

x

The x-coordinate (of a point or rectangle) to test against the region.

y

The y-coordinate (of a point or rectangle) to test against the region.

rect

A Rectangle object that identifies the rectangle to locate in the region.

height

The height of the rectangle to test against the region.

width

The width of the rectangle to test against the region.

Return Value

Returns true, if the specified point falls within the region; otherwise, returns false.


 Region.copyHandle

Region.copyHandle

Retrieves a copy of the Win32 handle for the region on which this object is based.

Syntax

public final int copyHandle()

Return Value

Returns a copy of the Win32 handle to the region that underlies this object.

Remarks

When you copy a region handle, you own the handle and are responsible for freeing it.


 Region.createElliptical

Region.createElliptical

Creates an elliptical region based on a specified bounding rectangle.

Syntax

public static final Region createElliptical( Rectangle rect )

public static final Region createElliptical( int x, int y, int width, int height )

Parameters

rect

A Rectangle object that specifies the region's bounding rectangle.

x

The x-coordinate of the bounding rectangle.

y

The y-coordinate of the bounding rectangle.

width

The width of the bounding rectangle.

height

The height of the bounding rectangle.

Return Value

Returns a Region object that defines the newly created elliptical region.


 Region.createPolygonal

Region.createPolygonal

Creates a region based on an array of points.

Syntax

public static final Region createPolygonal( Point [] points )

public static final Region createPolygonal( Point [] points, int fillMode )

Parameters

points

An array of Point objects on which to base the region.

fillMode

The fill mode with which to paint the resulting polygon. This value must be one of the enumeration constants defined in the PolyFillMode class.

Return Value

Returns the newly created Region object.

Remarks

The Region object returned by createPolygonal consists of the shape that results from connecting the specified points.

If no fill mode is specified in the call to this method, a default value of PolyFillMode.ALTERNATE is used.


 Region.createRectangular

Region.createRectangular

Creates a rectangular region based on a specified bounding rectangle.

Syntax

public static final Region createRectangular( int x, int y, int width, int height )

public static final Region createRectangular( Rectangle rect )

Parameters

x

The x-coordinate of the bounding rectangle.

y

The y-coordinate of the bounding rectangle.

width

The width of the bounding rectangle.

height

The height of the bounding rectangle.

rect

A Rectangle object that specifies the bounding rectangle.

Return Value

Returns a new Region object based on the specified rectangle.

See Also createElliptical, createPolygonal


 Region.createRoundedRectangular

Region.createRoundedRectangular

Creates a rounded rectangular region based on a specified bounding rectangle.

Syntax

public static final Region createRoundedRectangular( Rectangle rect, int radius )

public static final Region createRoundedRectangular( int x, int y, int width, int height, int radius )

Parameters

rect

The rectangular area within which to draw the rounded rectangle.

x

The x-coordinate of the rectangular area.

y

The y-coordinate of the rectangular area.

width

The width of the rectangular area.

height

The height of the rectangular area.

radius

The radius of the ellipse used to draw the rounded corners.

Return Value

Returns a new Region object that defines the rounded rectangle.


 Region.destroyHandle

Region.destroyHandle

Called when this object is about to destroy its handle.

Syntax

protected void destroyHandle()

Remarks

If you create a Region object based on a Win32 handle, this handle is not freed in the default implementation of this method. However, in classes that extend the Region class you can override this function to free handles that the object does not own.


 Region.diffWith

Region.diffWith

Creates a new region that consists of all areas of this region that are not included in the specified one.

Syntax

public final Region diffWith( Region region )

Parameters

region

A Region object that defines the region to compare with this one.

Return Value

Returns a new Region object that contains the areas in the specified region that do not exist in this one.


 Region.dispose

Region.dispose

Frees all resources allocated by this object.

Syntax

public void dispose()

Remarks

The resources freed by this object are limited to those allocated by it. If you construct a Region object based on a previously-allocated Win32 handle, the call to dispose does not free this object.


 Region.equals

Region.equals

Retrieves a boolean value that indicates whether the specified object is equivalent to this Region object.

Syntax

public boolean equals( Object obj )

Parameters

obj

The object to compare to this one. This parameter must designate a valid Region object.

Return Value

Returns true if the specified object is equivalent to this one; otherwise, returns false.


 Region.finalize

Region.finalize

Frees the resources allocated by this object.

Syntax

protected void finalize()

Remarks

A call to finalize is equivalent to a call to the Region object's dispose method.


 Region.getBounds

Region.getBounds

Retrieves the bounding rectangle for this region.

Syntax

public final Rectangle getBounds()

Return Value

Returns a Rectangle object that specifies the region's bounding rectangle.

Remarks

The rectangle returned by getBounds specifies the smallest rectangle into which this region will fit.


 Region.getHandle

Region.getHandle

Retrieves the Win32 handle (HREGION) for this region.

Syntax

public int getHandle()

Return Value

Returns the Win32 handle for this region.

Exceptions

WFCException thrown if the dispose or finalize methods have already been called on this object.

Remarks

The handle returned by this method is not a copy of the region handle. Therefore, this handle should not be freed by the caller.


 Region.hashCode

Region.hashCode

Retrieves a hash code for this object.

Syntax

public int hashCode()

Return Value

Returns the object's hash code.


 Region.offset

Region.offset

Creates a new Region object which consists of this region, relocated by the specified offset.

Syntax

public final Region offset( Point point )

public final Region offset( int x, int y )

Parameters

point

A Point object that specifies the offset.

x

The amount by which to offset the region horizontally.

y

The amount by which to offset the region vertically.

Return Value

Returns a Region object that specifies the new region.


 Region.orWith

Region.orWith

Creates and returns a new region that represents a union between a specified region and this one.

Syntax

public final Region orWith( Region region )

Parameters

region

A Region object that specifies the region to combine with this one.

Return Value

Returns a Region object that encompasses all of the elements contained either in the specified region or this one.

See Also andWith, xorWith


 Region.Region

Region.Region

Creates a Region object.

Syntax

public Region()

public Region( int handle )

Parameters

handle

The Win32 handle to a region.

Remarks

If you create a Region object based on a Win32 region handle, this handle is not freed when the object frees its resources; you must free it.


 Region.xorWith

Region.xorWith

Creates a new Region object that contains all non-duplicate elements of this region and a specified one.

Syntax

public final Region xorWith( Region region )

Parameters

region

A Region object that specifies the region to combine with this one.

Return Value

Returns a new Region object. This object contains all the elements that appear in either the specified region or this one.

See Also andWith, orWith


RequestResizeEvent Class

Provides data for the requestResize event of the RichEdit control.

Event
  |
  +--RequestResizeEvent

package com.ms.wfc.ui

public class RequestResizeEvent
extends Event

Remarks

The requestResize event occurs when the text typed into the RichEdit control is too small or large for the control. A RequestResizeEvent object identifies the requested size of the RichEdit control.

For information about the WFC event model, see Handling Events in WFC.


 RequestResizeEvent Methods

RequestResizeEvent Methods

Constructors | Description
RequestResizeEvent | Creates a RequestResizeEvent object.


 RequestResizeEvent.RequestResizeEvent

RequestResizeEvent.RequestResizeEvent

Creates a RequestResizeEvent object.

Syntax

public RequestResizeEvent( Rectangle newRectangle )

Parameters

newRectangle

A Rectangle object that specifies the requested size of the control.


 RequestResizeEvent Fields

RequestResizeEvent Fields

Fields | Description
newRectangle | Specifies the requested size of the RichEdit control.


 RequestResizeEvent.newRectangle

RequestResizeEvent.newRectangle

Specifies the requested size of the RichEdit control.

Syntax

public final Rectangle newRectangle;


RequestResizeEventHandler Delegate

Identifies the method that will handle the requestResize event of a RichEdit control.

package com.ms.wfc.data.ui

public multicast delegate void RequestResizeEventHandler( Object sender, RequestResizeEvent e );

Remarks

The syntax of the RequestResizeEventhandler delegate specifies the signature for the event handler, where sender is the source of the event and e is an RequestResizeEvent object that provides the event data.

When you create an RequestResizeEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC.


RichEdit Class

Encapsulates a Win32 RichEdit control.

Component
  |
  +--Control
    |
    +--Edit
      |
      +--RichEdit

package com.ms.wfc.ui

public class RichEdit
extends Edit

Remarks

A rich edit control is a window in which the user can enter and edit formatted text. The text can be assigned directly to the control, or can be loaded from a Rich Text Format (RTF) or plain text file. The text can be assigned character and paragraph formatting, and can include embedded OLE objects.

The RichEdit control provides a programming interface for formatting text. This interface is provided through the RichEdit and associated classes.


 RichEdit Methods

RichEdit Methods

Constructors | Description
RichEdit | Creates a RichEdit control.

Methods | Description
addOnHScroll | Assigns a delegate to the hScroll event.
addOnIMEChange | Assigns a delegate to the IMEChange event.
addOnProtected | Assigns a delegate to the protected event.
addOnRequestResize | Assigns a delegate to the requestResize event.
addOnSelChange | Assigns a delegate to the selChange event.
addOnVScroll | Assigns a delegate to the vScroll event.
canPaste | Retrieves a boolean value that indicates whether the data in the specified Clipboard format can be pasted into this control.
dispose | Frees the resources allocated by this control.
find | Searches the RichEdit control for a specified string.
getAutoWordSelection | Retrieves a boolean value that indicates whether automatic word selection is enabled.
getBulletIndent | Retrieves the indention used in the RichEdit control when the bullet style is applied to the text.
getCharFromPosition | Retrieves the character closest to the specified point.
getDelimiter | Retrieves a string that contains the control's delimiters.
getFollowPunctuation | Retrieves a string that contains the non-leading punctuation for the RichEdit control.
getIMEColor | Retrieves the IME color settings of the RichEdit control.
getIMEOptions | Retrieves the IME options settings of the RichEdit control.
getLeadPunctuation | Retrieves a string that contains the leading punctuation characters for the RichEdit control.
getLineFromChar | Retrieves the line number of the line that contains the specified character position.
getOnHScroll | Retrieves the delegate assigned to the hScroll event.
getOnIMEChange | Retrieves the delegate assigned to the IMEChange event.
getOnProtected | Retrieves the delegate assigned to the protected event.
getOnRequestResize | Retrieves the delegate assigned to the requestResize event.
getOnSelChange | Retrieves the delegate assigned to the selChange event.
getOnVScroll | Retrieves the delegate assigned to the vScroll event.
getPositionFromChar | Returns the location of the character at the given index.
getRightMargin | Returns the right margin of the RichEdit control.
getRTF | Returns the text of the RichEdit control, including all RTF codes.
getSelAlignment | Retrieves the paragraph alignment for the RichEdit control.
getSelBullet | Retrieves a boolean value that indicates whether the bullet style is currently applied to the selection or insertion point.
getSelCharOffset | Returns a value that determines whether text in the RichEdit control appears on the baseline (normal), as a superscript above the baseline, or as a subscript below the baseline.
getSelColor | Retrieves the color of the currently selected text.
getSelFont | Retrieves the font that is used to format the currently selected text.
getSelHangingIndent | Retrieves the distance between the left edge of the first line of text in the selected paragraph and the left edge of subsequent lines in the same paragraph.
getSelIndent | Retrieves the distance between the left edge of the control and the left edge of the text that is currently selected or that is added at the insertion point.
getSelLength | Retrieves the number of characters currently selected.
getSelProtected | Retrieves a boolean value that indicates whether the current selection is protected.
getSelRightIndent | Returns the distance between the right edge of the RichEdit control and the right edge of the text that is selected or that is added at the current insertion point.
getSelRTF | Retrieves the currently selected text in a RichEdit control, including all RTF codes.
getSelStrikeThru | Retrieves a value that indicates strike-through format of the selection.
getSelTabs | Retrieves the absolute tab stop positions in the RichEdit control.
getSelText | Retrieves the currently selected text in the RichEdit control.
getSelType | Retrieves the type of the current selection.
getWordBreak | Retrieves a boolean value that indicates whether or not English word-breaking occurs in Japanese, Chinese, and Hangeul.
getWordPunctuation | Retrieves the type of punctuation table to be used to determine the RichEdit control's word-wrap and word-break layout.
loadFile | Loads a Rich Text Format (RTF) or text file into the RichEdit control.
moveInsertionPoint | Moves the insertion point up to, but not including, the first character in the RichEdit control that is a member of the specified character set.
onHScroll | Triggers the hScroll event.
onIMEChange | Triggers the IMEChange event.
onProtected | Triggers the protected event.
onRequestResize | Triggers the requestResize event.
onSelChange | Triggers the selChange event.
onVScroll | Triggers the vScroll event.
paste | Pastes data in a specific Clipboard format into the RichEdit control.
removeOnHScroll | Removes the delegate that is assigned to the hScroll event.
removeOnIMEChange | Removes the delegate that is assigned to the IMEChange event.
removeOnProtected | Removes the delegate that is assigned to the protected event.
removeOnRequestResize | Removes the delegate that is assigned to the requestResize event.
removeOnSelChange | Removes the delegate that is assigned to the selChange event.
removeOnVScroll | Removes the delegate that is assigned to the vScroll event.
saveFile | Saves the control's contents to a specified location.
setAutoWordSelection | Specifies whether the control supports auto word selection.
setBackColor | Sets the background color for the RichEdit control.
setBulletIndent | Sets the amount of indention to be used in this control when this control is configured to display bullets.
setDelimiter | Sets the delimiters for the RichEdit control.
setFollowPunctuation | Sets the non-leading punctuation for the RichEdit control.
setForeColor | Sets the fore color of the rich edit control.
setIMEColor | Sets the color of the IME composition window of the RichEdit control.
setIMEOptions | Sets options on the IME composition window of the RichEdit control.
setLeadPunctuation | Sets the leading punctuation for the RichEdit control.
setRightMargin | Sets the right margin of the RichEdit control.
setRTF | Sets the text of a RichEdit control, including all the RTF codes.
setSelAlignment | Sets the paragraph alignment for the RichEdit control.
setSelBullet | Specifies whether the bullet style should be applied to the current selection or insertion point.
setSelCharOffset | Determines whether text in the control appears on the baseline, as a superscript above the baseline, or as a subscript below the base line.
setSelColor | Sets the text color of the currently selected text.
setSelFont | Sets the font used to display the currently selected characters, or the characters immediately following the insertion point.
setSelHangingIndent | Sets the distance between the left edge of the first line of text in the selected paragraph and the left edge of subsequent lines in the same paragraph.
setSelIndent | Sets the distance between the left edge of the control and the left edge of the text that is currently selected or that is added at the insertion point.
setSelLength | Selects the specified number of characters, beginning at the current insertion point.
setSelProtected | Marks the current selection as protected.
setSelRightIndent | Sets the distance between the right edge of the control and the right edge of text that is selected or that is added at the current insertion point.
setSelRTF | Sets the currently selected text of a RichEdit control, including the text's RTF codes.
setSelTabs | Sets the absolute tab stop positions in a RichEdit control.
setSelText | Sets the selected text in the RichEdit control.
setWordBreak | Enables or disables English word-breaking in Japanese, Chinese, and Hangeul.
setWordPunctuation | Sets the type of punctuation table to be used to determine the RichEdit control's word-wrap and word-break layout.
span | Selects text in the RichEdit control based on a specified set of characters.


 RichEdit.addOnHScroll

RichEdit.addOnHScroll

Assigns a delegate to the hScroll event.

Syntax

public void addOnHScroll( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

A RichEdit control's hScroll event occurs when the user clicks the control's horizontal scroll bar.

See Also getOnHScroll, onHScroll, getScrollBars, setScrollBars


 RichEdit.addOnIMEChange

RichEdit.addOnIMEChange

Assigns a delegate to the IMEChange event.

Syntax

public void addOnIMEChange( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

The IMEChange event occurs when the user switches input methods on an Asian version of the Windows operating system.

See Also getOnIMEChange, onIMEChange


 RichEdit.addOnProtected

RichEdit.addOnProtected

Assigns a delegate to the protected event.

Syntax

public void addOnProtected( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

The protected event occurs when the user attempts to modify protected text in the control.

See Also getOnProtected, onProtected


 RichEdit.addOnRequestResize

RichEdit.addOnRequestResize

Assigns a delegate to the requestResize event.

Syntax

public void addOnRequestResize( RequestResizeEventHandler value )

Parameters

value

The RequestResizeEventHandler delegate to be notified when the event occurs.

Remarks

The requestResize event occurs when the text typed into the RichEdit control is too small or large for the control.

See Also getOnRequestResize, onRequestResize


 RichEdit.addOnSelChange

RichEdit.addOnSelChange

Assigns a delegate to the selChange event.

Syntax

public void addOnSelChange( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

The selChange event occurs when a user selects text in the RichEdit control.

See Also getOnSelChange, onSelChange


 RichEdit.addOnVScroll

RichEdit.addOnVScroll

Assigns a delegate to the vScroll event.

Syntax

public void addOnVScroll( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

A RichEdit control's vScroll event occurs when the user clicks the control's vertical scroll bar.

See Also getOnVScroll, onVScroll


 RichEdit.canPaste

RichEdit.canPaste

Retrieves a boolean value that indicates whether the data in the specified Clipboard format can be pasted into this control.

Syntax

public boolean canPaste( DataFormats.Format clipFormat )

Parameters

clipFormat

A DataFormats.Format object that specifies the Clipboard format.

Return Value

Returns true if the data in the specified format can be pasted into this control; otherwise, returns false.

See Also paste


 <b>RichEdit.dispose</b>

RichEdit.dispose

Frees the resources allocated by this control.

Syntax

public void dispose()

Remarks

This method is called when the control is ready to free its resources. This method should not be called at run time, and classes that extend this class should call super.dispose() in overrides of this method.


 <b>RichEdit.find</b>

RichEdit.find

Searches the RichEdit control for a specified string.

Syntax

public int find( String string )

public int find( String string, int options )

public int find( String string, int start, int options )

public int find( String string, int start, int end, int options )

Parameters

string

The string to locate in the control.

options

One or more flags that specify how to search for the text. This value can be a logical OR combination of one or more of the enumeration constants defined in the RichEditFind class. If you call a version of find that does not include this parameter, a default value of RichEditFind.NONE is used.

start

The offset at which to begin searching. If you call a version of find that does not include this parameter, a default value of 0 is used.

end

The offset at which to stop searching. If you call a version of find that does not include this parameter, the method searches to the end of the text in the control.

Return Value

Returns the zero-based offset at which the search string occurs. If the string does not appear in the control, this method returns -1.

Exceptions

WFCInvalidEnumException thrown if the options parameter specifies values that are not defined in the RichEditFind class.


 RichEditFind.getAutoWordSelection

RichEditFind.getAutoWordSelection

Retrieves a boolean value that indicates whether automatic word selection is enabled.

Syntax

public boolean getAutoWordSelection()

Return Value

Returns true if automatic word selection is on; otherwise, returns false.

Remarks

If automatic word selection is on, then selecting any part of the text in the control results in the selection of the entire word.

See Also setAutoWordSelection


 RichEdit.getBulletIndent

RichEdit.getBulletIndent

Retrieves the indention used in the RichEdit control when the bullet style is applied to the text.

Syntax

public int getBulletIndent()

Return Value

Returns, in pixels, the amount of indention.

Remarks

To apply the bullet style to text, use setSelBullet and then use the setBulletIndent method to specify how many pixels the text should be indented.


 RichEdit.getCharFromPosition

RichEdit.getCharFromPosition

Retrieves the character closest to the specified point.

Syntax

public char getCharFromPosition( Point pt )

Parameters

pt

A Point object that specifies the location from which to seek the nearest character.

Return Value

Returns the character closest to the specified point. If the specified point lies outside the area of the control, the last character in the control is returned.


 RichEdit.getDelimiter

RichEdit.getDelimiter

Retrieves a string that contains the control's delimiters.

Syntax

public String getDelimiter()

Return Value

Returns a string that contains the control's delimiters.


 RichEdit.getFollowPunctuation

RichEdit.getFollowPunctuation

Retrieves a string that contains the non-leading punctuation for the RichEdit control.

Syntax

public String getFollowPunctuation()

Return Value

Returns a string that contains the non-leading punctuation.

Remarks

This method applies only to Asian versions of the Windows operating system.

See Also getLeadPunctuation


 RichEdit.getIMEColor

RichEdit.getIMEColor

Retrieves the IME color settings of the RichEdit control.

Syntax

public RichEditIMEColor getIMEColor()

Return Value

Returns a RichEditIMEColor object that contains the IME color settings.

Remarks

This method applies only to Asian versions of the Windows operating system.

See Also setIMEColor


 RichEdit.getIMEOptions

RichEdit.getIMEOptions

Retrieves the IME options settings of the RichEdit control.

Syntax

public int getIMEOptions()

Return Value

Returns an integer that contains the IME options. The returned value is a logical combination of one or more of the enumeration constants defined in the RichEditIMEOptions class.

Remarks

This method applies only to Asian versions of the Windows operating system.

See Also setIMEOptions


 RichEdit.getLeadPunctuation

RichEdit.getLeadPunctuation

Retrieves a string that contains the leading punctuation characters for the RichEdit control.

Syntax

public String getLeadPunctuation()

Return Value

Returns a string that contains the leading punctuation.

Remarks

This method applies only to Asian versions of the Windows operating system.

See Also setLeadPunctuation


 RichEdit.getLineFromChar

RichEdit.getLineFromChar

Retrieves the line number of the line that contains the specified character position.

Syntax

public int getLineFromChar( int charPos )

Parameters

charPos

The character position for which to retrieve the line number.

Return Value

Returns a zero-based integer that identifies the line in which the specified character position occurs.


 RichEdit.getOnHScroll

RichEdit.getOnHScroll

Retrieves the delegate assigned to the hScroll event.

Syntax

public EventHandler getOnHScroll()

Return Value

Returns the EventHandler object assigned to the hScroll event.

See Also addOnHScroll, onHScroll


 RichEdit.getOnIMEChange

RichEdit.getOnIMEChange

Retrieves the delegate assigned to the IMEChange event.

Syntax

public EventHandler getOnIMEChange()

Return Value

Returns the EventHandler object assigned to the IMEChange event.

Remarks

This handler applies only to Asian versions of the Windows operating system.

See Also addOnIMEChange, onIMEChange


 RichEdit.getOnProtected

RichEdit.getOnProtected

Retrieves the delegate assigned to the protected event.

Syntax

public EventHandler getOnProtected()

Return Value

Returns the EventHandler object assigned to the protected event.

Remarks

The protected event occurs when the user attempts to modify protected text.

See Also addOnProtected, onProtected


 RichEdit.getOnRequestResize

RichEdit.getOnRequestResize

Retrieves the delegate assigned to the requestResize event.

Syntax

public RequestResizeEventHandler getOnRequestResize()

Return Value

Returns the RequestResizeEventHandler object assigned to the requestResize event.

Remarks

The requestResize event occurs when the text typed into the RichEdit control is too small or large for the control.

See Also addOnRequestResize, onRequestResize


 RichEdit.getOnSelChange

RichEdit.getOnSelChange

Retrieves the delegate assigned to the selChange event.

Syntax

public EventHandler getOnSelChange()

Return Value

Returns the EventHandler object assigned to the selChange event.

Remarks

The selChange event occurs when a user selects text in the RichEdit control or when the insertion point changes.

See Also addOnSelChange, onSelChange


 RichEdit.getOnVScroll

RichEdit.getOnVScroll

Retrieves the delegate assigned to the vScroll event.

Syntax

public EventHandler getOnVScroll()

Return Value

Returns the EventHandler object assigned to the vScroll event.

Remarks

The vScroll event occurs when a user clicks the vertical scroll bar in the RichEdit control.

See Also addOnVScroll, onVScroll


 RichEdit.getPositionFromChar

RichEdit.getPositionFromChar

Returns the location of the character at the given index.

Syntax

public Point getPositionFromChar( int index )

Parameters

index

The index of the character for which to retrieve the location.

Return Value

Returns a Point object that specifies the location of the specified character.

See Also getCharFromPosition


 RichEdit.getRightMargin

RichEdit.getRightMargin

Returns the right margin of the RichEdit control.

Syntax

public int getRightMargin()

Return Value

Returns the right margin of the control, in pixels.

See Also setRightMargin


 RichEdit.getRTF

RichEdit.getRTF

Returns the text of the RichEdit control, including all RTF codes.

Syntax

public String getRTF()

Return Value

Returns the text of the control, including all RTF codes.

See Also setRTF


 RichEdit.getSelAlignment

RichEdit.getSelAlignment

Retrieves the paragraph alignment for the RichEdit control.

Syntax

public int getSelAlignment()

Return Value

Returns one of the enumeration constants defined in the HorizontalAlignment class.

See Also setSelAlignment


 RichEdit.getSelBullet

RichEdit.getSelBullet

Retrieves a boolean value that indicates whether the bullet style is currently applied to the selection or insertion point.

Syntax

public boolean getSelBullet()

Return Value

Returns true if all of the characters in the selection have the bulleted style; otherwise, returns false.

See Also setSelBullet


 RichEdit.getSelCharOffset

RichEdit.getSelCharOffset

Returns a value that determines whether text in the RichEdit control appears on the baseline (normal), as a superscript above the baseline, or as a subscript below the baseline.

Syntax

public int getSelCharOffset()

Return Value

Returns 0 if the text appears on the baseline. If the text is superscript, this method returns a positive integer that indicates, in pixels, how far above the baseline the text appears. If the text is subscript, this method returns a negative integer that indicates, in pixels, how far below the baseline the text appears.

See Also setSelCharOffset


 RichEdit.getSelColor

RichEdit.getSelColor

Retrieves the color of the currently selected text.

Syntax

public Color getSelColor()

Return Value

Returns a Color object that specifies the color of the selected text.

Remarks

If no text is selected, this method returns the color at the insertion point. If the current selection includes more than one color, this method returns null.

See Also setSelColor


 RichEdit.getSelFont

RichEdit.getSelFont

Retrieves the font that is used to format the currently selected text.

Syntax

public Font getSelFont()

Return Value

Returns a Font object that describes the font used to format the selected text.

Remarks

If no text is currently selected, this method returns the font that is used to format the position of the insertion point. If the current selection includes more than one font, this method returns null.

See Also setSelFont


 RichEdit.getSelHangingIndent

RichEdit.getSelHangingIndent

Retrieves the distance between the left edge of the first line of text in the selected paragraph and the left edge of subsequent lines in the same paragraph.

Syntax

public int getSelHangingIndent()

Return Value

Returns the hanging indention, in pixels.

See Also setSelHangingIndent


 RichEdit.getSelIndent

RichEdit.getSelIndent

Retrieves the distance between the left edge of the control and the left edge of the text that is currently selected or that is added at the insertion point.

Syntax

public int getSelIndent()

Return Value

Returns the distance, in pixels, between the left edge of the control and the left edge of the selected text.

See Also setSelIndent


 RichEdit.getSelLength

RichEdit.getSelLength

Retrieves the number of characters currently selected.

Syntax

public int getSelLength()

Return Value

Returns the number of characters currently selected.

See Also setSelLength


 RichEdit.getSelProtected

RichEdit.getSelProtected

Retrieves a boolean value that indicates whether the current selection is protected.

Syntax

public boolean getSelProtected()

Return Value

Returns true if the current selection is protected; otherwise, returns false.

Remarks

If selected text is protected, an attempt to edit the text triggers the protected event.

See Also onProtected, setSelProtected


 RichEdit.getSelRightIndent

RichEdit.getSelRightIndent

Returns the distance between the right edge of the RichEdit control and the right edge of the text that is selected or that is added at the current insertion point.

Syntax

public int getSelRightIndent()

Return Value

Returns the amount of right indention, in pixels.

See Also setSelRightIndent


 RichEdit.getSelRTF

RichEdit.getSelRTF

Retrieves the currently selected text in a RichEdit control, including all RTF codes.

Syntax

public String getSelRTF()

Return Value

Returns the selected text.

See Also setSelRTF


 RichEdit.getSelStrikeThru

RichEdit.getSelStrikeThru

Retrieves a value that indicates strike-through format of the selection.

Syntax

public int getSelStrikeThru()

Return Value

Returns -1 if the selection contains a mix of styles. Returns 0 if none of the characters have the strike-through style, and returns 1 if all of the characters in the selection are struck through.


 RichEdit.getSelTabs

RichEdit.getSelTabs

Retrieves the absolute tab stop positions in the RichEdit control.

Syntax

public int[] getSelTabs()

Return Value

Returns an array of integers, in which each member specifies a tab offset in pixels.

See Also setSelTabs


 RichEdit.getSelText

RichEdit.getSelText

Retrieves the currently selected text in the RichEdit control.

Syntax

public String getSelText()

Return Value

Returns the currently selected text.

See Also setSelText


 RichEdit.getSelType

RichEdit.getSelType

Retrieves the type of the current selection.

Syntax

public int getSelType()

Return Value

Returns the type of the current selection. The returned value is one of the constants defined in the RichEditSelType enumeration.


 RichEdit.getWordBreak

RichEdit.getWordBreak

Retrieves a boolean value that indicates whether or not English word-breaking occurs in Japanese, Chinese, and Hangeul.

Syntax

public boolean getWordBreak()

Return Value

Returns true if English word-breaking is turned on; otherwise, returns false.

Remarks

This method is valid only on Asian versions of the Windows operating system.

See Also setWordBreak


 RichEdit.getWordPunctuation

RichEdit.getWordPunctuation

Retrieves the type of punctuation table to be used to determine the RichEdit control's word-wrap and word-break layout.

Syntax

public int getWordPunctuation()

Return Value

Returns the punctuation type. This value is one of the enumeration constants defined in the RichEditWordPunctuation class.

Remarks

This method is valid only on Asian versions of the Windows operating system.

See Also getWordBreak, setWordPunctuation


 RichEdit.loadFile

RichEdit.loadFile

Loads a Rich Text Format (RTF) or text file into the RichEdit control.

Syntax

public void loadFile( String path )

public synchronized void loadFile( String path, int fileType )

Parameters

path

The path to the file.

fileType

The file type to load. This value must be one of the enumeration constants defined in the RichEditStreamType class.

Exceptions

WFCInvalidArgumentException thrown when an invalid value is specified in the fileType parameter.

WFCException thrown when an error occurs while loading the file.

See Also saveFile


 RichEdit.moveInsertionPoint

RichEdit.moveInsertionPoint

Moves the insertion point up to, but not including, the first character in the RichEdit control that is a member of the specified character set.

Syntax

public void moveInsertionPoint( String characterSet )

public void moveInsertionPoint( String characterSet, boolean forward )

public void moveInsertionPoint( String characterSet, boolean forward, boolean negate )

Parameters

characterSet

A string expression that specifies the set of characters to look for when extending the selection, based on the value of the negate parameter.

forward

Set to true to move the cursor forward in the text; otherwise, set to false. The default value for this parameter is true.

negate

Set to true to include in the selection those characters that are not in the character set. Set to false to include in the selection the characters that are in the character set. The default setting for this parameter is false.

Remarks

When the negate parameter is set to true, the character set is found, and the text of the character set is selected, moveInsertionPoint deselects it. If the character set is not selected, and negate is set to true, moveInsertionPoint selects it.


 RichEdit.onHScroll

RichEdit.onHScroll

Triggers the hScroll event.

Syntax

protected void onHScroll( Event e )

Parameters

e

An Event object that provides the event data.

Remarks

A RichEdit control's hScroll event occurs when the user clicks the control's horizontal scroll bar.

See Also addOnHScroll, getOnHScroll


 RichEdit.onIMEChange

RichEdit.onIMEChange

Triggers the IMEChange event.

Syntax

protected void onIMEChange( Event e )

Parameters

e

An Event object that provides the event data.

Remarks

The IMEChange event occurs when the user switches input methods on an Asian version of the Windows operating system.

See Also addOnIMEChange, getOnIMEChange


 RichEdit.onProtected

RichEdit.onProtected

Triggers the protected event.

Syntax

protected void onProtected( Event e )

Parameters

e

An Event object that provides the event data.

Remarks

The protected event occurs when the user attempts to modify protected text in the control.

See Also addOnProtected, getOnProtected


 RichEdit.onRequestResize

RichEdit.onRequestResize

Triggers the requestResize event.

Syntax

protected void onRequestResize( RequestResizeEvent e )

Parameters

e

A RequestResizeEvent object that provides the event data.

Remarks

The requestResize event occurs when the text typed into the RichEdit control is too small or large for the control.

See Also addOnRequestResize, getOnRequestResize


 RichEdit.onSelChange

RichEdit.onSelChange

Triggers the selChange event.

Syntax

protected void onSelChange( Event e )

Parameters

e

An Event object that provides the event data.

Remarks

The selChange event occurs when a user selects text in the RichEdit control.

See Also addOnSelChange, getOnSelChange


 RichEdit.onVScroll

RichEdit.onVScroll

Triggers the vScroll event.

Syntax

protected void onVScroll( Event e )

Parameters

e

An Event object that provides the event data.

Remarks

A RichEdit control's vScroll event occurs when the user clicks the control's vertical scroll bar.

See Also addOnVScroll, getOnVScroll


 RichEdit.paste

RichEdit.paste

Pastes data in a specific Clipboard format into the RichEdit control.

Syntax

public void paste( DataFormats.Format clipFormat )

Parameters

clipFormat

A DataFormats.Format object that defines the data format.

See Also canPaste


 RichEdit.removeOnHScroll

RichEdit.removeOnHScroll

Removes the delegate that is assigned to the hScroll event.

Syntax

public void removeOnHScroll( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnHScroll, getOnHScroll


 RichEdit.removeOnIMEChange

RichEdit.removeOnIMEChange

Removes the delegate that is assigned to the IMEChange event.

Syntax

public void removeOnIMEChange( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

Remarks

The IMEChange event occurs when the user switches input methods on an Asian version of the Windows operating system.

See Also addOnIMEChange, getOnIMEChange


 RichEdit.removeOnProtected

RichEdit.removeOnProtected

Removes the delegate that is assigned to the protected event.

Syntax

public void removeOnProtected( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnProtected, getOnProtected


 RichEdit.removeOnRequestResize

RichEdit.removeOnRequestResize

Removes the delegate that is assigned to the requestResize event.

Syntax

public void removeOnRequestResize( RequestResizeEventHandler value )

Parameters

value

The RequestResizeEventHandler delegate to be removed.

See Also addOnRequestResize, getOnRequestResize


 RichEdit.removeOnSelChange

RichEdit.removeOnSelChange

Removes the delegate that is assigned to the selChange event.

Syntax

public void removeOnSelChange( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnSelChange, getOnSelChange


 RichEdit.removeOnVScroll

RichEdit.removeOnVScroll

Removes the delegate that is assigned to the vScroll event.

Syntax

public void removeOnVScroll( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnVScroll, getOnVScroll


 RichEdit.RichEdit

RichEdit.RichEdit

Creates a RichEdit control.

Syntax

public RichEdit()


 RichEdit.saveFile

RichEdit.saveFile

Saves the control's contents to a specified location.

Syntax

public void saveFile( String path )

public synchronized void saveFile( String path, int fileType )

Parameters

path

The path to the file.

fileType

The type of file to save. This value must be one of the enumeration constants defined in the RichEditStreamType class.

Exception

WFCInvalidArgumentException exception thrown if the value specified in fileType is invalid. WFCException thrown if an error occurs during the save operation.


 RichEdit.setAutoWordSelection

RichEdit.setAutoWordSelection

Specifies whether the control supports auto word selection.

Syntax

public void setAutoWordSelection( boolean autoWordSelection )

Parameters

autoWordSelection

Set to true to turn on auto word selection; otherwise, set to false.

See Also getAutoWordSelection


 RichEdit.setBackColor

RichEdit.setBackColor

Sets the background color for the RichEdit control.

Syntax

public void setBackColor( Color value )

Parameters

value

A Color object that describes the background color to set.

See Also setForeColor


 RichEdit.setBulletIndent

RichEdit.setBulletIndent

Sets the amount of indention to be used in this control when this control is configured to display bullets.

Syntax

public void setBulletIndent( int bulletIndent )

Parameters

bulletIndent

The indention amount, in pixels.

Remarks

Before calling this method, you must have called the setSelBullet method to ensure that the selected text is bulleted.

See Also getBulletIndent


 RichEdit.setDelimiter

RichEdit.setDelimiter

Sets the delimiters for the RichEdit control.

Syntax

public void setDelimiter( String delimiter )

Parameters

delimiter

A string that contains the punctuation characters.

Remarks

This method is valid only on Asian versions of the Windows operating system.

See Also getDelimiter


 RichEdit.setFollowPunctuation

RichEdit.setFollowPunctuation

Sets the non-leading punctuation for the RichEdit control.

Syntax

public void setFollowPunctuation( String punctuation )

Parameters

punctuation

A string that contains the punctuation characters.

Remarks

This method is valid only on Asian versions of the Windows operating system.


 RichEdit.setForeColor

RichEdit.setForeColor

Sets the fore color of the rich edit control.

Syntax

public void setForeColor( Color value )

Parameters

value

A Color object that describes the color to be used as the control's fore color.


 RichEdit.setIMEColor

RichEdit.setIMEColor

Sets the color of the IME composition window of the RichEdit control.

Syntax

public void setIMEColor( RichEditIMEColor value )

Parameters

value

A RichEditIMEColor object that specifies the color options.

Remarks

This method is valid only on Asian versions of the Windows operating system.

See Also getIMEColor


 RichEdit.setIMEOptions

RichEdit.setIMEOptions

Sets options on the IME composition window of the RichEdit control.

Syntax

public void setIMEOptions( int value )

Parameters

value

The IME options. This value must be a combination of one or more of the enumeration constants defined in the RichEditIMEOptions class.

Exceptions

WFCInvalidEnumException thrown if the value parameter is not a valid member of the RichEditIMEOptions class.

Remarks

This method is valid only on Asian versions of the Windows operating system.

See Also getIMEOptions


 RichEdit.setLeadPunctuation

RichEdit.setLeadPunctuation

Sets the leading punctuation for the RichEdit control.

Syntax

public void setLeadPunctuation( String punctuation )

Parameters

punctuation

A string that contains the punctuation characters.

Remarks

This method is valid only on Asian versions of the Windows operating system.

See Also getLeadPunctuation


 RichEdit.setRightMargin

RichEdit.setRightMargin

Sets the right margin of the RichEdit control.

Syntax

public void setRightMargin( int rightMargin )

Parameters

rightMargin

The right margin setting, in pixels.

See Also getRightMargin


 RichEdit.setRTF

RichEdit.setRTF

Sets the text of a RichEdit control, including all the RTF codes.

Syntax

public void setRTF( String rtfText )

Parameters

rtfText

The text to set, including all the RTF codes.

Exceptions

WFCException thrown if the text contains no RTF codes.

See Also getRTF


 RichEdit.setSelAlignment

RichEdit.setSelAlignment

Sets the paragraph alignment for the RichEdit control.

Syntax

public void setSelAlignment( int selAlignment )

Parameters

selAlignment

The paragraph alignment. This value must be one of the enumeration constants defined in the HorizontalAlignment class.

Exceptions

WFCInvalidEnumException thrown if the value specified in selAlignment is not a valid member of the HorizontalAlignment class.

Remarks

If no paragraph is selected, the alignment is applied to the paragraph in which the insertion point appears.

See Also getSelAlignment


 RichEdit.setSelBullet

RichEdit.setSelBullet

Specifies whether the bullet style should be applied to the current selection or insertion point.

Syntax

public void setSelBullet( boolean selBullet )

Parameters

selBullet

Set to true to apply the bullet style to the selection or insertion point; otherwise, set to false.

See Also getSelBullet


 RichEdit.setSelCharOffset

RichEdit.setSelCharOffset

Determines whether text in the control appears on the baseline, as a superscript above the baseline, or as a subscript below the base line.

Syntax

public void setSelCharOffset( int selCharOffset )

Parameters

selCharOffset

A value that specifies the character offset. If this value is zero, the text appears on the baseline. If it is a positive number, the number specifies the number of pixels by which to raise the selection above the baseline. If it is a negative number, this number specifies the number of pixels by which to subscript the selection.

Remarks

If no text is currently selected, the offset is applied to the current insertion point and to all text that the user types at the insertion point. The new offset applies only until the insertion point is moved.

See Also getSelCharOffset


 RichEdit.setSelColor

RichEdit.setSelColor

Sets the text color of the currently selected text.

Syntax

public void setSelColor( Color selColor )

Parameters

selColor

A Color object that describes the color to which to set the selection.

Remarks

If no text is currently selected, the color is applied to the current insertion point, and to all text that the user types at the insertion point. The new color format is in effect only until the insertion point changes.

See Also getSelColor


 RichEdit.setSelFont

RichEdit.setSelFont

Sets the font used to display the currently selected characters, or the characters immediately following the insertion point.

Syntax

public void setSelFont( Font font )

Parameters

font

A Font object that describes the font to apply to the selection.

Remarks

If no text is currently selected, the font is applied to the current insertion point, and to all text that the user types after the insertion point. The new font is in effect only until the insertion point changes.

See Also getSelFont


 RichEdit.setSelHangingIndent

RichEdit.setSelHangingIndent

Sets the distance between the left edge of the first line of text in the selected paragraph and the left edge of subsequent lines in the same paragraph.

Syntax

public void setSelHangingIndent( int selHangingIndent )

Parameters

selHangingIndent

The distance of the hanging indent, in pixels.

Remarks

To set the indention of the first line of a paragraph selection, use the setSelIndent method.

If no paragraph is currently selected, the hanging indent is applied to the paragraph in which the insertion point appears.

See Also getSelHangingIndent


 RichEdit.setSelIndent

RichEdit.setSelIndent

Sets the distance between the left edge of the control and the left edge of the text that is currently selected or that is added at the insertion point.

Syntax

public void setSelIndent( int selIndent )

Parameters

selIndent

The amount of indention, in pixels.

See Also getSelIndent


 RichEdit.setSelLength

RichEdit.setSelLength

Selects the specified number of characters, beginning at the current insertion point.

Syntax

public void setSelLength( int selLength )

Parameters

selLength

The length of the selection.

See Also getSelLength


 RichEdit.setSelProtected

RichEdit.setSelProtected

Marks the current selection as protected.

Syntax

public void setSelProtected( boolean protect )

Parameters

protect

Set to true to protect the current selection; otherwise, set to false.

Remarks

If the protect parameter is set to true, the protected event is fired when the user attempts to change the selection.

If no text is currently selected, the protection is is applied to the current insertion point, and to all text that the user types after the insertion point. The protection is in effect only until the insertion point changes.

See Also onProtected, getSelProtected


 RichEdit.setSelRightIndent

RichEdit.setSelRightIndent

Sets the distance between the right edge of the control and the right edge of text that is selected or that is added at the current insertion point.

Syntax

public void setSelRightIndent( int selRightIndent )

Parameters

selRightIndent

The indention space at the right of the selection or insertion point.

See Also getSelRightIndent


 RichEdit.setSelRTF

RichEdit.setSelRTF

Sets the currently selected text of a RichEdit control, including the text's RTF codes.

Syntax

public void setSelRTF( String selRTF )

Parameters

selRTF

The selected text.

Remarks

If no text is currently selected, the text specified in the selRTF paramter is inserted at the insertion point. If text is selected, the text replaces the selected text.

See Also getSelRTF


 RichEdit.setSelTabs

RichEdit.setSelTabs

Sets the absolute tab stop positions in a RichEdit control.

Syntax

public void setSelTabs( int selTabs[] )

Parameters

selTabs

An array of tabstops.

See Also getSelTabs


 RichEdit.setSelText

RichEdit.setSelText

Sets the selected text in the RichEdit control.

Syntax

public void setSelText( String selText )

Parameters

selText

The text to select

Remarks

If text is selected, it is replaced by the text specified in the selText parameter. If no text is selected, the text is placed at the insertion point.


 RichEdit.setWordBreak

RichEdit.setWordBreak

Enables or disables English word-breaking in Japanese, Chinese, and Hangeul.

Syntax

public void setWordBreak( boolean enable )

Parameters

enable

Set to true to enable English-language word breaking; otherwise, set to false.

Remarks

This method is used in conjunction with the setWordWrap and setWordPunctuation methods to determine the layout of text in the RichEdit control.

This method is valid for use only on Asian versions of the Windows operating system.

See Also getWordBreak


 RichEdit.setWordPunctuation

RichEdit.setWordPunctuation

Sets the type of punctuation table to be used to determine the RichEdit control's word-wrap and word-break layout.

Syntax

public void setWordPunctuation( int punc )

Parameters

punc

The punctuation table to be used. This value must be one of the enumeration constants defined in the RichEditWordPunctuation class.

Exceptions

WFCInvalidEnumException thrown if the punc parameter is not a valid member of the RichEditWordPunctuation class.

Remarks

This method is used in conjunction with the setWordBreak and setWordWrap methods to determine the layout of text in the RichEdit control.

This method is valid for use only on Asian versions of the Windows operating system.

See Also getWordPunctuation


 RichEdit.span

RichEdit.span

Selects text in the RichEdit control based on a specified set of characters.

Syntax

public void span( String characterSet )

public void span( String characterSet, boolean forward )

public void span( String characterSet, boolean forward, boolean negate )

Parameters

characterSet

A string expression that specifies the set of characters to look for when extending the selection, based on the value of the negate parameter.

forward

Set to true to move the cursor forward in the text; otherwise, set to false. The default value for this parameter is true.

negate

Set to true to include in the selection those characters that are not in the character set. Set to false to include in the selection the characters that are in the character set. The default setting for this parameter is false.

Remarks

The following example illustrates how a call to this method determines which characters in a character set are selected.

Suppose that you want to span to the characters "dog" in a string that consists of the characters "My life as a dog". In this case, the characterSet parameter contains the string "dog". If negate is set to true, all the characters up to the first character in "dog" are selected, but "dog" is not; the selection stops at the first character found in the character set. If negate is set to false, none of the text is selected, because the selection stops at the first character not included in the character set (the first character in "My life as a dog").

See Also moveInsertionPoint


RichEditFind Class

Defines constants that determine how a text search is carried out in a RichEdit control.

Enum
  |
  +--RichEditFind

package com.ms.wfc.ui

public class RichEditFind
extends Enum

Remarks

An application locates text in the RichEdit control by calling the RichEdit class' find method. This class defines the constants that you can pass to that method.

You can combine one or more of the values defined in this class using a logical OR operator.


 RichEditFind Methods

RichEditFind Methods

Methods | Description
valid | Retrieves a boolean value that indicates whether the specified value is a valid member of this class.


 RichEditFind.valid

RichEditFind.valid

Retrieves a boolean value that indicates whether the specified value is a valid member of this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check against the values defined in this class.

Return Value

Returns true if the value is valid; otherwise, returns false.


 RichEditFind Fields

RichEditFind Fields

Fields | Description
MATCHCASE | Indicates that the search is case-sensitive.
NOHIGHLIGHT | Indicates that the text, if found, should not be highlighted.
NONE | Indicates that the method should locate all instances of the search text, whether the instances are whole words or not.
WHOLEWORD | Indicates that the method should only locate instances of the search text that are whole words.


 RichEditFind.MATCHCASE

RichEditFind.MATCHCASE

Indicates that the search is case-sensitive.

Syntax

public static final int MATCHCASE;


 RichEditFind.NOHIGHLIGHT

RichEditFind.NOHIGHLIGHT

Indicates that the text, if found, should not be highlighted.

Syntax

public static final int NOHIGHLIGHT;


 RichEditFind.NONE

RichEditFind.NONE

Indicates that the method should locate all instances of the search text, whether the instances are whole words or not.

Syntax

public static final int NONE;


 RichEditFind.WHOLEWORD

RichEditFind.WHOLEWORD

Indicates that the method should only locate instances of the search text that are whole words.

Syntax

public static final int WHOLEWORD;


RichEditIMEColor Class

Defines the options that can be set on the text of the input method editor (IME) composition window of a RichEdit control.

package com.ms.wfc.ui

public class RichEditIMEColor

Remarks

To set the IME color options on the RichEdit control, initialize an instance of this object, and pass the object to the RichEdit object's setIMEColor method.

Setting IME color on a RichEdit control is applicable only on Asian versions of the operating system.


 RichEditIMEColor Methods

RichEditIMEColor Methods

Constructors | Description
RichEditIMEColor | Creates a RichEditIMEColor object.

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value is a valid member of this class.


 RichEditIMEColor.RichEditIMEColor

RichEditIMEColor.RichEditIMEColor

Creates a RichEditIMEColor object.

Syntax

public RichEditIMEColor()


 RichEditIMEColor.valid

RichEditIMEColor.valid

Retrieves a boolean value that indicates whether a specified value is a valid member of this class.

Syntax

public static boolean valid( int value )

Parameters

value

A value to compare to the constants defined in this class.

Return Value

Returns true if value is a valid member of this class; otherwise, returns false.


 RichEditIMEColor Fields

RichEditIMEColor Fields

Fields | Description
backColor | Specifies the background color of the input method editor (IME) composition window.
bold | Enables or disables the use of boldfaced text in the input method editor (IME) input window.
italic | Enables or disables the use of italics in the input method editor (IME) composition window.
protect | Enables or disables the protected attribute on text in the input method editor (IME) input window.
strikeOut | Enables or disables the use of strikeout text in the input method editor (IME) composition window.
textColor | Specifies the text color for the input method editor (IME) composition window.
underline | Enables or disables the use of underlining in the input method editor (IME) composition window.


 RichEditIMEColor.backColor

RichEditIMEColor.backColor

Specifies the background color of the input method editor (IME) composition window.

Syntax

public Color backColor;

Remarks

The default value of this field is Color.CONTROL.


 RichEditIMEColor.bold

RichEditIMEColor.bold

Enables or disables the use of boldfaced text in the input method editor (IME) input window.

Syntax

public boolean bold;

Remarks

The default value of this field is false.


 RichEditIMEColor.italic

RichEditIMEColor.italic

Enables or disables the use of italics in the input method editor (IME) composition window.

Syntax

public boolean italic;

Remarks

The default value of this field is false.


 RichEditIMEColor.protect

RichEditIMEColor.protect

Enables or disables the protected attribute on text in the input method editor (IME) input window.

Syntax

public boolean protect;

Remarks

The default value of this field is false.


 RichEditIMEColor.strikeOut

RichEditIMEColor.strikeOut

Enables or disables the use of strikeout text in the input method editor (IME) composition window.

Syntax

public boolean strikeout;

Remarks

The default value of this field is false.


 RichEditIMEColor.textColor

RichEditIMEColor.textColor

Specifies the text color for the input method editor (IME) composition window.

Syntax

public Color textColor;

Remarks

The default value of this field is Color.CONTROLTEXT.


 RichEditIMEColor.underline

RichEditIMEColor.underline

Enables or disables the use of underlining in the input method editor (IME) composition window.

Syntax

public boolean underline;

Remarks

The default value of this field is false.


RichEditIMEOptions Class

Defines constants that represent the options you can set on the RichEdit control's input method editor (IME) composition window.

Enum
  |
  +--RichEditIMEOptions

package com.ms.wfc.ui

public class RichEditIMEOptions
extends Enum

Remarks

To set the IME options on a RichEdit control, use the logical OR operator to combine one or more of the constants defined in this class, and pass the resulting value to the RichEdit object's setIMEOptions method.

This method is applicable only to Asian versions of the operating system.


 RichEditIMEOptions Methods

RichEditIMEOptions Methods

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value is a valid member of this class.


 RichEditIMEOptions.valid

RichEditIMEOptions.valid

Retrieves a boolean value that indicates whether a specified value is a valid member of this class.

Syntax

public static boolean valid( int value )

Parameters

value

A value to compare to the constants defined in this class.

Return Value

Returns true if value is a valid member of this class; otherwise, returns false.


 RichEditIMEOptions Fields

RichEditIMEOptions Fields

Fields | Description
CLOSESTATUSWINDOW | Specifies that the input method editor (IME) status window should close when the control receives the input focus.
FORCEACTIVE | Specifies that the input method editor (IME) should be activated when the control receives the input focus.
FORCEDISABLE | Specifies that the (IME) should be disabled when the control receives the input focus.
FORCEENABLE | Specifies that the input method editor (IME) should be enabled when the control receives the input focus.
FORCEINACTIVE | Specifies that the input method editor (IME) should be made inactive when the control receives the input focus.
FORCENONE | Specifies that input method editor (IME) handling should be disabled.
FORCEREMEMBER | Specifies that previous input method editor (IME) status should be restored when the control receives the input focus.
MULTIPLEEDIT | Specifies that the composition string will not be canceled or determined by focus changes. This allows an application to have separate comosition strings on each rich edit control.
VERTICAL | Specifies that vertical text input should be enabled.


 RichEditIMEOptions.CLOSESTATUSWINDOW

RichEditIMEOptions.CLOSESTATUSWINDOW

Specifies that the input method editor (IME) status window should close when the control receives the input focus.

Syntax

static public final int CLOSESTATUSWINDOW;


 RichEditIMEOptions.FORCEACTIVE

RichEditIMEOptions.FORCEACTIVE

Specifies that the input method editor (IME) should be activated when the control receives the input focus.

Syntax

static public final int FORCEACTIVE;


 RichEditIMEOptions.FORCEDISABLE

RichEditIMEOptions.FORCEDISABLE

Specifies that the (IME) should be disabled when the control receives the input focus.

Syntax

static public final int FORCEDISABLE;


 RichEditIMEOptions.FORCEENABLE

RichEditIMEOptions.FORCEENABLE

Specifies that the input method editor (IME) should be enabled when the control receives the input focus.

Syntax

static public final int FORCEENABLE;


 RichEditIMEOptions.FORCEINACTIVE

RichEditIMEOptions.FORCEINACTIVE

Specifies that the input method editor (IME) should be made inactive when the control receives the input focus.

Syntax

static public final int FORCEINACTIVE;


 RichEditIMEOptions.FORCENONE

RichEditIMEOptions.FORCENONE

Specifies that input method editor (IME) handling should be disabled.

Syntax

static public final int FORCENONE;


 RichEditIMEOptions.FORCEREMEMBER

RichEditIMEOptions.FORCEREMEMBER

Specifies that previous input method editor (IME) status should be restored when the control receives the input focus.

Syntax

static public final int FORCEREMEMBER;


 RichEditIMEOptions.MULTIPLEEDIT

RichEditIMEOptions.MULTIPLEEDIT

Specifies that the composition string will not be canceled or determined by focus changes. This allows an application to have separate comosition strings on each rich edit control.

Syntax

static public final int MULTIPLEEDIT;


 RichEditIMEOptions.VERTICAL

RichEditIMEOptions.VERTICAL

Specifies that vertical text input should be enabled.

Syntax

static public final int VERTICAL;


RichEditScrollBars Class

Defines constants that identify the type of scroll bars that should be used in a RichEdit control.

Enum
  |
  +--ScrollBars
    |
    +--RichEditScrollBars

package com.ms.wfc.ui

public class RichEditScrollBars
extends ScrollBars


 RichEditScrollBars Methods

RichEditScrollBars Methods

Methods | Description
valid | Retrieves a boolean value that indicates whether the specified value is a valid member of this class.


 RichEditScrollBars.valid

RichEditScrollBars.valid

Retrieves a boolean value that indicates whether the specified value is a valid member of this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check against the values defined in this class.

Return Value

Returns true if the value is valid; otherwise, returns false.


 RichEditScrollBars Fields

RichEditScrollBars Fields

Fields | Description
FORCED_BOTH | Indicates that the vertical and horizontal scroll bars should always be displayed.
FORCED_HORIZONTAL | Indicates that the horizontal scroll bar should always be displayed.
FORCED_VERTICAL | Indicates that the vertical scroll bar should always be displayed.


 RichEditScrollBars.FORCED_BOTH

RichEditScrollBars.FORCED_BOTH

Indicates that the vertical and horizontal scroll bars should always be displayed.

Syntax

public static final int FORCED_BOTH;


 RichEditScrollBars.FORCED_HORIZONTAL

RichEditScrollBars.FORCED_HORIZONTAL

Indicates that the horizontal scroll bar should always be displayed.

Syntax

public static final int FORCED_HORIZONTAL;


 RichEditScrollBars.FORCED_VERTICAL

RichEditScrollBars.FORCED_VERTICAL

Indicates that the vertical scroll bar should always be displayed.

Syntax

public static final int FORCED_VERTICAL;


RichEditSelType Class

Defines constants that indicate the type of selection in a RichEdit control.

Enum
  |
  +--RichEditSelType

package com.ms.wfc.ui

public class RichEditSelType
extends Enum

Remarks

An application determines the selection type by calling the RichEdit control's getSelType method. This method returns one of the constants defined in this class.


 RichEditSelType Methods

RichEditSelType Methods

Methods | Description
valid | Retrieves a boolean value that indicates whether the specified value is a valid member of this class.


 RichEditSelType.valid

RichEditSelType.valid

Retrieves a boolean value that indicates whether the specified value is a valid member of this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check against the values defined in this class.

Return Value

Returns true if the value is valid; otherwise, returns false.


 RichEditSelType Fields

RichEditSelType Fields

Fields | Description
EMPTY | Indicates that no text is selected.
MULTICHAR | Indicates that multiple characters are selected.
MULTIOBJECT | Indicates that multiple objects are selected.
OBJECT | Indicates that a single object is selected.
TEXT | Indicates that text is selected.


 RichEditSelType.EMPTY

RichEditSelType.EMPTY

Indicates that no text is selected.

Syntax

public static final int EMPTY;


 RichEditSelType.MULTICHAR

RichEditSelType.MULTICHAR

Indicates that multiple characters are selected.

Syntax

public static final int MULTICHAR;


 RichEditSelType.MULTIOBJECT

RichEditSelType.MULTIOBJECT

Indicates that multiple objects are selected.

Syntax

public static final int MULTIOBJECT;


 RichEditSelType.OBJECT

RichEditSelType.OBJECT

Indicates that a single object is selected.

Syntax

public static final int OBJECT;


 RichEditSelType.TEXT

RichEditSelType.TEXT

Indicates that text is selected.

Syntax

public static final int TEXT;


RichEditStreamType Class

Defines constants that identify the types of input and output streams used by the RichEdit control's saveFile and loadFile methods.

Enum
  |
  +--RichEditStreamType

package com.ms.wfc.ui

public class RichEditStreamType
extends Enum


 RichEditStreamType Methods

RichEditStreamType Methods

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value is a valid member of this class.


 RichEditStreamType.valid

RichEditStreamType.valid

Retrieves a boolean value that indicates whether a specified value is a valid member of this class.

Syntax

public static boolean valid( int value )

Parameters

value

A value to compare to the constants defined in this class.

Return Value

Returns true if value is a valid member of this class; otherwise, returns false.


 RichEditStreamType Fields

RichEditStreamType Fields

Fields | Description
PLAINTEXT | Indicates that the stream is a plain text stream that includes spaces in places of OLE objects.
RICH_NOOLEOBJS | Indicates that the stream is an RTF stream with spaces in place of OLE objects.
RICHTEXT | Indicates that the stream is a Rich Text Format (RTF) stream.
TEXT_TEXTOLEOBJS | Indicates that the stream is plain text with a textual representation of OLE objects.


 RichEditStreamType.PLAINTEXT

RichEditStreamType.PLAINTEXT

Indicates that the stream is a plain text stream that includes spaces in places of OLE objects.

Syntax

public static final int PLAINTEXT;


 RichEditStreamType.RICH_NOOLEOBJS

RichEditStreamType.RICH_NOOLEOBJS

Indicates that the stream is an RTF stream with spaces in place of OLE objects.

Syntax

public static final int RICH_NOOLEOBJS;

Remarks

This method is valid for use only with the RichEdit object's saveFile method.


 RichEditStreamType.RICHTEXT

RichEditStreamType.RICHTEXT

Indicates that the stream is a Rich Text Format (RTF) stream.

Syntax

public static final int RICHTEXT;


 RichEditStreamType.TEXT_TEXTOLEOBJS

RichEditStreamType.TEXT_TEXTOLEOBJS

Indicates that the stream is plain text with a textual representation of OLE objects.

Syntax

public static final int TEXT_TEXTOLEOBJS;

Remarks

This method is valid for use only with the RichEdit object's saveFile method.


RichEditWordPunctuation Class

Defines the types of punctuation tables that can be used with the RichEdit control's word-wrapping and word-breaking features.

Enum
  |
  +--RichEditWordPunctuation

package com.ms.wfc.ui

public class RichEditWordPunctuation
extends Enum

Remarks

The word-wrapping and word-breaking features of the RichEdit control enable English-language word-breaking on Asian versions of the Windows operating system.

An application uses the RichEdit class' setWordBreak method to apply word-breaking to the control, and uses the setWordPunctuation method to associate a punctuation table with the control.


 RichEditWordPunctuation Methods

RichEditWordPunctuation Methods

Methods | Description
valid | Retrieves a boolean value that indicates whether the specified value is a valid member of this class.


 RichEditWordPunctuation.valid

RichEditWordPunctuation.valid

Retrieves a boolean value that indicates whether the specified value is a valid member of this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check against the values defined in this class.

Return Value

Returns true if the value is valid; otherwise, returns false.


 RichEditWordPunctuation Fields

RichEditWordPunctuation Fields

Fields | Description
CUSTOM | Indicates that the control should use a custom-defined punctuation table.
LEVEL1 | Indicates that the control should use the pre-defined Level 1 punctuation table as the default.
LEVEL2 | Indicates that the control should use the pre-defined Level 2 punctuation table as the default.


 RichEditWordPunctuation.CUSTOM

RichEditWordPunctuation.CUSTOM

Indicates that the control should use a custom-defined punctuation table.

Syntax

public static final int CUSTOM;


 RichEditWordPunctuation.LEVEL1

RichEditWordPunctuation.LEVEL1

Indicates that the control should use the pre-defined Level 1 punctuation table as the default.

Syntax

public static final int LEVEL1;


 RichEditWordPunctuation.LEVEL2

RichEditWordPunctuation.LEVEL2

Indicates that the control should use the pre-defined Level 2 punctuation table as the default.

Syntax

public static final int LEVEL2;


SaveFileDialog Class

Encapsulates the Save As common dialog box control that allows the user to specify options for saving a file.

Component
  |
  +--CommonDialog
    |
    +--FileDialog
      |
      +--SaveFileDialog

package com.ms.wfc.ui

public class SaveFileDialog
extends FileDialog

Remarks

The following example sets options for a Save As dialog box, displays the dialog box, and stores the name the user saved the file under in a variable:

private void btnSave_click(Object source, Event e)
{
    SaveFileDialog sfd = new SaveFileDialog();
    sfd.setDefaultExt("java");	//sets the default extension
    sfd.setValidateNames(true); //enables name validation
    sfd.setCreatePrompt(true);  //prompts the user to create the file if it doesn't exist
    sfd.setInitialDir("c:\\program files");  //sets the initial directory
    int dlgResult = sfd.showDialog();
    if (dlgResult == DialogResult.OK) {
        String fname = sfd.getFileName(); //gets the name the file was stored under
        MessageBox.show(fname);
    }
}


 SaveFileDialog Methods

SaveFileDialog Methods

Methods | Description
getCreatePrompt | Retrieves a boolean value indicating whether the dialog box prompts the user for permission to create a file if the user specifies a file that does not exist.
getOverwritePrompt | Retrieves a boolean value indicating whether the Save As dialog box should display a warning if the user specifies a file name that already exists.
reset | Resets all dialog box options to their default values.
setCreatePrompt | Sets a boolean value indicating whether the dialog box prompts the user for permission to create a file if the user specifies a file that does not exist.
setOverwritePrompt | Sets a boolean value indicating whether the Save As dialog box should display a warning if the user specifies a file name that already exists.


 SaveFileDialog.getCreatePrompt

SaveFileDialog.getCreatePrompt

Retrieves a boolean value indicating whether the dialog box prompts the user for permission to create a file if the user specifies a file that does not exist.

Syntax

public final boolean getCreatePrompt()

Return Value

Returns true if the dialog box prompts the user before creating a file if the user specifies a file name that does not exist; returns false if the dialog box automatically creates the new file without prompting the user for permission.

See Also setCreatePrompt


 SaveFileDialog.getOverwritePrompt

SaveFileDialog.getOverwritePrompt

Retrieves a boolean value indicating whether the Save As dialog box should display a warning if the user specifies a file name that already exists.

Syntax

public final boolean getOverwritePrompt()

Return Value

Returns true if the dialog box prompts the user before overwriting an existing file if the user specifies a file name that already exists; returns false if the dialog box automatically overwrites the existing file without prompting the user for permission.

Remarks

The warning allows the user to specify whether to overwrite the existing file.

See Also setOverwritePrompt


 SaveFileDialog.reset

SaveFileDialog.reset

Resets all dialog box options to their default values.

Syntax

public void reset()

Overrides FileDialog.reset


 SaveFileDialog.setCreatePrompt

SaveFileDialog.setCreatePrompt

Sets a boolean value indicating whether the dialog box prompts the user for permission to create a file if the user specifies a file that does not exist.

Syntax

public final void setCreatePrompt( boolean value )

Parameters

value

Set to true if the dialog box prompts the user before creating a file if the user specifies a file name that does not exist; set to false if the dialog box automatically creates the new file without prompting the user for permission. The default value is false. If the user chooses to create the file, the dialog box closes and the function returns the specified name; otherwise, the dialog box remains open. The validateNames property must also be set to true for the user to be prompted for permission.

Remarks

For a code example using this method, see the SaveFileDialog control topic.

See Also getCreatePrompt


 SaveFileDialog.setOverwritePrompt

SaveFileDialog.setOverwritePrompt

Sets a boolean value indicating whether the Save As dialog box should display a warning if the user specifies a file name that already exists.

Syntax

public final void setOverwritePrompt( boolean value )

Parameters

value

Set to true if the dialog box prompts the user before overwriting an existing file if the user specifies a file name that already exists; set to false if the dialog box automatically overwrites the existing file without prompting the user for permission. The default value is true. If the user chooses to overwrite the file, the dialog box closes; otherwise, the dialog box remains open. The validateNames property must also be set to true for the user to be prompted for permission.

Remarks

The warning allows the user to choose whether to overwrite the existing file.

See Also getOverwritePrompt


Screen Class

Encapsulates the physical display device.

package com.ms.wfc.ui

public class Screen

Remarks

This object's constructor is private so that the object cannot be explicitly initialized. Instead, the object is initialized when you call its public methods. For example, the following illustrates how to call the Screen object's getPrimary method to retrieve a Screen object for the system's primary monitor:

Screen screen = Screen.getPrimary();


 Screen Methods

Screen Methods

Methods | Description
equals | Retrieves a boolean value that indicates whether the specified object is equal to this one.
fromControl | Retrieves a Screen object for the monitor that contains the largest portion of the specified control or window.
fromHwnd | Retrieves a Screen object for the monitor that contains the largest portion of the specified window.
fromPoint | Returns a Screen object for the monitor that contains the specified point.
fromRectangle | Returns a Screen object for the monitor that contains the largest portion of a specified rectangle.
getAllScreens | Retrieves an array of Screen objects that represents each monitor on the system.
getBounds | Retrieves the bounds of the monitor that is closest to the specified point, or that contains the largest region of the specified rectangle or control.
getPrimary | Retrieves a Screen object for the primary monitor.
getWorkingArea | Retrieves the working area for the monitor that is closest to the specified point or that contains the largest region of the specified rectangle or control.
hashCode | Computes and returns a hash code for this object.
toString | Retrieves a human-readable string representation of this object.


 <b>Screen.equals</b>

Screen.equals

Retrieves a boolean value that indicates whether the specified object is equal to this one.

Syntax

public boolean equals( Object obj )

Parameters

obj

The object to compare to this one.

Return Value

Returns true if the specified object is equivalent to this one; otherwise, returns false.


 Screen.fromControl

Screen.fromControl

Retrieves a Screen object for the monitor that contains the largest portion of the specified control or window.

Syntax

public static Screen fromControl( Control control )

Parameters

control

A Control object for which to retrieve the monitor.

Return Value

Returns a Screen object for the monitor that contains the largest region of the specified control. If no monitor contains the control, then the monitor closest to the specified control is returned.

See Also fromPoint, fromHwnd, fromRectangle


 Screen.fromHwnd

Screen.fromHwnd

Retrieves a Screen object for the monitor that contains the largest portion of the specified window.

Syntax

public static Screen fromHwnd( int hwnd )

Parameters

hwnd

The window handle for which to retrieve the monitor.

Return Value

Returns a Screen object for the monitor that contains the largest region of the specified window. If no monitor contains any portion of the specified window, then the monitor closest to the window is returned.

See Also fromControl, fromPoint, fromRectangle


 Screen.fromPoint

Screen.fromPoint

Returns a Screen object for the monitor that contains the specified point.

Syntax

public static Screen fromPoint( Point point )

Parameters

point

A Point object that specifies the location for which to retrieve a Screen object.

Return Value

Returns a Screen object for the monitor that contains the point. If no monitor contains the point, then the monitor closest to the specified point is returned.

See Also fromControl, fromHwnd, fromRectangle


 Screen.fromRectangle

Screen.fromRectangle

Returns a Screen object for the monitor that contains the largest portion of a specified rectangle.

Syntax

public static Screen fromRectangle( Rectangle rect )

Parameters

rect

A Rectangle object that specifies the area for which to retrieve the monitor.

Return Value

Returns a Screen object for the monitor that contains the largest region of the specified rectangle. If no monitor contains the rectangle, then the monitor closest to the rectangle is returned.

See Also fromControl, fromHwnd, fromPoint


 Screen.getAllScreens

Screen.getAllScreens

Retrieves an array of Screen objects that represents each monitor on the system.

Syntax

public static Screen[] getAllScreens()

Return Value

Returns an array of Screen objects in which each entry represents one of the monitors on the system.

See Also getPrimary


 Screen.getBounds

Screen.getBounds

Retrieves the bounds of the monitor that is closest to the specified point, or that contains the largest region of the specified rectangle or control.

Syntax

public static Rectangle getBounds( Point pt )

public static Rectangle getBounds( Rectangle rect )

public static Rectangle getBounds( Control ctl )

Parameters

pt

A Point object that specifies the coordinates for which to retrieve the monitor bounds.

rect

A Rectangle object that specifies the area for which to retrieve the monitor bounds.

ctl

The Control for which to retrieve the monitor bounds.

Return Value

Returns a Rectangle object that specifies the bounds of the monitor that contains the specified point, rectangle, or control. If no monitor contains the specified object, the monitor closest to the object is returned.

See Also getWorkingArea


 Screen.getPrimary

Screen.getPrimary

Retrieves a Screen object for the primary monitor.

Syntax

public static Screen getPrimary()

Return Value

Returns a Screen object for the primary monitor on the system. If the system contains only a single monitor, this method returns a Screen object for that monitor.

See Also getAllScreens


 Screen.getWorkingArea

Screen.getWorkingArea

Retrieves the working area for the monitor that is closest to the specified point or that contains the largest region of the specified rectangle or control.

Syntax

public static Rectangle getWorkingArea( Point pt )

public static Rectangle getWorkingArea( Rectangle rect )

public static Rectangle getWorkingArea( Control ctl )

Parameters

pt

A Point object that specifies the coordinates for which to retrieve the working area.

rect

A Rectangle object that specifies the area for which to retrieve the working area.

ctl

The Control object for which to retrieve the working area.

Return Value

Returns a Rectangle object that specifies the working area for the appropriate monitor. If no monitor contains the specified object, the monitor closest to the object is returned.

See Also getBounds


 Screen.hashCode

Screen.hashCode

Computes and returns a hash code for this object.

Syntax

public int hashCode()

Return Value

Returns the object's hash code.


 Screen.toString

Screen.toString

Retrieves a human-readable string representation of this object.

Syntax

public String toString()

Return Value

Returns a string representation of the object.


 Screen Fields

Screen Fields

Fields | Description
deviceName | Specifies the name of the device.
primary | Specifies whether this Screen object represents the primary monitor.
workingArea | Specifies the working area of the screen.


 Screen.deviceName

Screen.deviceName

Specifies the name of the device.

Syntax

public final String deviceName;


 Screen.primary

Screen.primary

Specifies whether this Screen object represents the primary monitor.

Syntax

public final boolean primary;


 Screen.workingArea

Screen.workingArea

Specifies the working area of the screen.

Syntax

public final Rectangle workingArea;

Remarks

The working area of the screen excludes taskbars and other docked windows.


ScrollBar Class

Represents the base class for scroll bar controls.

Control
  |
  +--ScrollBar

package com.ms.wfc.ui

public abstract class ScrollBar
extends Control

Remarks

This class implements the base functionality for all scroll bars controls.

Note Because the ScrollBar class is abstract, you must use a subclass to create a scroll bar control. Classes that extend ScrollBar include HScrollBar and VScrollBar, which implement horizontal and vertical scroll bars, respectively.

When you add a scroll bar control to a form, you should bring the scroll bar to the front of the z-order of the controls on the form. This ensures that the scroll bar is always drawn on top of the other controls. For example, if you anchor a control to the right side of the form and then resize the form to a smaller width, this control may appear on top of the scroll bar. To set the scroll bar at the front of the z-order in the Forms Designer, right-click the scroll bar control on the form and click Bring to Front on the shortcut menu. To set the scroll bar at the front of the z-order in code, call its bringToFront method.

To display scroll bars for the form itself, you can either explicitly use a scroll bar control or set the autoScroll property of the form. When you set the form's autoScoll property to true, horizontal and vertical scroll bars are automatically displayed when needed, and are excluded from the client area of the form. However, if you explicitly add a scroll bar control, the scroll bar is always displayed and is included in the form's client area. Therefore, to determine the area that is actually available for drawing on the form, you must manually subtract the height of the horizontal scroll bar and the width of the vertical scroll bar.

See Also ScrollEvent, ScrollEventType


 ScrollBar Methods

ScrollBar Methods

Constructors | Description
ScrollBar | Creates a scroll bar.

Methods | Description
addOnScroll | Assigns a delegate to the scroll event.
addOnValueChanged | Assigns a delegate to the valueChanged event.
getLargeChange | Retrieves the increment between each large change of the scroll thumb.
getMaximum | Retrieves the maximum value of the scroll bar.
getMinimum | Retrieves the minimum value of the scroll bar.
getSmallChange | Retrieves the increment between each small change of the scroll thumb.
getValue | Retrieves the current value of the scroll bar.
onScroll | Triggers the scroll event.
onValueChanged | Triggers the valueChanged event.
removeOnScroll | Removes the delegate that is assigned to the scroll event.
removeOnValueChanged | Removes the delegate that is assigned to the valueChanged event.
setLargeChange | Sets the increment between each large change of the scroll thumb.
setMaximum | Sets the maximum value of the scroll bar.
setMinimum | Sets the minimum possible value of the scroll bar.
setSmallChange | Sets the increment between each small change of the scroll thumb.
setValue | Sets the value of the scroll bar.


 ScrollBar.addOnScroll

ScrollBar.addOnScroll

Assigns a delegate to the scroll event.

Syntax

public void addOnScroll( ScrollEventHandler seh )

Parameters

seh

The ScrollEventHandler delegate to be notified when the event occurs.

Remarks

The scroll event occurs when the user changes the value of the scroll bar. This event can result from a variety of actions, such as clicking a scroll bar arrow or dragging the scroll thumb. For more information about the different types of scroll events, see ScrollEventType.

After the scroll event is triggered, the valueChanged event occurs.

You can programmatically change the value of the scroll bar by calling setValue; however, only the valueChanged event will occur.

See Also removeOnScroll


 ScrollBar.addOnValueChanged

ScrollBar.addOnValueChanged

Assigns a delegate to the valueChanged event.

Syntax

public void addOnValueChanged( EventHandler eh )

Parameters

eh

The EventHandler delegate to be notified when the event occurs.

Remarks

The valueChanged event occurs when the value of the scroll bar is changed, either programmatically or by the user.

Note When the user changes the value of the scroll bar, the scroll event is also triggered. The scroll event occurs before the valueChanged event.

To programmatically change the value of the scroll bar, call setValue.

See Also removeOnValueChanged


 ScrollBar.getLargeChange

ScrollBar.getLargeChange

Retrieves the increment between each large change of the scroll thumb.

Syntax

public int getLargeChange()

Return Value

Returns the large change increment. For more information, see setLargeChange.

See Also getSmallChange


 ScrollBar.getMaximum

ScrollBar.getMaximum

Retrieves the maximum value of the scroll bar.

Syntax

public int getMaximum()

Return Value

Returns the maximum value. For more information, see setMaximum.

See Also getMinimum, getValue


 ScrollBar.getMinimum

ScrollBar.getMinimum

Retrieves the minimum value of the scroll bar.

Syntax

public int getMinimum()

Return Value

Returns the minimum value. For more information, see setMinimum.

See Also getMaximum, getValue


 ScrollBar.getSmallChange

ScrollBar.getSmallChange

Retrieves the increment between each small change of the scroll thumb.

Syntax

public int getSmallChange()

Return Value

Returns the small change increment. For more information, see setSmallChange.

See Also getLargeChange


 ScrollBar.getValue

ScrollBar.getValue

Retrieves the current value of the scroll bar.

Syntax

public int getValue()

Return Value

Returns the value of the scroll bar.

Remarks

The value of the scroll bar represents the position of the scroll thumb.

See Also setValue, getMaximum, getMinimum


 ScrollBar.onScroll

ScrollBar.onScroll

Triggers the scroll event.

Syntax

protected void onScroll( ScrollEvent se )

Parameters

se

A ScrollEvent object that provides information about the event.

Remarks

The scroll event occurs when the user changes the value of the scroll bar.

When overriding onScroll, be sure to call super.onScroll.

See Also addOnScroll, removeOnScroll


 ScrollBar.onValueChanged

ScrollBar.onValueChanged

Triggers the valueChanged event.

Syntax

protected void onValueChanged( Event e )

Parameters

se

An Event object.

Remarks

The valueChanged event occurs when the value of the scroll bar is changed, either programmatically or by the user.

When overriding onValueChanged, be sure to call super.onValueChanged.

See Also addOnValueChanged, removeOnValueChanged


 ScrollBar.removeOnScroll

ScrollBar.removeOnScroll

Removes the delegate that is assigned to the scroll event.

Syntax

public void removeOnScroll( ScrollEventHandler seh )

Parameters

seh

The ScrollEventHandler delegate to be removed.

See Also addOnScroll


 ScrollBar.removeOnValueChanged

ScrollBar.removeOnValueChanged

Removes the delegate that is assigned to the valueChanged event.

Syntax

public void removeOnValueChanged( EventHandler eh )

Parameters

eh

The EventHandler delegate to be removed.

See Also addOnValueChanged


 ScrollBar.ScrollBar

ScrollBar.ScrollBar

Creates a scroll bar.

Syntax

public ScrollBar()

Remarks

Because the ScrollBar class is abstract, it cannot be instantiated. However, the constructor of a subclass should call super() to invoke this base constructor.


 ScrollBar.setLargeChange

ScrollBar.setLargeChange

Sets the increment between each large change of the scroll thumb.

Syntax

public void setLargeChange( int value )

Parameters

value

The new large change increment. The default value is 10.

Remarks

The large change value specifies the scroll increment when the user clicks on either side of the scroll thumb. This value is used to determine the size of the scroll thumb, relative to the range of the scroll bar.

Note When the user moves the thumb to its bottom-most or right-most position, the value of the scroll bar control is set to the maximium value minus the large change value plus one.

When you call setLargeChange at run time, the scroll bar control is automatically redrawn to reflect the new large change value.

See Also getLargeChange, setSmallChange


 ScrollBar.setMaximum

ScrollBar.setMaximum

Sets the maximum value of the scroll bar.

Syntax

public void setMaximum( int value )

Parameters

value

The new maximum value. The default value is 100.

Remarks

The maximum value represents the maximum scrolling position for the scroll bar. The values of the maximum and minimum properties determine the scroll bar's range. The value of the largeChange property is then used to determine the size of the scroll thumb, relative to the scrolling range.

When you call setMaximum at run time, the scroll bar control is automatically redrawn to reflect the new maximum value.

See Also getMaximum, setValue


 ScrollBar.setMinimum

ScrollBar.setMinimum

Sets the minimum possible value of the scroll bar.

Syntax

public void setMinimum( int value )

Parameters

value

The new minimum value. The default value is 0.

Remarks

The minimum value represents the minimum scrolling position for the scroll bar. The values of the maximum and minimum properties determine the scroll bar's range. The value of the largeChange property is then used to determine the size of the scroll thumb, relative to the scrolling range.

When you call setMinimum at run time, the scroll bar control is automatically redrawn to reflect the new minimum value.

See Also getMinimum, setValue


 ScrollBar.setSmallChange

ScrollBar.setSmallChange

Sets the increment between each small change of the scroll thumb.

Syntax

public void setSmallChange( int value )

Parameters

value

The new small change increment. The default value is 1.

Remarks

The small change value specifies the scroll increment when a scroll bar button is clicked.

See Also getSmallChange, setLargeChange


 ScrollBar.setValue

ScrollBar.setValue

Sets the value of the scroll bar.

Syntax

public void setValue( int value )

Parameters

value

The new value of the scroll bar.

Exceptions

WFCInvalidArgumentException thrown if value is less than the minimum value or greater than the maximum value.

Remarks

The value of the scroll bar represents the current position of the scroll thumb. When you call setValue at run time, the scroll bar control is automatically redrawn to reflect the new position.

Calling setValue triggers a valueChanged event; however, a scroll event is not generated.


ScrollBars Class

Defines constants that specify which scroll bars appear with a control.

Enum
  |
  +--ScrollBars

package com.ms.wfc.ui

public class ScrollBars
extends Enum


 ScrollBars Methods

ScrollBars Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 ScrollBars.valid

ScrollBars.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 ScrollBars Fields

ScrollBars Fields

Fields | Description
BOTH | Specifies that both horizontal and vertical scroll bars appear with the control.
HORIZONTAL | Specifies that only a horizontal scroll bar appears with the control.
NONE | Specifies that no scroll bars appear with the control.
VERTICAL | Specifies that only a vertical scroll bar appears with the control.


 ScrollBars.BOTH

ScrollBars.BOTH

Specifies that both horizontal and vertical scroll bars appear with the control.

Syntax

public static final int BOTH;


 ScrollBars.HORIZONTAL

ScrollBars.HORIZONTAL

Specifies that only a horizontal scroll bar appears with the control.

Syntax

public static final int HORIZONTAL;


 ScrollBars.NONE

ScrollBars.NONE

Specifies that no scroll bars appear with the control.

Syntax

public static final int NONE;


 ScrollBars.VERTICAL

ScrollBars.VERTICAL

Specifies that only a vertical scroll bar appears with the control.

Syntax

public static final int VERTICAL;


ScrollButton Class

Defines the constants that specify which scroll bar button is drawn.

Enum
  |
  +--ScrollButton

package com.ms.wfc.ui

public final class ScrollButton
extends Enum

Remarks

The constants in this class are used by the Graphics.drawScrollButton method to draw the buttons on a scroll bar.


 ScrollButton Methods

ScrollButton Methods

Methods | Description
valid | Determines whether the specified value is valid for this class.


 ScrollButton.valid

ScrollButton.valid

Determines whether the specified value is valid for this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 ScrollButton Fields

ScrollButton Fields

Fields | Description
DOWN | Specifies that a down arrow scroll bar button will be drawn.
LEFT | Specifies that a left arrow scroll bar button will be drawn.
RIGHT | Specifies that a right arrow scroll bar button will be drawn.
UP | Specifies that an up arrow scroll bar button will be drawn.


 ScrollButton.DOWN

ScrollButton.DOWN

Specifies that a down arrow scroll bar button will be drawn.

Syntax

public static final int DOWN;


 ScrollButton.LEFT

ScrollButton.LEFT

Specifies that a left arrow scroll bar button will be drawn.

Syntax

public static final int LEFT;


 ScrollButton.RIGHT

ScrollButton.RIGHT

Specifies that a right arrow scroll bar button will be drawn.

Syntax

public static final int RIGHT;


 ScrollButton.UP

ScrollButton.UP

Specifies that an up arrow scroll bar button will be drawn.

Syntax

public static final int UP;


ScrollEvent Class

Provides information about the scroll event of a scroll bar.

Event
  |
  +--ScrollEvent

package com.ms.wfc.ui

public class ScrollEvent
extends Event

Remarks

The scroll event occurs when the user changes the value of the scroll bar. This event can result from a variety of actions, such as clicking a scroll bar arrow or dragging the scroll thumb. A ScrollEvent object specifies the type of scroll event that occurred and the new value of the scroll bar.

For more information about the different types of scroll events, see ScrollEventType. For information about the WFC event model, see Handling Events in WFC.


 ScrollEvent Methods

ScrollEvent Methods

Constructors | Description
ScrollEvent | Creates a ScrollEvent object.


 ScrollEvent.ScrollEvent

ScrollEvent.ScrollEvent

Creates a ScrollEvent object.

Syntax

public ScrollEvent( int type, int newValue )

public ScrollEvent( Object extendedInfo, int type, int newValue )

Parameters

type

The type of scroll event that occurred. Set this parameter to one of the constants defined in the ScrollEventType class.

newValue

The new value of the scroll bar.

extendedInfo

Additional information supplied by com.ms.wfc.html events. You should not pass a value for this parameter outside the context of the com.ms.wfc.html package. For more information, see Event.extendedInfo and DhEventInfo.

Exceptions

WFCInvalidEnumException thrown if type is not a valid scroll event type.


 ScrollEvent Fields

ScrollEvent Fields

Fields | Description
newValue | Specifies the new value of the scroll bar.
type | Specifies the type of scroll event that occurred.


 ScrollEvent.newValue

ScrollEvent.newValue

Specifies the new value of the scroll bar.

Syntax

public final int newValue;

Remarks

The value of the scroll bar represents the position of the scroll thumb. When a scroll event occurs, the newValue field is automatically set to the proposed change in the scroll thumb. However, you can override this change by explicitly setting the value of this field in your event handler. For example:

private void myScrollBar_scroll(Object source, ScrollEvent e)
{
   /* If the user has dragged the scroll thumb, automatically
      reset the scroll thumb to the minimum position. */
   if (e.type == ScrollEventType.THUMB_POSITION)
      e.newValue = myScrollBar.getMinimum();

}

See Also type


 ScrollEvent.type

ScrollEvent.type

Specifies the type of scroll event that occurred.

Syntax

public final int type;

Remarks

This field can be set to one of the constants defined in the ScrollEventType class. For an example that shows how to check the value of this field in an event handler, see newValue.


ScrollEventHandler Delegate

Identifies the method that will handle the scroll event of a scroll bar control.

package com.ms.wfc.ui

public multicast delegate
void ScrollEventHandler( Object sender, ScrollEvent e );

Remarks

The syntax of the ScrollEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a ScrollEvent object that provides the event data.

When you create a ScrollEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC.


ScrollEventType Class

Defines the constants that specify the type of scroll event that occurred.

Enum
  |
  +--ScrollEventType

package com.ms.wfc.ui

public class ScrollEventType
extends Enum

Remarks

The scroll event occurs when the user changes the value of a scroll bar. This event can result from a variety of actions, such as clicking a scroll bar arrow or dragging the scroll thumb. Additionally, if the tabStop property of the scroll bar is set to true, keyboard actions (such as pressing the arrow keys) will trigger a scroll event when the scroll bar has focus.

When a scroll event occurs, the associated ScrollEvent object specifies the type of the scroll event and the proposed new value of the scroll bar control. Note that when the scroll thumb is moved to its bottom-most or right-most position, the new value is set to the maximum value minus the large change value plus one. (Note that you can override the new value by explicitly setting the newValue field of the ScrollEvent object in your event handler.)

For information about the WFC event model, see Handling Events in WFC.

See Also ScrollBar


 ScrollEventType Methods

ScrollEventType Methods

Methods | Description
valid | Determines whether the specified value is valid for this class.


 ScrollEventType.valid

ScrollEventType.valid

Determines whether the specified value is valid for this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 ScrollEventType Fields

ScrollEventType Fields

Fields | Description
ENDSCROLL | Specifies that the control has finished scrolling.
FIRST | Specifies that the HOME key was pressed to move the scroll thumb to the minimum value.
LARGE_DECREMENT | Specifies that the value of the scroll bar was decremented by a large change in the scroll thumb.
LARGE_INCREMENT | Specifies that the value of the scroll bar was incremented by a large change in the scroll thumb.
LAST | Specifies that the END key was pressed to move the scroll thumb to the maximum value.
SMALL_DECREMENT | Specifies that the value of the scroll bar was decremented by a small change in the scroll thumb.
SMALL_INCREMENT | Specifies that the value of the scroll bar was incremented by a small change in the scroll thumb.
THUMB_POSITION | Specifies that the user has dragged and released the scroll thumb.
THUMB_TRACK | Specifies that the user is currently dragging the scroll thumb.


 ScrollEventType.ENDSCROLL

ScrollEventType.ENDSCROLL

Specifies that the control has finished scrolling.

Syntax

public static final int ENDSCROLL;


 ScrollEventType.FIRST

ScrollEventType.FIRST

Specifies that the HOME key was pressed to move the scroll thumb to the minimum value.

Syntax

public static final int FIRST;

Remarks

In order for the scroll bar to accept keyboard input, it must have focus and its tabStop property must be set to true.


 ScrollEventType.LARGE_DECREMENT

ScrollEventType.LARGE_DECREMENT

Specifies that the value of the scroll bar was decremented by a large change in the scroll thumb.

Syntax

public static final int LARGE_DECREMENT;

Remarks

A scroll event of this type occurs when the user clicks above or to the left of the scroll thumb. Additionally, if the tabStop property of the scroll bar is set to true, this type of event occurs when the scroll bar has focus and the user presses the PAGE UP key.


 ScrollEventType.LARGE_INCREMENT

ScrollEventType.LARGE_INCREMENT

Specifies that the value of the scroll bar was incremented by a large change in the scroll thumb.

Syntax

public static final int LARGE_INCREMENT;

Remarks

A scroll event of this type occurs when the user clicks below or to the right of the scroll thumb. Additionally, if the tabStop property of the scroll bar is set to true, this type of event occurs when the scroll bar has focus and the user presses the PAGE DOWN key.


 ScrollEventType.LAST

ScrollEventType.LAST

Specifies that the END key was pressed to move the scroll thumb to the maximum value.

Syntax

public static final int LAST;

Remarks

In order for the scroll bar to accept keyboard input, it must have focus and its tabStop property must be set to true.


 ScrollEventType.SMALL_DECREMENT

ScrollEventType.SMALL_DECREMENT

Specifies that the value of the scroll bar was decremented by a small change in the scroll thumb.

Syntax

public static final int SMALL_DECREMENT;

Remarks

A scroll event of this type occurs when the user clicks the top or left scroll bar button. Additionally, if the tabStop property of the scroll bar is set to true, this type of event occurs when the scroll bar has focus and the user presses the up or left arrow keys.


 ScrollEventType.SMALL_INCREMENT

ScrollEventType.SMALL_INCREMENT

Specifies that the value of the scroll bar was incremented by a small change in the scroll thumb.

Syntax

public static final int SMALL_INCREMENT;

Remarks

A scroll event of this type occurs when the user clicks the bottom or right scroll bar button. Additionally, if the tabStop property of the scroll bar is set to true, this type of event occurs when the scroll bar has focus and the user presses the down or right arrow keys.


 ScrollEventType.THUMB_POSITION

ScrollEventType.THUMB_POSITION

Specifies that the user has dragged and released the scroll thumb.

Syntax

public static final int THUMB_POSITION;


 ScrollEventType.THUMB_TRACK

ScrollEventType.THUMB_TRACK

Specifies that the user is currently dragging the scroll thumb.

Syntax

public static final int THUMB_TRACK;


SelectionMode Class

Defines constants that specify how many items in a list a user can select at one time and how the user can make multiple selections.

Enum
  |
  +--SelectionMode

package com.ms.wfc.ui

public class SelectionMode
extends Enum


 SelectionMode Methods

SelectionMode Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 SelectionMode.valid

SelectionMode.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 SelectionMode Fields

SelectionMode Fields

Fields | Description
MULTI_EXTENDED | Specifies that more than one item at a time can be selected and that the user can use the SHIFT, CTRL, and arrow keys to make selections.
MULTI_SIMPLE | Specifies that more than one item at a time can be selected.
NONE | Specifies that no items can be selected.
ONE | Specifies that only one item at a time can be selected.


 SelectionMode.MULTI_EXTENDED

SelectionMode.MULTI_EXTENDED

Specifies that more than one item at a time can be selected and that the user can use the SHIFT, CTRL, and arrow keys to make selections.

Syntax

public static final int MULTI_EXTENDED;


 SelectionMode.MULTI_SIMPLE

SelectionMode.MULTI_SIMPLE

Specifies that more than one item at a time can be selected.

Syntax

public static final int MULTI_SIMPLE;


 SelectionMode.NONE

SelectionMode.NONE

Specifies that no items can be selected.

Syntax

public static final int NONE;


 SelectionMode.ONE

SelectionMode.ONE

Specifies that only one item at a time can be selected.

Syntax

public static final int ONE;


SelectionRange Class

Represents a date selection range in a MonthCalendar control.

package com.ms.wfc.ui

public class SelectionRange
implements IConstructable


 SelectionRange Methods

SelectionRange Methods

Constructors | Description
SelectionRange | Creates a SelectionRange object with the start and end of the range set to null.

Methods | Description
getEnd | Retrieves the end of the selection range.
getStart | Retrieves the start of the selection range.


 SelectionRange.getEnd

SelectionRange.getEnd

Retrieves the end of the selection range.

Syntax

public Time getEnd()

Return Value

Returns a Time object that represents the end of the selection range.


 SelectionRange.getStart

SelectionRange.getStart

Retrieves the start of the selection range.

Syntax

public Time getStart()

Return Value

Returns a Time object that represents the start of the selection range.


 SelectionRange.SelectionRange

SelectionRange.SelectionRange

Creates a SelectionRange object with the start and end of the range set to null.

Syntax

public SelectionRange()

public SelectionRange( Time lower, Time upper )

public SelectionRange( SelectionRange range )

Parameters

lower

A Time object that represents the start of the selection range.

upper

A Time object that represents the end of the selection range.

range

The existing SelectionRange object to base the new object on.


 SelectionRange Fields

SelectionRange Fields

Fields | Description
end | Specifies a Time object that represents the end of the selection range.
start | Specifies a Time object that represents the start of the selection range.


 SelectionRange.end

SelectionRange.end

Specifies a Time object that represents the end of the selection range.

Syntax

public Time end;


 SelectionRange.start

SelectionRange.start

Specifies a Time object that represents the start of the selection range.

Syntax

public Time start;


SelectionStyle Class

Defines constants that specify the borders a component can have when selected in the Forms Designer.

Enum
  |
  +--SelectionStyle

package com.ms.wfc.ui

public class SelectionStyle
extends Enum

Remarks

Setting the selection frame style for the component at design time can be a useful way to help the user distinguish between different selection modes (such as in-place editing mode and static design mode) supported by a component. However, changing the selection border style does not effect the behavior of a component in the designer. To modify the component's behavior in the Forms Designer, use the design-time hit-testing feature of the ICustomizer interface.

See Also ISelectionService


 SelectionStyle Methods

SelectionStyle Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 SelectionStyle.valid

SelectionStyle.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 SelectionStyle Fields

SelectionStyle Fields

Fields | Description
ACTIVE | Specifies an alternative selection border that typically indicates that a component is in editing mode.
SELECTED | Specifies the default selection border that typically indicates that a component is selected and can be dragged.


 SelectionStyle.ACTIVE

SelectionStyle.ACTIVE

Specifies an alternative selection border that typically indicates that a component is in editing mode.

Syntax

public static final int ACTIVE;

Remarks

When a component is in editing mode, clicking or dragging the component and the component edits the component itself but does not move the component.


 SelectionStyle.SELECTED

SelectionStyle.SELECTED

Specifies the default selection border that typically indicates that a component is selected and can be dragged.

Syntax

public static final int SELECTED;


Shortcut Class

Defines constants that specify shortcut keys that can be associated with menu items.

Enum
  |
  +--Shortcut

package com.ms.wfc.ui

public class Shortcut
extends Enum

Remarks

Values in this class are combinations of values from the Key class.


 Shortcut Fields

Shortcut Fields

Fields | Description
ALT_BKSP | Specifies the shortcut keys ALT+BACKSPACE.
CTRL_A | Specifies the shortcut keys CTRL+A.
CTRL_B | Specifies the shortcut keys CTRL+B.
CTRL_C | Specifies the shortcut keys CTRL+C.
CTRL_D | Specifies the shortcut keys CTRL+D.
CTRL_DEL | Specifies the shortcut keys CTRL+DELETE.
CTRL_E | Specifies the shortcut keys CTRL+E.
CTRL_F | Specifies the shortcut keys CTRL+F.
CTRL_F1 | Specifies the shortcut keys CTRL+F1.
CTRL_F11 | Specifies the shortcut keys CTRL+F11.
CTRL_F12 | Specifies the shortcut keys CTRL+F12.
CTRL_F2 | Specifies the shortcut keys CTRL+F2.
CTRL_F3 | Specifies the shortcut keys CTRL+F3.
CTRL_F4 | Specifies the shortcut keys CTRL+F4.
CTRL_F5 | Specifies the shortcut keys CTRL+F5.
CTRL_F6 | Specifies the shortcut keys CTRL+F6.
CTRL_F7 | Specifies the shortcut keys CTRL+F7.
CTRL_F8 | Specifies the shortcut keys CTRL+F8.
CTRL_F9 | Specifies the shortcut keys CTRL+F9.
CTRL_G | Specifies the shortcut keys CTRL+G.
CTRL_H | Specifies the shortcut keys CTRL+H.
CTRL_I | Specifies the shortcut keys CTRL+I.
CTRL_INS | Specifies the shortcut keys CTRL+INS.
CTRL_J | Specifies the shortcut keys CTRL+J.
CTRL_K | Specifies the shortcut keys CTRL+K.
CTRL_L | Specifies the shortcut keys CTRL+L.
CTRL_M | Specifies the shortcut keys CTRL+M.
CTRL_N | Specifies the shortcut keys CTRL+N.
CTRL_O | Specifies the shortcut keys CTRL+O.
CTRL_P | Specifies the shortcut keys CTRL+P.
CTRL_Q | Specifies the shortcut keys CTRL+Q.
CTRL_R | Specifies the shortcut keys CTRL+R.
CTRL_S | Specifies the shortcut keys CTRL+S.
CTRL_SHIFT_A | Specifies the shortcut keys CTRL+SHIFT+A.
CTRL_SHIFT_B | Specifies the shortcut keys CTRL+SHIFT+B.
CTRL_SHIFT_C | Specifies the shortcut keys CTRL+SHIFT+C.
CTRL_SHIFT_D | Specifies the shortcut keys CTRL+SHIFT+D.
CTRL_SHIFT_E | Specifies the shortcut keys CTRL+SHIFT+E.
CTRL_SHIFT_F | Specifies the shortcut keys CTRL+SHIFT+F.
CTRL_SHIFT_F1 | Specifies the shortcut keys CTRL+SHIFT+F1.
CTRL_SHIFT_F11 | Specifies the shortcut keys CTRL+SHIFT+F11.
CTRL_SHIFT_F12 | Specifies the shortcut keys CTRL+SHIFT+F12.
CTRL_SHIFT_F2 | Specifies the shortcut keys CTRL+SHIFT+F2.
CTRL_SHIFT_F3 | Specifies the shortcut keys CTRL+SHIFT+F3.
CTRL_SHIFT_F4 | Specifies the shortcut keys CTRL+SHIFT+F4.
CTRL_SHIFT_F5 | Specifies the shortcut keys CTRL+SHIFT+F5.
CTRL_SHIFT_F6 | Specifies the shortcut keys CTRL+SHIFT+F6.
CTRL_SHIFT_F7 | Specifies the shortcut keys CTRL+SHIFT+F7.
CTRL_SHIFT_F8 | Specifies the shortcut keys CTRL+SHIFT+F8.
CTRL_SHIFT_F9 | Specifies the shortcut keys CTRL+SHIFT+F9.
CTRL_SHIFT_G | Specifies the shortcut keys CTRL+SHIFT+G.
CTRL_SHIFT_H | Specifies the shortcut keys CTRL+SHIFT+H.
CTRL_SHIFT_I | Specifies the shortcut keys CTRL+SHIFT+I.
CTRL_SHIFT_J | Specifies the shortcut keys CTRL+SHIFT+J.
CTRL_SHIFT_K | Specifies the shortcut keys CTRL+SHIFT+K.
CTRL_SHIFT_L | Specifies the shortcut keys CTRL+SHIFT+L.
CTRL_SHIFT_M | Specifies the shortcut keys CTRL+SHIFT+M.
CTRL_SHIFT_N | Specifies the shortcut keys CTRL+SHIFT+N.
CTRL_SHIFT_O | Specifies the shortcut keys CTRL+SHIFT+O.
CTRL_SHIFT_P | Specifies the shortcut keys CTRL+SHIFT+P.
CTRL_SHIFT_Q | Specifies the shortcut keys CTRL+SHIFT+Q.
CTRL_SHIFT_R | Specifies the shortcut keys CTRL+SHIFT+R.
CTRL_SHIFT_S | Specifies the shortcut keys CTRL+SHIFT+S.
CTRL_SHIFT_T | Specifies the shortcut keys CTRL+SHIFT+T.
CTRL_SHIFT_U | Specifies the shortcut keys CTRL+SHIFT+U.
CTRL_SHIFT_V | Specifies the shortcut keys CTRL+SHIFT+V.
CTRL_SHIFT_W | Specifies the shortcut keys CTRL+SHIFT+W.
CTRL_SHIFT_X | Specifies the shortcut keys CTRL+SHIFT+X.
CTRL_SHIFT_Y | Specifies the shortcut keys CTRL+SHIFT+Y.
CTRL_SHIFT_Z | Specifies the shortcut keys CTRL+SHIFT+Z.
CTRL_T | Specifies the shortcut keys CTRL+T.
CTRL_U | Specifies the shortcut keys CTRL+U.
CTRL_V | Specifies the shortcut keys CTRL+V.
CTRL_W | Specifies the shortcut keys CTRL+W.
CTRL_X | Specifies the shortcut keys CTRL+X.
CTRL_Y | Specifies the shortcut keys CTRL+Y.
CTRL_Z | Specifies the shortcut keys CTRL+Z.
DEL | Specifies the shortcut key DELETE.
F1 | Specifies the shortcut key F1.
F11 | Specifies the shortcut key F11.
F12 | Specifies the shortcut key F12.
F2 | Specifies the shortcut key F2.
F3 | Specifies the shortcut key F3.
F4 | Specifies the shortcut key F4.
F5 | Specifies the shortcut key F5.
F6 | Specifies the shortcut key F6.
F7 | Specifies the shortcut key F7.
F8 | Specifies the shortcut key F8.
F9 | Specifies the shortcut key F9.
INS | Specifies the shortcut key INS.
NONE | Specifies that there is no shortcut key associated with the menu item.
SHIFT_DEL | Specifies the shortcut keys SHIFT+DELETE.
SHIFT_F1 | Specifies the shortcut keys SHIFT+F1.
SHIFT_F11 | Specifies the shortcut keys SHIFT+F11.
SHIFT_F12 | Specifies the shortcut keys SHIFT+F12.
SHIFT_F2 | Specifies the shortcut keys SHIFT+F2.
SHIFT_F3 | Specifies the shortcut keys SHIFT+F3.
SHIFT_F4 | Specifies the shortcut keys SHIFT+F4.
SHIFT_F5 | Specifies the shortcut keys SHIFT+F5.
SHIFT_F6 | Specifies the shortcut keys SHIFT+F6.
SHIFT_F7 | Specifies the shortcut keys SHIFT+F7.
SHIFT_F8 | Specifies the shortcut keys SHIFT+F8.
SHIFT_F9 | Specifies the shortcut keys SHIFT+F9.
SHIFT_INS | Specifies the shortcut keys SHIFT+INS.


 Shortcut.ALT_BKSP

Shortcut.ALT_BKSP

Specifies the shortcut keys ALT+BACKSPACE.

Syntax

public static final int ALT_BKSP;


 Shortcut.CTRL_A

Shortcut.CTRL_A

Specifies the shortcut keys CTRL+A.

Syntax

public static final int CTRL_A;


 Shortcut.CTRL_B

Shortcut.CTRL_B

Specifies the shortcut keys CTRL+B.

Syntax

public static final int CTRL_B;


 Shortcut.CTRL_C

Shortcut.CTRL_C

Specifies the shortcut keys CTRL+C.

Syntax

public static final int CTRL_C;


 Shortcut.CTRL_D

Shortcut.CTRL_D

Specifies the shortcut keys CTRL+D.

Syntax

public static final int CTRL_D;


 Shortcut.CTRL_DEL

Shortcut.CTRL_DEL

Specifies the shortcut keys CTRL+DELETE.

Syntax

public static final int CTRL_D;


 Shortcut.CTRL_E

Shortcut.CTRL_E

Specifies the shortcut keys CTRL+E.

Syntax

public static final int CTRL_E;


 Shortcut.CTRL_F

Shortcut.CTRL_F

Specifies the shortcut keys CTRL+F.

Syntax

public static final int CTRL_F;


 Shortcut.CTRL_F1

Shortcut.CTRL_F1

Specifies the shortcut keys CTRL+F1.

Syntax

public static final int CTRL_F1;


 Shortcut.CTRL_F11

Shortcut.CTRL_F11

Specifies the shortcut keys CTRL+F11.

Syntax

public static final int CTRL_F11;


 Shortcut.CTRL_F12

Shortcut.CTRL_F12

Specifies the shortcut keys CTRL+F12.

Syntax

public static final int CTRL_F12;


 Shortcut.CTRL_F2

Shortcut.CTRL_F2

Specifies the shortcut keys CTRL+F2.

Syntax

public static final int CTRL_F2;


 Shortcut.CTRL_F3

Shortcut.CTRL_F3

Specifies the shortcut keys CTRL+F3.

Syntax

public static final int CTRL_F3;


 Shortcut.CTRL_F4

Shortcut.CTRL_F4

Specifies the shortcut keys CTRL+F4.

Syntax

public static final int CTRL_F4;


 Shortcut.CTRL_F5

Shortcut.CTRL_F5

Specifies the shortcut keys CTRL+F5.

Syntax

public static final int CTRL_F5;


 Shortcut.CTRL_F6

Shortcut.CTRL_F6

Specifies the shortcut keys CTRL+F6.

Syntax

public static final int CTRL_F6;


 Shortcut.CTRL_F7

Shortcut.CTRL_F7

Specifies the shortcut keys CTRL+F7.

Syntax

public static final int CTRL_F7;


 Shortcut.CTRL_F8

Shortcut.CTRL_F8

Specifies the shortcut keys CTRL+F8.

Syntax

public static final int CTRL_F8;


 Shortcut.CTRL_F9

Shortcut.CTRL_F9

Specifies the shortcut keys CTRL+F9.

Syntax

public static final int CTRL_F9;


 Shortcut.CTRL_G

Shortcut.CTRL_G

Specifies the shortcut keys CTRL+G.

Syntax

public static final int CTRL_G;


 Shortcut.CTRL_H

Shortcut.CTRL_H

Specifies the shortcut keys CTRL+H.

Syntax

public static final int CTRL_H;


 Shortcut.CTRL_I

Shortcut.CTRL_I

Specifies the shortcut keys CTRL+I.

Syntax

public static final int CTRL_I;


 Shortcut.CTRL_INS

Shortcut.CTRL_INS

Specifies the shortcut keys CTRL+INS.

Syntax

public static final int CTRL_INS;


 Shortcut.CTRL_J

Shortcut.CTRL_J

Specifies the shortcut keys CTRL+J.

Syntax

public static final int CTRL_J;


 Shortcut.CTRL_K

Shortcut.CTRL_K

Specifies the shortcut keys CTRL+K.

Syntax

public static final int CTRL_K;


 Shortcut.CTRL_L

Shortcut.CTRL_L

Specifies the shortcut keys CTRL+L.

Syntax

public static final int CTRL_L;


 Shortcut.CTRL_M

Shortcut.CTRL_M

Specifies the shortcut keys CTRL+M.

Syntax

public static final int CTRL_M;


 Shortcut.CTRL_N

Shortcut.CTRL_N

Specifies the shortcut keys CTRL+N.

Syntax

public static final int CTRL_N;


 Shortcut.CTRL_O

Shortcut.CTRL_O

Specifies the shortcut keys CTRL+O.

Syntax

public static final int CTRL_O;


 Shortcut.CTRL_P

Shortcut.CTRL_P

Specifies the shortcut keys CTRL+P.

Syntax

public static final int CTRL_P;


 Shortcut.CTRL_Q

Shortcut.CTRL_Q

Specifies the shortcut keys CTRL+Q.

Syntax

public static final int CTRL_Q;


 Shortcut.CTRL_R

Shortcut.CTRL_R

Specifies the shortcut keys CTRL+R.

Syntax

public static final int CTRL_R;


 Shortcut.CTRL_S

Shortcut.CTRL_S

Specifies the shortcut keys CTRL+S.

Syntax

public static final int CTRL_S;


 Shortcut.CTRL_SHIFT_A

Shortcut.CTRL_SHIFT_A

Specifies the shortcut keys CTRL+SHIFT+A.

Syntax

public static final int CTRL_SHIFT_A;


 Shortcut.CTRL_SHIFT_B

Shortcut.CTRL_SHIFT_B

Specifies the shortcut keys CTRL+SHIFT+B.

Syntax

public static final int CTRL_SHIFT_B;


 Shortcut.CTRL_SHIFT_C

Shortcut.CTRL_SHIFT_C

Specifies the shortcut keys CTRL+SHIFT+C.

Syntax

public static final int CTRL_SHIFT_C;


 Shortcut.CTRL_SHIFT_D

Shortcut.CTRL_SHIFT_D

Specifies the shortcut keys CTRL+SHIFT+D.

Syntax

public static final int CTRL_SHIFT_D;


 Shortcut.CTRL_SHIFT_E

Shortcut.CTRL_SHIFT_E

Specifies the shortcut keys CTRL+SHIFT+E.

Syntax

public static final int CTRL_SHIFT_E;


 Shortcut.CTRL_SHIFT_F

Shortcut.CTRL_SHIFT_F

Specifies the shortcut keys CTRL+SHIFT+F.

Syntax

public static final int CTRL_SHIFT_F;


 Shortcut.CTRL_SHIFT_F1

Shortcut.CTRL_SHIFT_F1

Specifies the shortcut keys CTRL+SHIFT+F1.

Syntax

public static final int CTRL_SHIFT_F1;


 Shortcut.CTRL_SHIFT_F11

Shortcut.CTRL_SHIFT_F11

Specifies the shortcut keys CTRL+SHIFT+F11.

Syntax

public static final int CTRL_SHIFT_F11;


 Shortcut.CTRL_SHIFT_F12

Shortcut.CTRL_SHIFT_F12

Specifies the shortcut keys CTRL+SHIFT+F12.

Syntax

public static final int CTRL_SHIFT_F12;


 Shortcut.CTRL_SHIFT_F2

Shortcut.CTRL_SHIFT_F2

Specifies the shortcut keys CTRL+SHIFT+F2.

Syntax

public static final int CTRL_SHIFT_F2;


 Shortcut.CTRL_SHIFT_F3

Shortcut.CTRL_SHIFT_F3

Specifies the shortcut keys CTRL+SHIFT+F3.

Syntax

public static final int CTRL_SHIFT_F3;


 Shortcut.CTRL_SHIFT_F4

Shortcut.CTRL_SHIFT_F4

Specifies the shortcut keys CTRL+SHIFT+F4.

Syntax

public static final int CTRL_SHIFT_F4;


 Shortcut.CTRL_SHIFT_F5

Shortcut.CTRL_SHIFT_F5

Specifies the shortcut keys CTRL+SHIFT+F5.

Syntax

public static final int CTRL_SHIFT_F5;


 Shortcut.CTRL_SHIFT_F6

Shortcut.CTRL_SHIFT_F6

Specifies the shortcut keys CTRL+SHIFT+F6.

Syntax

public static final int CTRL_SHIFT_F6;


 Shortcut.CTRL_SHIFT_F7

Shortcut.CTRL_SHIFT_F7

Specifies the shortcut keys CTRL+SHIFT+F7.

Syntax

public static final int CTRL_SHIFT_F7;


 Shortcut.CTRL_SHIFT_F8

Shortcut.CTRL_SHIFT_F8

Specifies the shortcut keys CTRL+SHIFT+F8.

Syntax

public static final int CTRL_SHIFT_F8;


 Shortcut.CTRL_SHIFT_F9

Shortcut.CTRL_SHIFT_F9

Specifies the shortcut keys CTRL+SHIFT+F9.

Syntax

public static final int CTRL_SHIFT_F9;


 Shortcut.CTRL_SHIFT_G

Shortcut.CTRL_SHIFT_G

Specifies the shortcut keys CTRL+SHIFT+G.

Syntax

public static final int CTRL_SHIFT_G;


 Shortcut.CTRL_SHIFT_H

Shortcut.CTRL_SHIFT_H

Specifies the shortcut keys CTRL+SHIFT+H.

Syntax

public static final int CTRL_SHIFT_H;


 Shortcut.CTRL_SHIFT_I

Shortcut.CTRL_SHIFT_I

Specifies the shortcut keys CTRL+SHIFT+I.

Syntax

public static final int CTRL_SHIFT_I;


 Shortcut.CTRL_SHIFT_J

Shortcut.CTRL_SHIFT_J

Specifies the shortcut keys CTRL+SHIFT+J.

Syntax

public static final int CTRL_SHIFT_J;


 Shortcut.CTRL_SHIFT_K

Shortcut.CTRL_SHIFT_K

Specifies the shortcut keys CTRL+SHIFT+K.

Syntax

public static final int CTRL_SHIFT_K;


 Shortcut.CTRL_SHIFT_L

Shortcut.CTRL_SHIFT_L

Specifies the shortcut keys CTRL+SHIFT+L.

Syntax

public static final int CTRL_SHIFT_L;


 Shortcut.CTRL_SHIFT_M

Shortcut.CTRL_SHIFT_M

Specifies the shortcut keys CTRL+SHIFT+M.

Syntax

public static final int CTRL_SHIFT_M;


 Shortcut.CTRL_SHIFT_N

Shortcut.CTRL_SHIFT_N

Specifies the shortcut keys CTRL+SHIFT+N.

Syntax

public static final int CTRL_SHIFT_N;


 Shortcut.CTRL_SHIFT_O

Shortcut.CTRL_SHIFT_O

Specifies the shortcut keys CTRL+SHIFT+O.

Syntax

public static final int CTRL_SHIFT_O;


 Shortcut.CTRL_SHIFT_P

Shortcut.CTRL_SHIFT_P

Specifies the shortcut keys CTRL+SHIFT+P.

Syntax

public static final int CTRL_SHIFT_P;


 Shortcut.CTRL_SHIFT_Q

Shortcut.CTRL_SHIFT_Q

Specifies the shortcut keys CTRL+SHIFT+Q.

Syntax

public static final int CTRL_SHIFT_Q;


 Shortcut.CTRL_SHIFT_R

Shortcut.CTRL_SHIFT_R

Specifies the shortcut keys CTRL+SHIFT+R.

Syntax

public static final int CTRL_SHIFT_R;


 Shortcut.CTRL_SHIFT_S

Shortcut.CTRL_SHIFT_S

Specifies the shortcut keys CTRL+SHIFT+S.

Syntax

public static final int CTRL_SHIFT_S;


 Shortcut.CTRL_SHIFT_T

Shortcut.CTRL_SHIFT_T

Specifies the shortcut keys CTRL+SHIFT+T.

Syntax

public static final int CTRL_SHIFT_T;


 Shortcut.CTRL_SHIFT_U

Shortcut.CTRL_SHIFT_U

Specifies the shortcut keys CTRL+SHIFT+U.

Syntax

public static final int CTRL_SHIFT_U;


 Shortcut.CTRL_SHIFT_V

Shortcut.CTRL_SHIFT_V

Specifies the shortcut keys CTRL+SHIFT+V.

Syntax

public static final int CTRL_SHIFT_V;


 Shortcut.CTRL_SHIFT_W

Shortcut.CTRL_SHIFT_W

Specifies the shortcut keys CTRL+SHIFT+W.

Syntax

public static final int CTRL_SHIFT_W;


 Shortcut.CTRL_SHIFT_X

Shortcut.CTRL_SHIFT_X

Specifies the shortcut keys CTRL+SHIFT+X.

Syntax

public static final int CTRL_SHIFT_X;


 Shortcut.CTRL_SHIFT_Y

Shortcut.CTRL_SHIFT_Y

Specifies the shortcut keys CTRL+SHIFT+Y.

Syntax

public static final int CTRL_SHIFT_Y;


 Shortcut.CTRL_SHIFT_Z

Shortcut.CTRL_SHIFT_Z

Specifies the shortcut keys CTRL+SHIFT+Z.

Syntax

public static final int CTRL_SHIFT_Z;


 Shortcut.CTRL_T

Shortcut.CTRL_T

Specifies the shortcut keys CTRL+T.

Syntax

public static final int CTRL_T;


 Shortcut.CTRL_U

Shortcut.CTRL_U

Specifies the shortcut keys CTRL+U.

Syntax

public static final int CTRL_U;


 Shortcut.CTRL_V

Shortcut.CTRL_V

Specifies the shortcut keys CTRL+V.

Syntax

public static final int CTRL_V;


 Shortcut.CTRL_W

Shortcut.CTRL_W

Specifies the shortcut keys CTRL+W.

Syntax

public static final int CTRL_W;


 Shortcut.CTRL_X

Shortcut.CTRL_X

Specifies the shortcut keys CTRL+X.

Syntax

public static final int CTRL_X;


 Shortcut.CTRL_Y

Shortcut.CTRL_Y

Specifies the shortcut keys CTRL+Y.

Syntax

public static final int CTRL_Y;


 Shortcut.CTRL_Z

Shortcut.CTRL_Z

Specifies the shortcut keys CTRL+Z.

Syntax

public static final int CTRL_Z;


 Shortcut.DEL

Shortcut.DEL

Specifies the shortcut key DELETE.

Syntax

public static final int DEL;


 Shortcut.F1

Shortcut.F1

Specifies the shortcut key F1.

Syntax

public static final int F1;


 Shortcut.F11

Shortcut.F11

Specifies the shortcut key F11.

Syntax

public static final int F11;


 Shortcut.F12

Shortcut.F12

Specifies the shortcut key F12.

Syntax

public static final int F12;


 Shortcut.F2

Shortcut.F2

Specifies the shortcut key F2.

Syntax

public static final int F2;


 Shortcut.F3

Shortcut.F3

Specifies the shortcut key F3.

Syntax

public static final int F3;


 Shortcut.F4

Shortcut.F4

Specifies the shortcut key F4.

Syntax

public static final int F4;


 Shortcut.F5

Shortcut.F5

Specifies the shortcut key F5.

Syntax

public static final int F5;


 Shortcut.F6

Shortcut.F6

Specifies the shortcut key F6.

Syntax

public static final int F6;


 Shortcut.F7

Shortcut.F7

Specifies the shortcut key F7.

Syntax

public static final int F7;


 Shortcut.F8

Shortcut.F8

Specifies the shortcut key F8.

Syntax

public static final int F8;


 Shortcut.F9

Shortcut.F9

Specifies the shortcut key F9.

Syntax

public static final int F9;


 Shortcut.INS

Shortcut.INS

Specifies the shortcut key INS.

Syntax

public static final int INS;


 Shortcut.NONE

Shortcut.NONE

Specifies that there is no shortcut key associated with the menu item.

Syntax

public static final int NONE;


 Shortcut.SHIFT_DEL

Shortcut.SHIFT_DEL

Specifies the shortcut keys SHIFT+DELETE.

Syntax

public static final int SHIFT_DEL;


 Shortcut.SHIFT_F1

Shortcut.SHIFT_F1

Specifies the shortcut keys SHIFT+F1.

Syntax

public static final int SHIFT_F1;


 Shortcut.SHIFT_F11

Shortcut.SHIFT_F11

Specifies the shortcut keys SHIFT+F11.

Syntax

public static final int SHIFT_F11;


 Shortcut.SHIFT_F12

Shortcut.SHIFT_F12

Specifies the shortcut keys SHIFT+F12.

Syntax

public static final int SHIFT_F12;


 Shortcut.SHIFT_F2

Shortcut.SHIFT_F2

Specifies the shortcut keys SHIFT+F2.

Syntax

public static final int SHIFT_F2;


 Shortcut.SHIFT_F3

Shortcut.SHIFT_F3

Specifies the shortcut keys SHIFT+F3.

Syntax

public static final int SHIFT_F3;


 Shortcut.SHIFT_F4

Shortcut.SHIFT_F4

Specifies the shortcut keys SHIFT+F4.

Syntax

public static final int SHIFT_F4;


 Shortcut.SHIFT_F5

Shortcut.SHIFT_F5

Specifies the shortcut keys SHIFT+F5.

Syntax

public static final int SHIFT_F5;


 Shortcut.SHIFT_F6

Shortcut.SHIFT_F6

Specifies the shortcut keys SHIFT+F6.

Syntax

public static final int SHIFT_F6;


 Shortcut.SHIFT_F7

Shortcut.SHIFT_F7

Specifies the shortcut keys SHIFT+F7.

Syntax

public static final int SHIFT_F7;


 Shortcut.SHIFT_F8

Shortcut.SHIFT_F8

Specifies the shortcut keys SHIFT+F8.

Syntax

public static final int SHIFT_F8;


 Shortcut.SHIFT_F9

Shortcut.SHIFT_F9

Specifies the shortcut keys SHIFT+F9.

Syntax

public static final int SHIFT_F9;


 Shortcut.SHIFT_INS

Shortcut.SHIFT_INS

Specifies the shortcut keys SHIFT+INS.

Syntax

public static final int SHIFT_INS;


SortOrder Class

Defines constants that specify how items in a list are sorted.

Enum
  |
  +--SortOrder

package com.ms.wfc.ui

public class SortOrder
extends Enum


 SortOrder Methods

SortOrder Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 SortOrder.valid

SortOrder.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 SortOrder Fields

SortOrder Fields

Fields | Description
ASCENDING | Specifies that the items are sorted in ascending order.
DESCENDING | Specifies that the items are sorted in descending order.
NONE | Specifies that the items are not sorted.


 SortOrder.ASCENDING

SortOrder.ASCENDING

Specifies that the items are sorted in ascending order.

Syntax

public static final int ASCENDING;


 SortOrder.DESCENDING

SortOrder.DESCENDING

Specifies that the items are sorted in descending order.

Syntax

public static final int DESCENDING;


 SortOrder.NONE

SortOrder.NONE

Specifies that the items are not sorted.

Syntax

public static final int NONE;


Splitter Class

Encapsulates the splitter control, which allows the user to resize docked controls at run time.

Component
  |
  +--Control
    |
    +--Splitter

package com.ms.wfc.ui

public class Splitter
extends Control
implements IMessageFilter

Remarks

When the user passes the mouse pointer over the undocked edge of a control that can be resized by a splitter, the cursor changes to indicate that the control can be resized. The splitter allows the user to resize the docked control that is immediately before it in the docking order. Therefore, to enable the user to resize a docked control at run time, dock the control you want the user to be able to resize to an edge of a container, and then dock a splitter to the same side of that container.


 Splitter Methods

Splitter Methods

Constructors | Description
Splitter | Creates Splitter control.

Methods | Description
addOnSplitterMoved | Assigns a delegate to the splitterMoved event.
addOnSplitterMoving | Assigns a delegate to the splitterMoving event.
getMinExtra | Retrieves the minimum distance that must remain between the splitter and the edge of the opposite side of the container (or the closest control docked to that side).
getMinSize | Retrieves the minimum distance that must remain between the splitter and the container edge that the control is docked to.
onSplitterMoved | Triggers the splitterMoved event.
onSplitterMoving | Triggers the splitterMoving event.
removeOnSplitterMoved | Removes the delegate that is assigned to the splitterMoved event.
removeOnSplitterMoving | Removes the delegate that is assigned to the splitterMoving event.
setMinExtra | Sets the minimum distance that must remain between the splitter and the edge of the opposite side of the container (or the closest control docked to that side).
setMinSize | Sets the minimum distance that must remain between the splitter and the container edge that the control is docked to.
setSplitPosition | Sets the distance between the splitter and the container edge that the control is docked to.


 Splitter.addOnSplitterMoved

Splitter.addOnSplitterMoved

Assigns a delegate to the splitterMoved event.

Syntax

public void addOnSplitterMoved( SplitterEventHandler handler )

Parameters

handler

The SplitterEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the splitterMoved event to that method in the Properties window. The splitterMoved event occurs when the user finishes moving the splitter.

See Also removeOnSplitterMoved


 Splitter.addOnSplitterMoving

Splitter.addOnSplitterMoving

Assigns a delegate to the splitterMoving event.

Syntax

public void addOnSplitterMoving( SplitterEventHandler handler )

Parameters

handler

The SplitterEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the splitterMoving event to that method in the Properties window. The splitterMoving event occurs when the user is moving the splitter.

See Also removeOnSplitterMoving


 Splitter.getMinExtra

Splitter.getMinExtra

Retrieves the minimum distance that must remain between the splitter and the edge of the opposite side of the container (or the closest control docked to that side).

Syntax

public int getMinExtra()

Return Value

Returns the minimum distance, in pixels, that must remain between the splitter and the edge of the opposite side of the container (or the closest control docked to that side). For a horizontal splitter (a splitter docked to the top or bottom of a container), the minimum height of the area of the container reserved for undocked controls is this value minus the height of the splitter. For a vertical splitter (a splitter docked to the left or right of a container), the minimum width of the area of the container reserved for undocked controls is this value minus the width of the splitter. The user cannot move the splitter past the limit specified by this value.

See Also setMinExtra


 Splitter.getMinSize

Splitter.getMinSize

Retrieves the minimum distance that must remain between the splitter and the container edge that the control is docked to.

Syntax

public int getMinSize()

Return Value

Returns the minimum distance, in pixels, that must remain between the splitter and the container edge that the control is docked to. For a horizontal splitter (a splitter docked to the top or bottom of a container), this value is the minimum height of the resizable control. For a vertical splitter (a splitter docked to the left or right of a container), this value is the minimum width of the resizable control. The user cannot move the splitter past the limit specified by this value.

See Also setMinSize


 Splitter.onSplitterMoved

Splitter.onSplitterMoved

Triggers the splitterMoved event.

Syntax

protected void onSplitterMoved( SplitterEvent event )

Parameters

event

A SplitterEvent object that provides the event data.

Remarks

When overriding this method, call super.onSplitterMoved.

See Also addOnSplitterMoved


 Splitter.onSplitterMoving

Splitter.onSplitterMoving

Triggers the splitterMoving event.

Syntax

protected void onSplitterMoving( SplitterEvent event )

Parameters

event

A SplitterEvent object that provides the event data.

Remarks

When overriding this method, call super.onSplitterMoving.

See Also addOnSplitterMoving


 Splitter.removeOnSplitterMoved

Splitter.removeOnSplitterMoved

Removes the delegate that is assigned to the splitterMoved event.

Syntax

public void removeOnSplitterMoved( SplitterEventHandler handler )

Parameters

handler

The SplitterEventHandler delegate to be removed.

See Also addOnSplitterMoved


 Splitter.removeOnSplitterMoving

Splitter.removeOnSplitterMoving

Removes the delegate that is assigned to the splitterMoving event.

Syntax

public void removeOnSplitterMoving( SplitterEventHandler handler )

Parameters

handler

The SplitterEventHandler delegate to be removed.

See Also addOnSplitterMoving


 Splitter.setMinExtra

Splitter.setMinExtra

Sets the minimum distance that must remain between the splitter and the edge of the opposite side of the container (or the closest control docked to that side).

Syntax

public void setMinExtra( int value )

Parameters

value

The minimum distance, in pixels, that must remain between the splitter and the edge of the opposite side of the container (or the closest control docked to that side). For a horizontal splitter (a splitter docked to the top or bottom of a container), the minimum height of the area of the container reserved for undocked controls is this value minus the height of the splitter. For a vertical splitter (a splitter docked to the left or right of a container), the minimum width of the area of the container reserved for undocked controls is this value minus the width of the splitter. The user cannot move the splitter past the limit specified by this value. The default value is 25.

See Also getMinExtra


 Splitter.setMinSize

Splitter.setMinSize

Sets the minimum distance that must remain between the splitter and the container edge that the control is docked to.

Syntax

public void setMinSize( int value )

Parameters

value

The minimum distance, in pixels, that must remain between the splitter and the container edge that the control is docked to. For a horizontal splitter (a splitter docked to the top or bottom of a container), this value is the minimum height of the resizable control. For a vertical splitter (a splitter docked to the left or right of a container), this value is the minimum width of the resizable control. The user cannot move the splitter past the limit specified by this value. The default value is 25.

See Also getMinSize


 Splitter.setSplitPosition

Splitter.setSplitPosition

Sets the distance between the splitter and the container edge that the control is docked to.

Syntax

public void setSplitPosition( int split )

Parameters

split

The distance, in pixels, between the splitter and the container edge that the control is docked to. For a horizontal splitter (a splitter docked to the top or bottom of a container), this value is the height of the resizable control. For a vertical splitter (a splitter docked to the left or right of a container), this value is the width of the resizable control.


 Splitter.Splitter

Splitter.Splitter

Creates Splitter control.

Syntax

public Splitter()


SplitterEvent Class

Provides data for the splitterMoved and splitterMoving events of a Splitter control.

Event
  |
  +--SplitterEvent

package com.ms.wfc.ui

public class SplitterEvent
extends Event

Remarks

The splitterMoved event occurs when the user finishes moving the splitter. The splitterMoving event occurs when the user is moving the splitter. A SplitterEvent object specifies the position of the mouse pointer and the position of the upper-left corner of the splitter.


 SplitterEvent Methods

SplitterEvent Methods

Constructors | Description
SplitterEvent | Creates a SplitterEvent object.


 SplitterEvent.SplitterEvent

SplitterEvent.SplitterEvent

Creates a SplitterEvent object.

Syntax

public SplitterEvent( int x, int y, int splitX, int splitY )

Parameters

x

The x-coordinate of the mouse pointer (in client coordinates).

y

The y-coordinate of the mouse pointer (in client coordinates).

splitX

The x-coordinate of the upper-left corner of the splitter (in client coordinates).

splitY

The y-coordinate of the upper-left corner of the splitter (in client coordinates).


 SplitterEvent Fields

SplitterEvent Fields

Fields | Description
splitX | Specifies the x-coordinate of the upper-left corner of the splitter (in client coordinates).
splitY | Specifies the y-coordinate of the upper-left corner of the splitter (in client coordinates).
x | Specifies the x-coordinate of the mouse pointer (in client coordinates).
y | Specifies the y-coordinate of the mouse pointer (in client coordinates).


 SplitterEvent.splitX

SplitterEvent.splitX

Specifies the x-coordinate of the upper-left corner of the splitter (in client coordinates).

Syntax

public int splitX;


 SplitterEvent.splitY

SplitterEvent.splitY

Specifies the y-coordinate of the upper-left corner of the splitter (in client coordinates).

Syntax

public int splitY;


 SplitterEvent.x

SplitterEvent.x

Specifies the x-coordinate of the mouse pointer (in client coordinates).

Syntax

public final int x;


 SplitterEvent.y

SplitterEvent.y

Specifies the y-coordinate of the mouse pointer (in client coordinates).

Syntax

public final int y;


SplitterEventHandler Delegate

Identifies the method that will handle the splitterMoved and splitterMoving events of a Splitter control.

package com.ms.wfc.ui

public multicast delegate
void SplitterEventHandler( Object sender, SplitterEvent e );

Remarks

The syntax of the SplitterEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a SplitterEvent object that provides the event data.

When you create a SplitterEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered. For more information about delegates, see Handling Events in WFC.


StatusBar Class

Encapsulates the Windows status bar control.

Component
  |
  +--Control
    |
    +--StatusBar

package com.ms.wfc.ui

public class StatusBar
extends Control

Remarks

A status bar is an area, usually displayed at the bottom of a window, in which an application can display various kinds of status information. To display a single message on the status bar, set the showPanels property to false (the default), and set the text property of the status bar to the text you want to appear in the status bar. To divide the status bar into panels to display more than one type of information, set the showPanels property to true and use the addPanel method.


 StatusBar Methods

StatusBar Methods

Constructors | Description
StatusBar | Creates a StatusBar control.

Methods | Description
addOnDrawItem | Assigns a delegate to the drawItem event.
addOnPanelClick | Assigns a delegate to the panelClick event.
addPanel | Adds a panel to the end of the status bar.
getPanels | Retrieves all the panels that have been added to the status bar.
getShowPanels | Retrieves a boolean value indicating whether the status bar displays any panels that have been added to it using the addPanel method or whether the status bar displays a single line of text.
getSizingGrip | Retrieves a boolean value indicating whether the status bar has a sizing grip on its right side, which the user can drag to resize the status bar.
getStatusBarPanel | Retrieves the specified panel on the status bar.
insertPanel | Inserts a panel into the status bar at the specified location.
onDrawItem | Triggers the drawItem event.
onMouseDown | Triggers the mouseDown event.
onPanelClick | Triggers the panelClick event.
removeAllPanels | Removes all panels from the status bar.
removeOnDrawItem | Removes the delegate that is assigned to the drawItem event.
removeOnPanelClick | Removes the delegate that is assigned to the panelClick event.
removePanel | Removes the specified panel from the status bar.
setPanel | Replaces the panel at the specified position with a new panel.
setPanels | Removes all existing panels from the status bar and adds a set of new panels.
setShowPanels | Sets a boolean value indicating whether the status bar displays any panels that have been added to it using the addPanel method or whether the status bar displays a single line of text.
setSizingGrip | Sets a boolean value indicating whether the status bar has a sizing grip on its right side, which the user can drag to resize the status bar.
setText | Sets the text that will appear on the status bar when the showPanels property of the status bar is set to false.


 StatusBar.addOnDrawItem

StatusBar.addOnDrawItem

Assigns a delegate to the drawItem event.

Syntax

public void addOnDrawItem( StatusBarDrawItemEventHandler value )

Parameters

value

The StatusBarDrawItemEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the drawItem event to that method in the Properties window. The drawItem event occurs when when a visual aspect of an owner-drawn status bar changes.

See Also removeOnDrawItem


 StatusBar.addOnPanelClick

StatusBar.addOnPanelClick

Assigns a delegate to the panelClick event.

Syntax

public void addOnPanelClick( StatusBarPanelClickEventHandler value )

Parameters

value

The StatusBarPanelClickEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the panelClick event to that method in the Properties window. The panelClick event occurs when a panel on the status bar is clicked.

See Also removeOnPanelClick


 StatusBar.addPanel

StatusBar.addPanel

Adds a panel to the end of the status bar.

Syntax

public int addPanel( StatusBarPanel statusBarPanel )

Parameters

statusBarPanel

A StatusBarPanel object that you want to add to the status bar.

Return Value

Returns an integer that represents the zero-based index of the added panel.

Exceptions

WFCException thrown if the panel you want to add is already contained in another control.

ArrayIndexOutOfBoundsException thrown if the specified index is not valid.

Remarks

You can add panels to a status bar to display more than one type of information. This method automatically adds a panel to the end of the status bar. To add a panel in a specific location on the status bar, use the insertPanel method. To replace an existing panel, use the setPanel method. To set the text for a panel, use the StatusBarPanel.setText method.

See Also removePanel


 StatusBar.getPanels

StatusBar.getPanels

Retrieves all the panels that have been added to the status bar.

Syntax

public StatusBarPanel[] getPanels()

Return Value

Returns an array of StatusBarPanel objects that represent the panels that have been added to the status bar.

See Also setPanels


 StatusBar.getShowPanels

StatusBar.getShowPanels

Retrieves a boolean value indicating whether the status bar displays any panels that have been added to it using the addPanel method or whether the status bar displays a single line of text.

Syntax

public boolean getShowPanels()

Return Value

Returns true if the status bar displays any panels that have been added to it; returns false if the status bar displays a single line of text.

Remarks

When the showPanels property is set to false, the status bar displays the value of its text property.

See Also setShowPanels


 StatusBar.getSizingGrip

StatusBar.getSizingGrip

Retrieves a boolean value indicating whether the status bar has a sizing grip on its right side, which the user can drag to resize the status bar.

Syntax

public boolean getSizingGrip()

Return Value

Returns true if the status bar has a sizing grip; otherwise, returns false.

See Also setSizingGrip


 StatusBar.getStatusBarPanel

StatusBar.getStatusBarPanel

Retrieves the specified panel on the status bar.

Syntax

public StatusBarPanel getStatusBarPanel( int index )

Parameters

index

The zero-based index of the panel to return.

Return Value

Returns a StatusBarPanel object that represents the status bar panel.


 StatusBar.insertPanel

StatusBar.insertPanel

Inserts a panel into the status bar at the specified location.

Syntax

public int insertPanel( int index, StatusBarPanel panel )

Parameters

index

The zero-based index at which to insert the panel.

panel

A StatusBarPanel object that you want to add to the status bar.

Return Value

Returns an integer that represents the zero-based index of the added panel.

Exceptions

WFCException thrown if the panel you want to add is already contained in another control.

ArrayIndexOutOfBoundsException thrown if the specified index is not valid.

Remarks

To add a panel to the end of the status bar, you can also use the addPanel method. To replace an existing panel, use the setPanel method.


 StatusBar.onDrawItem

StatusBar.onDrawItem

Triggers the drawItem event.

Syntax

protected void onDrawItem( StatusBarDrawItemEvent event )

Parameters

event

A StatusBarDrawItemEvent object that provides the event data.

Remarks

When overriding this method, call super.onDrawItem.

See Also addOnDrawItem


 StatusBar.onMouseDown

StatusBar.onMouseDown

Triggers the mouseDown event.

Syntax

protected void onMouseDown( MouseEvent e )

Parameters

e

A MouseEvent object that provides the event data.

Remarks

When overriding this method, call super.onMouseDown.


 StatusBar.onPanelClick

StatusBar.onPanelClick

Triggers the panelClick event.

Syntax

protected void onPanelClick( StatusBarPanelClickEvent e )

Parameters

e

A StatusBarPanelClickEvent object that provides the event data.

Remarks

When overriding this method, call super.onPanelClick.

See Also addOnPanelClick


 StatusBar.removeAllPanels

StatusBar.removeAllPanels

Removes all panels from the status bar.

Syntax

public void removeAllPanels()

Remarks

To remove all panels from the status bar and replace them with new panels, use the setPanels method.


 StatusBar.removeOnDrawItem

StatusBar.removeOnDrawItem

Removes the delegate that is assigned to the drawItem event.

Syntax

public void removeOnDrawItem( StatusBarDrawItemEventHandler value )

Parameters

value

The StatusBarDrawItemEventHandler delegate to be removed.

See Also addOnDrawItem


 StatusBar.removeOnPanelClick

StatusBar.removeOnPanelClick

Removes the delegate that is assigned to the panelClick event.

Syntax

public void removeOnPanelClick( StatusBarPanelClickEventHandler value )

Parameters

value

The StatusBarPanelClickEventHandler delegate to be removed.

See Also addOnPanelClick


 StatusBar.removePanel

StatusBar.removePanel

Removes the specified panel from the status bar.

Syntax

public void removePanel( int index )

Parameters

index

The zero-based index of the panel to remove.

Exceptions

WFCInvalidArgumentException thrown if the specified index is not valid.

See Also addPanel


 StatusBar.setPanel

StatusBar.setPanel

Replaces the panel at the specified position with a new panel.

Syntax

public void setPanel( int index, StatusBarPanel panel )

Parameters

index

The zero-based index of the panel to replace.

panel

A StatusBarPanel object that represents the new panel to insert in place of the specified panel.

Exceptions

ArrayIndexOutOfBounds thrown if the specified index is not valid.


 StatusBar.setPanels

StatusBar.setPanels

Removes all existing panels from the status bar and adds a set of new panels.

Syntax

public void setPanels( StatusBarPanel[] array )

Parameters

array

An array of StatusBarPanel objects that represent the new panels to add to the status bar.

Remarks

To replace a single panel on the status bar, use the setPanel method. To remove all the panels without replacing them, use the removeAllPanels method.

See Also getPanels


 StatusBar.setShowPanels

StatusBar.setShowPanels

Sets a boolean value indicating whether the status bar displays any panels that have been added to it using the addPanel method or whether the status bar displays a single line of text.

Syntax

public void setShowPanels( boolean value )

Parameters

value

Set to true if the status bar displays any panels that have been added to it; returns false if the status bar displays a single line of text. The default value is false.

Remarks

When the showPanels property is set to false, the status bar displays the value of its text property.

See Also getShowPanels


 StatusBar.setSizingGrip

StatusBar.setSizingGrip

Sets a boolean value indicating whether the status bar has a sizing grip on its right side, which the user can drag to resize the status bar.

Syntax

public void setSizingGrip( boolean value )

Parameters

value

Set to true if the status bar has a sizing grip; otherwise, set to false. The default value is true.

See Also getSizingGrip


 StatusBar.setText

StatusBar.setText

Sets the text that will appear on the status bar when the showPanels property of the status bar is set to false.

Syntax

public void setText( String string )

Parameters

string

The text that appears on the status bar when the status bar's showPanels property is set to false.


 StatusBar.StatusBar

StatusBar.StatusBar

Creates a StatusBar control.

Syntax

public StatusBar()

Remarks

By default, the new status bar has no panels.


StatusBarDrawItemEvent Class

Provides data for the drawItem event of the StatusBar object.

Event
  |
  +DrawItemEvent
    |
    +--StatusBarDrawItemEvent

package com.ms.wfc.ui

public class StatusBarDrawItemEvent
extends DrawItemEvent

Remarks

The drawItem event occurs when a visual aspect of an owner-drawn status bar changes. A StatusBarDrawItemEvent object specifies the Graphics object to use to draw the panel, the Rectangle object in which to draw the panel, the panel identification number, state information about the panel, and the panel to draw.

For information about the WFC event model, see Handling Events in WFC.


 StatusBarDrawItemEvent Methods

StatusBarDrawItemEvent Methods

Constructors | Description
StatusBarDrawItemEvent | Creates a StatusBarDrawItemEvent object.


 StatusBarDrawItemEvent.StatusBarDrawItemEvent

StatusBarDrawItemEvent.StatusBarDrawItemEvent

Creates a StatusBarDrawItemEvent object.

Syntax

public StatusBarDrawItemEvent( Graphics g, Rectangle r, int panelId, int panelState, StatusBarPanel panel )

Parameters

g

The Graphics object used to draw the panel.

r

The Rectangle object that represents the rectangle in which the panel will be drawn.

panelId

The zero-based index of the panel.

panelState

An integer that includes state information about the panel.

panel

A StatusBarPanel object that represents the status bar panel to draw.


 StatusBarDrawItemEvent Fields

StatusBarDrawItemEvent Fields

Fields | Description
panel | Specifies the status bar panel to draw.


 StatusBarDrawItemEvent.panel

StatusBarDrawItemEvent.panel

Specifies the status bar panel to draw.

Syntax

public final StatusBarPanel panel;


StatusBarDrawItemEventHandler Delegate

Identifies the method that will handle the drawItem event of a StatusBar control.

package com.ms.wfc.ui

public multicast delegate
void StatusBarDrawItemEventHandler( Object sender, StatusBarDrawItemEvent e );

Remarks

The syntax of the StatusBarDrawItemEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a StatusBarDrawItemEvent object that provides the event data.

When you create a StatusBarDrawItemEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered. For more information about delegates, see Handling Events in WFC.


StatusBarPanel Class

Represents a panel in a StatusBar control.

Component
  |
  +--StatusBarPanel

package com.ms.wfc.ui

public class StatusBarPanel
extends Component


 StatusBarPanel Methods

StatusBarPanel Methods

Constructors | Description
StatusBarPanel | Creates a StatusBarPanel object.

Methods | Description
getAlignment | Retrieves a value indicating whether the text in the panel is left-aligned, right-aligned, or centered.
getAutoSize | Retrieves a value indicating whether the panel has a fixed-width, a width that is determined by the panel's contents, or a width that adjusts to share space on the status bar with other panels.
getBorderStyle | Retrieves a value indicating whether the panel has a raised border, a sunken border, or no border.
getIcon | Retrieves the icon displayed in the panel.
getMinWidth | Retrieves the minimum allowed width for the status bar panel.
getStyle | Retrieves a value indicating whether a panel on a status bar is owner-drawn (to support displaying images or a different font from the rest of the status bar) or system-drawn (the standard setting for displaying text).
getText | Retrieves the text displayed in the panel.
getToolTipText | Retrieves the ToolTip for the panel. (A ToolTip is the text that is displayed when the mouse pointer hovers over the panel.)
getWidth | Retrieves the width, in pixels, of the panel.
setAlignment | Sets a value indicating whether the text in the panel is left-aligned, right-aligned, or centered.
setAutoSize | Sets a value indicating whether the panel has a fixed-width, a width that is determined by the panel's contents, or a width that adjusts to share space on the status bar with other panels.
setBorderStyle | Sets a value indicating whether the panel has a raised border, a sunken border, or no border.
setIcon | Sets the icon to display in the panel.
setMinWidth | Sets the minimum allowed width for the status bar panel.
setStyle | Sets a value indicating whether a panel on a status bar is owner-drawn (to support displaying images or a different font from the rest of the status bar) or system-drawn (the standard setting for displaying text).
setText | Sets the text displayed in the panel.
setToolTipText | Sets the ToolTip for the panel. (A ToolTip is the text that is displayed when the mouse pointer hovers over the panel.)
setWidth | Sets the width, in pixels, of the panel.
toString | Retrieves a string that contains information about the panel.


 StatusBarPanel.getAlignment

StatusBarPanel.getAlignment

Retrieves a value indicating whether the text in the panel is left-aligned, right-aligned, or centered.

Syntax

public int getAlignment()

Return Value

Returns an integer that represents the alignment of the text in the panel. Possible return values are constants defined in the HorizontalAlignment class.

See Also setAlignment


 StatusBarPanel.getAutoSize

StatusBarPanel.getAutoSize

Retrieves a value indicating whether the panel has a fixed-width, a width that is determined by the panel's contents, or a width that adjusts to share space on the status bar with other panels.

Syntax

public int getAutoSize()

Return Value

Returns an integer that represents how the panel autosizes when the status bar resizes. Possible return values are constants defined in the StatusBarPanelAutoSize class.

See Also setAutoSize


 StatusBarPanel.getBorderStyle

StatusBarPanel.getBorderStyle

Retrieves a value indicating whether the panel has a raised border, a sunken border, or no border.

Syntax

public int getBorderStyle()

Return Value

Returns an integer that represents the panel border style. Possible return values are constants defined in the StatusBarPanelBorderStyle class.

See Also setBorderStyle


 StatusBarPanel.getIcon

StatusBarPanel.getIcon

Retrieves the icon displayed in the panel.

Syntax

public Icon getIcon()

Return Value

Returns an Icon object that represents the icon displayed in the panel.

See Also setIcon


 StatusBarPanel.getMinWidth

StatusBarPanel.getMinWidth

Retrieves the minimum allowed width for the status bar panel.

Syntax

public int getMinWidth()

Return Value

Returns an integer that represents minimum allowed width, in pixels, for the panel.

See Also setMinWidth


 StatusBarPanel.getStyle

StatusBarPanel.getStyle

Retrieves a value indicating whether a panel on a status bar is owner-drawn (to support displaying images or a different font from the rest of the status bar) or system-drawn (the standard setting for displaying text).

Syntax

public int getStyle()

Return Value

Returns an integer that indicates whether the panel is owner-drawn. Possible return values are constants defined in the StatusBarPanelStyle class.

See Also setStyle


 StatusBarPanel.getText

StatusBarPanel.getText

Retrieves the text displayed in the panel.

Syntax

public String getText()

Return Value

Returns a string that represents the text that appears in the panel.

See Also setText


 StatusBarPanel.getToolTipText

StatusBarPanel.getToolTipText

Retrieves the ToolTip for the panel. (A ToolTip is the text that is displayed when the mouse pointer hovers over the panel.)

Syntax

public String getToolTipText()

Return Value

Returns a string that represents the ToolTip text.

See Also setToolTipText


 StatusBarPanel.getWidth

StatusBarPanel.getWidth

Retrieves the width, in pixels, of the panel.

Syntax

public int getWidth()

Return Value

Returns an integer that represents the width of the panel.

See Also setWidth


 StatusBarPanel.setAlignment

StatusBarPanel.setAlignment

Sets a value indicating whether the text in the panel is left-aligned, right-aligned, or centered.

Syntax

public void setAlignment( int value )

Parameters

value

An integer that represents the alignment of the text in the panel. Possible values are constants defined in the HorizontalAlignment class. The default value is HorizontalAlignment.LEFT.

Exceptions

WFCInvalidEnumException thrown if the specified value is not a valid HorizontalAlignment constant.

See Also getAlignment


 StatusBarPanel.setAutoSize

StatusBarPanel.setAutoSize

Sets a value indicating whether the panel has a fixed-width, a width that is determined by the panel's contents, or a width that adjusts to share space on the status bar with other panels.

Syntax

public void setAutoSize( int autoSize )

Parameters

autoSize

An integer that represents how the panel autosizes when the status bar resizes. Possible values are constants defined in the StatusBarPanelAutoSize class. The default value is StatusBarPanelAutoSize.NONE.

Exceptions

WFCInvalidEnumException thrown if the specified value is not a valid StatusBarPanelAutoSize constant.

See Also getAutoSize


 StatusBarPanel.setBorderStyle

StatusBarPanel.setBorderStyle

Sets a value indicating whether the panel has a raised border, a sunken border, or no border.

Syntax

public void setBorderStyle( int border )

Parameters

border

An integer that represents the panel border style. Possible values are constants defined in the StatusBarPanelBorderStyle class. The default value is StatusBarPanelBorderStyle.SUNKEN.

Exceptions

WFCInvalidEnumException thrown if the specified value is not a valid StatusBarPanelBorderStyle constant.

See Also getBorderStyle


 StatusBarPanel.setIcon

StatusBarPanel.setIcon

Sets the icon to display in the panel.

Syntax

public void setIcon( Icon icon )

Parameters

icon

An Icon object that represents the icon to display in the panel.

See Also getIcon


 StatusBarPanel.setMinWidth

StatusBarPanel.setMinWidth

Sets the minimum allowed width for the status bar panel.

Syntax

public void setMinWidth( int width )

Parameters

width

An integer that represents minimum allowed width, in pixels, for the panel.

See Also getMinWidth


 StatusBarPanel.setStyle

StatusBarPanel.setStyle

Sets a value indicating whether a panel on a status bar is owner-drawn (to support displaying images or a different font from the rest of the status bar) or system-drawn (the standard setting for displaying text).

Syntax

public void setStyle( int style )

Parameters

style

An integer that indicates whether the panel is owner-drawn. Possible values are constants defined in the StatusBarPanelStyle class. The default value is StatusBarPanelStyle.TEXT.

Exceptions

WFCInvalidEnumException thrown if the specified value is not a valid StatusBarPanelStyle constant.

See Also getStyle


 StatusBarPanel.setText

StatusBarPanel.setText

Sets the text displayed in the panel.

Syntax

public void setText( String text )

Parameters

text

A string that represents the text that appears in the panel.

See Also getText


 StatusBarPanel.setToolTipText

StatusBarPanel.setToolTipText

Sets the ToolTip for the panel. (A ToolTip is the text that is displayed when the mouse pointer hovers over the panel.)

Syntax

public void setToolTipText( String text )

Parameters

text

A string that represents the ToolTip text.

See Also getToolTipText


 StatusBarPanel.setWidth

StatusBarPanel.setWidth

Sets the width, in pixels, of the panel.

Syntax

public void setWidth( int width )

Parameters

width

An integer that represents the width of the panel.

Exceptions

WFCInvalidArgumentException thrown if the specified value is less than the minimum width.

See Also getWidth


 StatusBarPanel.StatusBarPanel

StatusBarPanel.StatusBarPanel

Creates a StatusBarPanel object.

Syntax

public StatusBarPanel()


 StatusBarPanel.toString

StatusBarPanel.toString

Retrieves a string that contains information about the panel.

Syntax

public String toString()

Return Value

Returns a string that contains the class name for the control and the text it contains.


StatusBarPanelAutoSize Class

Defines constants that specify how a panel on a status bar autosizes when the status bar resizes.

Enum
  |
  +--StatusBarPanelAutoSize

package com.ms.wfc.ui

public class StatusBarPanelAutoSize
extends Enum


 StatusBarPanelAutoSize Methods

StatusBarPanelAutoSize Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 StatusBarPanelAutoSize.valid

StatusBarPanelAutoSize.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 StatusBarPanelAutoSize Fields

StatusBarPanelAutoSize Fields

Fields | Description
CONTENTS | Specifies that the width of the panel is determined by its contents.
NONE | Specifies that the width of the panel cannot be changed.
SPRING | Specifies that the panel shares the the available status bar space (the space not taken up by panels with the StatusBarPanelAutoSize.NONE and StatusBarPanelAutoSize.CONTENTS settings) with other panels that have the StatusBarPanelAutoSize.SPRING setting.


 StatusBarPanelAutoSize.CONTENTS

StatusBarPanelAutoSize.CONTENTS

Specifies that the width of the panel is determined by its contents.

Syntax

public static final int CONTENTS;


 StatusBarPanelAutoSize.NONE

StatusBarPanelAutoSize.NONE

Specifies that the width of the panel cannot be changed.

Syntax

public static final int NONE;


 StatusBarPanelAutoSize.SPRING

StatusBarPanelAutoSize.SPRING

Specifies that the panel shares the the available status bar space (the space not taken up by panels with the StatusBarPanelAutoSize.NONE and StatusBarPanelAutoSize.CONTENTS settings) with other panels that have the StatusBarPanelAutoSize.SPRING setting.

Syntax

public static final int SPRING;


StatusBarPanelBorderStyle Class

Defines constants that specify the appearance of the border for a panel on a status bar.

Enum
  |
  +--StatusBarPanelBorderStyle

package com.ms.wfc.ui

public class StatusBarPanelBorderStyle
extends Enum


 StatusBarPanelBorderStyle Methods

StatusBarPanelBorderStyle Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 StatusBarPanelBorderStyle.valid

StatusBarPanelBorderStyle.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 StatusBarPanelBorderStyle Fields

StatusBarPanelBorderStyle Fields

Fields | Description
NONE | Specifies that the status bar panel has no border.
RAISED | Specifies that the status bar panel has a three-dimensional raised border.
SUNKEN | Specifies that the status bar panel has a three-dimensional sunken border.


 StatusBarPanelBorderStyle.NONE

StatusBarPanelBorderStyle.NONE

Specifies that the status bar panel has no border.

Syntax

public static final int NONE;


 StatusBarPanelBorderStyle.RAISED

StatusBarPanelBorderStyle.RAISED

Specifies that the status bar panel has a three-dimensional raised border.

Syntax

public static final int RAISED;


 StatusBarPanelBorderStyle.SUNKEN

StatusBarPanelBorderStyle.SUNKEN

Specifies that the status bar panel has a three-dimensional sunken border.

Syntax

public static final int SUNKEN;


StatusBarPanelClickEvent Class

Provides data for the panelClick event of the StatusBar control.

Event
  |
  +--MouseEvent
    |
    +--StatusBarPanelClickEvent

package com.ms.wfc.ui

public class StatusBarPanelClickEvent
extends MouseEvent

Remarks

The panelClick event occurs when the user clicks a panel in the StatusBar control. A StatusBarPanelClickEvent specifies which panel was clicked, which mouse button was pressed, how many times the mouse button was pressed, and the coordinates of the location of the mouse click.

For information about the WFC event model, see Handling Events in WFC.


 StatusBarPanelClickEvent Methods

StatusBarPanelClickEvent Methods

Constructors | Description
StatusBarPanelClickEvent | Creates a StatusBarPanelClickEvent object.


 StatusBarPanelClickEvent.StatusBarPanelClickEvent

StatusBarPanelClickEvent.StatusBarPanelClickEvent

Creates a StatusBarPanelClickEvent object.

Syntax

public StatusBarPanelClickEvent( StatusBarPanel statusBarPanel, int button, int clicks, int x, int y )

Parameters

statusBarPanel

The StatusBarPanel object that represents the clicked panel.

button

An integer that indicates which mouse button was pressed.

clicks

An integer that indicates how many times the mouse button was pressed.

x

An integer that represents the x-coordinate of the mouse click.

y

An integer that represents the y-coordinate of the mouse click.


 StatusBarPanelClickEvent Fields

StatusBarPanelClickEvent Fields

Fields | Description
statusBarPanel | Specifies the StatusBarPanel object that represents the clicked panel.


 StatusBarPanelClickEvent.statusBarPanel

StatusBarPanelClickEvent.statusBarPanel

Specifies the StatusBarPanel object that represents the clicked panel.

Syntax

public final StatusBarPanel statusBarPanel;


StatusBarPanelClickEventHandler Delegate

Identifies the method that will handle the panelClick event of a StatusBar control.

package com.ms.wfc.ui

public multicast delegate
void StatusBarPanelClickEventHandler( Object sender, StatusBarPanelClickEvent e );

Remarks

The syntax of the StatusBarPanelClickEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a StatusBarPanelClickEvent object that provides the event data.

When you create a StatusBarPanelClickEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC.


StatusBarPanelStyle Class

Defines constants that specify whether a panel on a status bar is owner-drawn (to support displaying images or a different font from the rest of the status bar) or system-drawn (the standard setting for displaying text).

Enum
  |
  +--StatusBarPanelStyle

package com.ms.wfc.ui

public class StatusBarPanelStyle
extends Enum


 StatusBarPanelStyle Methods

StatusBarPanelStyle Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 StatusBarPanelStyle.valid

StatusBarPanelStyle.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 StatusBarPanelStyle Fields

StatusBarPanelStyle Fields

Fields | Description
OWNERDRAW | Specifies that the panel is owner-drawn.
TEXT | Specifies that the panel is drawn by the system.


 StatusBarPanelStyle.OWNERDRAW

StatusBarPanelStyle.OWNERDRAW

Specifies that the panel is owner-drawn.

Syntax

public static final int OWNERDRAW;

Remarks

Use this setting for status bar panels that display images or text in a different font.


 StatusBarPanelStyle.TEXT

StatusBarPanelStyle.TEXT

Specifies that the panel is drawn by the system.

Syntax

public static final int TEXT;

Remarks

Use this setting for status bar panels that display simple text in the standard font.


TabAlignment Class

Defines constants that specify where the tabs in a tab control are located.

Enum
  |
  +--TabAlignment

package com.ms.wfc.ui

public class TabAlignment
extends Enum


 TabAlignment Methods

TabAlignment Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 TabAlignment.valid

TabAlignment.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 TabAlignment Fields

TabAlignment Fields

Fields | Description
BOTTOM | Specifies that the tabs are located at the bottom of the control.
LEFT | Specifies that the tabs are located at the left edge of the control.
RIGHT | Specifies that the tabs are located at the right edge of the control.
TOP | Specifies that the tabs are located at the top of the control.


 TabAlignment.BOTTOM

TabAlignment.BOTTOM

Specifies that the tabs are located at the bottom of the control.

Syntax

public static final int BOTTOM;


 TabAlignment.LEFT

TabAlignment.LEFT

Specifies that the tabs are located at the left edge of the control.

Syntax

public static final int LEFT;


 TabAlignment.RIGHT

TabAlignment.RIGHT

Specifies that the tabs are located at the right edge of the control.

Syntax

public static final int RIGHT;


 TabAlignment.TOP

TabAlignment.TOP

Specifies that the tabs are located at the top of the control.

Syntax

public static final int TOP;


TabAppearance Class

Defines constants that specify the appearance of the tabs in a tab control or tab strip.

Enum
  |
  +--TabAppearance

package com.ms.wfc.ui

public class TabAppearance
extends Enum


 TabAppearance Methods

TabAppearance Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 TabAppearance.valid

TabAppearance.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 TabAppearance Fields

TabAppearance Fields

Fields | Description
BUTTONS | Specifies that the tabs have the standard appearance of three-dimensional buttons (such as those that appear on the Microsoft Windows 95 and Microsoft Windows NT taskbar).
FLAT_BUTTONS | Specifies that the tabs have the appearance of flat buttons.
NORMAL | Specifies that the tabs have the standard appearance of tabs.


 TabAppearance.BUTTONS

TabAppearance.BUTTONS

Specifies that the tabs have the standard appearance of three-dimensional buttons (such as those that appear on the Microsoft Windows 95 and Microsoft Windows NT taskbar).

Syntax

public static final int BUTTONS;


 TabAppearance.FLAT_BUTTONS

TabAppearance.FLAT_BUTTONS

Specifies that the tabs have the appearance of flat buttons.

Syntax

public static final int FLAT_BUTTONS;


 TabAppearance.NORMAL

TabAppearance.NORMAL

Specifies that the tabs have the standard appearance of tabs.

Syntax

public static final int NORMAL;


TabBase Class

Defines the base class that contains common functionality for the TabStrip and TabControl classes.

Component
  |
  +--Control
    |
    +--TabBase

package com.ms.wfc.ui

public abstract class TabBase
extends Control

Remarks

The TabBase class is abstract and cannot be instantiated.


 TabBase Methods

TabBase Methods

Constructors | Description
TabBase | Creates a TabBase object, usually as the base class for a TabStrip or TabControl control.

Methods | Description
addOnDrawItem | Assigns a delegate to the drawItem event.
addOnSelectedIndexChanged | Assigns a delegate to the selectedIndexChanged event.
getAlignment | Retrieves a value indicating where the tabs are located in the container control.
getAppearance | Retrieves a value indicating whether the tabs in this control have the appearance of standard tabs, three-dimensional buttons, or flat buttons.
getDisplayRect | Retrieves the rectangle that represents the display area of the control (the area not used to draw the tabs).
getDrawMode | Retrieves a value indicating whether the system draws the tabs or whether the parent control draws the tabs.
getHotTrack | Retrieves a boolean value indicating whether tabs are highlighted as the mouse pointer passes over them.
getImageList | Retrieves the image list control associated with this control.
getItemSize | Retrieves the height of all tabs and retrieves the width of tabs in a fixed-width (sizeMode set to TabSizeMode.FIXED) or owner-drawn (drawMode set to TabDrawMode.OWNERDRAWFIXED) control.
getMultiline | Retrieves a boolean value indicating whether multiple rows of tabs can be displayed to allow all tabs to be visible at one time.
getPadding | Retrieves the amount of horizontal and vertical space (padding) around the text and image displayed on the tabs in this control.
getRowCount | Retrieves the number of rows of tabs displayed in the control.
getSelectedIndex | Retrieves the index of the selected tab in this control.
getShowToolTips | Retrieves a boolean value indicating whether to display ToolTips for tabs that have ToolTip text associated with them.
getSizeMode | Retrieves a value indicating whether the size of each tab in this control is adjusted to what is displayed on the tab, whether the sizes of the tabs are adjusted so that each row of tabs fills the entire width of this control, or whether all tabs are assigned the same fixed width.
getTabCount | Retrieves the number of tabs contained in this control.
getTabRect | Retrieves the bounding rectangle for the specified tab in this control.
onDrawItem | Triggers the drawItem event.
onSelectedIndexChanged | Triggers the selectedIndexChanged event.
removeAll | Removes all tabs from this control.
removeOnDrawItem | Removes the delegate that is assigned to the drawItem event.
removeOnSelectedIndexChanged | Removes the delegate that is assigned to the selectedIndexChanged event.
setAlignment | Sets a value indicating where the tabs are located in the container control.
setAppearance | Sets a value indicating whether the tabs in this control have the appearance of standard tabs, three-dimensional buttons, or flat buttons.
setDisplayRectSize | Sets the size the display rectangle for this control.
setDrawMode | Sets a value indicating whether the system draws the tabs or whether the parent control draws the tabs.
setHotTrack | Sets a boolean value indicating whether tabs are highlighted as the mouse pointer passes over them.
setImageList | Sets the image list control associated with this control.
setItemSize | Sets the height of tabs; sets the width of tabs in a fixed-width (sizeMode set to TabSizeMode.FIXED) or owner-drawn (drawMode set to TabDrawMode.OWNERDRAWFIXED) control.
setMultiline | Sets a boolean value indicating whether multiple rows of tabs can be displayed to allow all tabs to be visible at one time.
setPadding | Sets the amount of horizontal and vertical space (padding) around the text and image displayed on the tabs in this control.
setSelectedIndex | Selects the specified tab.
setShowToolTips | Sets a boolean value indicating whether to display ToolTips for tabs that have ToolTip text associated with them.
setSizeMode | Sets a value indicating whether the size of each tab in this control is adjusted to what is displayed on the tab, whether the sizes of the tabs are adjusted so that each row of tabs fills the entire width of this control, or whether all tabs are assigned the same, fixed width.


 TabBase.addOnDrawItem

TabBase.addOnDrawItem

Assigns a delegate to the drawItem event.

Syntax

public final void addOnDrawItem( DrawItemEventHandler value )

Parameters

value

The DrawItemEventHandler delegate to be notified when the event occurs. The DrawItemEvent contains a Graphics object in which to paint the tab.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the drawItem event to that method in the Properties window. The drawItem event occurs when an owner-drawn tab needs to be redrawn. For a tab to be owner-drawn, the drawMode property must be set to TabDrawMode.OWNERDRAWFIXED.

See Also removeOnDrawItem


 TabBase.addOnSelectedIndexChanged

TabBase.addOnSelectedIndexChanged

Assigns a delegate to the selectedIndexChanged event.

Syntax

public final void addOnSelectedIndexChanged( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the selectedIndexChanged event to that method in the Properties window. The selectedIndexChanged event occurs when a different tab is selected by the user or programmatically.

See Also removeOnSelectedIndexChanged


 TabBase.getAlignment

TabBase.getAlignment

Retrieves a value indicating where the tabs are located in the container control.

Syntax

public final int getAlignment()

Return Value

Returns an integer that specifies where the tabs are located in the container control. Possible return values are constants defined in the TabAlignment class.

See Also setAlignment


 TabBase.getAppearance

TabBase.getAppearance

Retrieves a value indicating whether the tabs in this control have the appearance of standard tabs, three-dimensional buttons, or flat buttons.

Syntax

public final int getAppearance()

Return Value

Returns an integer that indicates what the tabs in this control look like. Possible return values are constants defined in the TabAppearance class.

Remarks

If the alignment property for this control is set to anything other than TabAlignment.TOP, tabs cannot have the appearance of flat buttons (tabs will look like three-dimensional buttons if the appearance property is set to TabAppearance.BUTTONS or TabAppearance.FLAT_BUTTONS).

See Also setAppearance


 TabBase.getDisplayRect

TabBase.getDisplayRect

Retrieves the rectangle that represents the display area of the control (the area not used to draw the tabs).

Syntax

public final Rectangle getDisplayRect()

Return Value

Returns a Rectangle object that represents the display area of the control, which is where you typically would place the children of a tab strip or tab control.


 TabBase.getDrawMode

TabBase.getDrawMode

Retrieves a value indicating whether the system draws the tabs or whether the parent control draws the tabs.

Syntax

public final int getDrawMode()

Return Value

Returns an integer that specifies the how the tabs in this control are drawn. Possible return values are constants defined in the TabDrawMode class.

See Also setDrawMode


 TabBase.getHotTrack

TabBase.getHotTrack

Retrieves a boolean value indicating whether tabs are highlighted as the mouse pointer passes over them.

Syntax

public final boolean getHotTrack()

Return Value

Returns true if the control provides feedback to the user by highlighting the tab that the mouse pointer is positioned over; otherwise, returns false.

See Also setHotTrack


 TabBase.getImageList

TabBase.getImageList

Retrieves the image list control associated with this control.

Syntax

public final ImageList getImageList()

Return Value

Returns an ImageList object that contains the images that can be displayed on tabs.

See Also setImageList


 TabBase.getItemSize

TabBase.getItemSize

Retrieves the height of all tabs and retrieves the width of tabs in a fixed-width (sizeMode set to TabSizeMode.FIXED) or owner-drawn (drawMode set to TabDrawMode.OWNERDRAWFIXED) control.

Syntax

public final Point getItemSize()

Return Value

Returns a Point object that contains the tab height and, if the tab is in a fixed-width or owner-drawn control, the tab width as well.

See Also setItemSize


 TabBase.getMultiline

TabBase.getMultiline

Retrieves a boolean value indicating whether multiple rows of tabs can be displayed to allow all tabs to be visible at one time.

Syntax

public final boolean getMultiline()

Return Value

Returns true if tabs can be displayed in multiple rows to allow all tabs to be visible at one time; returns false if tabs cannot be displayed in multiple rows and the user must navigate to tabs that are not displayed using the mouse, the keyboard, or the arrows that appear on the control.

See Also setMultiline


 TabBase.getPadding

TabBase.getPadding

Retrieves the amount of horizontal and vertical space (padding) around the text and image displayed on the tabs in this control.

Syntax

public final Point getPadding()

Return Value

Returns a Point object that contains the horizontal and vertical space, in pixels, that surrounds the text and image displayed on tabs in this control.

See Also setPadding


 TabBase.getRowCount

TabBase.getRowCount

Retrieves the number of rows of tabs displayed in the control.

Syntax

public final int getRowCount()

Return Value

Returns the number of rows of tabs displayed in the control.


 TabBase.getSelectedIndex

TabBase.getSelectedIndex

Retrieves the index of the selected tab in this control.

Syntax

public final int getSelectedIndex()

Return Value

Returns the zero-based index of the tab that is selected in this control. Returns -1 if no tab is selected.

See Also setSelectedIndex


 TabBase.getShowToolTips

TabBase.getShowToolTips

Retrieves a boolean value indicating whether to display ToolTips for tabs that have ToolTip text associated with them.

Syntax

public final boolean getShowToolTips()

Return Value

Returns true if ToolTips are displayed for tabs that have ToolTip text associated with them; otherwise, returns false.

Remarks

Use the setToolTipText method to set the ToolTip text for a tab.

See Also setShowToolTips


 TabBase.getSizeMode

TabBase.getSizeMode

Retrieves a value indicating whether the size of each tab in this control is adjusted to what is displayed on the tab, whether the sizes of the tabs are adjusted so that each row of tabs fills the entire width of this control, or whether all tabs are assigned the same fixed width.

Syntax

public final int getSizeMode()

Return Value

Returns an integer that indicates how tabs in this control are sized. Possible return values are constants defined in the TabSizeMode class.

Remarks

If the sizeMode property of a control is set to TabSizeMode.FIXED, the size of the tabs is determined by the itemSize property.

See Also setSizeMode


 TabBase.getTabCount

TabBase.getTabCount

Retrieves the number of tabs contained in this control.

Syntax

public final int getTabCount()

Return Value

Returns the number of tabs in this control.


 TabBase.getTabRect

TabBase.getTabRect

Retrieves the bounding rectangle for the specified tab in this control.

Syntax

public final Rectangle getTabRect( int index )

Parameters

index

The zero-based index of the tab to retrieve the bounding rectangle for.

Return Value

Returns a Rectangle object that represents the bounding rectangle for the specified tab.


 TabBase.onDrawItem

TabBase.onDrawItem

Triggers the drawItem event.

Syntax

protected void onDrawItem( DrawItemEvent e )

Parameters

e

A DrawItemEvent object that provides the event data.

Remarks

When overriding this method, call super.onDrawItem.

See Also addOnDrawItem


 TabBase.onSelectedIndexChanged

TabBase.onSelectedIndexChanged

Triggers the selectedIndexChanged event.

Syntax

protected void onSelectedIndexChanged( Event e )

Parameters

e

An Event object that provides the event data.

Remarks

When overriding this method, call super.onSelectedIndexChanged.

See Also addOnSelectedIndexChanged


 TabBase.removeAll

TabBase.removeAll

Removes all tabs from this control.

Syntax

public final void removeAll()

Remarks

When you remove tabs from the control, all information about the deleted tabs is lost.


 TabBase.removeOnDrawItem

TabBase.removeOnDrawItem

Removes the delegate that is assigned to the drawItem event.

Syntax

public final void removeOnDrawItem( DrawItemEventHandler value )

Parameters

value

The DrawItemEventHandler delegate to be removed. The DrawItemEvent contains a Graphics object in which to paint the tab.

See Also addOnDrawItem


 TabBase.removeOnSelectedIndexChanged

TabBase.removeOnSelectedIndexChanged

Removes the delegate that is assigned to the selectedIndexChanged event.

Syntax

public final void removeOnSelectedIndexChanged( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnSelectedIndexChanged


 TabBase.setAlignment

TabBase.setAlignment

Sets a value indicating where the tabs are located in the container control.

Syntax

public final void setAlignment( int alignment )

Parameters

alignment

An integer that specifies where the tabs are located in the container control. Possible values are constants defined in the TabAlignment class. If the alignment property is set to TabAlignment.LEFT or TabAlignment.RIGHT, the control is treated as a multiline tab control, regardless of the value of the multiLine property. If the alignment property for this control is set to anything other than TabAlignment.TOP, tabs cannot have the appearance of flat buttons (tabs will look like three-dimensional buttons if the appearance property is set to TabAppearance.BUTTONS or TabAppearance.FLAT_BUTTONS). The default value is TabAlignment.TOP.

Exceptions

WFCInvalidArgumentException thrown if the specified value is not a valid TabAlignment constant.

Remarks

For access keys to appear underlined in tab labels, the alignment property for this control must be set to TabAlignment.TOP or TabAlignment.BOTTOM.

See Also getAlignment


 TabBase.setAppearance

TabBase.setAppearance

Sets a value indicating whether the tabs in this control have the appearance of standard tabs, three-dimensional buttons, or flat buttons.

Syntax

public final void setAppearance( int value )

Parameters

value

An integer that indicates what the tabs in this control look like. Possible values are constants defined in the TabAppearance class. The default value is TabAppearance.NORMAL.

Exceptions

WFCInvalidArgumentException thrown if the specified value is not a valid TabAppearance constant.

Remarks

If the alignment property for this control is set to anything other than TabAlignment.TOP, tabs cannot have the appearance of flat buttons (tabs will look like three-dimensional buttons if the appearance property is set to TabAppearance.BUTTONS or TabAppearance.FLAT_BUTTONS).

See Also getAppearance


 TabBase.setDisplayRectSize

TabBase.setDisplayRectSize

Sets the size the display rectangle for this control.

Syntax

public final void setDisplayRectSize( int width, int height )

public final void setDisplayRectSize( Point p )

Parameters

width

The width of the display rectangle.

height

The height of the display rectangle.

p

A Point object that contains the width and height of the display rectangle.

Remarks

The size of this control adjusts to the size of the display rectangle. The size of the display rectangle can change from the value set with this method when tabs are added or deleted and the number of rows of tabs displayed changes.


 TabBase.setDrawMode

TabBase.setDrawMode

Sets a value indicating whether the system draws the tabs or whether the parent control draws the tabs.

Syntax

public final void setDrawMode( int value )

Parameters

value

An integer that specifies the how the tabs in this control are drawn. Possible values are constants defined in the TabDrawMode class. The default value is TabDrawMode.NORMAL.

Exceptions

WFCInvalidArgumentException thrown if the specified value is not a valid TabDrawMode constant.

See Also getDrawMode


 TabBase.setHotTrack

TabBase.setHotTrack

Sets a boolean value indicating whether tabs are highlighted as the mouse pointer passes over them.

Syntax

public final void setHotTrack( boolean hotTrack )

Parameters

hotTrack

Set to true if the control provides feedback to the user by highlighting the tab that the mouse pointer is positioned over; otherwise, set to false. The default value is false.

See Also getHotTrack


 TabBase.setImageList

TabBase.setImageList

Sets the image list control associated with this control.

Syntax

public final void setImageList( ImageList imageList )

Parameters

imageList

An ImageList object that contains the images you can display on tabs.

See Also getImageList


 TabBase.setItemSize

TabBase.setItemSize

Sets the height of tabs; sets the width of tabs in a fixed-width (sizeMode set to TabSizeMode.FIXED) or owner-drawn (drawMode set to TabDrawMode.OWNERDRAWFIXED) control.

Syntax

public final void setItemSize( Point size )

Parameters

itemSize

A Point object that contains the height and width of each tab. The width setting will be ignored if the tabs are not fixed-width or owner-drawn. The default size is 100 x 21 pixels.

See Also getItemSize


 TabBase.setMultiline

TabBase.setMultiline

Sets a boolean value indicating whether multiple rows of tabs can be displayed to allow all tabs to be visible at one time.

Syntax

public final void setMultiline( boolean value )

Parameters

value

Set to true if tabs can be displayed in multiple rows to allow all tabs to be visible at one time; set to false if tabs cannot be displayed in multiple rows and the user must navigate to tabs that are not displayed using the mouse, the keyboard, or the arrows that appear on the control. The default value is false.

See Also getMultiline


 TabBase.setPadding

TabBase.setPadding

Sets the amount of horizontal and vertical space (padding) around the text and image displayed on the tabs in this control.

Syntax

public final void setPadding( Point value )

Parameters

value

A Point object that contains the horizontal and vertical space, in pixels, that surrounds the text and image displayed on tabs in this control. The default value for horizontal and vertical padding is zero (0).

See Also getPadding


 TabBase.setSelectedIndex

TabBase.setSelectedIndex

Selects the specified tab.

Syntax

public void setSelectedIndex( int index )

Parameters

index

The zero-based index of the tab to select. Set to a value less than zero to specify that no tab is selected.

See Also getSelectedIndex


 TabBase.setShowToolTips

TabBase.setShowToolTips

Sets a boolean value indicating whether to display ToolTips for tabs that have ToolTip text associated with them.

Syntax

public final void setShowToolTips( boolean showToolTips )

Parameters

showToolTips

Set to true if ToolTips are displayed for tabs that have ToolTip text associated with them; otherwise, set to false. The default value is false.

Remarks

Use the setToolTipText method to set the ToolTip text for a tab.

See Also getShowToolTips


 TabBase.setSizeMode

TabBase.setSizeMode

Sets a value indicating whether the size of each tab in this control is adjusted to what is displayed on the tab, whether the sizes of the tabs are adjusted so that each row of tabs fills the entire width of this control, or whether all tabs are assigned the same, fixed width.

Syntax

public final void setSizeMode( int value )

Parameters

value

An integer that indicates how tabs in this control are sized. Possible values are constants defined in the TabSizeMode class. The default value is TabSizeMode.NORMAL (tab sizes are determined by the size of what is displayed on each tab).

Exceptions

WFCInvalidArgumentException thrown if the specified value is not a valid TabSizeMode constant.

Remarks

If the sizeMode property of a control is set to TabSizeMode.FIXED, the size of the tabs is determined by the itemSize property.

See Also getSizeMode


 TabBase.TabBase

TabBase.TabBase

Creates a TabBase object, usually as the base class for a TabStrip or TabControl control.

Syntax

public TabBase()


TabControl Class

Encapsulates the tab control.

Component
  |
  +--Control
    |
    +--TabBase
      |
      +--TabControl

package com.ms.wfc.ui

public class TabControl
extends TabBase

Remarks

A tab control contains tabbed pages (represented by TabPage objects), which can in turn contain other controls. The user displays the controls on a tabbed page by selecting the tab for the page. The tab can have the standard appearance of a tab or the appearance of a three-dimensional or flat button.

See Also TabStrip, TabBase, TabPage


 TabControl Methods

TabControl Methods

Methods | Description
add | Adds a tabbed page to this tab control.
getSelectedTab | Retrieves the tabbed page that is selected in this control.
getTabs | Retrieves all the tabbed pages in this control.
remove | Removes the specified tabbed page from this control.
setSelectedTab | Sets the tabbed page that is selected in this control and returns the zero-based index of that tab.
setTabs | Adds a set of tabbed pages to the tab control after removing all existing pages.


 TabControl.add

TabControl.add

Adds a tabbed page to this tab control.

Syntax

public void add( Control control )

Parameters

control

A Control object that represents the tabbed page to be added. This parameter must be a TabPage object.

Exceptions

WFCException thrown if the specified control is not a TabPage object.

Remarks

The new page becomes the last page in the tab control. If the added tabbed page is already a child of another control, it is removed as a child of the first control before being added as a child of this control.

See Also remove


 TabControl.getSelectedTab

TabControl.getSelectedTab

Retrieves the tabbed page that is selected in this control.

Syntax

public TabPage getSelectedTab()

Return Value

Returns a TabPage object that represents the selected tabbed page.

See Also setSelectedTab


 TabControl.getTabs

TabControl.getTabs

Retrieves all the tabbed pages in this control.

Syntax

public TabPage[] getTabs()

Return Value

Returns an array of TabPage objects that represent the tabbed pages in this control.

See Also setTabs


 TabControl.remove

TabControl.remove

Removes the specified tabbed page from this control.

Syntax

public void remove( Control control )

Parameters

control

A TabPage object that represents the tabbed page to remove. If the value you supply is not a TabPage object found in the child list for this tab control, this method has no effect.

See Also add


 TabControl.setSelectedTab

TabControl.setSelectedTab

Sets the tabbed page that is selected in this control and returns the zero-based index of that tab.

Syntax

public final int setSelectedTab( TabPage tab )

Parameters

tab

A TabPage object that represents the tabbed page to select. If the value you supply is not a TabPage object found in the child list for this tab control, this method has no effect.

Return Value

Returns the zero-based index of the selected tabbed page. Returns -1 if no tabbed page was selected.

See Also getSelectedTab


 TabControl.setTabs

TabControl.setTabs

Adds a set of tabbed pages to the tab control after removing all existing pages.

Syntax

public void setTabs( TabPage[] tabPages )

Parameters

tabPages

An array of TabPage objects that represent the tabbed pages that you want this control to contain.

See Also getTabs


TabDrawMode Class

Defines constants that specify whether the tabs in a TabStrip or TabControl control are system-drawn or owner-drawn (drawn by the parent window).

Enum
  |
  +--TabDrawMode

package com.ms.wfc.ui

public class TabDrawMode
extends Enum


 TabDrawMode Methods

TabDrawMode Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 TabDrawMode.valid

TabDrawMode.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 TabDrawMode Fields

TabDrawMode Fields

Fields | Description
NORMAL | Specifies that the system draws the tabs in the control.
OWNERDRAWFIXED | Specifies that the parent window draws the tabs in the control.


 TabDrawMode.NORMAL

TabDrawMode.NORMAL

Specifies that the system draws the tabs in the control.

Syntax

public static final int NORMAL;


 TabDrawMode.OWNERDRAWFIXED

TabDrawMode.OWNERDRAWFIXED

Specifies that the parent window draws the tabs in the control.

Syntax

public static final int OWNERDRAWFIXED;


TabItem Class

Encapsulates a tab in a tab strip.

Component
  |
  +--TabItem

package com.ms.wfc.ui

public class TabItem
extends Component
implements IConstructable

Remarks

This class contains information about a tab in a tab strip, such as the text displayed on the tab, the ToolTip text for the tab, and an index that indicates which image in the tab strip's image list is displayed on the tab.


 TabItem Methods

TabItem Methods

Constructors | Description
TabItem | Creates a TabItem object.

Methods | Description
getImageIndex | Retrieves the index of the image that appears on this tab.
getItemData | Retrieves user data stored in the tab.
getText | Retrieves the text displayed on the tab.
getToolTipText | Retrieves the ToolTip text for the tab.
setImageIndex | Sets the index of the image that appears on this tab.
setItemData | Sets the user data to store in the tab.
setText | Sets the text displayed on the tab.
setToolTipText | Sets the ToolTip text for the tab.


 TabItem.getImageIndex

TabItem.getImageIndex

Retrieves the index of the image that appears on this tab.

Syntax

public final int getImageIndex()

Return Value

Returns the zero-based index within an ImageList object of the image that appears on this tab. Returns -1 if no image appears on the tab.

Remarks

In addition to setting the imageIndex property, you must create an ImageList object, add images to the ImageList object, and then associate the ImageList object with the TabStrip control using the setImageList method to display images on tabs.

See Also setImageIndex


 TabItem.getItemData

TabItem.getItemData

Retrieves user data stored in the tab.

Syntax

public final Object getItemData()

Return Value

Returns an object that contains user data.

See Also setItemData


 TabItem.getText

TabItem.getText

Retrieves the text displayed on the tab.

Syntax

public final String getText()

Return Value

Returns the text displayed on the tab.

See Also setText


 TabItem.getToolTipText

TabItem.getToolTipText

Retrieves the ToolTip text for the tab.

Syntax

public final String getToolTipText()

Return Value

Returns the ToolTip text for the tab (the text that is displayed when the mouse pointer hovers over the tab if the showToolTips property of the tab strip is set to true.

See Also setToolTipText


 TabItem.setImageIndex

TabItem.setImageIndex

Sets the index of the image that appears on this tab.

Syntax

public final void setImageIndex( int imageIndex )

Parameters

imageIndex

The zero-based index within an ImageList object of the image that appears on this tab. Set to -1 if you do not want to display an image on the tab. The default value is -1.

Remarks

In addition to setting the imageIndex property, you must create an ImageList object, add images to the ImageList object, and then associate the ImageList object with the TabStrip control using the setImageList method to display images on tabs.

See Also getImageIndex


 TabItem.setItemData

TabItem.setItemData

Sets the user data to store in the tab.

Syntax

public final void setItemData( Object itemData )

Parameters

itemData

An object that contains user data.

See Also getItemData


 TabItem.setText

TabItem.setText

Sets the text displayed on the tab.

Syntax

public final void setText( String text )

Parameters

text

The text displayed on the tab. The default value is the code name of the TabItem object.

See Also getText


 TabItem.setToolTipText

TabItem.setToolTipText

Sets the ToolTip text for the tab.

Syntax

public final void setToolTipText( String toolTipText )

Parameters

toolTipText

The ToolTip text for the tab (the text that is displayed when the mouse pointer hovers over the tab if the showToolTips property of the tab strip is set to true.

See Also getToolTipText


 TabItem.TabItem

TabItem.TabItem

Creates a TabItem object.

Syntax

public TabItem()

public TabItem( String text )

Parameters

text

The text for the tab.


TabPage Class

Encapsulates a tab page in a tab control.

Component
  |
  +--Control
    |
    +--Panel
      |
      +--TabPage

package com.ms.wfc.ui

public class TabPage
extends Panel

Remarks

A tab page is essentially a Panel object with a TabItem object associated with it. This class contains information about a tab in a tab control, such as the text displayed on the tab, the ToolTip text for the tab, and an index that indicates which image in the tab control's image list is displayed on the tab.


 TabPage Methods

TabPage Methods

Constructors | Description
TabPage | Creates a TabItem object.

Methods | Description
getImageIndex | Retrieves the index of the image that appears on this tab.
getToolTipText | Retrieves the ToolTip text for the tab.
setImageIndex | Sets the index of the image that appears on this tab.
setText | Sets the text displayed on the tab.
setToolTipText | Sets the ToolTip text for the tab.


 TabPage.getImageIndex

TabPage.getImageIndex

Retrieves the index of the image that appears on this tab.

Syntax

public final int getImageIndex()

Return Value

Returns the zero-based index within an ImageList object of the image that appears on this tab. Returns -1 if no image appears on the tab.

Remarks

In addition to setting the imageIndex property, you must create an ImageList object, add images to the ImageList object, and then associate the ImageList object with the TabStrip control using the setImageList method to display images on tabs.

See Also setImageIndex


 TabPage.getToolTipText

TabPage.getToolTipText

Retrieves the ToolTip text for the tab.

Syntax

public final String getToolTipText()

Return Value

Returns the ToolTip text for the tab (the text that is displayed when the mouse pointer hovers over the tab if the showToolTips property of the tab control is set to true).

See Also setToolTipText


 TabPage.setImageIndex

TabPage.setImageIndex

Sets the index of the image that appears on this tab.

Syntax

public final void setImageIndex( int imageIndex )

Parameters

imageIndex

The zero-based index within an ImageList object of the image that appears on this tab. Set to -1 if you do not want to display an image on the tab. The default value is -1.

Remarks

In addition to setting the imageIndex property, you must create an ImageList object, add images to the ImageList object, and then associate the ImageList object with the TabStrip control using the setImageList method to display images on tabs.

See Also getImageIndex


 TabPage.setText

TabPage.setText

Sets the text displayed on the tab.

Syntax

public void setText( String text )

Parameters

text

The text displayed on the tab. The default value is the code name of the TabItem object.


 TabPage.setToolTipText

TabPage.setToolTipText

Sets the ToolTip text for the tab.

Syntax

public final void setToolTipText( String toolTipText )

Parameters

toolTipText

The ToolTip text for the tab (the text that is displayed when the mouse pointer hovers over the tab if the showToolTips property of the tab control is set to true).

See Also getToolTipText


 TabPage.TabPage

TabPage.TabPage

Creates a TabItem object.

Syntax

public TabPage()

public TabPage( String text )

Parameters

text

The text for the tab.


TabSizeMode Class

Defines constants that specify how tabs in a TabStrip or TabControl control are sized.

Enum
  |
  +--TabSizeMode

package com.ms.wfc.ui

public class TabSizeMode
extends Enum


 TabSizeMode Methods

TabSizeMode Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 TabSizeMode.valid

TabSizeMode.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 TabSizeMode Fields

TabSizeMode Fields

Fields | Description
FILL_TO_RIGHT | Specifies that the width of each tab is increased, if necessary, so that each row of tabs fills the entire width of the container control.
FIXED | Specifies that all tabs in a control are the same width.
NORMAL | Specifies that the size of each tab is determined by the the size of what is displayed on the tab and that the size of tabs in a row are not adjusted to fill the entire width of the container control.


 TabSizeMode.FILL_TO_RIGHT

TabSizeMode.FILL_TO_RIGHT

Specifies that the width of each tab is increased, if necessary, so that each row of tabs fills the entire width of the container control.

Syntax

public static final int FILL_TO_RIGHT;

Remarks

This style applies only to TabStrip or TabControl controls whose multiLine property is set to true.


 TabSizeMode.FIXED

TabSizeMode.FIXED

Specifies that all tabs in a control are the same width.

Syntax

public static final int FIXED;


 TabSizeMode.NORMAL

TabSizeMode.NORMAL

Specifies that the size of each tab is determined by the the size of what is displayed on the tab and that the size of tabs in a row are not adjusted to fill the entire width of the container control.

Syntax

public static final int NORMAL;


TabStrip Class

Encapsulates a tab strip control.

Component
  |
  +--Control
    |
    +--TabBase
      |
      +--TabStrip

package com.ms.wfc.ui

public class TabStrip
extends TabBase

Remarks

Many methods of the TabStrip control take either a TabItem object or a string as a parameter. If you pass a string to one of these methods, a TabItem object whose text property is set to that string is created and used by the method.


 TabStrip Methods

TabStrip Methods

Methods | Description
addTab | Adds a tab to the tab strip.
findTab | Searches for the specified tab in the tab strip, returning the zero-based index of the tab within the tab strip if it is found.
getSelectedTab | Retrieves the tab that is selected in this tab strip.
getTab | Retrieves the specified tab.
getTabs | Retrieves all the tabs in this tab strip.
getTabText | Retrieves the text for the specified tab.
insertTab | Adds a tab to the tab strip at the specified position.
removeTab | Removes the specified tab from the tab strip.
setSelectedTab | Selects the specified tab in this tab strip.
setTab | Replaces the specified tab.
setTabs | Adds a set of tabs to the tab strip after removing all existing tabs.


 TabStrip.addTab

TabStrip.addTab

Adds a tab to the tab strip.

Syntax

public final int addTab( TabItem item )

public final int addTab( String text )

Parameters

item

The TabItem object that represents the tab to add to the tab strip.

text

The text to display on the tab that is added to the tab strip.

Return Value

Returns the zero-based index of the inserted tab within the tab strip.

Remarks

If you pass a string to this method, a new TabItem object that has the passed string as its text property is created and then added to the tab control.

See Also removeTab


 TabStrip.findTab

TabStrip.findTab

Searches for the specified tab in the tab strip, returning the zero-based index of the tab within the tab strip if it is found.

Syntax

public final int findTab( TabItem item )

public final int findTab( String text )

Parameters

item

The TabItem object that represents the tab to search for.

text

The text for the tab to search for.

Return Value

Returns the zero-based index of the tab if it is found in the tab strip; returns -1 if the tab is not found.

Remarks

This method uses the equals method to determine whether the TabItem object passed in the item parameter or created from the text parameter is equal to one of the tabs contained in this tab strip.


 TabStrip.getSelectedTab

TabStrip.getSelectedTab

Retrieves the tab that is selected in this tab strip.

Syntax

public final TabItem getSelectedTab()

Return Value

Returns a TabItem object that represents the tab that is selected in this tab strip.

See Also setSelectedTab


 TabStrip.getTab

TabStrip.getTab

Retrieves the specified tab.

Syntax

public final TabItem getTab( int index )

Parameters

index

The zero-based index of the tab to retrieve.

Return Value

Returns a TabItem object that represents the tab at the specified position.

Exceptions

WFCInvalidArgumentException thrown if the specified index is not valid.

See Also setTab


 TabStrip.getTabs

TabStrip.getTabs

Retrieves all the tabs in this tab strip.

Syntax

public final TabItem[] getTabs()

Return Value

Returns a zero-based array of TabItem objects that represent the tabs in this tab strip. The tabs in the array are in the order they appear in the tab strip.

See Also setTabs


 TabStrip.getTabText

TabStrip.getTabText

Retrieves the text for the specified tab.

Syntax

public final String getTabText( int index )

Parameters

index

The zero-based index of the tab whose text you want to retrieve.

Return Value

Returns the text for the specified tab.


 TabStrip.insertTab

TabStrip.insertTab

Adds a tab to the tab strip at the specified position.

Syntax

public final int insertTab( int index, TabItem item )

public final int insertTab( int index, String text )

Parameters

index

The zero-based position where you want to insert the tab into the tab strip.

item

The TabItem object that represents the tab to insert into the tab strip.

text

The text for a new tab to create and add to the tab strip.

Exceptions

WFCInvalidArgumentException thrown if the specified index is not valid.

Remarks

If you pass a string to this method, a new TabItem object that has the passed string as its text property is created and then added to the tab control.


 TabStrip.removeTab

TabStrip.removeTab

Removes the specified tab from the tab strip.

Syntax

public final void removeTab( int index )

Parameters

index

The zero-based index of the tab to remove.

Remarks

When you remove a tab from the tab strip, all information about the deleted tab is lost.

See Also addTab


 TabStrip.setSelectedTab

TabStrip.setSelectedTab

Selects the specified tab in this tab strip.

Syntax

public final int setSelectedTab( TabItem tab )

public final int setSelectedTab( String text )

Parameters

tab

A TabItem object that represents the tab to select in this tab strip.

text

The text for the tab to select.

Return Value

Returns the zero-based index of the specified tab if it is found in the tab strip; returns -1 if the tab is not found.

Exceptions

WFCInvalidStateException thrown if the specified tab is not found in this tab strip.

Remarks

If you specify a tab that is not contained in this tab strip, no tab will be selected. This method uses the equals method to determine whether the TabItem object passed in the item parameter or created from the text parameter is equal to one of the tabs contained in this tab strip.

See Also getSelectedTab


 TabStrip.setTab

TabStrip.setTab

Replaces the specified tab.

Syntax

public final void setTab( int index, TabItem item )

public final void setTab( int index, String text )

Parameters

index

The zero-based index of the tab to replace.

item

The TabItem object that represents the tab to replace the specified tab with.

text

The text for a the tab to replace the specified tab with.

Exceptions

WFCInvalidArgumentException thrown if the specified index is not valid.

See Also getTab


 TabStrip.setTabs

TabStrip.setTabs

Adds a set of tabs to the tab strip after removing all existing tabs.

Syntax

public final void setTabs( TabItem[] value )

public final void setTabs( String[] value )

Parameters

value

A zero-based array of TabItem objects that represent the tabs to populate this tab strip with. The order of the tabs is the order in which they are displayed in the tab strip.

value

A zero-based array of strings objects that represent the text for the tabs to populate this tab strip with. One TabItem object is created to contain each string and is then added to the tab strip. The order of the tabs is the order in which they are displayed in the tab strip.

See Also getTabs


TextFormat Class

Defines a group of constants that indicate how text should be formatted.

package com.ms.wfc.ui

public class TextFormat

Remarks

The constants defined in this class are used to specify how text should be formatted when drawn on a Graphics object. To draw text on a Graphics object, use the object's drawString method.


 TextFormat Methods

TextFormat Methods

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value is a valid member of the TextFormat class.


 TextFormat.valid

TextFormat.valid

Retrieves a boolean value that indicates whether a specified value is a valid member of the TextFormat class.

Syntax

public static boolean valid( int format )

Parameters

format

The value to verify against the constants defined in this class.

Return Value

Returns true if the specified value is valid; otherwise, returns false.


 TextFormat Fields

TextFormat Fields

Fields | Description
BOTTOM | Specifies that the text should be formatted along the bottom of a rectangle.
EDITCONTROL | Specifies that the text should be formatted in the same manner in which the Edit control formats text.
ENDELLIPSIS | Specifies that an ellipsis should be placed at the end of the text if the text is too long to fit into the rectangle.
EXPANDTABS | Specifies that the tabs in the text should be expanded.
HORIZONTALCENTER | Specifies that the text should be centered horizontally.
LEFT | Specifies that the text should be aligned to the left.
NOPREFIX | Specifies that prefixes should be turned off.
PATHELLIPSIS | Specifies that an ellipsis should be placed in the middle of the text. If the text contains backslashes (\), as much of the text that appears after the last backslash character is preserved as is possible.
RIGHT | Specifies that the text should be aligned to the right.
RIGHTTOLEFT | The text is laid from right to left, as when using Hebrew or Arabic fonts.
SINGLELINE | Specifies that carriage returns and line feed characters do not cause line breaks.
TOP | Specifies that the text should be aligned along the top of the rectangle.
VERTICALCENTER | Specifies that the text should be aligned vertically.
WORDBREAK | Specifies that words should automatically be broken at the end of a line.


 TextFormat.BOTTOM

TextFormat.BOTTOM

Specifies that the text should be formatted along the bottom of a rectangle.

Syntax

public static final int BOTTOM;


 TextFormat.EDITCONTROL

TextFormat.EDITCONTROL

Specifies that the text should be formatted in the same manner in which the Edit control formats text.

Syntax

public static final int EDITCONTROL;

Remarks

When this constant is used, the Graphics object calculates the average character width of the text in the same manner as does the Edit control. Additionally, the last line of multiline text is not drawn if the text would be only partially visible.


 TextFormat.ENDELLIPSIS

TextFormat.ENDELLIPSIS

Specifies that an ellipsis should be placed at the end of the text if the text is too long to fit into the rectangle.

Syntax

public static final int ENDELLIPSIS;


 TextFormat.EXPANDTABS

TextFormat.EXPANDTABS

Specifies that the tabs in the text should be expanded.

Syntax

public static final int EXPANDTABS;


 TextFormat.HORIZONTALCENTER

TextFormat.HORIZONTALCENTER

Specifies that the text should be centered horizontally.

Syntax

public static final int HORIZONTALCENTER;


 TextFormat.LEFT

TextFormat.LEFT

Specifies that the text should be aligned to the left.

Syntax

public static final int LEFT;


 TextFormat.NOPREFIX

TextFormat.NOPREFIX

Specifies that prefixes should be turned off.

Syntax

public static final int NOPREFIX;

Remarks

Use of this constant indicates that prefix characters should not be processed in text formatting. Prefix characters are mnemonic characters that begin with an ampersand (&). Typically, Windows omits the ampersand when drawing the text and underscores the character that follows the ampersand.


 TextFormat.PATHELLIPSIS

TextFormat.PATHELLIPSIS

Specifies that an ellipsis should be placed in the middle of the text. If the text contains backslashes (\), as much of the text that appears after the last backslash character is preserved as is possible.

Syntax

public static final int PATHELLIPSIS;


 TextFormat.RIGHT

TextFormat.RIGHT

Specifies that the text should be aligned to the right.

Syntax

public static final int RIGHT;


 TextFormat.RIGHTTOLEFT

TextFormat.RIGHTTOLEFT

The text is laid from right to left, as when using Hebrew or Arabic fonts.

Syntax

public static final int RIGHTTOLEFT;


 TextFormat.SINGLELINE

TextFormat.SINGLELINE

Specifies that carriage returns and line feed characters do not cause line breaks.

Syntax

public static final int SINGLELINE;


 TextFormat.TOP

TextFormat.TOP

Specifies that the text should be aligned along the top of the rectangle.

Syntax

public static final int TOP;


 TextFormat.VERTICALCENTER

TextFormat.VERTICALCENTER

Specifies that the text should be aligned vertically.

Syntax

public static final int VERTICALCENTER;


 TextFormat.WORDBREAK

TextFormat.WORDBREAK

Specifies that words should automatically be broken at the end of a line.

Syntax

public static final int WORDBREAK;


TickStyle Class

Defines constants that specify where tick marks appear in a trackbar control.

Enum
  |
  +--TickStyle

package com.ms.wfc.ui

public class TickStyle
extends Enum


 TickStyle Methods

TickStyle Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 TickStyle.valid

TickStyle.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 TickStyle Fields

TickStyle Fields

Fields | Description
BOTH | Specifies that tick marks appear on both sides of the control.
BOTTOMRIGHT | Specifies that tick marks appear on the bottom of a horizontal control or on the right of a vertical control.
NONE | Specifies that no tick marks are visible in the control.
TOPLEFT | Specifies that tick marks appear on the top of a horizontal control or on the left of a vertical control.


 TickStyle.BOTH

TickStyle.BOTH

Specifies that tick marks appear on both sides of the control.

Syntax

public static final int BOTH;


 TickStyle.BOTTOMRIGHT

TickStyle.BOTTOMRIGHT

Specifies that tick marks appear on the bottom of a horizontal control or on the right of a vertical control.

Syntax

public static final int BOTTOMRIGHT;


 TickStyle.NONE

TickStyle.NONE

Specifies that no tick marks are visible in the control.

Syntax

public static final int NONE;


 TickStyle.TOPLEFT

TickStyle.TOPLEFT

Specifies that tick marks appear on the top of a horizontal control or on the left of a vertical control.

Syntax

public static final int TOPLEFT;


ToolBar Class

Encapsulates the ToolBar custom control.

Component
  |
  +--Control
    |
    +--ToolBar

package com.ms.wfc.ui

public class ToolBar
extends Control


 ToolBar Methods

ToolBar Methods

Constructors | Description
ToolBar | Creates a Toolbar control.

Methods | Description
addButton | Adds a button to the toolbar.
addOnButtonClick | Assigns a delegate to the buttonClick event.
addOnButtonDropDown | Assigns a delegate to the buttonDropDown event.
getAppearance | Retrieves the state of the toolbar's appearance.
getAutoSize | Retrieves a boolean value that indicates whether this ToolBar control is configured to autosize itself based on the size of the text and images the buttons contain.
getBorderStyle | Retrieves an integer constant that indicates the ToolBar control's border style value.
getButton | Retrieves the button at the specified index.
getButtonCount | Retrieves the number of buttons in this ToolBar control.
getButtons | Retrieves an array that contains the buttons in this ToolBar control.
getButtonSize | Retrieves the size of the buttons in this ToolBar control.
getDivider | Retrieves a boolean value that indicates whether this ToolBar control displays a visual divider.
getDropDownArrows | Retrieves a boolean value that indicates whether a downward-pointing arrow appears next to buttons that have the ToolBarButtonStyle.DROPDOWN style set.
getImageList | Retrieves the ToolBar control's image list.
getImageSize | Retrieves the size of the images in the toolbar's image list.
getShowToolTips | Retrieves a boolean value that indicates whether a ToolTip is displayed when the mouse cursor is positioned over the buttons in this control.
getTextAlign | Retrieves an integer constant that specifies how text is positioned in relation to the images on a toolbar button.
getWrappable | Retrieves a boolean value that indicates whether the buttons on the toolbar wrap when there is insufficient space to display the buttons on a single line.
insertButton | Inserts a button into the ToolBar control at the specified index.
onButtonClick | Triggers the buttonClick event.
onButtonDropDown | Triggers the buttonDropDown event.
removeAll | Removes all of the buttons from the ToolBar control.
removeButton | Removes the button at the specified index.
removeOnButtonClick | Removes the delegate that is assigned to the buttonClick event.
removeOnButtonDropDown | Removes the delegate assigned to the buttonDropDown event.
setAppearance | Sets the appearance of the toolbar.
setAutoSize | Specifies whether the ToolBar control resizes itself automatically to accommodate the images and text that are displayed on toolbar buttons.
setBorderStyle | Sets the border style for the ToolBar control.
setButton | Replaces the button at the specified index.
setButtons | Sets all the buttons on the ToolBar control.
setButtonSize | Sets the size of the buttons on the ToolBar control.
setDivider | Specifies whether the Toolbar control displays a visual divider to distinguish it from adjacent controls.
setDock | Specifies how the ToolBar control is docked to its parent window.
setDropDownArrows | Specifies whether arrows are displayed next to toolbar buttons that have the ToolBarButtonStyle.DROPDOWN style set.
setImageList | Associates an image list with the ToolBar control.
setShowToolTips | Specifies whether ToolTips are displayed when the mouse cursor is positioned over the buttons in this control.
setTextAlign | Specifies how text is positioned in relation to the images that are displayed on the buttons in this control.
setWrappable | Specifies whether the buttons on this control wrap to the next line when the toolbar is too narrow to display all the buttons on a single line.


 ToolBar.addButton

ToolBar.addButton

Adds a button to the toolbar.

Syntax

public final void addButton( ToolBarButton button )

Parameters

button

A ToolbarButton object that specifies the button to add.

Remarks

If the toolbar already contains buttons, the object specified in the button parameter is added to the end of the button list.

See Also removeButton


 ToolBar.addOnButtonClick

ToolBar.addOnButtonClick

Assigns a delegate to the buttonClick event.

Syntax

public final void addOnButtonClick( ToolBarButtonClickEventHandler value )

Parameters

value

The ToolBarButtonClickEventHandler to notify when the event occurs.

Remarks

A ToolBar object's buttonClick event occurs when any of its child buttons are clicked.

See Also removeOnButtonClick


 ToolBar.addOnButtonDropDown

ToolBar.addOnButtonDropDown

Assigns a delegate to the buttonDropDown event.

Syntax

public final void addOnButtonDropDown( ToolBarButtonClickEventHandler value )

Parameters

value

The ToolBarButtonClickEventHandler to notify when the event occurs.

Remarks

The buttonDropDown event occurs when the user clicks on a toolbar button that has the ToolBarButtonStyle.DROPDOWN style set.

See Also ToolBarButtonStyle, removeOnButtonDropDown


 ToolBar.getAppearance

ToolBar.getAppearance

Retrieves the state of the toolbar's appearance.

Syntax

public final int getAppearance()

Return Value

Returns an integer constant that identifies the toolbar's appearance. This value must be one of the enumeration constants defined in the ToolBarAppearance class.

Remarks

The appearance of a toolbar indicates whether the toolbar appears as a flat toolbar or a normal one. In a flat toolbar, all the buttons on the toolbar appear flat and are highlighted when the mouse moves over them. In a normal toolbar, the buttons of the toolbar appear as normal Windows pushbuttons.

See Also setAppearance


 ToolBar.getAutoSize

ToolBar.getAutoSize

Retrieves a boolean value that indicates whether this ToolBar control is configured to autosize itself based on the size of the text and images the buttons contain.

Syntax

public final boolean getAutoSize()

Return Value

Returns true if the toolbar is currently set to autosize; otherwise, returns false.

See Also setAutoSize


 ToolBar.getBorderStyle

ToolBar.getBorderStyle

Retrieves an integer constant that indicates the ToolBar control's border style value.

Syntax

public int getBorderStyle()

Return Value

Returns the ToolBar control's border style. This value must be one of the enumeration constants defined in the BorderStyle class.

See Also setBorderStyle


 ToolBar.getButton

ToolBar.getButton

Retrieves the button at the specified index.

Syntax

public final ToolBarButton getButton( int index )

Parameters

index

The index of the toolbar button to retrieve.

Return Value

Returns a ToolBarButton object for the button at the specified index.

Exceptions

WFCInvalidArgumentException thrown if index specifies a number outside the valid range of buttons.

See Also setButton


 ToolBar.getButtonCount

ToolBar.getButtonCount

Retrieves the number of buttons in this ToolBar control.

Syntax

public final int getButtonCount()

Return Value

Returns the number of buttons in this toolbar.


 ToolBar.getButtons

ToolBar.getButtons

Retrieves an array that contains the buttons in this ToolBar control.

Syntax

public final ToolBarButton[] getButtons()

Return Value

Returns an array of ToolBarButton objects if this toolbar contains buttons; otherwise, returns an empty ToolBarButton array.

See Also setButtons


 ToolBar.getButtonSize

ToolBar.getButtonSize

Retrieves the size of the buttons in this ToolBar control.

Syntax

public final Point getButtonSize()

Return Value

Returns a Point object that specifies the height and width of the buttons on the toolbar.

See Also setButtonSize


 ToolBar.getDivider

ToolBar.getDivider

Retrieves a boolean value that indicates whether this ToolBar control displays a visual divider.

Syntax

public final boolean getDivider()

Return Value

Returns true if the toolbar displays a divider; otherwise, returns false.

Remarks

A divider is intended to visually distinguish the toolbar from controls adjacent to it, such as menus or other controls.

See Also setDivider


 ToolBar.getDropDownArrows

ToolBar.getDropDownArrows

Retrieves a boolean value that indicates whether a downward-pointing arrow appears next to buttons that have the ToolBarButtonStyle.DROPDOWN style set.

Syntax

public final boolean getDropDownArrows()

Return Value

Returns true if the arrow appears next to the drop-down button; otherwise, returns false.

Remarks

A drop-down button is one that, when clicked, displays other windows or menus.

See Also setDropDownArrows


 ToolBar.getImageList

ToolBar.getImageList

Retrieves the ToolBar control's image list.

Syntax

public final ImageList getImageList()

Return Value

Returns an ImageList object that contains the images displayed on the buttons of this control.

See Also setImageList


 ToolBar.getImageSize

ToolBar.getImageSize

Retrieves the size of the images in the toolbar's image list.

Syntax

public Point getImageSize()

Return Value

Returns a Point object that specifies the size of the images in the toolbar's image list.

See Also ImageList, setImageList


 ToolBar.getShowToolTips

ToolBar.getShowToolTips

Retrieves a boolean value that indicates whether a ToolTip is displayed when the mouse cursor is positioned over the buttons in this control.

Syntax

public final boolean getShowToolTips()

Return Value

Returns true if ToolTips are to be displayed; otherwise, returns false.

See Also setShowToolTips


 ToolBar.getTextAlign

ToolBar.getTextAlign

Retrieves an integer constant that specifies how text is positioned in relation to the images on a toolbar button.

Syntax

public final int getTextAlign()

Return Value

Returns an integer that specifies the alignment of the text. The returned value is one of the enumeration constants defined in the ToolBarTextAlign class.

See Also setTextAlign


 ToolBar.getWrappable

ToolBar.getWrappable

Retrieves a boolean value that indicates whether the buttons on the toolbar wrap when there is insufficient space to display the buttons on a single line.

Syntax

public final boolean getWrappable()

Return Value

Returns true if the buttons wrap; otherwise, returns false.

See Also setWrappable


 ToolBar.insertButton

ToolBar.insertButton

Inserts a button into the ToolBar control at the specified index.

Syntax

public final void insertButton( int index, ToolBarButton button )

Parameters

index

The index at which to insert the button.

button

A ToolBarButton object that specifies the button to add to the toolbar.

Exceptions

WFCInvalidArgumentException thrown if button is null or if index is less than zero or greater than the number of buttons in the control.


 ToolBar.onButtonClick

ToolBar.onButtonClick

Triggers the buttonClick event.

Syntax

protected void onButtonClick( ToolBarButtonClickEvent e )

Parameters

e

The ToolBarButtonClickEvent object that provides the event data.

Remarks

The buttonClick event occurs when a button in the toolbar control is clicked.

See Also addOnButtonClick, removeOnButtonClick


 ToolBar.onButtonDropDown

ToolBar.onButtonDropDown

Triggers the buttonDropDown event.

Syntax

protected void onButtonDropDown( ToolBarButtonClickEvent e )

Parameters

e

The ToolBarButtonClickEvent object that provides the event data.

Remarks

The buttonDropDown event occurs when the user clicks a button that has the ToolBarButtonStyle.DROPDOWN style set.

See Also addOnButtonDropDown, removeOnButtonDropDown


 ToolBar.removeAll

ToolBar.removeAll

Removes all of the buttons from the ToolBar control.

Syntax

public final void removeAll()

See Also addButton, insertButton, removeButton


 ToolBar.removeButton

ToolBar.removeButton

Removes the button at the specified index.

Syntax

public final void removeButton( int index )

Parameters

index

The index of the button to remove.

Exceptions

WFCInvalidArgumentException thrown if index is less than zero or is greater than or equal to the number of buttons in the toolbar.

See Also addButton, insertButton, removeAll


 ToolBar.removeOnButtonClick

ToolBar.removeOnButtonClick

Removes the delegate that is assigned to the buttonClick event.

Syntax

public final void removeOnButtonClick( ToolBarButtonClickEventHandler value )

Parameters

value

The ToolBarButtonClickEventHandler that specifies the delegate to be removed.

See Also addOnButtonClick, onButtonClick


 ToolBar.removeOnButtonDropDown

ToolBar.removeOnButtonDropDown

Removes the delegate assigned to the buttonDropDown event.

Syntax

public final void removeOnButtonDropDown( ToolBarButtonClickEventHandler value )

Parameters

value

The ToolBarButtonClickEventHandler object that specifies the delegate to be removed.

See Also addOnButtonDropDown, onButtonDropDown


 ToolBar.setAppearance

ToolBar.setAppearance

Sets the appearance of the toolbar.

Syntax

public final void setAppearance( int appear )

Parameters

appear

An integer that identifies the new appearance. This value must be one of the enumeration constants defined in the ToolBarAppearance class.

See Also getAppearance


 ToolBar.setAutoSize

ToolBar.setAutoSize

Specifies whether the ToolBar control resizes itself automatically to accommodate the images and text that are displayed on toolbar buttons.

Syntax

public final void setAutoSize( boolean value )

Parameters

value

Set to true to set autosizing; otherwise, set to false.

See Also getAutoSize


 ToolBar.setBorderStyle

ToolBar.setBorderStyle

Sets the border style for the ToolBar control.

Syntax

public void setBorderStyle( int style )

Parameters

style

The new border style. This value must be one of the enumeration constants defined in the BorderStyle class.

See Also getBorderStyle


 ToolBar.setButton

ToolBar.setButton

Replaces the button at the specified index.

Syntax

public final void setButton( int index, ToolBarButton button )

Parameters

index

The index at which to set the button.

button

A ToolBarButton object that specifies the button to set.

See Also getButton


 ToolBar.setButtons

ToolBar.setButtons

Sets all the buttons on the ToolBar control.

Syntax

public final void setButtons( ToolBarButton[] array )

Parameters

array

An array of ToolBarButton objects that specifies the buttons to add.

Remarks

When you use this method to populate a toolbar, all buttons previously added to the toolbar are removed.

See Also setButtons


 ToolBar.setButtonSize

ToolBar.setButtonSize

Sets the size of the buttons on the ToolBar control.

Syntax

public final void setButtonSize( Point size )

Parameters

size

A Point object that specifies the size of the buttons on the toolbar.

See Also getButtonSize


 ToolBar.setDivider

ToolBar.setDivider

Specifies whether the Toolbar control displays a visual divider to distinguish it from adjacent controls.

Syntax

public final void setDivider( boolean value )

Parameters

value

Set to true to display a visual divider; otherwise, set to false.

See Also getDivider


 ToolBar.setDock

ToolBar.setDock

Specifies how the ToolBar control is docked to its parent window.

Syntax

public void setDock( int value )

Parameters

value

The docking style value. This value must be one of the enumeration constants defined in the ControlDock class.


 ToolBar.setDropDownArrows

ToolBar.setDropDownArrows

Specifies whether arrows are displayed next to toolbar buttons that have the ToolBarButtonStyle.DROPDOWN style set.

Syntax

public final void setDropDownArrows( boolean value )

Parameters

value

Set to true to display the drop-down arrow; otherwise, set to false.

See Also getDropDownArrows


 ToolBar.setImageList

ToolBar.setImageList

Associates an image list with the ToolBar control.

Syntax

public final void setImageList( ImageList value )

Parameters

value

An ImageList object that specifies the image list for this control.

See Also getImageList


 ToolBar.setShowToolTips

ToolBar.setShowToolTips

Specifies whether ToolTips are displayed when the mouse cursor is positioned over the buttons in this control.

Syntax

public final void setShowToolTips( boolean show )

Parameters

show

Set to true to display the ToolTips; otherwise, set to false.

See Also getShowToolTips


 ToolBar.setTextAlign

ToolBar.setTextAlign

Specifies how text is positioned in relation to the images that are displayed on the buttons in this control.

Syntax

public final void setTextAlign( int value )

Parameters

value

A constant that specifies the text position. This value must be one of the enumeration constants defined in the ToolBarTextAlign class.

See Also getTextAlign


 ToolBar.setWrappable

ToolBar.setWrappable

Specifies whether the buttons on this control wrap to the next line when the toolbar is too narrow to display all the buttons on a single line.

Syntax

public final void setWrappable( boolean wrap )

Parameters

wrap

Set to true to wrap the buttons; otherwise, set to false.

See Also getWrappable


 ToolBar.ToolBar

ToolBar.ToolBar

Creates a Toolbar control.

Syntax

public ToolBar()

Remarks

To make a ToolBar control useful, use the addButton method to add buttons to the toolbar.


ToolBarAppearance Class

Defines the enumeration constants that specify the appearance of a Toolbar control.

Enum
  |
  +--ToolBarAppearance

package com.ms.wfc.ui

public class ToolBarAppearance
extends Enum

Remarks

To specify the appearance of a ToolBar control, set its appearance property in the Properties window or use the ToolBar class' setAppearance method.


 ToolBarAppearance Methods

ToolBarAppearance Methods

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value is a valid member of this class.


 ToolBarAppearance.valid

ToolBarAppearance.valid

Retrieves a boolean value that indicates whether a specified value is a valid member of this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to compare to the constants defined in this class.

Return Value

Returns true if the value is valid; otherwise, returns false.


 ToolBarAppearance Fields

ToolBarAppearance Fields

Fields | Description
FLAT | Specifies that the toolbar is drawn to appear flat.
NORMAL | Specifies that the toolbar is drawn as a normal Windows toolbar.


 ToolBarAppearance.FLAT

ToolBarAppearance.FLAT

Specifies that the toolbar is drawn to appear flat.

Syntax

public static final int FLAT;

Remarks

When this style is applied to a toolbar, its buttons are drawn flat and are highlighted when the mouse moves over them. In addition, toggle buttons within a flat toolbar are inset.


 ToolBarAppearance.NORMAL

ToolBarAppearance.NORMAL

Specifies that the toolbar is drawn as a normal Windows toolbar.

Syntax

public static final int NORMAL;

Remarks

When this style is applied to a toolbar, all the buttons on the toolbar appear as normal Windows pushbuttons.


ToolBarButton Class

Encapsulates a button on a toolbar.

Component
  |
  +--ToolBarButton

package com.ms.wfc.ui

public class ToolBarButton
extends Component

Remarks

A toolbar usually consists of a horizontally arranged group of buttons that contain some combination of images and text which, when combined, provide a visual cue as to the button's purpose. A WFC toolbar is encapsulated in the ToolBar class. After creating an instance of this class, you can use the class' addButton method successively to add buttons to the toolbar. Each of these buttons is a ToolBarButton object instance.


 ToolBarButton Methods

ToolBarButton Methods

Constructors | Description
ToolBarButton | Creates a ToolBarButton object.

Methods | Description
getDropDownMenu | Retrieves the drop-down menu associated with this button.
getEnabled | Retrieves a boolean value that indicates whether this button is enabled.
getImageIndex | Retrieves the index of the image displayed on this button.
getItemData | Retrieves the data currently associated with this button.
getPartialPush | Retrieves a boolean value that indicates whether a toggle button on the toolbar is partially pushed.
getPushed | Retrieves a boolean value that indicates whether a toggle button on the toolbar is pushed.
getRect | Retrieves the rectangular area that this button occupies.
getStyle | Retrieves the style of this button.
getText | Retrieves the text that is displayed on this button.
getToolTipText | Retrieves the text that is to be displayed in a ToolTip when the mouse cursor is positioned over this button.
getVisible | Retrieves a boolean value that indicates whether the toolbar button is visible.
setDropDownMenu | Associates a menu with this button.
setEnabled | Enables or disables this button.
setImageIndex | Sets the index for the image associated with this button.
setItemData | Sets user-defined data on this button.
setPartialPush | Specifies whether this button is partially pushed.
setPushed | Specifies whether this button should be pushed.
setStyle | Sets this button's style.
setText | Sets the button's text.
setToolTipText | Sets the text to be displayed in a ToolTip when the mouse cursor is positioned over this button.
setVisible | Specifies whether this button is visible.
toString | Retrieves a human-readable string representation of this object.


 ToolBarButton.getDropDownMenu

ToolBarButton.getDropDownMenu

Retrieves the drop-down menu associated with this button.

Syntax

public final Menu getDropDownMenu()

Return Value

Returns a Menu object that identifies the menu to be displayed when this button is pressed.

Remarks

You can associate a menu with a toolbar button by defining the button style as ToolBarButtonStyle.DROPDOWN.

See Also setDropDownMenu


 ToolBarButton.getEnabled

ToolBarButton.getEnabled

Retrieves a boolean value that indicates whether this button is enabled.

Syntax

public final boolean getEnabled()

Return Value

Returns true if this button is enabled; otherwise, returns false.

See Also setEnabled


 ToolBarButton.getImageIndex

ToolBarButton.getImageIndex

Retrieves the index of the image displayed on this button.

Syntax

public final int getImageIndex()

Return Value

Returns the index of the image, if one is associated with this button; otherwise, returns -1.

Remarks

The value returned by this method specifies an image in the parent toolbar's image list.


 ToolBarButton.getItemData

ToolBarButton.getItemData

Retrieves the data currently associated with this button.

Syntax

public final Object getItemData()

Return Value

Returns the user-defined data associated with this button, if this object has been set; otherwise, returns null.

See Also setItemData


 ToolBarButton.getPartialPush

ToolBarButton.getPartialPush

Retrieves a boolean value that indicates whether a toggle button on the toolbar is partially pushed.

Syntax

public final boolean getPartialPush()

Return Value

Returns true if this button is partially pushed; otherwise, returns false.

Remarks

Unless the style on this button is ToolBarButtonStyle.TOGGLE, this method always returns false.

See Also setPartialPush


 ToolBarButton.getPushed

ToolBarButton.getPushed

Retrieves a boolean value that indicates whether a toggle button on the toolbar is pushed.

Syntax

public final boolean getPushed()

Return Value

Returns true if the button is pushed; otherwise, returns false.

Remarks

This method applies only to toolbar buttons created with the style ToolBarButtonStyle.TOGGLE. For all other buttons, this method always returns false.

See Also setPushed


 ToolBarButton.getRect

ToolBarButton.getRect

Retrieves the rectangular area that this button occupies.

Syntax

public final Rectangle getRect()

Return Value

Returns a Rectangle object that specifies the area that this button occupies. If this button has no parent, this method returns null.


 ToolBarButton.getStyle

ToolBarButton.getStyle

Retrieves the style of this button.

Syntax

public final int getStyle()

Return Value

Returns the button's style. The value returned by this method must be one of the enumeration constants defined in the ToolBarButtonStyle class.

See Also setStyle


 ToolBarButton.getText

ToolBarButton.getText

Retrieves the text that is displayed on this button.

Syntax

public final String getText()

Return Value

Returns a string containing this button's caption.

Remarks

To determine how the text on a button is aligned with regard to images displayed on the button, use the ToolBar class' setTextAlign method.

See Also setText


 ToolBarButton.getToolTipText

ToolBarButton.getToolTipText

Retrieves the text that is to be displayed in a ToolTip when the mouse cursor is positioned over this button.

Syntax

public final String getToolTipText()

Return Value

Returns the ToolTip text.

See Also setToolTipText


 ToolBarButton.getVisible

ToolBarButton.getVisible

Retrieves a boolean value that indicates whether the toolbar button is visible.

Syntax

public final boolean getVisible()

Return Value

Returns true if the button is visible; otherwise, returns false.

See Also setVisible


 ToolBarButton.setDropDownMenu

ToolBarButton.setDropDownMenu

Associates a menu with this button.

Syntax

public final void setDropDownMenu( Menu value )

Parameters

value

A Menu object that identifies the menu to display when this button is pressed.

Remarks

This method applies only to buttons created with the style ToolBarButtonStyle.DROPDOWN.


 ToolBarButton.setEnabled

ToolBarButton.setEnabled

Enables or disables this button.

Syntax

public final void setEnabled( boolean value )

Parameters

value

Set to true to enable this button; otherwise, set to false.

See Also getEnabled


 ToolBarButton.setImageIndex

ToolBarButton.setImageIndex

Sets the index for the image associated with this button.

Syntax

public final void setImageIndex( int index )

Parameters

index

The index of the image.

Remarks

The index parameter references an image in the parent toolbar's image list. For more information on associating an image list with a toolbar, see ToolBar.setImageList.


 ToolBarButton.setItemData

ToolBarButton.setItemData

Sets user-defined data on this button.

Syntax

public final void setItemData( Object value )

Parameters

value

An object that contains the user-defined data for this button.

See Also getItemData


 ToolBarButton.setPartialPush

ToolBarButton.setPartialPush

Specifies whether this button is partially pushed.

Syntax

public final void setPartialPush( boolean value )

Parameters

value

Set to true to indicate that this button is partially pushed; otherwise, set to false.

Remarks

This method applies only to toolbar buttons created with the ToolBarButtonStyle.TOGGLE style.

See Also getPartialPush


 ToolBarButton.setPushed

ToolBarButton.setPushed

Specifies whether this button should be pushed.

Syntax

public final void setPushed( boolean value )

Parameters

value

Set to true to indicate that this button is pushed; otherwise, set to false.

Remarks

This method can be used only with buttons created with the style ToolBarButtonStyle.TOGGLE.

See Also getPushed


 ToolBarButton.setStyle

ToolBarButton.setStyle

Sets this button's style.

Syntax

public final void setStyle( int value )

Parameters

value

The button's style. This value must be one of the enumeration constants defined in the ToolBarButtonStyle class.

See Also getStyle


 ToolBarButton.setText

ToolBarButton.setText

Sets the button's text.

Syntax

public final void setText( String text )

Parameters

text

The text to display on this button.

Remarks

While text is set on a per-button basis, text alignment, which governs how a caption is positioned relative to a button's image, is set on a per-toolbar basis. To set text alignment for a toolbar, use the ToolBar.setTextAlign method.


 ToolBarButton.setToolTipText

ToolBarButton.setToolTipText

Sets the text to be displayed in a ToolTip when the mouse cursor is positioned over this button.

Syntax

public final void setToolTipText( String value )

Parameters

value

The text to display when the mouse cursor is positioned over this button.

See Also getToolTipText


 ToolBarButton.setVisible

ToolBarButton.setVisible

Specifies whether this button is visible.

Syntax

public final void setVisible( boolean value )

Parameters

value

Set to true to make this button visible; otherwise, set to false.

See Also getVisible


 ToolBarButton.ToolBarButton

ToolBarButton.ToolBarButton

Creates a ToolBarButton object.

Syntax

public ToolBarButton()


 ToolBarButton.toString

ToolBarButton.toString

Retrieves a human-readable string representation of this object.

Syntax

public String toString()

Return Value

Returns a string representation of this object.


ToolBarButtonClickEvent Class

Provides data for the buttonClick and buttonDropDown events of the ToolBar control.

Event
  |
  +--ToolBarButtonClickEvent

package com.ms.wfc.ui

public class ToolBarButtonClickEvent
extends Event

Remarks

The ToolBarButtonClickEvent object specifies which button in the toolbar is the target of the event. For information about the WFC event model, see Handling Events in WFC.


 ToolBarButtonClickEvent Methods

ToolBarButtonClickEvent Methods

Constructors | Description
ToolBarButtonClickEvent | Creates a ToolBarButtonClickEvent object.


 ToolBarButtonClickEvent.ToolBarButtonClickEvent

ToolBarButtonClickEvent.ToolBarButtonClickEvent

Creates a ToolBarButtonClickEvent object.

Syntax

public ToolBarButtonClickEvent( ToolBarButton toolBarButton )

Parameters

toolBarButton

A ToolBarButton object that specifies the button that was clicked.


 ToolBarButtonClickEvent Fields

ToolBarButtonClickEvent Fields

Fields | Description
toolBarButton | Specifies the toolbar button that was clicked.


 ToolBarButtonClickEvent.toolBarButton

ToolBarButtonClickEvent.toolBarButton

Specifies the toolbar button that was clicked.

Syntax

public ToolBarButton toolBarButton;


ToolBarButtonClickEventHandler Delegate

Identifies the method that will handle the buttonClick and buttonDropDown events of a ToolBar control.

package com.ms.wfc.ui

public multicast delegate
void ToolBarButtonClickEventHandler( Object sender, ToolBarButtonClickEvent e );

Remarks

The syntax of the ToolBarButtonClickEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a ToolBarButtonClickEvent object that provides the event data.

When you create a ToolBarButtonClickEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC.


ToolBarButtonStyle Class

Encapsulates the styles that you can assign to toolbar buttons.

Enum
  |
  +--ToolBarButtonStyle

package com.ms.wfc.ui

public class ToolBarButtonStyle
extends Enum


 ToolBarButtonStyle Methods

ToolBarButtonStyle Methods

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value is a valid member of this class.


 ToolBarButtonStyle.valid

ToolBarButtonStyle.valid

Retrieves a boolean value that indicates whether a specified value is a valid member of this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to compare to the constants defined in this class.

Return Value

Returns true if the value is valid; otherwise, returns false.


 ToolBarButtonStyle Fields

ToolBarButtonStyle Fields

Fields | Description
DROPDOWN | Specifies that the button, when pressed, can display other menus or windows.
PUSHBUTTON | Specifies that the button behaves like a standard Windows pushbutton.
SEPARATOR | Specifies that the button acts as a separator.
TOGGLE | Specifies that the button acts as a toggle button.


 ToolBarButtonStyle.DROPDOWN

ToolBarButtonStyle.DROPDOWN

Specifies that the button, when pressed, can display other menus or windows.

Syntax

public static final int DROPDOWN;


 ToolBarButtonStyle.PUSHBUTTON

ToolBarButtonStyle.PUSHBUTTON

Specifies that the button behaves like a standard Windows pushbutton.

Syntax

public static final PUSHBUTTON;


 ToolBarButtonStyle.SEPARATOR

ToolBarButtonStyle.SEPARATOR

Specifies that the button acts as a separator.

Syntax

public static final int SEPARATOR;


 ToolBarButtonStyle.TOGGLE

ToolBarButtonStyle.TOGGLE

Specifies that the button acts as a toggle button.

Syntax

public static final int TOGGLE;


ToolBarTextAlign Class

Defines the constants that determine how text is positioned on a toolbar button.

Enum
  |
  +--ToolBarTextAlign

package com.ms.wfc.ui

public class ToolBarTextAlign
extends Enum

Remarks

The alignment of text is set for an entire toolbar using the ToolBar object's setTextAlign method. The enumeration constant that you pass to this method applies to the text alignment for all the buttons in the toolbar.


 ToolBarTextAlign Methods

ToolBarTextAlign Methods

Methods | Description
valid | Retrieves a boolean value that indicates whether a specified value is a valid member of this class.


 ToolBarTextAlign.valid

ToolBarTextAlign.valid

Retrieves a boolean value that indicates whether a specified value is a valid member of this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to compare to the constants defined in this class.

Return Value

Returns true if the value is valid; otherwise, returns false.


 ToolBarTextAlign Fields

ToolBarTextAlign Fields

Fields | Description
RIGHT | Specifies that the text appears to the right of the image.
UNDERNEATH | Specifies that the text appears beneath the image.


 ToolBarTextAlign.RIGHT

ToolBarTextAlign.RIGHT

Specifies that the text appears to the right of the image.

Syntax

public static final int RIGHT;


 <b>ToolBarTextAlign.UNDERNEATH</b>

ToolBarTextAlign.UNDERNEATH

Specifies that the text appears beneath the image.

Syntax

public static final int UNDERNEATH;


ToolTip Class

Encapsulates the ToolTip control which provides a tooltip for the controls on a form.

Component
  |
  +--ToolTip

package com.ms.wfc.ui

public final class ToolTip
extends Component
implements IExtenderProvider


 ToolTip Methods

ToolTip Methods

Constructors | Description
ToolTip | Creates a ToolTip object.

Methods | Description
getActivate | Retrieves a boolean value that indicates whether the ToolTip control is currently active.
getAutomaticDelay | Retrieves the automatic delay for the ToolTip control.
getAutoPopDelay | Retrieves the ToolTip control's autopop delay.
getInitialDelay | Sets the initial delay for the ToolTip control.
getReshowDelay | Retrieves the current value of the ToolTip control's reshow delay.
getShowAlways | Retrieves a boolean value that indicates whether the tooltip window is displayed even when its parent control is not active.
getToolTip | Retrieves the tooltip text associated with the specified control.
removeAll | Removes all the tooltips currently associated with the ToolTip control.
setActivate | Activates or deactivates the ToolTip control.
setAutomaticDelay | Sets the automatic delay on the ToolTip control.
setAutoPopDelay | Sets the autopop delay on a ToolTip control.
setInitialDelay | Sets the ToolTip control's initial delay.
setReshowDelay | Sets the reshow display which designates the time it takes for subsequent ToolTip windows to appear as the mouse pointer moves from one tooltip region to another.
setShowAlways | Sets a boolean value that indicates whether the ToolTip window should be displayed even when its parent control is not active.
setToolTip | Associates tooltip text with the specified control.


 ToolTip.getActivate

ToolTip.getActivate

Retrieves a boolean value that indicates whether the ToolTip control is currently active.

Syntax

public boolean getActivate()

Return Value

Returns true if the control is currently active; otherwise, returns false.

See Also setActivate


 ToolTip.getAutomaticDelay

ToolTip.getAutomaticDelay

Retrieves the automatic delay for the ToolTip control.

Syntax

public int getAutomaticDelay()

Return Value

Returns the automatic delay, which is the amount of time in milliseconds that passes before the tooltip is displayed.

Remarks

For more information on automatic delay times, see setAutomaticDelay.


 ToolTip.getAutoPopDelay

ToolTip.getAutoPopDelay

Retrieves the ToolTip control's autopop delay.

Syntax

public int getAutoPopDelay()

Return Value

Returns the autopop delay in milliseconds.

Remarks

The autopop delay designates the period of time, in milliseconds, that the tooltip remains visible when the mouse pointer is stationary within the tooltip region.

See Also setAutoPopDelay


 ToolTip.getInitialDelay

ToolTip.getInitialDelay

Sets the initial delay for the ToolTip control.

Syntax

public int getInitialDelay()

Return Value

Returns the initial delay in milliseconds.

Remarks

The initial delay designates the period of time, in milliseconds, that the mouse pointer must remain stationary within the tooltip region before the tooltip text is displayed.

See Also setInitialDelay, getAutomaticDelay, setAutomaticDelay


 ToolTip.getReshowDelay

ToolTip.getReshowDelay

Retrieves the current value of the ToolTip control's reshow delay.

Syntax

public int getReshowDelay()

Return Value

Returns the value of the reshow delay in milliseconds.

Remarks

The reshow delay designates the period, in milliseconds, that must transpire before subsequent tooltip windows appear as the mouse pointer moves from one tooltip region to another.

See Also setReshowDelay


 ToolTip.getShowAlways

ToolTip.getShowAlways

Retrieves a boolean value that indicates whether the tooltip window is displayed even when its parent control is not active.

Syntax

public boolean getShowAlways()

Return Value

Returns true if the window will always be displayed; otherwise, returns false.

See Also setShowAlways


 ToolTip.getToolTip

ToolTip.getToolTip

Retrieves the tooltip text associated with the specified control.

Syntax

public String getToolTip( Control control )

Parameters

control

A Control object that specifies the control for which to retrieve the tooltip text.

Return Value

Returns the tooltip text.

See Also setToolTip


 ToolTip.removeAll

ToolTip.removeAll

Removes all the tooltips currently associated with the ToolTip control.

Syntax

public void removeAll()

See Also setToolTip


 ToolTip.setActivate

ToolTip.setActivate

Activates or deactivates the ToolTip control.

Syntax

public void setActivate( boolean value )

Parameters

value

Set to true to activate the control; otherwise, set to false.

See Also getActivate


 ToolTip.setAutomaticDelay

ToolTip.setAutomaticDelay

Sets the automatic delay on the ToolTip control.

Syntax

public void setAutomaticDelay( int value )

Parameters

value

The new automatic delay in milliseconds.

Remarks

When you set the automatic delay on a ToolTip control, the delay is propagated to the control's other delay properties. The autopop delay is always set to 10 times the automatic delay. The initial delay is set to the same time as the automatic delay, and the reshow delay is set to 1/5 of the auto delay.

See Also getAutomaticDelay, setAutoPopDelay, setInitialDelay, setReshowDelay


 ToolTip.setAutoPopDelay

ToolTip.setAutoPopDelay

Sets the autopop delay on a ToolTip control.

Syntax

public void setAutoPopDelay( int value )

Parameters

value

The new value in milliseconds.

Remarks

The autopop delay designates the length of time that the tooltip window remains visible when the mouse pointer is stationary within the tooltip region.

See Also getAutomaticDelay, setAutomaticDelay, setInitialDelay, setReshowDelay


 ToolTip.setInitialDelay

ToolTip.setInitialDelay

Sets the ToolTip control's initial delay.

Syntax

public void setInitialDelay( int value )

Parameters

value

The new value in milliseconds.

Remarks

This is the length of time the pointer must remain stationary within a tooltip region before the tooltip window appears.

See Also getAutomaticDelay, setAutomaticDelay, setAutoPopDelay, setReshowDelay


 ToolTip.setReshowDelay

ToolTip.setReshowDelay

Sets the reshow display which designates the time it takes for subsequent ToolTip windows to appear as the mouse pointer moves from one tooltip region to another.

Syntax

public void setReshowDelay( int value )

Parameters

value

The amount of the reshow delay in milliseconds.

See Also getReshowDelay


 ToolTip.setShowAlways

ToolTip.setShowAlways

Sets a boolean value that indicates whether the ToolTip window should be displayed even when its parent control is not active.

Syntax

public void setShowAlways( boolean value )

Parameters

value

Set to true to always display the ToolTip window; otherwise, set to false.

See Also getShowAlways


 ToolTip.setToolTip

ToolTip.setToolTip

Associates tooltip text with the specified control.

Syntax

public void setToolTip( Control control, String caption )

Parameters

control

A Control object that specifies the control with which to associate the tooltip text.

caption

The text to display.

See Also getToolTip


 ToolTip.ToolTip

ToolTip.ToolTip

Creates a ToolTip object.

Syntax

public ToolTip()

public ToolTip( IContainer cont )

Parameters

cont

The container (IContainer) on which to create the control.


TrackBar Class

Encapsulates a trackbar control (also known as a slider control), which contains a slider for selecting a value in a range.

Component
  |
  +--Control
    |
    +--TrackBar

package com.ms.wfc.ui

public class TrackBar
extends Control


 TrackBar Methods

TrackBar Methods

Constructors | Description
TrackBar | Creates a TrackBar control.

Methods | Description
addOnScroll | Assigns a delegate to the scroll event.
addOnValueChanged | Assigns a delegate to the valueChanged event.
getAutoSize | Retrieves a boolean value indicating whether the trackbar automatically adjusts its size to fit the size of the slider.
getLargeChange | Retrieves the number of units the slider moves when the user presses the PAGE UP or PAGE DOWN key or clicks in the control on either side of the slider.
getMaximum | Retrieves the maximum value of the trackbar.
getMinimum | Retrieves the minimum value of the trackbar.
getOrientation | Retrieves a value indicating whether the trackbar is oriented horizontally or vertically.
getSmallChange | Retrieves the number of units the slider moves when the user presses the LEFT ARROW, RIGHT ARROW, UP ARROW, or DOWN ARROW key.
getTickFrequency | Retrieves the number of units between tick marks.
getTickStyle | Retrieves a value indicating where tick marks appear in a trackbar.
getValue | Retrieves the value of the trackbar (the position of the trackbar slider).
onScroll | Triggers the scroll event.
propertyChanged | Triggers the propertyChanged event.
removeOnScroll | Removes the delegate that is assigned to the scroll event.
removeOnValueChanged | Removes the delegate that is assigned to the valueChanged event.
setAutoSize | Sets a boolean value indicating whether the trackbar automatically adjusts its size to fit the size of the slider.
setLargeChange | Sets the number of units the slider moves when the user presses the PAGE UP or PAGE DOWN key or clicks in the control on either side of the slider.
setMaximum | Sets the maximum value of the trackbar.
setMinimum | Sets the minimum value of the trackbar.
setOrientation | Sets a value indicating whether the trackbar is oriented horizontally or vertically.
setRange | Sets the minimum and maximum values for the trackbar.
setSmallChange | Sets the number of units the slider moves when the user presses the LEFT ARROW, RIGHT ARROW, UP ARROW, or DOWN ARROW key.
setTickFrequency | Sets the number of units between tick marks.
setTickStyle | Sets a value indicating where tick marks appear in a trackbar.
setValue | Sets the value of the trackbar (the position of the trackbar slider).


 TrackBar.addOnScroll

TrackBar.addOnScroll

Assigns a delegate to the scroll event.

Syntax

public void addOnScroll( EventHandler value )

Parameters

value

The EventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the scroll event to that method in the Properties window. The scroll event occurs when the user moves the slider to change the value of the trackbar.

See Also removeOnScroll


 TrackBar.addOnValueChanged

TrackBar.addOnValueChanged

Assigns a delegate to the valueChanged event.

Syntax

public void addOnValueChanged( EventHandler eh )

Parameters

eh

The EventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the valueChanged event to that method in the Properties window. The valueChanged event occurs when the value of the trackbar is changed by the user or programmatically.

See Also removeOnValueChanged


 TrackBar.getAutoSize

TrackBar.getAutoSize

Retrieves a boolean value indicating whether the trackbar automatically adjusts its size to fit the size of the slider.

Syntax

public boolean getAutoSize()

Return Value

Returns true if the trackbar adjusts its height (for a horizontal trackbar) or width (for a vertical trackbar) to fit the slider; otherwise, returns false.

See Also setAutoSize


 TrackBar.getLargeChange

TrackBar.getLargeChange

Retrieves the number of units the slider moves when the user presses the PAGE UP or PAGE DOWN key or clicks in the control on either side of the slider.

Syntax

public int getLargeChange()

Return Value

Returns an integer that indicates the number of units the slider moves when the user presses the PAGE UP or PAGE DOWN key or clicks in the control on either side of the slider.

See Also setLargeChange


 TrackBar.getMaximum

TrackBar.getMaximum

Retrieves the maximum value of the trackbar.

Syntax

public int getMaximum()

Return Value

Returns the maximum value of the trackbar.

See Also setMaximum


 TrackBar.getMinimum

TrackBar.getMinimum

Retrieves the minimum value of the trackbar.

Syntax

public int getMinimum()

Return Value

Returns the minimum value of the trackbar.

See Also setMinimum


 TrackBar.getOrientation

TrackBar.getOrientation

Retrieves a value indicating whether the trackbar is oriented horizontally or vertically.

Syntax

public int getOrientation()

Return Value

Returns Orientation.HORIZONTAL if the trackbar is oriented horizontally; returns Orientation.VERTICAL if the trackbar is oriented vertically.

See Also setOrientation


 TrackBar.getSmallChange

TrackBar.getSmallChange

Retrieves the number of units the slider moves when the user presses the LEFT ARROW, RIGHT ARROW, UP ARROW, or DOWN ARROW key.

Syntax

public int getSmallChange()

Return Value

Returns the number of units the slider moves when the user presses an arrow key.

See Also setSmallChange


 TrackBar.getTickFrequency

TrackBar.getTickFrequency

Retrieves the number of units between tick marks.

Syntax

public int getTickFrequency()

Return Value

Returns the number of units between tick marks.

See Also setTickFrequency


 TrackBar.getTickStyle

TrackBar.getTickStyle

Retrieves a value indicating where tick marks appear in a trackbar.

Syntax

public int getTickStyle()

Return Value

Returns an integer that indicates whether tick marks appear at the top (or left) of the trackbar, at the bottom (or right) of the trackbar, on both sides of the trackbar, or not at all. Possible return values are constants defined in the TickStyle class.

See Also setTickStyle


 TrackBar.getValue

TrackBar.getValue

Retrieves the value of the trackbar (the position of the trackbar slider).

Syntax

public int getValue()

Return Value

Returns the value of the trackbar.

See Also setValue


 TrackBar.onScroll

TrackBar.onScroll

Triggers the scroll event.

Syntax

protected void onScroll( Event e )

Parameters

e

An Event object that provides the event data.

Remarks

When overriding this method, call super.onScroll.

See Also addOnScroll


 TrackBar.propertyChanged

TrackBar.propertyChanged

Triggers the propertyChanged event.

Syntax

protected void propertyChanged( int property )

Parameters

property

An integer that provides the event data.

Remarks

When overriding this method, call super.propertyChanged.


 TrackBar.removeOnScroll

TrackBar.removeOnScroll

Removes the delegate that is assigned to the scroll event.

Syntax

public void removeOnScroll( EventHandler value )

Parameters

value

The EventHandler delegate to be removed.

See Also addOnScroll


 TrackBar.removeOnValueChanged

TrackBar.removeOnValueChanged

Removes the delegate that is assigned to the valueChanged event.

Syntax

public void removeOnValueChanged( EventHandler eh )

Parameters

eh

The EventHandler delegate to be removed.

See Also addOnValueChanged


 TrackBar.setAutoSize

TrackBar.setAutoSize

Sets a boolean value indicating whether the trackbar automatically adjusts its size to fit the size of the slider.

Syntax

public void setAutoSize( boolean value )

Parameters

value

Set to true if the trackbar adjusts its height (for a horizontal trackbar) or width (for a vertical trackbar) to fit the slider; otherwise, set to false. The default value is true.

See Also getAutoSize


 TrackBar.setLargeChange

TrackBar.setLargeChange

Sets the number of units the slider moves when the user presses the PAGE UP or PAGE DOWN key or clicks in the control on either side of the slider.

Syntax

public void setLargeChange( int value )

Parameters

value

An integer that indicates the number of units the slider moves when the user presses the PAGE UP or PAGE DOWN key or clicks in the control on either side of the slider. The default value is 5.

See Also getLargeChange


 TrackBar.setMaximum

TrackBar.setMaximum

Sets the maximum value of the trackbar.

Syntax

public void setMaximum( int value )

Parameters

value

The maximum value for the trackbar. The default value is 10.

See Also setRange, getMaximum


 TrackBar.setMinimum

TrackBar.setMinimum

Sets the minimum value of the trackbar.

Syntax

public void setMinimum( int value )

Parameters

value

The minimum value of the trackbar. The default value is 0.

See Also setRange, getMinimum


 TrackBar.setOrientation

TrackBar.setOrientation

Sets a value indicating whether the trackbar is oriented horizontally or vertically.

Syntax

public void setOrientation( int value )

Parameters

value

Set to Orientation.HORIZONTAL to orient the trackbar horizontally; set to Orientation.VERTICAL to orient the trackbar vertically. The default value is Orientation.HORIZONTAL.

Exceptions

WFCInvalidEnumException thrown if the specified value is not a valid Orientation constant.

See Also getOrientation


 TrackBar.setRange

TrackBar.setRange

Sets the minimum and maximum values for the trackbar.

Syntax

public void setRange( int minValue, int maxValue )

Parameters

minValue

The minimum value of the trackbar.

maxValue

The maximum value for the trackbar.

See Also setMinimum, setMinimum


 TrackBar.setSmallChange

TrackBar.setSmallChange

Sets the number of units the slider moves when the user presses the LEFT ARROW, RIGHT ARROW, UP ARROW, or DOWN ARROW key.

Syntax

public void setSmallChange( int value )

Parameters

value

The number of units the slider moves when the user presses an arrow key. The default value is 1.

See Also getSmallChange


 TrackBar.setTickFrequency

TrackBar.setTickFrequency

Sets the number of units between tick marks.

Syntax

public void setTickFrequency( int value )

Parameters

value

The number of units between tick marks. The default value is 1.

Remarks

For a small trackbar with a large range, it is visually confusing to mark each unit in the range with a tick mark. You can set the tickFrequency to a number greater than one (the default) to alleviate this problem. For example, if a trackbar has a range of 0 (zero) to 100, set the tickFrequency property to 10 to display one tick mark for every ten units on the track bar.

See Also getTickFrequency


 TrackBar.setTickStyle

TrackBar.setTickStyle

Sets a value indicating where tick marks appear in a trackbar.

Syntax

public void setTickStyle( int value )

Parameters

value

An integer that indicates whether tick marks appear at the top (or left) of the trackbar, at the bottom (or right) of the trackbar, on both sides of the trackbar, or not at all. Possible values are constants defined in the TickStyle class. The default value is TickStyle.BOTTOMRIGHT.

Exceptions

WFCInvalidEnumException thrown if the specified value is not a valid TickStyle constant.

See Also getTickStyle


 TrackBar.setValue

TrackBar.setValue

Sets the value of the trackbar (the position of the trackbar slider).

Syntax

public void setValue( int value )

Parameters

value

An integer that represents the value to set for the trackbar.

Exceptions

WFCInvalidArgumentException thrown if the specified value less than the minimum value or greater than the maximum value for the trackbar.

See Also getValue


 TrackBar.TrackBar

TrackBar.TrackBar

Creates a TrackBar control.

Syntax

public TrackBar()


TreeNode Class

Represents a node in a TreeView control.

package com.ms.wfc.ui

public class TreeNode
implements Cloneable, IConstructable, IPersistable

Remarks

When you add, remove, or clone a node, all of the node's children are included in the operation.


 TreeNode Methods

TreeNode Methods

Constructors | Description
TreeNode | Creates a TreeNode control.

Methods | Description
addNode | Adds a child node to the node.
beginEdit | Begins in-place editing of the node's label text, replacing the label with a single-line edit control containing the text.
clone | Clones the entire subtree rooted at this node.
collapse | Collapses the node.
endEdit | Ends in-place editing of the node's label text.
ensureVisible | Ensures that the node is visible, expanding the parent node or scrolling the tree view control, if necessary.
expand | Expands the node.
getBounds | Retrieves the bounding rectangle for the node relative to the upper-left corner of the tree view control's client area.
getChecked | Retrieves a boolean value that indicates whether the check box for the node is checked.
getExtension | Retrieves the file name extension for the file to store the node's persistent data in.
getFirstNode | Retrieves the first child node that this node contains.
getFullPath | Retrieves the full path to this node.
getImageIndex | Retrieves the index of the image that appears next to this node.
getLastNode | Retrieves the last child node that this node contains.
getNextNode | Retrieves the node immediately after this node in the parent node's child list.
getNextVisibleNode | Retrieves the first visible node after this node in the tree view control.
getNode | Retrieves the child node of this node at the specified zero-based index.
getNodeCount | Retrieves a value indicating how many child nodes this node has.
getNodes | Retrieves an array containing all the child nodes in this node.
getParent | Retrieves the parent node for this node.
getPrevNode | Retrieves the node immediately before this node in the parent node's child list.
getPrevVisibleNode | Retrieves the last visible node before this node in the tree view control.
getSelectedImageIndex | Retrieves the index of the image that appears next to this node when it is selected.
getText | Retrieves the label text for this node.
getTreeView | Retrieves the tree view control that contains this node.
insertNode | Inserts the specified node as a child of this node at the specified position.
isEditing | Retrieves a boolean value indicating whether the user is currently editing this node in the tree view control.
isExpanded | Retrieves a boolean value indicating whether this node is currently expanded in the tree view control.
isSelected | Retrieves a boolean value indicating whether this node is currently selected in the tree view control.
isVisible | Retrieves a boolean value indicating whether this node is currently visible in the tree view control.
remove | Removes this node and all its children from the tree view control.
removeAll | Removes all children of this node.
removeNode | Removes the specified child node from this node.
save | Saves this TreeNode object to the given data stream.
setChecked | Sets a boolean value that indicates whether the check box for the node is checked.
setImageIndex | Sets the index of the image that appears next to this node.
setNode | Replaces the child node at the specified position.
setNodes | Adds a set of child nodes to this node.
setSelectedImageIndex | Sets the index of the image that appears next to this node when it is selected.
setText | Sets the label text for this node.
toggle | Expands the node if it is collapsed; collapses the node if it is expanded.
toString | Retrieves a String that contains the node label text.


 TreeNode.addNode

TreeNode.addNode

Adds a child node to the node.

Syntax

public TreeNode addNode( String text )

public void addNode( TreeNode node )

Parameters

text

The text for the new child node.

node

A TreeNode object that represents the child node to add to the node.

Return Value

Returns a TreeNode object that represents the new child node.

Remarks

The added child node is placed after existing child nodes. To add a set of child nodes at one time, use the setNodes method. To insert a child node into the node at a specific position, use the insertNode method.

See Also removeNode


 TreeNode.beginEdit

TreeNode.beginEdit

Begins in-place editing of the node's label text, replacing the label with a single-line edit control containing the text.

Syntax

public void beginEdit()

Exceptions

WFCException thrown if the labelEdit property is set to false.

See Also endEdit


 TreeNode.clone

TreeNode.clone

Clones the entire subtree rooted at this node.

Syntax

public Object clone()

Return Value

Returns a node that corresponds to the cloned subtree.


 TreeNode.collapse

TreeNode.collapse

Collapses the node.

Syntax

public void collapse()

See Also expand


 TreeNode.endEdit

TreeNode.endEdit

Ends in-place editing of the node's label text.

Syntax

public void endEdit( boolean cancel )

Parameters

cancel

Set to true if the edit operation is canceled without changes being saved; set to false if changes to the label text are saved.

See Also beginEdit


 TreeNode.ensureVisible

TreeNode.ensureVisible

Ensures that the node is visible, expanding the parent node or scrolling the tree view control, if necessary.

Syntax

public void ensureVisible()


 TreeNode.expand

TreeNode.expand

Expands the node.

Syntax

public void expand()

See Also collapse


 TreeNode.getBounds

TreeNode.getBounds

Retrieves the bounding rectangle for the node relative to the upper-left corner of the tree view control's client area.

Syntax

public Rectangle getBounds()

Return Value

Returns a Rectangle object that represents the bounding rectangle for the control.


 TreeNode.getChecked

TreeNode.getChecked

Retrieves a boolean value that indicates whether the check box for the node is checked.

Syntax

public boolean getChecked()

Return Value

Returns true if the check box for the node is checked; otherwise, returns false.

See Also setChecked


 TreeNode.getExtension

TreeNode.getExtension

Retrieves the file name extension for the file to store the node's persistent data in.

Syntax

public String getExtension()

Return Value

Returns null.

Remarks

Because the TreeNode object does not store its persistent data in a file with a file name extension, this method always returns null.

See Also IPersistable.getExtension


 TreeNode.getFirstNode

TreeNode.getFirstNode

Retrieves the first child node that this node contains.

Syntax

public TreeNode getFirstNode()

Return Value

Returns a TreeNode object that represents the first item in this node's child list. Returns null if this node has no children.


 TreeNode.getFullPath

TreeNode.getFullPath

Retrieves the full path to this node.

Syntax

public String getFullPath()

Return Value

Returns a string that contains the names of all the nodes that must navigated to get to this node, starting at the root node. The node labels are separated by the delimiter character specified in the pathSeparator property of the TreeView control that contains this node. For example, if the delimiter character of the tree view control is set to the backslash (\), this method returns a string in this form: Country\Region\State.


 TreeNode.getImageIndex

TreeNode.getImageIndex

Retrieves the index of the image that appears next to this node.

Syntax

public int getImageIndex()

Return Value

Returns the zero-based index within an ImageList object of the image that appears next to this node when it is selected. Returns -1 if the imageIndex property of the node has never been explicitly set, and the image that appears next to the node is specified in the imageIndex property of the TreeView control that contains this node.

See Also setImageIndex


 TreeNode.getLastNode

TreeNode.getLastNode

Retrieves the last child node that this node contains.

Syntax

public TreeNode getLastNode()

Return Value

Returns a TreeNode object that represents the last item in this node's child list. Returns null if this node has no children.


 TreeNode.getNextNode

TreeNode.getNextNode

Retrieves the node immediately after this node in the parent node's child list.

Syntax

public TreeNode getNextNode()

Return Value

Returns a TreeNode object that represents the node immediately after this node in the parent node's child list. Returns null if this node is the last or only child node of the parent node.

See Also getPrevNode


 TreeNode.getNextVisibleNode

TreeNode.getNextVisibleNode

Retrieves the first visible node after this node in the tree view control.

Syntax

public TreeNode getNextVisibleNode()

Return Value

Returns a TreeNode object that represents the first visible node after this node in the tree view control. The returned node can be a child node, a sibling node, or a node from another branch in the tree view control. Returns null if this node is the last visible node in the tree view control.

See Also getPrevVisibleNode


 TreeNode.getNode

TreeNode.getNode

Retrieves the child node of this node at the specified zero-based index.

Syntax

public TreeNode getNode( int index )

Parameters

index

The index of the child node to retrieve.

Return Value

Returns a TreeNode object that represents the retrieved tree node.

See Also setNode


 TreeNode.getNodeCount

TreeNode.getNodeCount

Retrieves a value indicating how many child nodes this node has.

Syntax

public int getNodeCount()

public int getNodeCount(boolean includeSubTrees)

Parameters

includeSubTrees

Set to true to include nodes in subtrees rooted at this node; otherwise, set to false (or omit).

Return Value

Returns an integer that represents the number of child nodes this node has.


 TreeNode.getNodes

TreeNode.getNodes

Retrieves an array containing all the child nodes in this node.

Syntax

public TreeNode[] getNodes()

Return Value

Returns a zero-based array of TreeNode objects that represent the child nodes in this node. The nodes are placed in the array in the order they appear in the tree view control.

See Also setNodes


 TreeNode.getParent

TreeNode.getParent

Retrieves the parent node for this node.

Syntax

public TreeNode getParent()

Return Value

Returns a TreeNode object that represents the parent node for this node. Returns null if called on the node that is the virtual root for the tree view control (the node that is the parent node to the root nodes in the control).


 TreeNode.getPrevNode

TreeNode.getPrevNode

Retrieves the node immediately before this node in the parent node's child list.

Syntax

public TreeNode getPrevNode()

Return Value

Returns a TreeNode object that represents the node immediately before this node in the parent node's child list. Returns null if this node is the first or only child node of the parent node.

See Also getNextNode


 TreeNode.getPrevVisibleNode

TreeNode.getPrevVisibleNode

Retrieves the last visible node before this node in the tree view control.

Syntax

public TreeNode getPrevVisibleNode()

Return Value

Returns a TreeNode object that represents the last visible node before this node in the tree view control. The returned node can be a child node, a sibling node, or a node from another branch in the tree view control. Returns null if this node is the first visible node in the tree view control.

See Also getNextVisibleNode


 TreeNode.getSelectedImageIndex

TreeNode.getSelectedImageIndex

Retrieves the index of the image that appears next to this node when it is selected.

Syntax

public int getSelectedImageIndex()

Return Value

Returns the zero-based index within an ImageList object of the image that appears next to this node when it is selected. Returns -1 if the selectedImageIndex property of the node has never been explicitly set and the image that appears next to the node is specified in the selectedImageIndex property of the TreeView control that contains this node.

See Also setSelectedImageIndex


 TreeNode.getText

TreeNode.getText

Retrieves the label text for this node.

Syntax

public String getText()

Return Value

Returns the text that appears in the label for this node.

See Also setText


 TreeNode.getTreeView

TreeNode.getTreeView

Retrieves the tree view control that contains this node.

Syntax

public TreeView getTreeView()

Return Value

Returns a TreeView object that represents the tree view control that contains this node.


 TreeNode.insertNode

TreeNode.insertNode

Inserts the specified node as a child of this node at the specified position.

Syntax

public void insertNode( int index, TreeNode node )

Parameters

index

The zero-based position where you want to insert the child node into this node. If this number is less than zero, the child node is inserted at the top of the node. If this number is greater than the number of child nodes this node currently contains, the child node is inserted at the bottom of this node.

node

A TreeNode object that represents the child node that you want insert into this node.


 TreeNode.isEditing

TreeNode.isEditing

Retrieves a boolean value indicating whether the user is currently editing this node in the tree view control.

Syntax

public boolean isEditing()

Return Value

Returns true if the user is currently editing this node; otherwise, returns false.


 TreeNode.isExpanded

TreeNode.isExpanded

Retrieves a boolean value indicating whether this node is currently expanded in the tree view control.

Syntax

public boolean isExpanded()

Return Value

Returns true if this node is currently expanded; otherwise, returns false.


 TreeNode.isSelected

TreeNode.isSelected

Retrieves a boolean value indicating whether this node is currently selected in the tree view control.

Syntax

public boolean isSelected()

Return Value

Returns true if this node is currently selected; otherwise, returns false.


 TreeNode.isVisible

TreeNode.isVisible

Retrieves a boolean value indicating whether this node is currently visible in the tree view control.

Syntax

public boolean isVisible()

Return Value

Returns true if this node is currently visible; otherwise, returns false.


 TreeNode.remove

TreeNode.remove

Removes this node and all its children from the tree view control.

Syntax

public void remove()

Remarks

To remove all the children of this node without removing this node itself, use the removeAll method.


 TreeNode.removeAll

TreeNode.removeAll

Removes all children of this node.

Syntax

public void removeAll()

Remarks

To remove this node and its children, use the remove method. To remove one specific child node, use the removeNode method.


 TreeNode.removeNode

TreeNode.removeNode

Removes the specified child node from this node.

Syntax

public void removeNode( int index )

Parameters

index

The zero-based index of the child node to remove.

See Also addNode


 TreeNode.save

TreeNode.save

Saves this TreeNode object to the given data stream.

Syntax

public void save( IDataStream stream )

Parameters

stream

An IPersistable object that represents the data stream to write to.


 TreeNode.setChecked

TreeNode.setChecked

Sets a boolean value that indicates whether the check box for the node is checked.

Syntax

public void setChecked( boolean value )

Parameters

value

Set to true to check the check box for the node; set to false to clear the check box.

Remarks

If the TreeView.checkBoxes property of the tree view control that contains this node is set to false, this method has no effect.

See Also getChecked


 TreeNode.setImageIndex

TreeNode.setImageIndex

Sets the index of the image that appears next to this node.

Syntax

public void setImageIndex( int value )

Parameters

value

Set to the zero-based index within an ImageList object of the image that appears next to this node when it is selected. Returns -1 if the imageIndex property of the node has never been explicitly set and the image that appears next to the node is specified in the TreeView.setImageIndex property of the tree view control that contains this node.

Remarks

If you have set the selectedImageIndex property of this node or of the tree view control that contains this node to a different image, that image will appear next to the node when the node is selected.

See Also getImageIndex


 TreeNode.setNode

TreeNode.setNode

Replaces the child node at the specified position.

Syntax

public void setNode( int index, TreeNode node )

Parameters

index

The zero-based index of the child node you want to replace.

node

A TreeNode object that represents the new node that you want insert in the place of the child node currently at the specified position.

Exceptions

WFCInvalidArgumentException thrown if the specified index is not valid.

See Also getNode


 TreeNode.setNodes

TreeNode.setNodes

Adds a set of child nodes to this node.

Syntax

public void setNodes( TreeNode[] nodes )

Parameters

nodes

A zero-based array of TreeNode objects that represent the child nodes you want to add to this node.

Remarks

This method removes all existing child nodes from this node before inserting the new nodes.

See Also getNodes


 TreeNode.setSelectedImageIndex

TreeNode.setSelectedImageIndex

Sets the index of the image that appears next to this node when it is selected.

Syntax

public void setSelectedImageIndex( int value )

Parameters

value

Set to the zero-based index within an ImageList object of the image that appears next to this node when it is selected. Returns -1 if the selectedImageIndex property of the node has never been explicitly set, and the image that appears next to the node is specified in the TreeView.setSelectedImageIndex property of the tree view control that contains this node.

See Also getSelectedImageIndex


 TreeNode.setText

TreeNode.setText

Sets the label text for this node.

Syntax

public void setText( String value )

Parameters

value

The text that appears in the label for this node.

See Also getText


 TreeNode.toggle

TreeNode.toggle

Expands the node if it is collapsed; collapses the node if it is expanded.

Syntax

public void toggle()


 TreeNode.toString

TreeNode.toString

Retrieves a String that contains the node label text.

Syntax

public String toString()

Return Value

Returns a String that specifies the node label text.


 TreeNode.TreeNode

TreeNode.TreeNode

Creates a TreeNode control.

Syntax

public TreeNode()

public TreeNode( IDataStream stream )

public TreeNode( String text )

public TreeNode( String text, TreeNode[] children )

public TreeNode( String text, int imageIndex, int selectedImageIndex )

public TreeNode( String text, int imageIndex, int selectedImageIndex, TreeNode[] children )

Parameters

stream

The IDataStream object to read from to create the node.

text

The label text for the node.

children

An array of TreeNode objects that represent the child nodes to add to the node.

imageIndex

The zero-based index within an ImageList object of the image that appears by default next to the node.

selectedImageIndex

The zero-based index within an ImageList object of the image that appears next to the node when it is selected.


TreeNodesEditDialog Class

Represents the TreeNode Editor dialog box that is used for editing tree view nodes from the Properties window.

Component
  |
  +--Control
    |
    +--Form
      |
      +--TreeNodesEditDialog

package com.ms.wfc.ui

public class TreeNodesEditDialog
extends Form

Remarks

You display this dialog box by clicking the ellipsis button next to the nodes property value for a TreeView control. The user can use this dialog box to add and delete nodes, add children to nodes, edit node labels, and set the images to display next to the node when it is selected and unselected.


 TreeNodesEditDialog Methods

TreeNodesEditDialog Methods

Constructors | Description
TreeNodesEditDialog | Creates a TreeNodesEditDialog object.

Methods | Description
getNodes | Retrieves the nodes in the tree view control.


 TreeNodesEditDialog.getNodes

TreeNodesEditDialog.getNodes

Retrieves the nodes in the tree view control.

Syntax

public TreeNode[] getNodes()

Return Value

Returns an array of TreeNode objects that represents the nodes that were specified in the dialog box.


 TreeNodesEditDialog.TreeNodesEditDialog

TreeNodesEditDialog.TreeNodesEditDialog

Creates a TreeNodesEditDialog object.

Syntax

public TreeNodesEditDialog()


TreeView Class

Encapsulates a Windows tree view control.

Component
  |
  +--Control
    |
    +--TreeView

package com.ms.wfc.ui

public class TreeView
extends Control


 TreeView Methods

TreeView Methods

Constructors | Description
TreeView | Creates a TreeView control.

Methods | Description
addNode | Adds a root node to the tree view control.
addOnAfterCheck | Assigns a delegate to the afterCheck event.
addOnAfterCollapse | Assigns a delegate to the afterCollapse event.
addOnAfterExpand | Assigns a delegate to the afterExpand event.
addOnAfterLabelEdit | Assigns a delegate to the afterLabelEdit event.
addOnAfterSelect | Assigns a delegate to the afterSelect event.
addOnBeforeCheck | Assigns a delegate to the beforeCheck event.
addOnBeforeCollapse | Assigns a delegate to the beforeCollapse event.
addOnBeforeExpand | Assigns a delegate to the beforeExpand event.
addOnBeforeLabelEdit | Assigns a delegate to the beforeLabelEdit event.
addOnBeforeSelect | Assigns a delegate to the beforeSelect event.
addOnItemDrag | Assigns a delegate to the itemDrag event.
beginUpdate | Maintains performance while items are added to the tree view control one at a time by preventing the TreeView control from painting until the endUpdate method is called.
collapseAll | Collapses all root nodes in the tree view control.
endUpdate | Resumes painting the TreeView control after painting is suspended by the beginUpdate method.
expandAll | Expands all root nodes in the tree view control.
getBorderStyle | Retrieves a value indicating the kind of border the tree view control has.
getCheckBoxes | Retrieves a boolean value indicating whether a check box appears next to each node in the tree view control.
getHideSelection | Retrieves a boolean value indicating whether the selected node in the tree view control remains highlighted when the control loses the focus.
getHotTracking | Retrieves a boolean value indicating whether nodes in the tree view control are highlighted as the mouse pointer passes over them.
getImageIndex | Retrieves the index of the image that appears by default next to nodes in the tree view control.
getImageList | Retrieves the image list control associated with the tree view control.
getIndent | Retrieves the distance, in pixels, that nodes are indented relative to their parent nodes.
getLabelEdit | Retrieves a boolean value indicating whether the user can edit the labels of tree view nodes.
getNode | Retrieves the node at the specified zero-based index.
getNodeAt | Retrieves the node at the specified location.
getNodeCount | Retrieves the number of root nodes contained in the tree view control.
getNodes | Retrieves an array containing all the root nodes in the tree view control.
getPathSeparator | Retrieves the delimiter character used in the path returned by the TreeNode.getFullPath method.
getScrollable | Retrieves a boolean value indicating whether a scroll bar is added to the tree view control when there is not enough room to display all the tree view nodes in the control's client area.
getSelectedImageIndex | Retrieves the index of the image that appears next to the node that is currently selected in the tree view control.
getSelectedNode | Retrieves the currently selected node in the tree view control.
getShowLines | Retrieves a boolean value indicating whether a line is drawn to connect each child node to its parent node in the tree view control.
getShowPlusMinus | Retrieves a boolean value indicating whether a plus (+) or minus (-) button, which allows the user to expand or collapse a node by clicking, appears next to tree nodes that have children.
getShowRootLines | Retrieves a boolean value indicating whether a line is drawn to connect all the root nodes of the tree view control.
getSorted | Retrieves a boolean value indicating whether the nodes in the tree view control are sorted alphabetically.
getTopNode | Retrieves first visible node in a tree view control.
getVisibleCount | Retrieves the number of nodes that can be fully visible in the tree view control.
insertNode | Inserts the specified node into the tree view control as a root node at the specified position.
onAfterCheck | Triggers the afterCheck event.
onAfterCollapse | Triggers the afterCollapse event.
onAfterExpand | Triggers the afterExpand event.
onAfterLabelEdit | Triggers the afterLabelEdit event.
onAfterSelect | Triggers the afterSelect event.
onBeforeCheck | Triggers the beforeCheck event.
onBeforeCollapse | Triggers the beforeCollapse event.
onBeforeExpand | Triggers the beforeExpand event.
onBeforeLabelEdit | Triggers the beforeLabelEdit event.
onBeforeSelect | Triggers the beforeSelect event.
onCreateHandle | Triggers the createHandle event.
onItemDrag | Triggers the itemDrag event.
removeAll | Remove all nodes from the tree view control.
removeOnAfterCheck | Removes the delegate that is assigned to the afterCheck event.
removeOnAfterCollapse | Removes the delegate that is assigned to the afterCollapse event.
removeOnAfterExpand | Removes the delegate that is assigned to the afterExpand event.
removeOnAfterLabelEdit | Removes the delegate that is assigned to the afterLabelEdit event.
removeOnAfterSelect | Removes the delegate that is assigned to the afterSelect event.
removeOnBeforeCheck | Removes the delegate that is assigned to the beforeCheck event.
removeOnBeforeCollapse | Removes the delegate that is assigned to the beforeCollapse event.
removeOnBeforeExpand | Removes the delegate that is assigned to the beforeExpand event.
removeOnBeforeLabelEdit | Removes the delegate that is assigned to the beforeLabelEdit event.
removeOnBeforeSelect | Removes the delegate that is assigned to the beforeSelect event.
removeOnItemDrag | Removes the delegate that is assigned to the itemDrag event.
resetIndent | Resets the indentation to the system default.
setBorderStyle | Sets a value indicating the kind of border the tree view control has.
setCheckBoxes | Sets a boolean value indicating whether a check box appears next to each node in the tree view control.
setHideSelection | Sets a boolean value indicating whether the selected node in the tree view control remains highlighted when the control loses the focus.
setHotTracking | Sets a boolean value indicating whether nodes in the tree view control are highlighted as the mouse pointer passes over them.
setImageIndex | Sets the index of the image that appears by default next to nodes in the tree view control.
setImageList | Sets the image list control associated with the tree view control.
setIndent | Sets the distance, in pixels, that nodes are indented relative to their parent nodes.
setLabelEdit | Sets a boolean value indicating whether the user can edit the labels of tree view nodes.
setNode | Replaces the node at the specified position in the tree view control.
setNodes | Adds a set of root nodes to the tree view control.
setPathSeparator | Sets the delimiter character used in the path returned by the TreeNode.getFullPath method.
setScrollable | Sets a boolean value indicating whether a scroll bar is added to the tree view control when there is not enough room to display all the tree view nodes in the control's client area.
setSelectedImageIndex | Sets the index of the image that appears next to the node that is currently selected in the tree view control.
setSelectedNode | Selects the specified node in the tree view control.
setShowLines | Sets a boolean value indicating whether a line connects each child node to its parent node in the tree view control.
setShowPlusMinus | Sets a boolean value indicating whether a plus (+) or minus (-) button, which allows the user to expand or collapse a node by clicking, appears next to tree nodes that have children.
setShowRootLines | Sets a boolean value indicating whether a line is drawn to connect all the root nodes of the tree view control.
setSorted | Sets a boolean value indicating whether the nodes in the tree view control are sorted alphabetically.
shouldPersistIndent | Retrieves a boolean value indicating whether the value of the indent property has been explicitly set and should therefore be persisted.


 TreeView.addNode

TreeView.addNode

Adds a root node to the tree view control.

Syntax

public TreeNode addNode( String text )

public void addNode( TreeNode node )

Parameters

text

The text for the new tree node.

node

A TreeNode object that represents the root node to add to the tree view control.

Return Value

Returns a TreeNode object that represents the new node.

Remarks

To add a set of tree nodes at one time, use the setNodes method. To insert a node into the tree view control at a specific position, use the insertNode method.


 TreeView.addOnAfterCheck

TreeView.addOnAfterCheck

Assigns a delegate to the afterCheck event.

Syntax

public void addOnAfterCheck( TreeViewEventHandler value )

Parameters

value

The TreeViewEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the afterCheck event to that method in the Properties window. The afterCheck event occurs when the check box for a tree node has been checked.

See Also removeOnAfterCheck


 TreeView.addOnAfterCollapse

TreeView.addOnAfterCollapse

Assigns a delegate to the afterCollapse event.

Syntax

public void addOnAfterCollapse( TreeViewEventHandler value )

Parameters

value

The TreeViewEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the afterCollapse event to that method in the Properties window. The afterCollapse event occurs when a tree node has been collapsed.

See Also removeOnAfterCollapse


 TreeView.addOnAfterExpand

TreeView.addOnAfterExpand

Assigns a delegate to the afterExpand event.

Syntax

public void addOnAfterExpand( TreeViewEventHandler value )

Parameters

value

The TreeViewEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the afterExpand event to that method in the Properties window. The afterExpand event occurs when a tree node has been expanded.

See Also removeOnAfterExpand


 TreeView.addOnAfterLabelEdit

TreeView.addOnAfterLabelEdit

Assigns a delegate to the afterLabelEdit event.

Syntax

public void addOnAfterLabelEdit( NodeLabelEditEventHandler value )

Parameters

value

The NodeLabelEditEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the afterLabelEdit event to that method in the Properties window. The afterLabelEdit event occurs when the user finishes editing the text for a tree node. The string the user has typed is passed to the event handler, which can reject the change and reset the text to what it was before the user began editing the text. If the labelEdit property is set to false, this event is not triggered, and the user cannot edit in the tree view control.

See Also removeOnAfterLabelEdit


 TreeView.addOnAfterSelect

TreeView.addOnAfterSelect

Assigns a delegate to the afterSelect event.

Syntax

public void addOnAfterSelect( TreeViewEventHandler value )

Parameters

value

The TreeViewEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the afterSelect event to that method in the Properties window. The afterSelect event occurs when the selection in the tree view control has changed.

See Also removeOnAfterSelect


 TreeView.addOnBeforeCheck

TreeView.addOnBeforeCheck

Assigns a delegate to the beforeCheck event.

Syntax

public void addOnBeforeCheck( TreeViewCancelEventHandler value )

Parameters

value

The TreeViewCancelEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the beforeCheck event to that method in the Properties window. The beforeCheck event occurs when the check box for a tree node is about to be checked. If the event handler cancels this event, the check box will not be checked.

See Also removeOnBeforeCheck


 TreeView.addOnBeforeCollapse

TreeView.addOnBeforeCollapse

Assigns a delegate to the beforeCollapse event.

Syntax

public void addOnBeforeCollapse( TreeViewCancelEventHandler value )

Parameters

value

The TreeViewCancelEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the beforeCollapse event to that method in the Properties window. The beforeCollapse event occurs when a tree node is about to be collapsed. If the event handler cancels this event, the node will not be collapsed.

See Also removeOnBeforeCollapse


 TreeView.addOnBeforeExpand

TreeView.addOnBeforeExpand

Assigns a delegate to the beforeExpand event.

Syntax

public void addOnBeforeExpand( TreeViewCancelEventHandler value )

Parameters

value

The TreeViewCancelEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the beforeExpand event to that method in the Properties window. The beforeExpand event occurs when a tree node is about to be expanded. If the event handler cancels this event, the node will not be expanded.

See Also removeOnBeforeExpand


 TreeView.addOnBeforeLabelEdit

TreeView.addOnBeforeLabelEdit

Assigns a delegate to the beforeLabelEdit event.

Syntax

public void addOnBeforeLabelEdit( NodeLabelEditEventHandler value )

Parameters

value

The NodeLabelEditEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the beforeLabelEdit event to that method in the Properties window. The beforeLabelEdit event occurs when the user starts editing the text for a tree node. To prevent the user from editing text in the tree view control, your event handler can cancel this event. If the labelEdit property is set to false, this event is not triggered, and the user cannot edit in the tree view control.

See Also removeOnBeforeLabelEdit


 TreeView.addOnBeforeSelect

TreeView.addOnBeforeSelect

Assigns a delegate to the beforeSelect event.

Syntax

public void addOnBeforeSelect( TreeViewCancelEventHandler value )

Parameters

value

The TreeViewCancelEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the beforeSelect event to that method in the Properties window. The beforeSelect event occurs when the selection in the tree view control is about to change. If the event handler cancels this event, the selection will not change.

See Also removeOnBeforeSelect


 TreeView.addOnItemDrag

TreeView.addOnItemDrag

Assigns a delegate to the itemDrag event.

Syntax

public final void addOnItemDrag( ItemDragEventHandler value )

Parameters

value

The ItemDragEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the itemDrag event to that method in the Properties window. The itemDrag event occurs when the user begins dragging an item.

See Also removeOnItemDrag


 TreeView.beginUpdate

TreeView.beginUpdate

Maintains performance while items are added to the tree view control one at a time by preventing the TreeView control from painting until the endUpdate method is called.

Syntax

public void beginUpdate()

Remarks

Call the endUpdate method when all the items have been added to the tree view control so that the control can resume painting.


 TreeView.collapseAll

TreeView.collapseAll

Collapses all root nodes in the tree view control.

Syntax

public void collapseAll()

Remarks

If you call the expandAll method after calling the collapseAll method, any lower-level roots that were originally expanded will again be expanded.


 TreeView.endUpdate

TreeView.endUpdate

Resumes painting the TreeView control after painting is suspended by the beginUpdate method.

Syntax

public void endUpdate()


 TreeView.expandAll

TreeView.expandAll

Expands all root nodes in the tree view control.

Syntax

public void expandAll()

Remarks

If you call the expandAll method after calling the collapseAll method, any lower-level roots that were originally expanded will again be expanded.


 TreeView.getBorderStyle

TreeView.getBorderStyle

Retrieves a value indicating the kind of border the tree view control has.

Syntax

public int getBorderStyle()

Return Value

Returns an integer that specifies the kind of border the tree view control has. Possible return values are constants defined in the BorderStyle class. If the value is BorderStyle.FIXED_3D, the tree view control has a three-dimensional border.

See Also setBorderStyle


 TreeView.getCheckBoxes

TreeView.getCheckBoxes

Retrieves a boolean value indicating whether a check box appears next to each node in the tree view control.

Syntax

public boolean getCheckBoxes()

Return Value

Returns true if a check box appears next to each node in the tree view control; otherwise, returns false.

See Also setCheckBoxes


 TreeView.getHideSelection

TreeView.getHideSelection

Retrieves a boolean value indicating whether the selected node in the tree view control remains highlighted when the control loses the focus.

Syntax

public boolean getHideSelection()

Return Value

Returns true if the selected node does not appear highlighted when the tree view control loses the focus; returns false if the selected node still appears highlighted when the tree view control loses the focus.

See Also setHideSelection


 TreeView.getHotTracking

TreeView.getHotTracking

Retrieves a boolean value indicating whether nodes in the tree view control are highlighted as the mouse pointer passes over them.

Syntax

public boolean getHotTracking()

Return Value

Returns true if the tree view control provides feedback to the user by highlighting the node that the mouse pointer is positioned over; otherwise, returns false.

See Also setHotTracking


 TreeView.getImageIndex

TreeView.getImageIndex

Retrieves the index of the image that appears by default next to nodes in the tree view control.

Syntax

public int getImageIndex()

Return Value

Returns the zero-based index within an ImageList object of the image that appears by default next to the node.

Remarks

The default image will not appear next to a node if you have explicitly set the imageIndex property for that node to another image. In addition, if you have set the selectedImageIndex property of the tree view control to a different image, that image will appear next to the node instead of the default image when the node is selected. To display images in a tree view control, you must create an ImageList object, add images to the ImageList object, associate the ImageList object with the TreeView control using the setImageList method, and specify which image to display next to nodes in the tree view using the setImageIndex method. If you want a different image to display next to a node when it is selected, use the setSelectedImageIndex method.

See Also setImageIndex


 TreeView.getImageList

TreeView.getImageList

Retrieves the image list control associated with the tree view control.

Syntax

public ImageList getImageList()

Return Value

Returns an ImageList object that contains a set of images from which you can choose the image to display next to nodes and the image to display next to the selected node.

See Also setImageList


 TreeView.getIndent

TreeView.getIndent

Retrieves the distance, in pixels, that nodes are indented relative to their parent nodes.

Syntax

public int getIndent()

Return Value

Returns an integer that represents the number of pixels by which each level of nodes is indented relative to the level above.

See Also setIndent


 TreeView.getLabelEdit

TreeView.getLabelEdit

Retrieves a boolean value indicating whether the user can edit the labels of tree view nodes.

Syntax

public boolean getLabelEdit()

Return Value

Returns true if the user can edit the labels of tree view nodes at run time; otherwise, returns false.

See Also setLabelEdit


 TreeView.getNode

TreeView.getNode

Retrieves the node at the specified zero-based index.

Syntax

public TreeNode getNode( int index )

Parameters

index

The index of the node to retrieve.

Return Value

Returns a TreeNode object that represents the retrieved tree node.

See Also setNode


 TreeView.getNodeAt

TreeView.getNodeAt

Retrieves the node at the specified location.

Syntax

public TreeNode getNodeAt( int x, int y )

public TreeNode getNodeAt( Point pt )

Parameters

x

The x-coordinate of the location to test (expressed in client coordinates).

y

The y-coordinate of the location to test (expressed in client coordinates).

pt

A Point object that contains the x- and y-coordinates of the location to test (expressed in client coordinates).

Return Value

Returns a TreeNode object that represents the tree node at the specified location. If there is no node at the specified location, returns null.


 TreeView.getNodeCount

TreeView.getNodeCount

Retrieves the number of root nodes contained in the tree view control.

Syntax

public int getNodeCount()

public int getNodeCount( boolean includeSubTrees )

Parameters

includeSubTrees

Set to true to include all nodes in the tree view control; set to false (or omit) to include only root nodes.

Return Value

Returns an integer that represents the number of nodes contained in the tree view control.


 TreeView.getNodes

TreeView.getNodes

Retrieves an array containing all the root nodes in the tree view control.

Syntax

public TreeNode[] getNodes()

Return Value

Returns a zero-based array of TreeNode objects that represent the root nodes in the tree view control.

See Also setNodes


 TreeView.getPathSeparator

TreeView.getPathSeparator

Retrieves the delimiter character used in the path returned by the TreeNode.getFullPath method.

Syntax

public String getPathSeparator()

Return Value

Returns a string, usually a single character, that is used as the delimiter character in the path returned by the TreeNode.getFullPath method.

See Also setPathSeparator


 TreeView.getScrollable

TreeView.getScrollable

Retrieves a boolean value indicating whether a scroll bar is added to the tree view control when there is not enough room to display all the tree view nodes in the control's client area.

Syntax

public boolean getScrollable()

Return Value

Returns true if scroll bars are added to the control when necessary to allow the user to see all the nodes; otherwise, returns false.

See Also setScrollable


 TreeView.getSelectedImageIndex

TreeView.getSelectedImageIndex

Retrieves the index of the image that appears next to the node that is currently selected in the tree view control.

Syntax

public int getSelectedImageIndex()

Return Value

Returns the zero-based index within an ImageList object of the image that appears next to the node that is currently selected in the tree view control.

Remarks

To display images in a tree view control, you must create an ImageList object, add images to the ImageList object, associate the ImageList object with the TreeView control using the setImageList method, and specify which image to display next to nodes in the tree view using the setImageIndex method. If you want a different image to display next to a node when it is selected, use the setSelectedImageIndex method.

See Also setSelectedImageIndex


 TreeView.getSelectedNode

TreeView.getSelectedNode

Retrieves the currently selected node in the tree view control.

Syntax

public TreeNode getSelectedNode()

Return Value

Returns a TreeNode object that represents the currently selected node in the tree view control. If no node is currently selected, returns null.

See Also setSelectedNode


 TreeView.getShowLines

TreeView.getShowLines

Retrieves a boolean value indicating whether a line is drawn to connect each child node to its parent node in the tree view control.

Syntax

public boolean getShowLines()

Return Value

Returns true if a line is drawn to connect each child node to its parent node when the child node is visible in the tree view control; otherwise, returns false.

See Also setShowLines


 TreeView.getShowPlusMinus

TreeView.getShowPlusMinus

Retrieves a boolean value indicating whether a plus (+) or minus (-) button, which allows the user to expand or collapse a node by clicking, appears next to tree nodes that have children.

Syntax

public boolean getShowPlusMinus()

Return Value

Returns true if a plus or minus button appears next to tree nodes that have children; otherwise, returns false.

Remarks

The plus and minus buttons appear only next to root nodes if the showRootLines property is set to true.

See Also setShowPlusMinus


 TreeView.getShowRootLines

TreeView.getShowRootLines

Retrieves a boolean value indicating whether a line is drawn to connect all the root nodes of the tree view control.

Syntax

public boolean getShowRootLines()

Return Value

Returns true if a line is drawn to connect all the root nodes of the tree view control; otherwise, returns false.

Remarks

If the showLines property is set to false, no line is drawn to connect the root nodes of the tree view control, even if the value of the rootLines property is set to true.

See Also setShowRootLines


 TreeView.getSorted

TreeView.getSorted

Retrieves a boolean value indicating whether the nodes in the tree view control are sorted alphabetically.

Syntax

public boolean getSorted()

Return Value

Returns true if the nodes are sorted alphabetically; otherwise, returns false.

See Also setSorted


 TreeView.getTopNode

TreeView.getTopNode

Retrieves first visible node in a tree view control.

Syntax

public TreeNode getTopNode()

Return Value

Returns a TreeNode object that represents the first visible node in a tree view control.

Remarks

Initially, the node with the index zero (0) is at the top of the tree view control; if the tree view control contents have been scrolled, a different node can be at the top.


 TreeView.getVisibleCount

TreeView.getVisibleCount

Retrieves the number of nodes that can be fully visible in the tree view control.

Syntax

public int getVisibleCount()

Return Value

Returns the number of nodes that can be fully visible in the tree view control.

Remarks

The number of nodes that can be fully visible in the control can be greater than the number of nodes in the control. The control calculates this value by dividing the height of the client window by the height of an item.


 TreeView.insertNode

TreeView.insertNode

Inserts the specified node into the tree view control as a root node at the specified position.

Syntax

public void insertNode( int index, TreeNode node )

Parameters

index

The zero-based position where you want to insert the node into the tree view control. If this number is less than zero, the node is inserted at the top of the control. If this number is greater than the number of nodes currently in the control, the node is inserted at the bottom of the control.

node

A TreeNode object that represents the node that you want insert into the tree view control.


 TreeView.onAfterCheck

TreeView.onAfterCheck

Triggers the afterCheck event.

Syntax

protected void onAfterCheck( TreeViewEvent e )

Parameters

e

A TreeViewEvent object that provides the event data.

Remarks

When overriding this method, call super.onAfterCheck.

See Also addOnAfterCheck


 TreeView.onAfterCollapse

TreeView.onAfterCollapse

Triggers the afterCollapse event.

Syntax

protected void onAfterCollapse( TreeViewEvent e )

Parameters

e

A TreeViewEvent object that provides the event data.

Remarks

When overriding this method, call super.onAfterCollapse.

See Also addOnAfterCollapse


 TreeView.onAfterExpand

TreeView.onAfterExpand

Triggers the afterExpand event.

Syntax

protected void onAfterExpand( TreeViewEvent e )

Parameters

e

A TreeViewEvent object that provides the event data.

Remarks

When overriding this method, call super.onAfterExpand.

See Also addOnAfterExpand


 TreeView.onAfterLabelEdit

TreeView.onAfterLabelEdit

Triggers the afterLabelEdit event.

Syntax

protected void onAfterLabelEdit( NodeLabelEditEvent e )

Parameters

e

A NodeLabelEditEvent object that provides the event data.

Remarks

When overriding this method, call super.onAfterLabelEdit.

See Also addOnAfterLabelEdit


 TreeView.onAfterSelect

TreeView.onAfterSelect

Triggers the afterSelect event.

Syntax

protected void onAfterSelect( TreeViewEvent e )

Parameters

e

A TreeViewEvent object that provides the event data.

Remarks

When overriding this method, call super.onAfterSelect.

See Also addOnAfterSelect


 TreeView.onBeforeCheck

TreeView.onBeforeCheck

Triggers the beforeCheck event.

Syntax

protected void onBeforeCheck( TreeViewCancelEvent e )

Parameters

e

A TreeViewCancelEvent object that provides the event data.

Remarks

When overriding this method, call super.onBeforeCheck.

See Also addOnBeforeCheck


 TreeView.onBeforeCollapse

TreeView.onBeforeCollapse

Triggers the beforeCollapse event.

Syntax

protected void onBeforeCollapse( TreeViewCancelEvent e )

Parameters

e

A TreeViewCancelEvent object that provides the event data.

Remarks

When overriding this method, call super.onBeforeCollapse.

See Also addOnBeforeCollapse


 TreeView.onBeforeExpand

TreeView.onBeforeExpand

Triggers the beforeExpand event.

Syntax

protected void onBeforeExpand( TreeViewCancelEvent e )

Parameters

e

A TreeViewCancelEvent object that provides the event data.

Remarks

When overriding this method, call super.onBeforeExpand.

See Also addOnBeforeExpand


 TreeView.onBeforeLabelEdit

TreeView.onBeforeLabelEdit

Triggers the beforeLabelEdit event.

Syntax

protected void onBeforeLabelEdit( NodeLabelEditEvent e )

Parameters

e

A NodeLabelEditEvent object that provides the event data.

Remarks

When overriding this method, call super.onBeforeLabelEdit.

See Also addOnBeforeLabelEdit


 TreeView.onBeforeSelect

TreeView.onBeforeSelect

Triggers the beforeSelect event.

Syntax

protected void onBeforeSelect( TreeViewCancelEvent e )

Parameters

e

A TreeViewCancelEvent object that provides the event data.

Remarks

When overriding this method, call super.onBeforeSelect.

See Also addOnBeforeSelect


 TreeView.onCreateHandle

TreeView.onCreateHandle

Triggers the createHandle event.

Syntax

protected void onCreateHandle( Event e )

Parameters

e

An Event object that provides the event data.

Remarks

When overriding this method, call super.onCreateHandle.


 TreeView.onItemDrag

TreeView.onItemDrag

Triggers the itemDrag event.

Syntax

protected void onItemDrag( ItemDragEvent e )

Parameters

e

An ItemDragEvent object that provides the event data.

Remarks

When overriding this method, call super.onItemDrag.

See Also addOnItemDrag


 TreeView.removeAll

TreeView.removeAll

Remove all nodes from the tree view control.

Syntax

public void removeAll()


 TreeView.removeOnAfterCheck

TreeView.removeOnAfterCheck

Removes the delegate that is assigned to the afterCheck event.

Syntax

public void removeOnAfterCheck( TreeViewEventHandler value )

Parameters

value

The TreeViewEventHandler delegate to be removed.

See Also addOnAfterCheck


 TreeView.removeOnAfterCollapse

TreeView.removeOnAfterCollapse

Removes the delegate that is assigned to the afterCollapse event.

Syntax

public void removeOnAfterCollapse( TreeViewEventHandler value )

Parameters

value

The TreeViewEventHandler delegate to be removed.

See Also addOnAfterCollapse


 TreeView.removeOnAfterExpand

TreeView.removeOnAfterExpand

Removes the delegate that is assigned to the afterExpand event.

Syntax

public void removeOnAfterExpand( TreeViewEventHandler value )

Parameters

value

The TreeViewEventHandler delegate to be removed.

See Also addOnAfterExpand


 TreeView.removeOnAfterLabelEdit

TreeView.removeOnAfterLabelEdit

Removes the delegate that is assigned to the afterLabelEdit event.

Syntax

public void removeOnAfterLabelEdit( NodeLabelEditEventHandler value )

Parameters

value

The NodeLabelEditEventHandler delegate to be removed.

See Also addOnAfterLabelEdit


 TreeView.removeOnAfterSelect

TreeView.removeOnAfterSelect

Removes the delegate that is assigned to the afterSelect event.

Syntax

public void removeOnAfterSelect( TreeViewEventHandler value )

Parameters

value

The TreeViewEventHandler delegate to be removed.

See Also addOnAfterSelect


 TreeView.removeOnBeforeCheck

TreeView.removeOnBeforeCheck

Removes the delegate that is assigned to the beforeCheck event.

Syntax

public void removeOnBeforeCheck( TreeViewCancelEventHandler value )

Parameters

value

The TreeViewCancelEventHandler delegate to be removed.

See Also addOnBeforeCheck


 TreeView.removeOnBeforeCollapse

TreeView.removeOnBeforeCollapse

Removes the delegate that is assigned to the beforeCollapse event.

Syntax

public void removeOnBeforeCollapse( TreeViewCancelEventHandler value )

Parameters

value

The TreeViewCancelEventHandler delegate to be removed.

See Also addOnBeforeCollapse


 TreeView.removeOnBeforeExpand

TreeView.removeOnBeforeExpand

Removes the delegate that is assigned to the beforeExpand event.

Syntax

public void removeOnBeforeExpand( TreeViewCancelEventHandler value )

Parameters

value

The TreeViewCancelEventHandler delegate to be removed.

See Also addOnBeforeExpand


 TreeView.removeOnBeforeLabelEdit

TreeView.removeOnBeforeLabelEdit

Removes the delegate that is assigned to the beforeLabelEdit event.

Syntax

public void removeOnBeforeLabelEdit( NodeLabelEditEventHandler value )

Parameters

value

The NodeLabelEditEventHandler delegate to be removed.

See Also addOnBeforeLabelEdit


 TreeView.removeOnBeforeSelect

TreeView.removeOnBeforeSelect

Removes the delegate that is assigned to the beforeSelect event.

Syntax

public void removeOnBeforeSelect( TreeViewCancelEventHandler value )

Parameters

value

The TreeViewCancelEventHandler delegate to be removed.

See Also addOnBeforeSelect


 TreeView.removeOnItemDrag

TreeView.removeOnItemDrag

Removes the delegate that is assigned to the itemDrag event.

Syntax

public final void removeOnItemDrag( ItemDragEventHandler value )

Parameters

value

The ItemDragEventHandler delegate to be removed.

See Also addOnItemDrag


 TreeView.resetIndent

TreeView.resetIndent

Resets the indentation to the system default.

Syntax

public void resetIndent()

See Also getIndent, setIndent


 TreeView.setBorderStyle

TreeView.setBorderStyle

Sets a value indicating the kind of border the tree view control has.

Syntax

public void setBorderStyle( int value )

Parameters

value

An integer that specifies the kind of border the tree view control has. Possible return values are constants defined in the BorderStyle class. If the value is BorderStyle.FIXED_3D, the tree view control has a three-dimensional border. The default value is BorderStyle.FIXED_3D.

Exceptions

WFCInvalidEnumException thrown if the specified value is not a valid BorderStyle constant.

See Also getBorderStyle


 TreeView.setCheckBoxes

TreeView.setCheckBoxes

Sets a boolean value indicating whether a check box appears next to each node in the tree view control.

Syntax

public void setCheckBoxes( boolean value )

Parameters

value

Set to true if a check box appears next to each node in the tree view control; otherwise, set to false. The default value is false.

See Also getCheckBoxes


 TreeView.setHideSelection

TreeView.setHideSelection

Sets a boolean value indicating whether the selected node in the tree view control remains highlighted when the control loses the focus.

Syntax

public void setHideSelection( boolean value )

Parameters

value

Set to true if the selected node does not appear highlighted when the tree view control loses the focus; set to false if the selected node still appears highlighted when the tree view control loses the focus. The default value is true.

See Also getHideSelection


 TreeView.setHotTracking

TreeView.setHotTracking

Sets a boolean value indicating whether nodes in the tree view control are highlighted as the mouse pointer passes over them.

Syntax

public void setHotTracking( boolean value )

Parameters

value

Set to true if the tree view control provides feedback to the user by highlighting the node that the mouse pointer is positioned over; otherwise, set to false. The default value is false.

See Also getHotTracking


 TreeView.setImageIndex

TreeView.setImageIndex

Sets the index of the image that appears by default next to nodes in the tree view control.

Syntax

public void setImageIndex( int value )

Parameters

value

The zero-based index within an ImageList object of the image that appears by default next to the node. The default value is zero (0).

Remarks

The default image will not appear next to a node if you have explicitly set the imageIndex property for that node to another image. In addition, if you have set the selectedImageIndex property of the tree view control to a different image, that image will appear next to the node instead of the default image when the node is selected. To display images in a tree view control, you must create an ImageList object, add images to the ImageList object, associate the ImageList object with the TreeView control using the setImageList method, and specify which image to display next to nodes in the tree view using the setImageIndex method. If you want a different image to display next to a node when it is selected, use the setSelectedImageIndex method.

See Also getImageIndex


 TreeView.setImageList

TreeView.setImageList

Sets the image list control associated with the tree view control.

Syntax

public void setImageList( ImageList value )

Parameters

value

An ImageList object that contains a set of images from which you can choose the image to display next to nodes and the image to display next to the selected node. You must create an ImageList object and populate it with images before you can associate the image list with a TreeView control. By default, the tree view control is not associated with an image list. This means that no images (other than the plus (+) or minus (-) that indicates that the node can be expanded or collapsed) appear next to the nodes. To hide the plus and minus signs, set the showPlusMinus property to false.

See Also getImageList


 TreeView.setIndent

TreeView.setIndent

Sets the distance, in pixels, that nodes are indented relative to their parent nodes.

Syntax

public void setIndent( int value )

Parameters

value

An integer that represents the number of pixels by which each level of nodes is indented relative to the level above. The default value is determined by the system.

See Also getIndent


 TreeView.setLabelEdit

TreeView.setLabelEdit

Sets a boolean value indicating whether the user can edit the labels of tree view nodes.

Syntax

public void setLabelEdit( boolean value )

Parameters

value

Set to true if the user can edit the labels of tree view nodes at run time; otherwise, set to false. The default value is false.

See Also getLabelEdit


 TreeView.setNode

TreeView.setNode

Replaces the node at the specified position in the tree view control.

Syntax

public void setNode( int index, TreeNode node )

Parameters

index

The zero-based index of the node you want to replace.

node

A TreeNode object that represents the new node that you want insert in place of the node currently at the specified position.

Exceptions

WFCInvalidArgumentException thrown if the specified index is not valid.

See Also getNode


 TreeView.setNodes

TreeView.setNodes

Adds a set of root nodes to the tree view control.

Syntax

public void setNodes( TreeNode[] nodes )

Parameters

nodes

A zero-based array of TreeNode objects that represent the nodes you want to add to the tree view control.

Remarks

This method removes all existing nodes from the tree view control before inserting the new nodes.

See Also getNodes


 TreeView.setPathSeparator

TreeView.setPathSeparator

Sets the delimiter character used in the path returned by the TreeNode.getFullPath method.

Syntax

public void setPathSeparator( String value )

Parameters

value

A string, usually a single character, to be used as the delimiter character in the path returned by the TreeNode.getFullPath method. The default value is the backslash (\).

See Also getPathSeparator


 TreeView.setScrollable

TreeView.setScrollable

Sets a boolean value indicating whether a scroll bar is added to the tree view control when there is not enough room to display all the tree view nodes in the control's client area.

Syntax

public void setScrollable( boolean value )

Parameters

value

Set to true if scroll bars are added to the control when necessary to allow the user to see all the nodes; otherwise, set to false. The default value is true.

See Also getScrollable


 TreeView.setSelectedImageIndex

TreeView.setSelectedImageIndex

Sets the index of the image that appears next to the node that is currently selected in the tree view control.

Syntax

public void setSelectedImageIndex( int value )

Parameters

value

The zero-based index within an ImageList object of the image that you want to appear next to a node when it is selected in the tree view control. The default value is zero (0).

Remarks

To display images in a tree view control, you must create an ImageList object, add images to the ImageList object, associate the ImageList object with the TreeView control using the setImageList method, and specify which image to display next to nodes in the tree view using the setImageIndex method. If you want a different image to display next to a node when it is selected, use the setSelectedImageIndex method.

See Also getSelectedImageIndex


 TreeView.setSelectedNode

TreeView.setSelectedNode

Selects the specified node in the tree view control.

Syntax

public void setSelectedNode( TreeNode value )

Parameters

value

A TreeNode object that represents the node to select in the tree view control.

See Also getSelectedNode


 TreeView.setShowLines

TreeView.setShowLines

Sets a boolean value indicating whether a line connects each child node to its parent node in the tree view control.

Syntax

public void setShowLines( boolean value )

Parameters

value

Set to true if a line is drawn to connect each child node to its parent node when the child node is visible in the tree view control; otherwise, set to false. The default value is true.

See Also getShowLines


 TreeView.setShowPlusMinus

TreeView.setShowPlusMinus

Sets a boolean value indicating whether a plus (+) or minus (-) button, which allows the user to expand or collapse a node by clicking, appears next to tree nodes that have children.

Syntax

public void setShowPlusMinus( boolean value )

Parameters

value

Set to true if a plus or minus button appears next to tree nodes that have children; otherwise, set to false. The default value is true. The plus and minus buttons appear next to root nodes only if the showRootLines property is set to true.

See Also getShowPlusMinus


 TreeView.setShowRootLines

TreeView.setShowRootLines

Sets a boolean value indicating whether a line is drawn to connect all the root nodes of the tree view control.

Syntax

public void setShowRootLines( boolean value )

Parameters

value

Set to true if a line is drawn to connect all the root nodes of the tree view control; otherwise, set to false. The default value is true.

Remarks

If the showLines property is set to false, no line is drawn to connect the root nodes of the tree view control, even if the value of the showRootLines property is set to true.

See Also getShowRootLines


 TreeView.setSorted

TreeView.setSorted

Sets a boolean value indicating whether the nodes in the tree view control are sorted alphabetically.

Syntax

public void setSorted( boolean value )

Parameters

value

Set to true if the nodes are sorted alphabetically; otherwise, set to false. The default value is false.

See Also getSorted


 TreeView.shouldPersistIndent

TreeView.shouldPersistIndent

Retrieves a boolean value indicating whether the value of the indent property has been explicitly set and should therefore be persisted.

Syntax

public boolean shouldPersistIndent()

Return Value

Returns true if the the indent property has been explicitly set; returns false if the indent property has not been explicitly set, and the system indentation setting is being used.


 TreeView.TreeView

TreeView.TreeView

Creates a TreeView control.

Syntax

public TreeView()


TreeViewCancelEvent Class

Provides data for the beforeCollapse, the beforeExpand, and the beforeSelect events of a TreeView control.

Event
  |
  +--TreeViewEvent
    |
    +--TreeViewCancelEvent

package com.ms.wfc.ui

public class TreeViewCancelEvent
extends TreeViewEvent

Remarks

The beforeCollapse event occurs when a tree node is about to be collapsed. The beforeExpand event occurs when a tree node is about to be expanded. The beforeSelect event occurs when the selection in the tree view control is about to change. The TreeViewCancelEvent object specifies which tree node is about to be expanded, collapsed, or selected and whether the operation has been canceled.

For information about the WFC event model, see Handling Events in WFC.


 TreeViewCancelEvent Methods

TreeViewCancelEvent Methods

Constructors | Description
TreeViewCancelEvent | Creates a TreeViewCancelEvent object.


 TreeViewCancelEvent.TreeViewCancelEvent

TreeViewCancelEvent.TreeViewCancelEvent

Creates a TreeViewCancelEvent object.

Syntax

public TreeViewCancelEvent( TreeNode node, boolean cancel )

Parameters

node

The tree node that is about to be expanded, collapsed, or selected.

cancel

Set to true to cancel the operation; otherwise, set to false.


 TreeViewCancelEvent Fields

TreeViewCancelEvent Fields

Fields | Description
cancel | Specifies whether to cancel the operation.


 TreeViewCancelEvent.cancel

TreeViewCancelEvent.cancel

Specifies whether to cancel the operation.

Syntax

public boolean cancel;


TreeViewCancelEventHandler Delegate

Identifies the method that will handle the beforeCollapse, the beforeExpand, and the beforeSelect events of a TreeView control.

package com.ms.wfc.ui

public multicast delegate
void TreeViewCancelEventHandler( Object sender, TreeViewCancelEvent e );

Remarks

The syntax of the TreeViewCancelEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a TreeViewCancelEvent object that provides the event data.

When you create a TreeViewCancelEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC.


TreeViewEvent Class

Provides data for the afterCollapse, the afterExpand, and the afterSelect events of a TreeView control.

Event
  |
  +--TreeViewEvent

package com.ms.wfc.ui

public class TreeViewEvent
extends Event

Remarks

The afterCollapse event occurs when a tree node has been collapsed. The afterExpand event occurs when a tree node has been expanded. The afterSelect event occurs when the selection in the tree view control has changed. The TreeViewEvent object specifies which tree node has been expanded, collapsed, or selected.

For information about the WFC event model, see Handling Events in WFC.


 TreeViewEvent Methods

TreeViewEvent Methods

Constructors | Description
TreeViewEvent | Creates a TreeViewEvent object.


 TreeViewEvent.TreeViewEvent

TreeViewEvent.TreeViewEvent

Creates a TreeViewEvent object.

Syntax

public TreeViewEvent( TreeNode node )

Parameters

node

The tree node that has been expanded, collapsed, or selected.


 TreeViewEvent Fields

TreeViewEvent Fields

Fields | Description
node | Specifies the tree node that has been expanded, collapsed, or selected.


 TreeViewEvent.node

TreeViewEvent.node

Specifies the tree node that has been expanded, collapsed, or selected.

Syntax

public TreeNode node;


TreeViewEventHandler Delegate

Identifies the method that will handle the afterCollapse, the afterExpand, and the afterSelect events of a TreeView control.

package com.ms.wfc.ui

public multicast delegate
void TreeViewEventHandler( Object sender, TreeViewEvent e );

Remarks

The syntax of the TreeViewEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is a TreeViewEvent object that provides the event data.

When you create a TreeViewEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered.

For more information about delegates, see Handling Events in WFC.


UpDown Class

Encapsulates the up-down control.

Component
  |
  +--Control
    |
    +--UpDown

package com.ms.wfc.ui

public class UpDown
extends Control

Remarks

An up-down control is a pair of arrow buttons that the user can click to increment or decrement a value, such as a scroll position or a number displayed in a companion control. An up-down control is most often used with a companion control, which is called a buddy window. To the user, an up-down control and its buddy window often look like a single control.

You can specify that an up-down control automatically positions itself next to its buddy window and that it automatically sets the caption of the buddy window to its current position. For example, you can use an up-down control with an edit control to prompt the user for numeric input (a combination that is sometimes referred to as a spinner control). An up-down control without a buddy window functions as a sort of simplified scroll bar. For example, a tab control sometimes displays an up-down control to enable the user to scroll additional tabs into view.


 UpDown Methods

UpDown Methods

Constructors | Description
UpDown | Creates an UpDown control.

Methods | Description
addOnUpDownChanged | Assigns a delegate to the upDownChanged event.
addOnValueChanged | Assigns a delegate to the valueChanged event.
decrement | Decreases the value of the up-down control by the default amount (the amount specified by the increment field of the first UpDownAcceleration object in the array returned by the getAcceleration method).
getAcceleration | Retrieves information about how quickly the value of the up-down control changes when the user clicks the up and down arrows in the control.
getAlignment | Retrieves a value indicating how the up-down control is positioned relative to its buddy control.
getAutoBuddy | Retrieves a boolean value indicating whether the up-down control automatically uses the previous control in the tab order as its buddy control (the control that displays the value of the up-down control).
getAutoSize | Retrieves a boolean value indicating whether the up-down control automatically adjusts its size to fit the size of its buddy control.
getBuddyControl | Retrieves the buddy control for the up-down control (the control that displays the value of the up-down control).
getHorizontal | Retrieves a boolean value indicating whether the up-down control's arrows point to the left and right instead of up and down.
getInterceptArrowKeys | Retrieves a boolean value indicating whether the user can press the UP ARROW and DOWN ARROW keys to increment and decrement the value of the up-down control.
getMaximum | Retrieves the upper limit for the value of the up-down control.
getMinimum | Retrieves the lower limit for the value of the up-down control.
getModifyBuddy | Retrieves a boolean value indicating whether text displayed in the buddy control of the up-down control changes to match the value of the up-down control.
getRadix | Retrieves a value indicating whether the buddy control for the up-down control displays numbers in decimal or hexadecimal digits.
getThousandsSeparator | Retrieves a boolean value indicating whether a thousands separator is inserted between every three decimal places.
getValue | Retrieves the value of the up-down control.
getWrap | Retrieves a boolean value indicating whether the value of the up-down control "wraps" back to the minimum value when the user increments the value of the control past the maximum value and "wraps" back to the maximum value when the user decrements the value of the control past the minimum value.
increment | Increases the value of the up-down control by the default amount (the amount specified by the increment field of the first UpDownAcceleration object in the array returned by the getAcceleration method).
onUpDownChanged | Triggers the upDownChanged event.
onValueChanged | Triggers the valueChanged event.
removeOnUpDownChanged | Removes the delegate that is assigned to the upDownChanged event.
removeOnValueChanged | Removes the delegate that is assigned to the valueChanged event.
setAcceleration | Sets how quickly the value of the up-down control changes when the user clicks the up and down arrows in the control.
setAlignment | Sets a value indicating how the up-down control is positioned relative to its buddy control.
setAutoBuddy | Sets a boolean value indicating whether the up-down control automatically uses the previous control in the tab order as its buddy control (the control that displays the value of the up-down control).
setAutoSize | Sets a boolean value indicating whether the up-down control automatically adjusts its size to fit the size of its buddy control.
setBuddyControl | Sets the buddy control for the up-down control (the control that displays the value of the up-down control).
setHorizontal | Sets a boolean value indicating whether the up-down control's arrows point to the left and right instead of up and down.
setInterceptArrowKeys | Sets a boolean value indicating whether the user can press the UP ARROW and DOWN ARROW keys to increment and decrement the value of the up-down control.
setMaximum | Sets the upper limit for the value of the up-down control.
setMinimum | Sets the lower limit for the value of the up-down control.
setModifyBuddy | Sets a boolean value indicating whether text displayed in the buddy control of the up-down control changes to match the value of the up-down control.
setRadix | Sets a value indicating whether the buddy control for the up-down control displays numbers in decimal or hexadecimal digits.
setThousandsSeparator | Sets a boolean value indicating whether a thousands separator is inserted between every three decimal places.
setValue | Sets the value of the up-down control.
setWrap | Sets a boolean value indicating whether the value of the up-down control "wraps" back to the minimum value when the user increments the value of the control past the maximum value and "wraps" back to the maximum value when the user decrements the value of the control past the minimum value.


 UpDown.addOnUpDownChanged

UpDown.addOnUpDownChanged

Assigns a delegate to the upDownChanged event.

Syntax

public void addOnUpDownChanged( UpDownChangedEventHandler value )

Parameters

value

The UpDownChangedEventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the upDownChanged event to that method in the Properties window. The upDownChanged event occurs when the value of the control is about to change as a result of the user's clicking the up or down arrow. This event is sent before the value of the up-down control changes so that the change can be tracked, modified, or canceled.

See Also removeOnUpDownChanged


 UpDown.addOnValueChanged

UpDown.addOnValueChanged

Assigns a delegate to the valueChanged event.

Syntax

public void addOnValueChanged( EventHandler eh )

Parameters

eh

The EventHandler delegate to be notified when the event occurs.

Remarks

Passing an event handler as a parameter to this method is equivalent to setting the valueChanged event to that method in the Properties window. The valueChanged event occurs when the scroll bar position is changed by the user or programmatically.

See Also removeOnValueChanged


 UpDown.decrement

UpDown.decrement

Decreases the value of the up-down control by the default amount (the amount specified by the increment field of the first UpDownAcceleration object in the array returned by the getAcceleration method).

Syntax

public void decrement()

See Also increment


 UpDown.getAcceleration

UpDown.getAcceleration

Retrieves information about how quickly the value of the up-down control changes when the user clicks the up and down arrows in the control.

Syntax

public UpDownAcceleration[] getAcceleration()

Return Value

Returns an array of UpDownAcceleration objects. Each UpDownAcceleration object contains an amount by which to change the value of the up-down control and an amount of time that elapses before the change takes effect. The UpDownAcceleration objects in the array are arranged in ascending order based on the value of their seconds fields.

See Also setAcceleration


 UpDown.getAlignment

UpDown.getAlignment

Retrieves a value indicating how the up-down control is positioned relative to its buddy control.

Syntax

public int getAlignment()

Return Value

Returns an integer indicating whether the up-down control is positioned to the left or right of its buddy control or whether the programmer determines the position of the up-down control relative to its buddy control. Possible return values are constants defined in the UpDownAlignment class.

See Also setAlignment


 UpDown.getAutoBuddy

UpDown.getAutoBuddy

Retrieves a boolean value indicating whether the up-down control automatically uses the previous control in the tab order as its buddy control (the control that displays the value of the up-down control).

Syntax

public boolean getAutoBuddy()

Return Value

Returns true if this up-down control automatically uses the previous control in the tab order as its buddy control; otherwise, returns false.

Remarks

If this property is set to true and there is no previous control in the tab order, the up-down control uses the next control in the tab order as its buddy control. Setting the autoBuddy property to true automatically sets the buddyControl property to the previous control in the tab order. Setting the buddyControl property to something other than the previous control in the tab order (or next control, if there is no previous control), automatically sets the autoBuddy property to false.

See Also setAutoBuddy


 UpDown.getAutoSize

UpDown.getAutoSize

Retrieves a boolean value indicating whether the up-down control automatically adjusts its size to fit the size of its buddy control.

Syntax

public final boolean getAutoSize()

Return Value

Returns true if the up-down control automatically adjusts its size to fit the size of its buddy control; otherwise, returns false.

See Also setAutoSize


 UpDown.getBuddyControl

UpDown.getBuddyControl

Retrieves the buddy control for the up-down control (the control that displays the value of the up-down control).

Syntax

public Control getBuddyControl()

Return Value

Returns a Control object that represents the buddy control for the up-down control. Setting the autoBuddy property to true automatically sets the buddyControl property to the previous control in the tab order. Setting the buddyControl property to something other than the previous control in the tab order (or next control, if there is no previous control), automatically sets the autoBuddy property to false.

See Also setBuddyControl


 UpDown.getHorizontal

UpDown.getHorizontal

Retrieves a boolean value indicating whether the up-down control's arrows point to the left and right instead of up and down.

Syntax

public boolean getHorizontal()

Return Value

Returns true if the arrows on the up-down control point left and right; returns false if the arrows point up and down.

See Also setHorizontal


 UpDown.getInterceptArrowKeys

UpDown.getInterceptArrowKeys

Retrieves a boolean value indicating whether the user can press the UP ARROW and DOWN ARROW keys to increment and decrement the value of the up-down control.

Syntax

public boolean getInterceptArrowKeys()

Return Value

Returns true if the user can press the UP ARROW and DOWN ARROW keys to change the value of the up-down control; otherwise, returns false.

See Also setInterceptArrowKeys


 UpDown.getMaximum

UpDown.getMaximum

Retrieves the upper limit for the value of the up-down control.

Syntax

public int getMaximum()

Return Value

Returns the upper limit for the value of the up-down control.

See Also setMaximum


 UpDown.getMinimum

UpDown.getMinimum

Retrieves the lower limit for the value of the up-down control.

Syntax

public int getMinimum()

Return Value

Returns the lower limit for the value of the up-down control.

See Also setMinimum


 UpDown.getModifyBuddy

UpDown.getModifyBuddy

Retrieves a boolean value indicating whether text displayed in the buddy control of the up-down control changes to match the value of the up-down control.

Syntax

public boolean getModifyBuddy()

Return Value

Returns true if the up-down control modifies the text of its buddy control to match its own value each time that value changes; otherwise, returns false.

Remarks

The text displayed in the buddy control is the value of the buddy control formatted as a decimal or hexadecimal number. To specify whether the value is displayed as a decimal or hexadecimal number, use the setRadix method.

See Also setModifyBuddy


 UpDown.getRadix

UpDown.getRadix

Retrieves a value indicating whether the buddy control for the up-down control displays numbers in decimal or hexadecimal digits.

Syntax

public int getRadix()

Return Value

Returns Radix.DECIMAL if the up-down control's buddy control displays numbers in decimal format; Radix.HEXADECIMAL if the up-down control's buddy control displays numbers in hexadecimal format.

See Also setRadix


 UpDown.getThousandsSeparator

UpDown.getThousandsSeparator

Retrieves a boolean value indicating whether a thousands separator is inserted between every three decimal places.

Syntax

public boolean getThousandsSeparator()

Return Value

Returns true if a thousands separator is inserted between every three decimal places; otherwise, returns false.

See Also setThousandsSeparator


 UpDown.getValue

UpDown.getValue

Retrieves the value of the up-down control.

Syntax

public int getValue()

Return Value

Returns the value of this up-down control.

See Also setValue


 UpDown.getWrap

UpDown.getWrap

Retrieves a boolean value indicating whether the value of the up-down control "wraps" back to the minimum value when the user increments the value of the control past the maximum value and "wraps" back to the maximum value when the user decrements the value of the control past the minimum value.

Syntax

public boolean getWrap()

Return Value

Returns true if the value of the up-down control begins again at the minimum value when the user increments the value of the control past the maximum value and vice versa; otherwise, returns false.

See Also setWrap


 UpDown.increment

UpDown.increment

Increases the value of the up-down control by the default amount (the amount specified by the increment field of the first UpDownAcceleration object in the array returned by the getAcceleration method).

Syntax

public void increment()

See Also decrement


 UpDown.onUpDownChanged

UpDown.onUpDownChanged

Triggers the upDownChanged event.

Syntax

protected void onUpDownChanged( UpDownChangedEvent event )

Parameters

event

An UpDownChangedEvent object that provides the event data.

Remarks

When overriding this method, call super.onUpDownChanged.

See Also addOnUpDownChanged


 UpDown.onValueChanged

UpDown.onValueChanged

Triggers the valueChanged event.

Syntax

protected void onValueChanged( Event e )

Parameters

e

An Event object that provides the event data.

Remarks

When overriding this method, call super.onValueChanged.

See Also addOnValueChanged


 UpDown.removeOnUpDownChanged

UpDown.removeOnUpDownChanged

Removes the delegate that is assigned to the upDownChanged event.

Syntax

public void removeOnUpDownChanged( UpDownChangedEventHandler value )

Parameters

value

The UpDownChangedEventHandler delegate to be removed.

See Also addOnUpDownChanged


 UpDown.removeOnValueChanged

UpDown.removeOnValueChanged

Removes the delegate that is assigned to the valueChanged event.

Syntax

public void removeOnValueChanged( EventHandler eh )

Parameters

eh

The EventHandler delegate to be removed.

See Also addOnValueChanged


 UpDown.setAcceleration

UpDown.setAcceleration

Sets how quickly the value of the up-down control changes when the user clicks the up and down arrows in the control.

Syntax

public void setAcceleration( UpDownAcceleration[] value )

Parameters

value

An array of UpDownAcceleration objects. Each UpDownAcceleration object contains an amount by which to change the value of the up-down control and an amount of time that elapses before the change takes effect. The UpDownAcceleration objects in the array should be arranged in ascending order based on the value of their seconds fields. By default, an up-down control contains three UpDownAcceleration objects: for the first UpDownAcceleration object, the seconds field is set to 0 (zero), and the increment field is set to 1; for the second, the seconds field is set to 2, and the increment field is set to 5; and for the third, the seconds field is set to 5, and the increment field is set to 20. This means that when the user clicks an arrow button, the value of the up-down control changes by 1. If the user clicks an arrow button and holds the mouse button down, the value of the up-down control starts to change by increments of 5 after 2 seconds and starts to change by increments of 20 after 5 seconds.

Exceptions

WFCInvalidArgumentException thrown if the specified value is not valid.

WFCSystemException thrown if the acceleration information cannot be set.

See Also getAcceleration


 UpDown.setAlignment

UpDown.setAlignment

Sets a value indicating how the up-down control is positioned relative to its buddy control.

Syntax

public void setAlignment( int value )

Parameters

value

An integer indicating whether the up-down control is positioned to the left or right of its buddy control or whether the programmer determines the position of the up-down control relative to its buddy control. Possible values are constants defined in the UpDownAlignment class. The default value is UpDownAlignment.RIGHT.

Exceptions

WFCInvalidEnumException thrown if the specified value is not a valid UpDownAlignment constant.

See Also getAlignment


 UpDown.setAutoBuddy

UpDown.setAutoBuddy

Sets a boolean value indicating whether the up-down control automatically uses the previous control in the tab order as its buddy control (the control that displays the value of the up-down control).

Syntax

public void setAutoBuddy( boolean value )

Parameters

value

Set to true if this up-down control automatically uses the previous control in the tab order as its buddy control; otherwise, set to false.

Remarks

The default value is false. If this property is set to true and there is no previous control in the tab order, the up-down control uses the next control in the tab order as its buddy control. Setting the autoBuddy property to true automatically sets the buddyControl property to the previous control in the tab order. Setting the buddyControl property to something other than the previous control in the tab order (or the next control if there is no previous control) automatically sets the autoBuddy property to false.

See Also getAutoBuddy


 UpDown.setAutoSize

UpDown.setAutoSize

Sets a boolean value indicating whether the up-down control automatically adjusts its size to fit the size of its buddy control.

Syntax

public final void setAutoSize( boolean value )

Parameters

value

Set to true if the up-down control automatically adjusts its size to fit the size of its buddy control; otherwise, set to false. The default value is true.

See Also getAutoSize


 UpDown.setBuddyControl

UpDown.setBuddyControl

Sets the buddy control for the up-down control (the control that displays the value of the up-down control).

Syntax

public void setBuddyControl( Control control )

Parameters

control

A Control object that represents the buddy control for the up-down control. Setting the autoBuddy property to true automatically sets the buddyControl property to the previous control in the tab order. Setting the buddyControl property to something other than the previous control in the tab order (or the next control if there is no previous control) automatically sets the autoBuddy property to false.

See Also getBuddyControl


 UpDown.setHorizontal

UpDown.setHorizontal

Sets a boolean value indicating whether the up-down control's arrows point to the left and right instead of up and down.

Syntax

public void setHorizontal( boolean horz )

Parameters

horz

Set to true if the arrows on the up-down control point left and right; set to false if the arrows point up and down. The default value is false.

See Also getHorizontal


 UpDown.setInterceptArrowKeys

UpDown.setInterceptArrowKeys

Sets a boolean value indicating whether the user can press the UP ARROW and DOWN ARROW keys to increment and decrement the value of the up-down control.

Syntax

public void setInterceptArrowKeys( boolean value )

Parameters

value

Set to true if the user can press the UP ARROW and DOWN ARROW keys to change the value of the up-down control; otherwise, set to false. The default value is false.

See Also getInterceptArrowKeys


 UpDown.setMaximum

UpDown.setMaximum

Sets the upper limit for the value of the up-down control.

Syntax

public void setMaximum( int value )

Parameters

value

The upper limit for the value of the up-down control. The default value is 100.

See Also getMaximum


 UpDown.setMinimum

UpDown.setMinimum

Sets the lower limit for the value of the up-down control.

Syntax

public void setMinimum( int value )

Parameters

value

The lower limit for the value of the up-down control. The default value is 0.

See Also getMinimum


 UpDown.setModifyBuddy

UpDown.setModifyBuddy

Sets a boolean value indicating whether text displayed in the buddy control of the up-down control changes to match the value of the up-down control.

Syntax

public void setModifyBuddy( boolean value )

Parameters

value

Set to true if the up-down control modifies the text of its buddy control to match its own value each time that value changes; otherwise, set to false. The default value is true.

Remarks

The text displayed in the buddy control is the value of the buddy control formatted as a decimal or hexadecimal number. To specify whether the value is displayed as a decimal or hexadecimal number, use the setRadix method.

See Also getModifyBuddy


 UpDown.setRadix

UpDown.setRadix

Sets a value indicating whether the buddy control for the up-down control displays numbers in decimal or hexadecimal digits.

Syntax

public void setRadix( int value )

Parameters

value

Set to Radix.DECIMAL if the up-down control's buddy control displays numbers in decimal format; set to Radix.HEXADECIMAL if the up-down control's buddy control displays numbers in hexadecimal format. The default value is Radix.DECIMAL.

Exceptions

WFCInvalidArgumentException thrown if the specified value is not a valid Radix constant.

See Also getRadix


 UpDown.setThousandsSeparator

UpDown.setThousandsSeparator

Sets a boolean value indicating whether a thousands separator is inserted between every three decimal places.

Syntax

public void setThousandsSeparator( boolean value )

Parameters

value

Set to true if a thousands separator is inserted between every three decimal places; otherwise, set to false. The default value is true.

See Also getThousandsSeparator


 UpDown.setValue

UpDown.setValue

Sets the value of the up-down control.

Syntax

public void setValue( int value )

Parameters

value

The value to set for this up-down control.

Exceptions

WFCInvalidArgumentException thrown if the specified value is not within the range delimited by the minimum and maximum properties.

See Also getValue


 UpDown.setWrap

UpDown.setWrap

Sets a boolean value indicating whether the value of the up-down control "wraps" back to the minimum value when the user increments the value of the control past the maximum value and "wraps" back to the maximum value when the user decrements the value of the control past the minimum value.

Syntax

public void setWrap( boolean value )

Parameters

value

Set to true if the value of the up-down control begins again at the minimum value when the user increments the value of the control past the maximum value and vice versa; otherwise, set to false. The default value is false.

See Also getWrap


 UpDown.UpDown

UpDown.UpDown

Creates an UpDown control.

Syntax

public UpDown()


UpDownAcceleration Class

Contains the amount that the up-down control's value changes when the user clicks an arrow button and the amount of time that elapses before the change takes effect.

package com.ms.wfc.ui

public class UpDownAcceleration
implements IConstructable

Remarks

An up-down control can contain an array of UpDownAcceleration objects. The value change specified by each UpDownAcceleration object takes effect after the number of seconds specified by its seconds field have elapsed and remains in effect until the value change specified by the next UpDownAcceleration object in the array takes effect.

For example, an up-down control contains three UpDownAcceleration objects by default: for the first UpDownAcceleration object, the seconds field is set to 0 (zero), and the increment field is set to 1; for the second, the seconds field is set to 2, and the increment field is set to 5; and for the third, the seconds field is set to 5, and the increment field is set to 20. This means that when the user clicks an arrow button, the value of the up-down control changes by 1. If the user clicks an arrow button and holds the mouse button down, the value of the up-down control starts to change by increments of 5 after 2 seconds and starts to change by increments of 20 after 5 seconds.


 UpDownAcceleration Methods

UpDownAcceleration Methods

Constructors | Description
UpDownAcceleration | Creates an UpDownAcceleration object.


 UpDownAcceleration.UpDownAcceleration

UpDownAcceleration.UpDownAcceleration

Creates an UpDownAcceleration object.

Syntax

public UpDownAcceleration()

public UpDownAcceleration ( int sec, int inc )

Parameters

sec

The number of seconds that elapse before the value change takes effect in the up-down control.

inc

The amount that the value of the up-down control changes.


 UpDownAcceleration Fields

UpDownAcceleration Fields

Fields | Description
increment | Specifies the amount that the value of the up-down control changes.
seconds | Specifies the number of seconds that elapse before the value change takes effect in the up-down control.


 UpDownAcceleration.increment

UpDownAcceleration.increment

Specifies the amount that the value of the up-down control changes.

Syntax

public int increment;


 UpDownAcceleration.seconds

UpDownAcceleration.seconds

Specifies the number of seconds that elapse before the value change takes effect in the up-down control.

Syntax

public int seconds;


UpDownAlignment Class

Defines constants that specify how the up-down control is positioned relative to its buddy control.

Enum
  |
  +--UpDownAlignment

package com.ms.wfc.ui

public class UpDownAlignment
extends Enum


 UpDownAlignment Methods

UpDownAlignment Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 UpDownAlignment.valid

UpDownAlignment.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 UpDownAlignment Fields

UpDownAlignment Fields

Fields | Description
LEFT | Specifies that the up-down control is positioned next to the right edge of the buddy window.
MANUAL | Specifies that the position of the up-down control is determined by the programmer.
RIGHT | Specifies that the up-down control is positioned next to the left edge of the buddy window.


 UpDownAlignment.LEFT

UpDownAlignment.LEFT

Specifies that the up-down control is positioned next to the right edge of the buddy window.

Syntax

public static final int LEFT;

Remarks

The width of the buddy window is decreased to accommodate the width of the up-down control.


 UpDownAlignment.MANUAL

UpDownAlignment.MANUAL

Specifies that the position of the up-down control is determined by the programmer.

Syntax

public static final int MANUAL;


 UpDownAlignment.RIGHT

UpDownAlignment.RIGHT

Specifies that the up-down control is positioned next to the left edge of the buddy window.

Syntax

public static final int RIGHT;

Remarks

The buddy window is moved to the right, and its width is decreased to accommodate the width of the up-down control.


UpDownChangedEvent Class

Provides data for the upDownChanged event of the UpDown object.

Event
  |
  +--UpDownChangedEvent

package com.ms.wfc.ui

public class UpDownChangedEvent
extends Event

Remarks

The upDownChanged event occurs when the value of the control is about to change as a result of the user's clicking the up or down arrow in the up-down control. This event is sent to the parent control of an up-down control before the value of the up-down control changes so that the change can be tracked, modified, or canceled. A UpDownChangedEvent object specifies the current value of the up-down control and the proposed change to this value. If the change is accepted, the new value of the up-down control is the sum of the current value and the proposed change.


 UpDownChangedEvent Methods

UpDownChangedEvent Methods

Constructors | Description
UpDownChangedEvent | Creates an UpDownChangedEvent object.


 UpDownChangedEvent.UpDownChangedEvent

UpDownChangedEvent.UpDownChangedEvent

Creates an UpDownChangedEvent object.

Syntax

public UpDownChangedEvent( int value, int delta )

Parameters

value

The current value of the up-down control. This parameter is for informational use only. This value cannot be modified.

delta

The proposed change to the value of the up-down control. If the change is accepted, the new value of the up-down control is the sum of value and delta.


 UpDownChangedEvent Fields

UpDownChangedEvent Fields

Fields | Description
delta | Specifies the proposed change to the value of the up-down control.
value | Specifies the current value of the up-down control.


 UpDownChangedEvent.delta

UpDownChangedEvent.delta

Specifies the proposed change to the value of the up-down control.

Syntax

public int delta;

Remarks

If the change is accepted, the new value of the up-down control is the sum of the value and delta fields. The new value can be modified. The delta value can also be modified.


 UpDownChangedEvent.value

UpDownChangedEvent.value

Specifies the current value of the up-down control.

Syntax

public final int value;

Remarks

This field is for informational use only. This value cannot be modified.


UpDownChangedEventHandler Delegate

Identifies the method that will handle the upDownChanged event of the UpDown control.

package com.ms.wfc.ui

public multicast delegate
void UpDownChangedEventHandler( Object sender, UpDownChangedEvent e );

Remarks

The syntax of the UpDownChangedEventHandler delegate specifies the signature for the event handler, where sender is the source of the event and e is an UpDownChangedEvent object that provides the event data.

When you create a UpDownChangedEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered. For more information about delegates, see Handling Events in WFC.


UserControl Class

Represents an empty control that can be used in the Forms Designer to create other controls.

Component
  |
  +--Control
    |
    +--Form
      |
      +--UserControl

package com.ms.wfc.ui

public class UserControl
extends Form

Remarks

The UserControl class extends the Form class, thereby inheriting all the standard positioning code and mnemonic-handling code necessary in a user control.


 UserControl Methods

UserControl Methods

Constructors | Description
UserControl | Creates a UserControl object.


 UserControl.UserControl

UserControl.UserControl

Creates a UserControl object.

Syntax

public UserControl()

Remarks

You will almost always want to subclass this class rather than instantiate it directly. Be sure to call super from the constructors of subclasses of this class.


ViewEnum Class

Defines constants that specify how list items are displayed in a list view control.

Enum
  |
  +--ViewEnum

package com.ms.wfc.ui

public class ViewEnum
extends Enum


 ViewEnum Methods

ViewEnum Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 ViewEnum.valid

ViewEnum.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 ViewEnum Fields

ViewEnum Fields

Fields | Description
LARGEICON | Specifies that each item appears as a full-sized icon with a label below it.
LIST | Specifies that each item appears as a small icon with a label to the right of it.
REPORT | Specifies that each item appears on its own line with information arranged in columns.
SMALLICON | Specifies that each item appears as a small icon with a label to the right of it.


 ViewEnum.LARGEICON

ViewEnum.LARGEICON

Specifies that each item appears as a full-sized icon with a label below it.

Syntax

public static final int LARGEICON;


 ViewEnum.LIST

ViewEnum.LIST

Specifies that each item appears as a small icon with a label to the right of it.

Syntax

public static final int LIST;

Remarks

Items are arranged in columns and cannot be dragged.


 ViewEnum.REPORT

ViewEnum.REPORT

Specifies that each item appears on its own line with information arranged in columns.

Syntax

public static final int REPORT;

Remarks

The leftmost column contains the small icon and label, and subsequent columns contain subitems as specified by the application.


 ViewEnum.SMALLICON

ViewEnum.SMALLICON

Specifies that each item appears as a small icon with a label to the right of it.

Syntax

public static final int SMALLICON;


VScrollBar Class

Encapsulates a scroll bar that is always oriented vertically.

Component
  |
  +--Control
    |
    +--ScrollBar
      |
      +--VScrollBar

package com.ms.wfc.ui

public class VScrollBar
extends ScrollBar

See Also HScrollBar


 VScrollBar Methods

VScrollBar Methods

Constructors | Description
VScrollBar | Creates a VScrollBar control.


 VScrollBar.VScrollBar

VScrollBar.VScrollBar

Creates a VScrollBar control.

Syntax

public VScrollBar()


Package com.ms.wfc.util

Provides miscellaneous utility classes.

Classes

ArrayEnumerator

Enumerates all the elements in an Object array.

ArraySorter

Provides methods to sort arrays.

Debug

Provides a set of utility functions for debugging code.

EmptyEnumeratorException

Represents an exception indicating that there are no more elements to enumerate.

EmptyQueueException

Represents an exception indicating that there are no more items in the queue.

EmptyStackException

Represents an exception indicating that there are no more items in the stack.

HashTable

Implements a hash table data structure, which stores key-value pairs.

List

Provides a lightweight, dynamically sizing array.

NumberFormat

Provides number format styles associated with the Value formatting methods.

Root

Represents the debug version of the com.ms.dll.Root class.

StringSorter

Provides methods to perform a locale-based comparison of strings and the sorting of arrays.

Utils

Represents a collection of small utility functions.

Value

Provides methods for data type conversions, string formatting, and string parsing.

Interfaces

IComparer

Allows two objects to be compared.

IEnumerator

Provides a generic enumeration interface.

Delegates

DebugMessageEventHandler

Defines a callback delegate that can be inserted into a message that displays events for the Debug class.


ArrayEnumerator Class

Enumerates all the elements in an Object array.

package com.ms.wfc.util

public class ArrayEnumerator
implements IEnumerator


 ArrayEnumerator Methods

ArrayEnumerator Methods

Constructors | Description
ArrayEnumerator | Creates an ArrayEnumerator object.

Methods | Description
clone | Creates an identical copy of this enumerator.
hasMoreItems | Determines whether there are more items in the array past the current item.
nextItem | Retrieves the next item in the array and increments the current position.
reset | Resets the current position to the first element of the array.


 ArrayEnumerator.ArrayEnumerator

ArrayEnumerator.ArrayEnumerator

Creates an ArrayEnumerator object.

Syntax

public ArrayEnumerator( Object[] items )

Parameters

items

The Object array to enumerate.


 ArrayEnumerator.clone

ArrayEnumerator.clone

Creates an identical copy of this enumerator.

Syntax

public Object clone()

Return Value

Returns a new ArrayEnumerator object that refers to the same Object array but has a unique current position.


 ArrayEnumerator.hasMoreItems

ArrayEnumerator.hasMoreItems

Determines whether there are more items in the array past the current item.

Syntax

public boolean hasMoreItems()

Return Value

Returns true if there are more items in the array; otherwise, returns false.


 ArrayEnumerator.nextItem

ArrayEnumerator.nextItem

Retrieves the next item in the array and increments the current position.

Syntax

public Object nextItem()

Return Value

Returns the next item in the array.

Exceptions

EmptyEnumeratorException thrown if there are no more elements in the array.


 ArrayEnumerator.reset

ArrayEnumerator.reset

Resets the current position to the first element of the array.

Syntax

public void reset()


ArraySorter Class

Provides methods to sort arrays.

package com.ms.wfc.util

public final class ArraySorter

Remarks

Instances of this class are created only by the sort method.


 ArraySorter Methods

ArraySorter Methods

Methods | Description
sort | Sorts an object array using the IComparer interface to compare elements.


 ArraySorter.sort

ArraySorter.sort

Sorts an object array using the IComparer interface to compare elements.

Syntax

public static void sort( Object[] items, IComparer comparer )

public static void sort( Object[] items, int index, int count, IComparer comparer )

Parameters

items

The Object array to sort.

comparer

The IComparer interface to use to compare the elements.

index

The zero-based index at which to begin sorting.

count

The number of elements to sort.


Debug Class

Provides a set of utility functions for debugging code.

package com.ms.wfc.util

public class Debug

Remarks

By using methods in the Debug class to print debugging information and check your logic with assertions, you can make your code more robust without impacting your shipping product's performance.

Methods in the Debug class generally fall into four categories:

  • Methods that print debug information. These methods automatically compile out of your code if you don't have either DEBUG or TRACE conditional switches set.
  • Methods that return strings that contain useful debugging information. These methods are always available.
  • Methods that retrieve values of registry- or environment-configurable switches and are used to switch debug code in and out. These methods automatically compile out of your code or return false if you don't have a DEBUG conditional switch set.
  • Methods that display an assertion dialog box and compile out if the DEBUG conditional switch is not set.

By default, output is routed to the Output window within the Visual Studio Designer. If the application is launched from a command line, the output is directed to a console window. You can redirect the output from within Visual Studio by setting custom properties. The output directory can be specified in the Compile tab in the Project Properties dialog box.

You can redirect the output to a file using the /out command-line switch when running builds from the command line. By default, command-line errors are displayed in a message box.

See Also Debugging Applications


 Debug Methods

Debug Methods

Methods | Description
addOnDisplayAssert | Adds an event handler to display an assertion dialog box.
addOnDisplayMessage | Adds an event handler to display debug information to the user.
assert | Checks for a condition and displays a message if the condition is false.
defineSwitch | Defines a new debug switch.
displaySwitches | Displays a list of switches that the application currently has installed.
fail | Sets an assertion that always fails.
getEnumText | Retrieves the text name for a value defined in an enumerator class.
getExceptionText | Retrieves both the exception name and description and the stack trace for the specified exception.
getObjectText | Retrieves the contents of the specified object.
getStackTraceText | Retrieves the current stack trace for this thread.
getSwitch | Retrieves the value for the specified switch.
getSwitchListText | Retrieves a table of available switches that can be set.
print | Prints the specified message to the current debug output mechanism.
printEnum | Prints the text name for the value defined in an enumerator class.
printEnumIf | Prints the text name for a value defined in an enumerator class.
printException | Prints both the exception name and description and the stack trace to the exception to debug output.
printExceptionIf | Prints both the exception name and description and the stack trace to the exception to debug output.
printIf | Prints the specified message to the current debug output mechanism.
println | Prints the specified message to the current debug output mechanism.
printlnIf | Prints the specified message to the current debug output mechanism.
printObject | Prints the contents of the specified object to debug output.
printObjectIf | Prints the contents of the specified object to debug output.
printStackTrace | Prints a trace of the current callstack to debug output.
printStackTraceIf | Prints a trace of the current callstack to debug output.
printSwitchList | Prints a table of available switches that can be set.
removeOnDisplayAssert | Removes an assertion event handler.
removeOnDisplayMessage | Removes a print event handler.


 Debug.addOnDisplayAssert

Debug.addOnDisplayAssert

Adds an event handler to display an assertion dialog box.

Syntax

public static synchronized void addOnDisplayAssert( DebugMessageEventHandler handler )

Parameters

handler

The DebugMessageEventHandler delegate to route assertions to.

Remarks

Assertion dialog boxes are typically displayed when an unexpected situation occurs in a program, such as hitting the default case of a switch statement when all the values should be covered.

Use the addOnDisplayAssert method to display your own assertion dialog box. The default behavior of the Debug class is to display a Windows message box that contains an assertion message.

See Also assert, removeOnDisplayAssert


 Debug.addOnDisplayMessage

Debug.addOnDisplayMessage

Adds an event handler to display debug information to the user.

Syntax

public static synchronized void addOnDisplayMessage( DebugMessageEventHandler handler )

Parameters

handler

The DebugMessageEventHandler delegate to route debug messages to.

Remarks

The event handler will be called in response to the Debug.print or Debug.println statements. The default behavior of the Debug class is to send this information to System.out.

See Also removeOnDisplayMessage


 Debug.assert

Debug.assert

Checks for a condition and displays a message if the condition is false.

Syntax

public static void assert( boolean condition, String message )

Parameters

condition

The condition to check.

message

A message to display if the condition parameter evaluates to false.

Remarks

It is good practice to guard your coding assumptions with the use of asserts. This method will be omitted from your code unless you have the DEBUG conditional compile switch set.


 Debug.defineSwitch

Debug.defineSwitch

Defines a new debug switch.

Syntax

public static void defineSwitch( String name, String description )

Parameters

name

The name of the switch to define.

description

A string that describes what the switch does.

Remarks

A switch is a debugging tool that allows you to dynamically switch logic bits in and out of code. For example, you may have logic in your code that prints information every time part of your application paints so you can see when and why it is painting. However, you probably don't want to see an endless stream of text displayed all the time. You can use switches to add your special logic but keep it from being invoked unless you need it. You can dynamically switch logic on and off without recompiling, which can reduce development time.

You typically define a switch only once. To define a switch, add a call to Debug.defineSwitch in your class initializer:

import com.ms.wfc.util.Debug;
public class Class1 {
   // Static initializer
   static {
      Debug.defineSwitch("MYSWITCH", "Description of my switch.");
   }
}

This creates the switch when your class loads. To conditionally print information to debug output when MYSWITCH is set, use code such as:

Debug.printlnIf("MYSWITCH", "Print important debugging information here.");

A switch can be set either from the registry or from an environment variable. To set a switch from the registry, type the switch name as a non-zero DWORD value under the key HKEY_CURRENT_USER\Software\Microsoft\WFC\DebugSwitches. To set a switch from the environment, set an environment variable named WFCD_switch name to either 1 or Y.

Switches are set to false in versions of your product that do not have the DEBUG conditional compile switch set.

See Also getSwitch


 Debug.displaySwitches

Debug.displaySwitches

Displays a list of switches that the application currently has installed.

Syntax

public static void displaySwitches()

Remarks

You can make transient modifications to the value of switches from this dialog box. These switches are set to false in versions of your product that do not have the DEBUG conditional compile switch set. This method call is also compiled out.

See Also defineSwitch, getSwitch


 Debug.fail

Debug.fail

Sets an assertion that always fails.

Syntax

public static void fail( String message )

Parameters

message

The message to display.

Remarks

Use the fail method to block code paths that should never be entered. This method will be omitted from your code unless you have the DEBUG conditional compile switch set.


 Debug.getEnumText

Debug.getEnumText

Retrieves the text name for a value defined in an enumerator class.

Syntax

public static String getEnumText( int value, Class enumClass )

Parameters

value

The value of the enumerator.

enumClass

The enumerator class that defines the value.

Return Value

Returns the name of the enumerator value.


 Debug.getExceptionText

Debug.getExceptionText

Retrieves both the exception name and description and the stack trace for the specified exception.

Syntax

public static String getExceptionText( Throwable t )

Parameters

t

The exception to retrieve.

Return Value

Returns a string describing the exception.

See Also printException


 Debug.getObjectText

Debug.getObjectText

Retrieves the contents of the specified object.

Syntax

public static String getObjectText( Object object )

Parameters

object

The object to retrieve the text from.

Return Value

Returns a string describing the fields in the object.


 Debug.getStackTraceText

Debug.getStackTraceText

Retrieves the current stack trace for this thread.

Syntax

public static String getStackTraceText()

Return Value

Returns a string containing the current stack trace.


 Debug.getSwitch

Debug.getSwitch

Retrieves the value for the specified switch.

Syntax

public static boolean getSwitch( String name )

Parameters

name

The name of the switch. This performs a lookup for the actual switch object.

Return Value

Returns true if the switch is set; otherwise, returns false. If the switch name cannot be found, returns false.

Remarks

A switch is a debugging tool that allows you to dynamically swap bits of logic in and out of code. For example, you may have logic in your code that prints information every time part of your application paints so you can see when and why it is painting. However, you probably don't want to see an endless stream of text displayed all the time. You can use switches to add your special logic but keep it from being invoked unless you need it. You can dynamically switch logic on and off without recompiling.

A switch can be set either from the registry or from an environment variable. To set a switch from the registry, type the switch name as a non-zero DWORD value under the key HKEY_CURRENT_USER\Software\Microsoft\WFC\DebugSwitches. To set a switch from the environment, set an environment variable named WFCD_switchName to either 1 or Y.

Note Switches always return false in retail builds, but it is a good idea to wrap your code in a #IF Debug clause to reduce the size of your class file.


 Debug.getSwitchListText

Debug.getSwitchListText

Retrieves a table of available switches that can be set.

Syntax

public static String getSwitchListText()

Return Value

Returns a table listing the available switches and their descriptions.


 Debug.print

Debug.print

Prints the specified message to the current debug output mechanism.

Syntax

public static void print( String message )

Parameters

message

The message to print.

Remarks

By default, this method prints through System.out.print to the screen. If you are running in a native code debugger, it also outputs to the debugger's output window. This method will be omitted from your code unless you have either the DEBUG or TRACE conditional compile switch set.


 Debug.printEnum

Debug.printEnum

Prints the text name for the value defined in an enumerator class.

Syntax

public static void printEnum( int value, Class enumClass )

Parameters

value

The value of the enumerator.

enumClass

The enumerator class that defines the value.

Remarks

This method will be omitted from your code unless you have the DEBUG conditional compile switch set.

See Also getEnumText


 Debug.printEnumIf

Debug.printEnumIf

Prints the text name for a value defined in an enumerator class.

Syntax

public static void printEnumIf( boolean condition, int value, Class enumClass )

public static void printEnumIf( String name, int value, Class enumClass )

Parameters

condition

The condition to check.

value

The value of the enumerator.

enumClass

The enumerator class that defines the value.

name

The name of the switch to check.

Remarks

In the first syntax, this method prints the text name for a value defined in an enumerator class if the specified condition is true. In the second syntax, this method prints the text name for a value defined in an enumerator class if the named switch is set to true.

This method will be omitted from your code unless you have the DEBUG conditional compile switch set.

See Also getEnumText


 Debug.printException

Debug.printException

Prints both the exception name and description and the stack trace to the exception to debug output.

Syntax

public static void printException( Throwable t )

Parameters

t

The exception to print.

Remarks

This method will be omitted from your code unless you have the DEBUG conditional compile switch set.

See Also getExceptionText


 Debug.printExceptionIf

Debug.printExceptionIf

Prints both the exception name and description and the stack trace to the exception to debug output.

Syntax

public static void printExceptionIf( boolean condition, Throwable t )

public static void printExceptionIf( String name, Throwable t )

Parameters

condition

The condition to check.

t

The exception to print.

name

The name of the switch to check.

Remarks

In the first syntax, this method prints the specified exception if the condition evaluates to true. In the second syntax, this method prints the specified exception if the specified switch is set to true.

This method will be omitted from your code unless you have the DEBUG conditional compile switch set.

See Also getExceptionText


 Debug.printIf

Debug.printIf

Prints the specified message to the current debug output mechanism.

Syntax

public static void printIf( boolean condition, String message )

public static void printIf( String name, String message )

Parameters

condition

The condition by which message should be printed.

message

The message to print if condition is true.

name

The name of the switch to check.

Remarks

In the first syntax, this method prints the specified message if the condition evaluates to true. In the second syntax, this method prints the specified message if the specified switch is set to true.

By default, this method prints through System.out.print to the screen. This method will be omitted from your code unless you have the DEBUG conditional compile switch set.


 Debug.println

Debug.println

Prints the specified message to the current debug output mechanism.

Syntax

public static void println( String message )

Parameters

message

The message to print.

Remarks

By default, this method prints through System.out.println to the screen. If you are running the program from within a native code debugger, this outputs to the debugger's window. This method is omitted from your code unless you have the DEBUG conditional compile switch set.


 Debug.printlnIf

Debug.printlnIf

Prints the specified message to the current debug output mechanism.

Syntax

public static void printlnIf( boolean condition, String message )

public static void printlnIf( String name, String message )

Parameters

condition

The condition by which the message should be printed.

message

The message to print.

name

The name of the switch to check.

Remarks

By default, this method prints through System.out.println to the screen. If you are running the program from within a native code debugger, this outputs to the debugger's window. This method will be omitted from your code unless you have the DEBUG conditional compile switch set.


 Debug.printObject

Debug.printObject

Prints the contents of the specified object to debug output.

Syntax

public static void printObject( Object object )

Parameters

object

The object to print.

Remarks

This method will be omitted from your code unless you have either the DEBUG or TRACE conditional compile switches set.

See Also getObjectText


 Debug.printObjectIf

Debug.printObjectIf

Prints the contents of the specified object to debug output.

Syntax

public static void printObjectIf( boolean condition, Object object )

public static void printObjectIf( String name, Object object )

Parameters

condition

The condition to check.

object

The object to print.

name

The name of the switch to check.

Remarks

In the first syntax, this method prints the specified message if the condition evaluates to true. In the second syntax, this method prints the specified message if the specified switch is set to true.

This method will be omitted from your code unless you have either the DEBUG or TRACE conditional compile switches set.

See Also getObjectText


 Debug.printStackTrace

Debug.printStackTrace

Prints a trace of the current callstack to debug output.

Syntax

public static void printStackTrace()

Remarks

This method will be omitted from your code unless you have either the DEBUG or TRACE conditional compile switches set.

See Also getStackTraceText


 Debug.printStackTraceIf

Debug.printStackTraceIf

Prints a trace of the current callstack to debug output.

Syntax

public static void printStackTraceIf( boolean condition )

public static void printStackTraceIf( String name )

Parameters

condition

The condition to check.

name

The name of the switch to check.

Remarks

In the first syntax, this method prints a trace of the current callstack to debug output if the condition evaluates to true. In the second syntax, this method prints a trace of the current callstack if the specified switch is set to true.

This method will be omitted from your code unless you have either the DEBUG or TRACE conditional compile switches set.


 Debug.printSwitchList

Debug.printSwitchList

Prints a table of available switches that can be set.

Syntax

public static void printSwitchList()

Remarks

This method will be omitted from your code unless you have either the DEBUG or TRACE conditional compile switches set.

See Also getSwitchListText


 Debug.removeOnDisplayAssert

Debug.removeOnDisplayAssert

Removes an assertion event handler.

Syntax

public static synchronized void removeOnDisplayAssert( DebugMessageEventHandler handler )

Parameters

handler

The DebugMessageEventHandler delegate to remove.

See also addOnDisplayAssert


 Debug.removeOnDisplayMessage

Debug.removeOnDisplayMessage

Removes a print event handler.

Syntax

public static synchronized void removeOnDisplayMessage( DebugMessageEventHandler handler )

Parameters

handler

The DebugMessageEventHandler delegate to remove.

See also addOnDisplayMessage


DebugMessageEventHandler Delegate

Defines a callback delegate that can be inserted into a message that displays events for the Debug class.

package com.ms.wfc.util

public multicast delegate
void class DebugMessageEventHandler( String message );

Remarks

Use the DebugMessageEventHandler delegate to change the routing of debug events to a file, logging database, or some other location. The delegate is declared as multicast, so you can route a single message to multiple places at one time.

When you create a DebugMessageEventHandler delegate, you specify the method that will handle the event. Once the delegate is assigned to the event, the handler method is automatically invoked whenever the event is triggered. For more information about delegates, see Handling Events in WFC.

See Also Debug, addOnDisplayAssert, addOnDisplayMessage, removeOnDisplayAssert, removeOnDisplayMessage


EmptyEnumeratorException Class

Represents an exception indicating that there are no more elements to enumerate.

WFCException
  |
  +--EmptyEnumeratorException

package com.ms.wfc.util

public class EmptyEnumeratorException
extends WFCException


 EmptyEnumeratorException Methods

EmptyEnumeratorException Methods

Constructors | Description
EmptyEnumeratorException | Creates an EmptyEnumeratorException object.


 EmptyEnumeratorException.EmptyEnumeratorException

EmptyEnumeratorException.EmptyEnumeratorException

Creates an EmptyEnumeratorException object.

Syntax

public EmptyEnumeratorException()

public EmptyEnumeratorException( String s )

Parameters

s

The message to display with this exception. If you do not specify a value for this parameter, the exception has a default localized message.


EmptyQueueException Class

Represents an exception indicating that there are no more items in the queue.

WFCException
  |
  +--EmptyQueueException

package com.ms.wfc.util

public class EmptyQueueException
extends WFCException


 EmptyQueueException Methods

EmptyQueueException Methods

Constructors | Description
EmptyQueueException | Creates an EmptyQueueException object.


 EmptyQueueException.EmptyQueueException

EmptyQueueException.EmptyQueueException

Creates an EmptyQueueException object.

Syntax

public EmptyQueueException()

public EmptyQueueException( String s )

Parameters

s

The message to display when this exception occurs. If you do not specify a value for this parameter, the exception has a default localized message.


EmptyStackException Class

Represents an exception indicating that there are no more items in the stack.

WFCException
  |
  +--EmptyStackException

package com.ms.wfc.util

public class EmptyStackException
extends WFCException


 EmptyStackException Methods

EmptyStackException Methods

Constructors | Description
EmptyStackException | Creates an EmptyStackException object.


 EmptyStackException.EmptyStackException

EmptyStackException.EmptyStackException

Creates an EmptyStackException object.

Syntax

public EmptyStackException()

public EmptyStackException( String s )

Parameters

s

The message to display when this exception occurs. If you do not specify a value for this parameter, the exception has a default localized message.


HashTable Class

Implements a hash table data structure, which stores key-value pairs.

package com.ms.wfc.util

public class HashTable
implements Cloneable

Remarks

A lookup based on key values is extremely fast, but there is the added overhead of maintaining a complete hash table. For a lightweight, dynamic array implementation, see the List class.


 HashTable Methods

HashTable Methods

Constructors | Description
HashTable | Creates a HashTable object.

Methods | Description
clone | Creates an identical copy of this HashTable object.
combine | Computes a combined hash code based on two or more hash codes.
containsKey | Determines whether a key is present in the current list of keys, using a hash code for lookup.
containsValue | Determines whether the value is present in the current list of values.
getEmpty | Determines whether the hash table contains any items.
getKey | Retrieves the key associated with the specified item.
getKeyEnumerator | Retrieves an enumerator for the list of keys.
getKeys | Retrieves the complete list of keys stored in the hash table. This list is not sorted.
getSize | Retrieves the current number of items stored.
getValue | Retrieves the object stored with the specified key.
getValueEnumerator | Retrieves an enumerator for the list of values.
getValues | Retrieves the complete list of values stored in the hash table. This list is not sorted.
hashCode | Retrieves the hash code for the specified object.
rehash | Rehashes the entire hash table, placing all items in the correct place.
removeAllValues | Removes all items from the hash table.
removeValue | Removes the value associated with the specified key.
setValue | Stores a value in the hash table.
toString | Creates a meaningful string representation of the contents of the hash table.


 HashTable.clone

HashTable.clone

Creates an identical copy of this HashTable object.

Syntax

public Object clone()

Return Value

Returns an identical copy of this HashTable object.


 HashTable.combine

HashTable.combine

Computes a combined hash code based on two or more hash codes.

Syntax

public static int combine( int h1, int h2 )

public static int combine( int h1, int h2, int h3 )

public static int combine( int h1, int h2, int h3, int h4 )

public static int combine( int h1, int h2, int h3, int h4, int h5 )

Parameters

h1, h2, h3, h4, h5

The hash codes to be combined.


 HashTable.containsKey

HashTable.containsKey

Determines whether a key is present in the current list of keys, using a hash code for lookup.

Syntax

public boolean containsKey( Object key )

Parameters

key

The key to check.

Return Value

Returns true if the key is found; otherwise, returns false.


 HashTable.containsValue

HashTable.containsValue

Determines whether the value is present in the current list of values.

Syntax

public boolean containsValue( Object value )

Parameters

value

The Object value to search for.

Return Value

Returns true if the value is found; otherwise, returns false.

Remarks

This method scans each element in the hash table and performs a comparison to find the item.


 HashTable.getEmpty

HashTable.getEmpty

Determines whether the hash table contains any items.

Syntax

public boolean getEmpty()

Return Value

Returns true if the hash table contains any items; otherwise, returns false.


 HashTable.getKey

HashTable.getKey

Retrieves the key associated with the specified item.

Syntax

public Object getKey( Object value )

Parameters

value

The value to search for.

Return Value

Returns the key associated with the value.

Remarks

This method scans each element in the hash table and performs a comparison to find the item.


 HashTable.getKeyEnumerator

HashTable.getKeyEnumerator

Retrieves an enumerator for the list of keys.

Syntax

public IEnumerator getKeyEnumerator()

Return Value

Returns an IEnumerator object.


 HashTable.getKeys

HashTable.getKeys

Retrieves the complete list of keys stored in the hash table. This list is not sorted.

Syntax

public Object[] getKeys()

public Object[] getKeys( Class cls )

public Object[] getKeys( Object[] val )

public Object[] getKeys( Object[] val, int offset )

Parameters

cls

The class to create the array from.

val

The Object array to populate with the keys.

offset

The index into the val array to start inserting keys.

Exceptions

WFCInvalidArguementException thrown if the length of the val array is less than the item count.


 HashTable.getSize

HashTable.getSize

Retrieves the current number of items stored.

Syntax

public int getSize()

Return Value

Returns the item count.


 HashTable.getValue

HashTable.getValue

Retrieves the object stored with the specified key.

Syntax

public Object getValue( Object key )

Parameters

key

The key to search for.

Return Value

Returns the object stored with key, or returns null if the key is not found.


 HashTable.getValueEnumerator

HashTable.getValueEnumerator

Retrieves an enumerator for the list of values.

Syntax

public IEnumerator getValueEnumerator()

Return Value

Returns an IEnumerator object.


 HashTable.getValues

HashTable.getValues

Retrieves the complete list of values stored in the hash table. This list is not sorted.

Syntax

public Object[] getValues()

public Object[] getValues( Class cls )

public Object[] getValues( Object[] val )

public Object[] getValues( Object[] val, int offset )

Parameters

cls

The class to create the array from.

val

The Object array to populate with the values.

offset

The index into the val array to begin retrieving keys.

Return Value

Returns the Object array of values.

Exceptions

WFCInvalidArgumentException thrown if the val array is not large enough to hold the list of keys, the offset parameter is out of bounds, or the offset parameter is too small.


 HashTable.hashCode

HashTable.hashCode

Retrieves the hash code for the specified object.

Syntax

public static int hashCode( Object obj )

Parameters

obj

The object to compute the hash code for.


 HashTable.HashTable

HashTable.HashTable

Creates a HashTable object.

Syntax

public HashTable()

public HashTable( int minBuckets )

public HashTable( int minBuckets, float maxAverageDepthT )

Parameters

minBuckets

The minimum number of buckets in the hash table.

maxAverageDepthT

The maximum average depth in all buckets before more buckets are added.

Remarks

By default, the bucket has a maximum average depth of 2.


 HashTable.rehash

HashTable.rehash

Rehashes the entire hash table, placing all items in the correct place.

Syntax

public void rehash()


 HashTable.removeAllValues

HashTable.removeAllValues

Removes all items from the hash table.

Syntax

public void removeAllValues()


 HashTable.removeValue

HashTable.removeValue

Removes the value associated with the specified key.

Syntax

public Object removeValue( Object key )

Parameters

key

The key of the value to remove.

Return Value

Returns the value that was removed, or returns null if the key was not found.


 HashTable.setValue

HashTable.setValue

Stores a value in the hash table.

Syntax

public Object setValue( Object key, Object value )

Parameters

key

The key to store the value under.

value

The value to store.

Return Value

Returns the value that was stored.


 HashTable.toString

HashTable.toString

Creates a meaningful string representation of the contents of the hash table.

Syntax

public String toString()

Return Value

Returns the string representation of the hash table.


IComparer Interface

Allows two objects to be compared.

package com.ms.wfc.util

public interface IComparer

Remarks

This interface is used by the ArraySorter class to implement generic sorting of arrays.


 IComparer Methods

IComparer Methods

Methods | Description
compare | Compares two objects.


 IComparer.compare

IComparer.compare

Compares two objects.

Syntax

public int compare( Object x, Object y )

Parameters

x

The first object to compare.

y

The object to compare with the first object.

Return Value

An implementation of this method must return a value less than zero if x is less than y, a value greater than zero if x is greater than y, or zero if x is equal to y.


IEnumerator Interface

Provides a generic enumeration interface. Objects that implement this interface support sequential scanning of all the contained elements.

Cloneable
  |
  +--IEnumerator

package com.ms.wfc.util

public interface IEnumerator
extends Cloneable


 IEnumerator Methods

IEnumerator Methods

Methods | Description
hasMoreItems | Determines whether there are more items to enumerate.
nextItem | Retrieves the next item.
reset | Resets the current location to the first element.


 IEnumerator.hasMoreItems

IEnumerator.hasMoreItems

Determines whether there are more items to enumerate.

Syntax

public boolean hasMoreItems()

Return Value

Returns true if there are more items to enumerate; otherwise, returns false.


 IEnumerator.nextItem

IEnumerator.nextItem

Retrieves the next item.

Syntax

public Object nextItem()

Return Value

Returns the next item.

Remarks

If the last item has already been retrieved, this method should throw an exception.


 IEnumerator.reset

IEnumerator.reset

Resets the current location to the first element.

Syntax

public void reset()


List Class

Provides a lightweight, dynamically sizing array.

package com.ms.wfc.util

public class List
implements Cloneable

Remarks

The only extra overhead above the array items is 12 bytes that are used to store the increment, capacity, and version of the list. For a key-value store, see HashTable.

None of the methods in this class are synchronized to provide optimal performance. If a list is used in a multithreaded scenario, you should synchronize the list before calling functions, as shown in the following example:

public void doSomething(List list)
{
   Object[] objs;
   synchronized(list) {
      objs = list.getAllItems();
   }

   // Use objs.
}


 List Methods

List Methods

Constructors | Description
List | Creates a List object.

Methods | Description
addItem | Adds an item to the list.
addItems | Adds all items to the list.
clone | Creates an identical copy of this list.
containsItem | Determines whether the specified item is contained in the list.
dequeueItem | Removes an item from the beginning of the list. This removes the item stored at the 0 index.
dequeueItemOrNull | Removes an item from the beginning of the list. This removes the item stored at the 0 index.
enqueueItem | Adds an item to the end of the list.
ensureCapacity | Ensures the minimum capacity of the list.
equals | Tests for equality between this list and the object.
findIndex | Searches the list for the specified item.
findLastIndex | Searches for an item starting from the end of the list.
getAllItems | Retrieves an array containing all the items in the list.
getCapacity | Retrieves the current capacity of the list. This doesn't reflect the number of items.
getEmpty | Determines whether the list currently contains no items.
getItem | Retrieves the item stored at the index location.
getItemEnumerator | Retrieves an enumerator for all the items in the list.
getItems | Retrieves an array containing the items in the list starting at the specified index for a designated number of items.
getSize | Retrieves the current number of items stored in the list.
getVersion | Retrieves the current version of the list.
hashCode | Computes the hash code for this object.
insertItem | Inserts the item at the specified position.
insertItems | Inserts items starting at the specified position.
moveItem | Moves the item from the source index to the destination index.
moveItems | Moves items starting from the source index to the destination index.
peekQueue | Retrieves the next item in the queue without removing it from the queue. This retrieves the item at the beginning of the list.
peekStack | Retrieves the topmost item in the stack without removing it. This retrieves the item at the end of the list.
popItem | Retrieves and removes the topmost item in the stack.
popItemOrNull | Retrieves and removes the topmost item in the stack.
pushItem | Inserts an item into the stack.
removeAllItems | Removes all items from the list.
removeItem | Removes the specified item from the list.
removeItems | Removes a number of items starting at the specified index.
reverseItems | Reverses all items in the list.
setAllItems | Sets all the items in the list given an array of items.
setItem | Sets an item in the list to be the specified item.
setItems | Sets a number of items starting at the specified index.
setSize | Sets the number of items contained in the list.
sort | Sorts the entire list using the specified comparer.
toString | Creates a string representation of this list.
trimToSize | Removes excess space from the list, ensuring that the capacity of the list is equal to the number of items.


 List.addItem

List.addItem

Adds an item to the list.

Syntax

public void addItem( Object item )

Parameters

item

The item to add to the list.

Remarks

If the capacity of the list is exceeded, it automatically doubles in size.


 List.addItems

List.addItems

Adds all items to the list.

Syntax

public void addItems( Object[] items )

public void addItems( Object[] items, int src, int count )

public void addItems( List list )

public void addItems( List list, int src, int count )

Parameters

items

The array of items to add to the list.

src

The index in the items parameter to start adding items from.

count

The number of items to add.

list

The list of items to add to the list.

Exceptions

WFCInvalidArgumentException thrown if upper or lower bounds of the index or count are exceeded.

Remarks

If the capacity of the list is exceeded, it automatically doubles in size.


 List.clone

List.clone

Creates an identical copy of this list.

Syntax

public Object clone()

Return Value

Returns an identical copy of this list.


 List.containsItem

List.containsItem

Determines whether the specified item is contained in the list.

Syntax

public boolean containsItem( Object item )

Parameters

item

The item to search for.

Return Value

Returns true if the item is in the list; otherwise, returns false.


 List.dequeueItem

List.dequeueItem

Removes an item from the beginning of the list. This removes the item stored at the 0 index.

Syntax

public Object dequeueItem()

Return value

Returns the item that was removed.

Exceptions

EmptyQueueException thrown if there are no items in the list.


 List.dequeueItemOrNull

List.dequeueItemOrNull

Removes an item from the beginning of the list. This removes the item stored at the 0 index.

Syntax

public Object dequeueItemOrNull()

Return value

Returns the item that was removed, or returns null if there are no items in the list.


 List.enqueueItem

List.enqueueItem

Adds an item to the end of the list.

Syntax

public void enqueueItem( Object item )

Parameters

item

The item to add.


 List.ensureCapacity

List.ensureCapacity

Ensures the minimum capacity of the list.

Syntax

public final void ensureCapacity( int min )

Parameters

min

The minimum capacity for the list.

Remarks

If the list is not large enough, the capacity is increased by the capacity increment. If the capacity increment is 0, the size of the list doubles.


 List.equals

List.equals

Tests for equality between this list and the object.

Syntax

public boolean equals( Object obj )

Parameters

obj

The object to compare.

Return Value

Returns true if the objects are equal; otherwise, returns false.


 List.findIndex

List.findIndex

Searches the list for the specified item.

Syntax

public int findIndex( Object item )

public int findIndex( Object item, int minIndex )

Parameters

item

The item to search for.

minIndex

The index to start searching from.

Return Value

Returns the index of the item, or returns -1 if the item is not found.


 List.findLastIndex

List.findLastIndex

Searches for an item starting from the end of the list.

Syntax

public int findLastIndex( Object item )

public int findLastIndex( Object item, int maxIndex )

Parameters

item

The item to search for.

maxIndex

The index to start searching from.

Return Value

Returns the index of the item, or returns -1 if the item is not found.


 List.getAllItems

List.getAllItems

Retrieves an array containing all the items in the list.

Syntax

public Object[] getAllItems()

public Object[] getAllItems( Class cls )

public Object[] getAllItems( Object[] val )

public Object[] getAllItems( Object[] val, int offset )

Parameters

cls

The class to make the array. The resulting array will be this type.

val

The array to populate.

offset

The offset in the val parameter at which to start inserting items.

Return Value

Returns the Object array containing all items in the list.

Exceptions

WFCInvalidArgumentException thrown if the val parameter is too small to hold the contents of the list or if the offset parameter is out of bounds.


 List.getCapacity

List.getCapacity

Retrieves the current capacity of the list. This doesn't reflect the number of items.

Syntax

public int getCapacity()

Return Value

Returns the capacity (length) of the list.

See Also getSize


 List.getEmpty

List.getEmpty

Determines whether the list currently contains no items.

Syntax

public boolean getEmpty()

Return Value

Returns true if the list is currently empty; otherwise, returns false.


 List.getItem

List.getItem

Retrieves the item stored at the index location.

Syntax

public Object getItem( int index )

Parameters

index

The index to retrieve the item from.

Return Value

Returns an item from the specified index for the array.

Exceptions

WFCInvalidArgumentException thrown if the index value is greater than the item count or less than zero.


 List.getItemEnumerator

List.getItemEnumerator

Retrieves an enumerator for all the items in the list.

Syntax

public IEnumerator getItemEnumerator()

Return Value

Returns the enumerator for the items in the list.


 List.getItems

List.getItems

Retrieves an array containing the items in the list starting at the specified index for a designated number of items.

Syntax

public Object[] getItems( int src, int count )

public Object[] getItems( int src, int count, Class cls )

public Object[] getItems( int src, int count, Object[] val )

public Object[] getItems( int src, int count, Object[] val, int dst )

Parameters

src

The index to start retrieving items from.

count

The number of items to retrieve.

cls

The class to make the array. The resulting array will be this type.

val

The array to populate.

dst

The index in the val parameter at which to start inserting items.

Return Value

Returns the Object array containing all requested items.

Exceptions

WFCInvalidArgumentException thrown if the src parameter is greater than the item count or less than zero, the count parameter is out of bounds, or the index parameter is out of bounds.

Remarks

The resulting array will be of type cls if it is specified.


 List.getSize

List.getSize

Retrieves the current number of items stored in the list.

Syntax

public int getSize()

Return Value

Returns the item count.


 List.getVersion

List.getVersion

Retrieves the current version of the list.

Syntax

public int getVersion()

Return Value

Returns the version of the list.

Remarks

The version is incremented when any change is made to the list.


 List.hashCode

List.hashCode

Computes the hash code for this object.

Syntax

public int hashCode()

Return Value

Returns the hash code.


 List.insertItem

List.insertItem

Inserts the item at the specified position.

Syntax

public void insertItem( int index, Object item )

Parameters

index

The index to insert the item at.

item

The item to insert.

Exceptions

WFCInvalidArgumentException thrown if the index parameter is greater than the item count or less than zero.

Remarks

Any item with an index equal to or greater than the index parameter is shifted down.


 List.insertItems

List.insertItems

Inserts items starting at the specified position.

Syntax

public void insertItems( int dst, Object[] items )

public void insertItems( int dst, Object[] items, int src, int count )

public void insertItems( int dst, List list )

public void insertItems( int dst, List list, int src, int count )

Parameters

dst

The index to start inserting items at.

items

The Object array of items to insert into the list.

src

The index in items to start inserting from.

count

The number of items to insert.

list

The list of items to insert into the list.

Exceptions

WFCInvalidArgumentException thrown if the src parameter is greater than the item count or less than zero, the count parameter is out of bounds, or the index parameter is out of bounds.

Remarks

Any items with an index equal to or greater than the index parameter are shifted down.


 List.List

List.List

Creates a List object.

Syntax

public List()

public List( int capInit )

public List( int capInit, int capInc )

public List( Object[] items )

public List( Object[] items, int capInc )

Parameters

capInit

The initial capacity for the list.

capInc

The amount to increase the capacity by when the current capacity is exceeded. If no value is specified for this parameter, the capacity increment is 0. When a list has a 0 capacity increment, it doubles in size whenever the capacity is exceeded.

items

The array of items to initially populate the list with.

Remarks

The default constructor has an initial size of 10 items and a capacity increment of 0. When a list is created with a 0 capacity increment, the list doubles in size whenever the capacity is exceeded.


 List.moveItem

List.moveItem

Moves the item from the source index to the destination index.

Syntax

public void moveItem( int src, int dst )

Parameters

src

The source index of the item to move.

dst

The destination index for the item.

Exceptions

WFCInvalidArgumentException thrown if the src parameter is greater than the item count or less than zero or the index parameter is out of bounds.


 List.moveItems

List.moveItems

Moves items starting from the source index to the destination index.

Syntax

public void moveItems( int src, int dst, int count )

Parameters

src

The index of the first item to move.

dst

The destination index of the first item.

count

The number of items to move.

Exceptions

WFCInvalidArgumentException thrown if the src parameter is greater than the item count or less than zero, the count parameter is out of bounds, or the index parameter is out of bounds.


 List.peekQueue

List.peekQueue

Retrieves the next item in the queue without removing it from the queue. This retrieves the item at the beginning of the list.

Syntax

public Object peekQueue()

Return Value

Returns the first item in the queue.


 List.peekStack

List.peekStack

Retrieves the topmost item in the stack without removing it. This retrieves the item at the end of the list.

Syntax

public Object peekStack()

Return Value

Returns the last item in the list, or returns null if there are no items.


 List.popItem

List.popItem

Retrieves and removes the topmost item in the stack.

Syntax

public Object popItem()

Return Value

Returns the last item in the list.

Exceptions

EmptyStackException thrown if there are no items in the stack.


 List.popItemOrNull

List.popItemOrNull

Retrieves and removes the topmost item in the stack.

Syntax

public Object popItemOrNull()

Return Value

Returns the last item in the list, or returns null if there are no items.


 List.pushItem

List.pushItem

Inserts an item into the stack.

Syntax

public void pushItem( Object item )

Parameters

item

The item to insert into the stack.

Remarks

The item is inserted at the end of the list.


 List.removeAllItems

List.removeAllItems

Removes all items from the list.

Syntax

public void removeAllItems()

Return Value

Returns true if the item was removed, or returns false if the item was not found.


 List.removeItem

List.removeItem

Removes the specified item from the list.

Syntax

public boolean removeItem( Object item )

public Object removeItem( int index )

Parameters

item

The item to remove.

index

The index of the item to remove.

Return Value

The first syntax returns true if the item was removed, or returns false if the item was not found. The second syntax returns the index of the item that was removed.

Exceptions

WFCInvalidArgumentException thrown if the index parameter is greater than the item count or less than zero.


 List.removeItems

List.removeItems

Removes a number of items starting at the specified index.

Syntax

public void removeItems( int index, int count )

Parameters

index

The index of the first item to remove.

count

The number of items to remove starting at the specified index.

Remarks

All items after the index parameter are shifted forward.


 List.reverseItems

List.reverseItems

Reverses all items in the list.

Syntax

public void reverseItems()

public void reverseItems( int index, int count )

Parameters

index

The index at which to start reversing.

count

The number of items to reverse.

Exceptions

WFCInvalidArgumentException thrown if either the count parameter or the index parameter is out of bounds.


 List.setAllItems

List.setAllItems

Sets all the items in the list given an array of items.

Syntax

public void setAllItems( Object[] items )

Parameters

items

The Object array to set the list to.

Remarks

The size of the list is modified to match the length of the items array.


 List.setItem

List.setItem

Sets an item in the list to be the specified item.

Syntax

public void setItem( int index, Object item )

Parameters

index

The index of the item to set.

item

The item that replaces the item at the specified index.

Exceptions

WFCInvalidArgumentException thrown if the index parameter is greater than the item count or less than zero.


 List.setItems

List.setItems

Sets a number of items starting at the specified index.

Syntax

public void setItems( int dst, Object[] items )

public void setItems( int dst, Object[] items, int src, int count )

public void setItems( int dst, List list )

public void setItems( int dst, List list, int src, int count )

Parameters

dst

The index at which to start setting items.

items

The Object array of items to set into the list.

src

The index in the items parameter to start copying from.

count

The number of items to set.

list

The list to set the items to.


 List.setSize

List.setSize

Sets the number of items contained in the list.

Syntax

public void setSize( int size )

Parameters

size

The new number of items in the list.

Exceptions

WFCInvalidArgumentException thrown if the size is less than zero.

Remarks

If the new size is larger that the old size, the new items are populated with null values. If the new size is smaller than the old size, items are removed.


 List.sort

List.sort

Sorts the entire list using the specified comparer.

Syntax

public void sort( IComparer comp )

public void sort( IComparer comp, int index, int count )

Parameters

comp

The IComparer object to use to compare items.

index

The index to start sorting from.

count

The number of items to sort.

Exceptions

WFCInvalidArgumentException thrown if either the count parameter or the index parameter is out of bounds.

See Also ArraySorter.sort


 List.toString

List.toString

Creates a string representation of this list.

Syntax

public String toString()

Return Value

Returns the string representation of this list.


 List.trimToSize

List.trimToSize

Removes excess space from the list, ensuring that the capacity of the list is equal to the number of items.

Syntax

public void trimToSize()


NumberFormat Class

Provides number format styles associated with the Value formatting methods.

Enum
  |
  +--NumberFormat

package com.ms.wfc.util

public class NumberFormat
extends Enum


 NumberFormat Methods

NumberFormat Methods

Methods | Description
valid | Determines whether the specified value is one of the constants defined in this class.


 NumberFormat.valid

NumberFormat.valid

Determines whether the specified value is one of the constants defined in this class.

Syntax

public static boolean valid( int value )

Parameters

value

The value to check.

Return Value

Returns true if the value is valid; otherwise, returns false.


 NumberFormat Fields

NumberFormat Fields

Fields | Description
GROUP_DIGITS | Specifies that numbers should be grouped with a thousands separator; for example, "1,000,456".
LEADING_DIGIT | Specifies that a leading digit should be used.
NEGATIVE_PARENS | Specifies that negative values should be placed inside parentheses.
NO_GROUP_DIGITS | Specifies that numbers should not be grouped with a thousands separator; for example; "1000456".
NO_LEADING_DIGIT | Specifies that a leading digit should not be used.
NO_NEGATIVE_PARENS | Specifies that negative values should not be placed inside parentheses.


 NumberFormat.GROUP_DIGITS

NumberFormat.GROUP_DIGITS

Specifies that numbers should be grouped with a thousands separator; for example, "1,000,456".

Syntax

public static final int GROUP_DIGITS;


 NumberFormat.LEADING_DIGIT

NumberFormat.LEADING_DIGIT

Specifies that a leading digit should be used.

Syntax

public static final int LEADING_DIGIT;


 NumberFormat.NEGATIVE_PARENS

NumberFormat.NEGATIVE_PARENS

Specifies that negative values should be placed inside parentheses.

Syntax

public static final int NEGATIVE_PARENS;


 NumberFormat.NO_GROUP_DIGITS

NumberFormat.NO_GROUP_DIGITS

Specifies that numbers should not be grouped with a thousands separator; for example; "1000456".

Syntax

public static final int NO_GROUP_DIGITS;


 NumberFormat.NO_LEADING_DIGIT

NumberFormat.NO_LEADING_DIGIT

Specifies that a leading digit should not be used.

Syntax

public static final int NO_LEADING_DIGIT;


 NumberFormat.NO_NEGATIVE_PARENS

NumberFormat.NO_NEGATIVE_PARENS

Specifies that negative values should not be placed inside parentheses.

Syntax

public static final int NO_NEGATIVE_PARENS;


Root Class

Represents the debug version of the com.ms.dll.Root class.

package com.ms.wfc.util

public class Root

Remarks

This class is useful in tracking down root leaks. All the tracking features are enabled only on debug builds. Therefore, this class can always be used to allocate roots. Note that this does not prevent objects from being released through garbage collection because only the current store has references to the objects.


 Root Methods

Root Methods

Methods | Description
alloc | Allocates a root object.
checkLeaks | Determines whether any roots have been leaked.
free | Frees a root that has been allocated.
get | Retrieves the object associated with the root value.


 Root.alloc

Root.alloc

Allocates a root object.

Syntax

public synchronized static int alloc( Object o )

Parameters

o

The object to be allocated.

Return Value

Returns the root reference of the object.

See Also com.ms.dll.Root.alloc


 Root.checkLeaks

Root.checkLeaks

Determines whether any roots have been leaked.

Syntax

public synchronized static void checkLeaks()

Remarks

This method dumps the results of the search to STDIN using Debug.print.


 Root.free

Root.free

Frees a root that has been allocated.

Syntax

public synchronized static void free( int root )

Parameters

root

The root reference to free.


 Root.get

Root.get

Retrieves the object associated with the root value.

Syntax

public synchronized static Object get( int root )

Parameters

root

The root reference to an object.

Return Value

Returns the object associated with the root value.

See Also com.ms.dll.Root.get


StringSorter Class

Provides methods to perform a locale-based comparison of strings and the sorting of arrays.

package com.ms.wfc.util

public final class StringSorter


 StringSorter Methods

StringSorter Methods

Methods | Description
compare | Compares two strings.
sort | Sorts the elements in an object array.


 StringSorter.compare

StringSorter.compare

Compares two strings.

Syntax

public static int compare( String s1, String s2 )

public static int compare( String s1, String s2, int options )

public static int compare( Locale locale, String s1, String s2, int options )

Parameters

s1

The first string.

s2

The second string.

locale

A Locale object that represents the locale to be used.

options

The string comparison flags. You can specify any bitwise combination of the following flags:

  • IGNORECASE Ignores case.
  • IGNOREKANATYPE Does not differentiate between Hiragana and Katakana characters.
  • IGNORENONSPACE Ignores nonspacing characters (such as accents, diacritics, and vowel marks).
  • IGNORESYMBOLS Ignores symbols.
  • IGNOREWIDTH Does not differentiate between single-byte and double-byte characters.
  • STRINGSORT All nonalphanumeric characters (including the hyphen and apostrophe) come before alphanumeric characters.

Return Value

Returns -1 if s1 is less than s2, 0 if s1 equals s2, or 1 if s1 is greater than s2.

Remarks

If the two strings are different lengths, they are compared up to the length of the shortest one. If they are equal to that point, the return value indicates that the longer string is greater. Note that if the return value is 0, the two strings are equal in the collation sense, though not necessarily identical.

A null string always sorts before a non-null string. Two null strings are considered equal.


 StringSorter.sort

StringSorter.sort

Sorts the elements in an object array.

Syntax

public static void sort( Object[] items )

public static void sort( Object[] items, int index, int count )

public static void sort( String[] keys, Object[] items )

public static void sort( String[] keys, Object[] items, int index, int count )

public static void sort( Object[] items, int options )

public static void sort( Object[] items, int index, int count, int options )

public static void sort( String[] keys, Object[] items, int options )

public static void sort( String[] keys, Object[] items, int index, int count, int options )

public static void sort( Locale locale, Object[] items, int options )

public static void sort( Locale locale, Object[] items, int index, int count, int options )

public static void sort( Locale locale, String[] keys, Object[] items, int options )

public static void sort( Locale locale, String[] keys, Object[] items, int index, int count, int options )

Parameters

items

The object array to sort.

index

The zero-based index at which to begin sorting.

count

The number of elements to sort.

keys

The keys to sort by. If null, the sort key for an element is produced by calling the toString method.

locale

A Locale object that specifies the locale to use. If no value is specified or if null is passed, the current locale is used.

options

The sorting options. You can specify any bitwise combination of the StringSorter fields.

Remarks

This method sorts the array based on the string representation of the elements. If the items array is not a string array, the toString method of each of the elements is called to produce the string representation.

This method also sorts the object array based on the string array. Elements in the keys array specify the sort keys for corresponding elements in the items array. The range of elements given by the index and count parameters is sorted in both arrays according to the specified locale and sorting options.

If the keys parameter is null, the sort keys are instead computed by calling the toString method of each element in the items array. The null keys always sort before non-null keys.


 StringSorter Fields

StringSorter Fields

Fields | Description
DESCENDING | Specifies that two strings are sorted in descending order.
IGNORECASE | Specifies that case is ignored when comparing or sorting two strings.
IGNOREKANATYPE | Specifies that Hiragana and Katakana characters are not differentiated.
IGNORENONSPACE | Specifies that nonspacing characters (such as accents, diacritics, and vowel marks) are ignored when comparing or sorting two strings.
IGNORESYMBOLS | Specifies that symbols are ignored when comparing or sorting two strings.
IGNOREWIDTH | Specifies that character widths are ignored when comparing or sorting two strings.
STRINGSORT | Specifies that punctuation and symbols are treated the same when comparing or sorting strings.


 StringSorter.DESCENDING

StringSorter.DESCENDING

Specifies that two strings are sorted in descending order.

Syntax

public static final int DESCENDING;

Remarks

You can specify this flag in calls to sort, but not in calls to compare.


 StringSorter.IGNORECASE

StringSorter.IGNORECASE

Specifies that case is ignored when comparing or sorting two strings.

Syntax

public static final int IGNORECASE;

Remarks

When this flag is specified in calls to compare and sort, the strings are considered equal if they differ only in case.


 StringSorter.IGNOREKANATYPE

StringSorter.IGNOREKANATYPE

Specifies that Hiragana and Katakana characters are not differentiated.

Syntax

public static final int IGNOREKANATYPE;

Remarks

When this flag is specified in calls to compare and sort, corresponding Hiragana and Katakana characters are treated as equal.


 StringSorter.IGNORENONSPACE

StringSorter.IGNORENONSPACE

Specifies that nonspacing characters (such as accents, diacritics, and vowel marks) are ignored when comparing or sorting two strings.

Syntax

public static final int IGNORENONSPACE;

Remarks

When this flag is specified in calls to compare and sort, the strings are considered equal if they differ only in how characters are accented.


 StringSorter.IGNORESYMBOLS

StringSorter.IGNORESYMBOLS

Specifies that symbols are ignored when comparing or sorting two strings.

Syntax

public static final int IGNORESYMBOLS;

Remarks

When this flag is specified in calls to compare and sort, the strings are considered equal if they differ only in the symbol characters they contain.


 StringSorter.IGNOREWIDTH

StringSorter.IGNOREWIDTH

Specifies that character widths are ignored when comparing or sorting two strings.

Syntax

public static final int IGNOREWIDTH;

Remarks

When this flag is specified in calls to compare and sort, single-byte characters and their corresponding double-byte characters are not differentiated.


 StringSorter.STRINGSORT

StringSorter.STRINGSORT

Specifies that punctuation and symbols are treated the same when comparing or sorting strings.

Syntax

public static final int STRINGSORT;

Remarks

Typically, strings are compared using a word sort technique, where all punctuation marks and other non-alphanumeric characters, except the hyphen and the apostrophe, come before any alphanumeric character. (The hyphen and the apostrophe are treated differently from the other non-alphanumeric symbols to ensure that prefixes such as coop and co-op stay together within a sorted list.)

If the STRINGSORT flag is specified in calls to compare and sort, strings are compared using a string sort technique, where the hyphen and apostrophe are treated like any other nonalphanumeric symbols. They precede the alphanumeric symbols.


Utils Class

Represents a collection of small utility functions.

package com.ms.wfc.util

public class Utils


 Utils Methods

Utils Methods

Methods | Description
appendArrays | Appends two arrays to form a new array.
appendFormat | Appends the specified format string to the buffer using a string array to apply a format.
appendStrings | Appends two strings, even if one or both of the strings are null.
arraysEqual | Compares two arrays for equality.
arrayUnion | Creates a new array from two existing arrays.
capitalize | Capitalizes the first letter of a string.
createPOINT | Creates a Win32 POINT structure from the specified coordinates.
createRECT | Creates a Win32 RECT structure from the specified coordinates.
decapitalize | Converts the first letter of a string to lowercase.
equals | Compares two objects for equality and checks for null values.
format | Formats a string by replacing all occurrences of %n with the specified strings.
getJavaIdentifier | Determines whether the string is a valid Java identifier.
getPrimitiveWord | Determines whether a string is a Java primitive word.
getReservedWord | Determines whether the string is a reserved Java keyword.
getSuperclass | Retrieves the superclass of the specified class.
getSystemErrorMessage | Retrieves the text associated with the last Win32 error.
intToHex | Creates a string that contains the hexadecimal representation of the integer with the specified number of hexadecimal digits.
longToHex | Creates a string that contains the hexadecimal representation of the long value with the specified number of hexadecimal digits.
parseDblList | Parses the string for a list of double values.
parseIntList | Parses the string for a list of integer values.
parseStringList | Parses the string into substrings that are separated by tokens.
quotedChar | Creates a string that contains the specified character that can be put into a stream that can be compiled.
quotedString | Creates a string that contains the same value as the specified string and can be put into a compilable quoted string.
stringsEqual | Compares two strings for equality.
stringsEqualIgnoreCase | Compares two strings for case-insensitive equality.
stripClassName | Retrieves the name of the class without the package name.
trimArray | Trims an array to a specified length.
trimBlanks | Retrieves a substring with the leading and trailing white space removed.
unparseStringList | Retrieves a string that contains each element of the specified strings separated by the specified token.
validateIdentifier | Validates that the string is a valid Java identifier and not a reserved word.


 Utils.appendArrays

Utils.appendArrays

Appends two arrays to form a new array.

Syntax

public static Object[] appendArrays( Class classType, Object[] array1, Object[] array2 )

Parameters

classType

The class type of the resulting array.

array1

The first array to append.

array2

The second array to append.

Return Value

If both array1 and array2 are null, null is returned. If either of these arrays is null and the other is non-null, the non-null array is returned, and the classType parameter is ignored. If both arrays are non-null, a new array of type classType is returned; the values of array1 are copied into the new array, followed by the values of array2.

Exceptions

java.lang.ArrayStoreException thrown if the values in array1 and array2 cannot be stored in the new array of type classType.

See Also appendStrings


 Utils.appendFormat

Utils.appendFormat

Appends the specified format string to the buffer using a string array to apply a format.

Syntax

public static void appendFormat( StringBuffer buffer, String format, String[] args )

Parameters

buffer

The StringBuffer object to append the formatted string to.

format

The format string to append.

args

The string array to apply to the format.

Remarks

The format string can contain parameters in the form of "%0" through "%9" that will be replaced by the elements in the args array. It also replaces the percent (%) character with the current locale's list separator.

The following example generates the string "Of left and right, left is better":

StringBuffer sb = new StringBuffer(256);
String format = "Of %0 and %1, %0 is better";
String[] args = { "left", "right" };
appendFormat(sb, format, args);

See Also format


 Utils.appendStrings

Utils.appendStrings

Appends two strings, even if one or both of the strings are null.

Syntax

public static String appendStrings( String s1, String s2 )

Parameters

s1

The left string to append.

s2

The right string to append.

Return Value

Returns the appended string.


 Utils.arraysEqual

Utils.arraysEqual

Compares two arrays for equality.

Syntax

public static boolean arraysEqual( Object[] array1, Object[] array2 )

Parameters

array1

The first array to compare.

array2

The second array to compare.

Return Value

Returns true if the arrays are equal; otherwise, returns false.

Remarks

Each element is compared to the respective element in the opposite array. If either array is null, this method returns false.


 Utils.arrayUnion

Utils.arrayUnion

Creates a new array from two existing arrays.

Syntax

public static Object[] arrayUnion( Object[] array1, Object[] array2 )

Parameters

array1

The first array to join.

array2

The second array to join.

Return Value

Returns the union of the two arrays. If either array is null, null is returned. If the length of either array is zero, the first array is returned.


 Utils.capitalize

Utils.capitalize

Capitalizes the first letter of a string.

Syntax

public static String capitalize( String name )

Parameters

name

The string to capitalize.

Return Value

Returns the string with the first letter capitalized.


 Utils.createPOINT

Utils.createPOINT

Creates a Win32 POINT structure from the specified coordinates.

Syntax

public static POINT createPOINT( int x, int y )

Parameters

x

The x coordinate location.

y

The y coordinate location.

Return Value

Returns a POINT structure containing the specified values.


 Utils.createRECT

Utils.createRECT

Creates a Win32 RECT structure from the specified coordinates.

Syntax

public static RECT createRECT( int x, int y, int width, int height )

Parameters

x

The x coordinate location.

y

The y coordinate location.

width

The width of the rectangle.

height

The height of the rectangle.

Return Value

Returns a RECT structure containing the specified values.


 Utils.decapitalize

Utils.decapitalize

Converts the first letter of a string to lowercase.

Syntax

public static String decapitalize( String name )

Parameters

name

The string to convert to lowercase.

Return Value

Returns the string with the first letter in lowercase.

Remarks

This method converts the first letter of the string to lowercase if the second letter is lowercase.


 Utils.equals

Utils.equals

Compares two objects for equality and checks for null values.

Syntax

public static boolean equals( Object obj1, Object obj2 )

Parameters

obj1

The first object to compare.

obj2

The second object to compare.

Return Value

Returns true if the objects are equal; otherwise, returns false.


 Utils.format

Utils.format

Formats a string by replacing all occurrences of %n with the specified strings.

Syntax

public static String format( String format, String arg1 )

public static String format( String format, String arg1, String arg2 )

public static String format( String format, String arg1, String arg2, String arg3 )

public static String format( String format, String arg1, String arg2, String arg3, String arg4 )

public static String format( String format, String[] args )

Parameters

format

The string to format.

arg1

The first replacement string for %0.

arg2

The second replacement string for %1.

arg3

The third replacement string for %2.

arg4

The fourth replacement string for %3.

args

The array of replacement strings. Replaces all occurrences of %0 through %9 with items from the array.

Return Value

Returns the formatted string.

Remarks

The percent (%) character is replaced with the current locale's list separator.

See Also appendFormat


 Utils.getJavaIdentifier

Utils.getJavaIdentifier

Determines whether the string is a valid Java identifier.

Syntax

public static boolean getJavaIdentifier( String s )

Parameters

s

The string to check.

Return Value

Returns true if the string is a valid Java identifier; otherwise, returns false.

Remarks

An identifier is an unlimited-length sequence of Java letters and digits, the first of which must be a Java letter. An identifier cannot have the same spelling (Unicode sequence) as a keyword, boolean literal, or null literal.


 Utils.getPrimitiveWord

Utils.getPrimitiveWord

Determines whether a string is a Java primitive word.

Syntax

public static boolean getPrimitiveWord( String s )

Parameters

s

The string to check.

Return Value

Returns true if the string is a reserved Java primitive; otherwise, returns false.


 Utils.getReservedWord

Utils.getReservedWord

Determines whether the string is a reserved Java keyword.

Syntax

public static boolean getReservedWord( String s )

Parameters

s

The string to check.

Return Value

Returns true if the string is a reserved Java keyword; otherwise, returns false.


 Utils.getSuperclass

Utils.getSuperclass

Retrieves the superclass of the specified class.

Syntax

public static Class getSuperclass( Class type )

Parameter

type

The class to get the superclass of.

Return Value

Returns the superclass of the specified type.

Remarks

This method correctly returns the superclass of an array class type. For example, the superclass of Control[].class will be returned as Component[].class. The standard Java reflection APIs always return Object.class as the superclass of any array type.


 Utils.getSystemErrorMessage

Utils.getSystemErrorMessage

Retrieves the text associated with the last Win32 error.

Syntax

public static String getSystemErrorMessage()

public static String getSystemErrorMessage( int errorCode )

Parameters

errorCode

The code for the Win32 error that occurred.

Return Value

Returns the text associated with the specified error code.


 Utils.intToHex

Utils.intToHex

Creates a string that contains the hexadecimal representation of the integer with the specified number of hexadecimal digits.

Syntax

public static String intToHex( int value, int digits )

Parameters

value

The integer to create the hexadecimal string for.

digits

The number of hexadecimal digits to put into the string.

Return Value

Returns the hexadecimal representation of the specified value.


 Utils.longToHex

Utils.longToHex

Creates a string that contains the hexadecimal representation of the long value with the specified number of hexadecimal digits.

Syntax

public static String longToHex( long value, int digits )

Parameters

value

The long value to create the hexadecimal string for.

digits

The number of hexadecimal digits to put into the string.

Return Value

Returns the hexadecimal representation of the specified value.


 Utils.parseDblList

Utils.parseDblList

Parses the string for a list of double values.

Syntax

public static double[] parseDblList( String s )

Parameters

s

The string to check.

Return Value

Returns an array of double values found in the string.

Remarks

The double values must be separated by the list character as determined by the region settings. This is typically a comma (,).


 Utils.parseIntList

Utils.parseIntList

Parses the string for a list of integer values.

Syntax

public static int[] parseIntList( String s )

public static int[] parseIntList( String s, char token )

Parameters

s

The string to parse.

token

The token to search for.

Return Value

Returns the array of integer values found in the string.

Remarks

In the first syntax, the integer values must be separated by the list character as determined by the region settings. This is typically a comma (,). In the second syntax, the values must be separated by the token parameter.


 Utils.parseStringList

Utils.parseStringList

Parses the string into substrings that are separated by tokens.

Syntax

public static String[] parseStringList( String s )

public static String[] parseStringList( String s, char token )

public static String[] parseStringList( String s, String token, boolean wantBlanks )

Parameters

s

The string to parse.

token

The token to search for.

wantBlanks

Set to true to include empty entries in the resulting array; otherwise, set to false.

Return Value

Returns the array of strings found.


 Utils.quotedChar

Utils.quotedChar

Creates a string that contains the specified character that can be put into a stream that can be compiled.

Syntax

public static String quotedChar(char c)

Parameters

c

The character to quote.

Return Value

Returns the quoted string.


 Utils.quotedString

Utils.quotedString

Creates a string that contains the same value as the specified string and can be put into a compilable quoted string.

Syntax

public static String quotedString( char c )

public static String quotedString( String s )

public static String quotedString( String s, String quote )

Parameters

c

The character to quote.

s

The string to quote.

quote

The optional character to quote the string with. This character is placed before and after the contents of the resulting string.

Return Value

Returns the quoted string.

Remarks

A character will be placed before and after the contents of the resulting string.


 Utils.stringsEqual

Utils.stringsEqual

Compares two strings for equality.

Syntax

public static boolean stringsEqual( String left, String right )

Parameters

left

The left string to compare.

right

The right string to compare.

Return Value

Returns true if the strings are equal; otherwise, returns false. If either string is null, this method returns false.


 Utils.stringsEqualIgnoreCase

Utils.stringsEqualIgnoreCase

Compares two strings for case-insensitive equality.

Syntax

public static boolean stringsEqualIgnoreCase( String left, String right )

Parameters

left

The left string to compare.

right

The right string to compare.

Return Value

Returns true if the strings are equal; otherwise, returns false. If either string is null, this method returns false.


 Utils.stripClassName

Utils.stripClassName

Retrieves the name of the class without the package name.

Syntax

public static String stripClassName( String name )

Parameters

name

The full class name.

Return Value

Returns the class name without the package name.


 Utils.trimArray

Utils.trimArray

Trims an array to a specified length.

Syntax

public static Object[] trimArray( Object[] ar, int len )

Parameters

ar

The array to trim.

len

The specified length.

Return Value

Returns the array, or returns null if the array is null.


 Utils.trimBlanks

Utils.trimBlanks

Retrieves a substring with the leading and trailing white space removed.

Syntax

public static String trimBlanks( String s )

public static String trimBlanks( String s, int left, int right )

Parameters

s

The string to retrieve the substring from.

left

The starting index of the substring.

right

The ending index of the substring.

Return Value

Returns the substring of the specified string with the leading and trailing white space removed.


 Utils.unparseStringList

Utils.unparseStringList

Retrieves a string that contains each element of the specified strings separated by the specified token.

Syntax

public static String unparseStringList( String[] strings, String token )

Parameters

strings

The array of strings to unpack.

token

The token to insert between elements.

Return Value

Returns the string containing all elements of the specified strings.


 Utils.validateIdentifier

Utils.validateIdentifier

Validates that the string is a valid Java identifier and not a reserved word.

Syntax

public static void validateIdentifier( String s )

Parameters

s

The string to check.

Exceptions

WFCInvalidArgumentException thrown if any condition is not met.


Value Class

Provides methods for data type conversions, string formatting, and string parsing.

package com.ms.wfc.util

public class Value

Remarks

This class supports conversions between primitive types (such as int, double, and boolean), primitive wrapper objects (such as Integer, Double, and Boolean), Strings, variants (objects of type com.ms.com.Variant), and Time objects. The conversion methods fall into the following four categories:

public xxx to xxx( Object value )

Converts an object to a primitive type value. The argument can be a primitive wrapper object, a string, or a variant, and the result is the value of the argument converted to a primitive type.

public Object toObject( xxx value )

Converts a primitive type value or a variant value to a primitive wrapper object. If the argument is a primitive type value, the result is a primitive wrapper object of the corresponding type. If the argument is a variant, the result is a primitive wrapper object that corresponds to the dynamic type of the variant.

public String toString( xxx value )

Converts a primitive type value or an object to a string. If the argument is a primitive type value, the result is the string representation of the value. If the argument is an object, the result is the string produced by calling the object's toString method.

public Variant toVariant( xxx value )

Converts a primitive type value, a primitive wrapper object, or a string to a variant.

The following table lists the associations used by the toObject method to convert a variant to a Java wrapper object.
Variant | Java Class
VariantEmpty | null
VariantNull | null
VariantShort | java.lang.Short
VariantInt | java.lang.Integer
VariantFloat | java.lang.Float
VariantDouble | java.lang.Double
VariantCurrency | java.lang.Double
VariantDate | com.ms.wfc.app.Time
VariantString | java.lang.String
VariantDispatch | java.lang.Object
VariantError | java.lang.Integer
VariantBoolean | java.lang.Boolean
VariantUnknown | java.lang.Object
VariantDecimal | java.lang.Double
VariantSignedChar | java.lang.Byte
VariantByte | java.lang.Byte

The following table lists the associations used by the toVariant method to convert a Java wrapper object to a variant.

Java Class | Variant
java.lang.Object | VariantDispatch
java.lang.Boolean | VariantBoolean
java.lang.Character | VariantShort
java.lang.Byte | VariantByte
java.lang.Short | VariantShort
java.lang.Integer | VariantInt
java.lang.Long | VariantDouble
java.lang.Float | VariantFloat
java.lang.Double | VariantDouble
java.lang.String | VariantString
com.ms.wfc.app.Time | VariantDate


 Value Methods

Value Methods

Methods | Description
assignVariant | Assigns a value to a variant.
format | Formats a value using a format string.
formatCurrency | Formats a numeric value using currency formatting.
formatNumber | Formats a numeric value using number formatting.
isNull | Determines whether a specified value is null.
parseNumber | Converts a string to a number.
toBoolean | Converts an object to a boolean value.
toByte | Converts an object to a byte value.
toChar | Converts an object to a character.
toDouble | Converts an object to a double value.
toFloat | Converts an object to a float value.
toInt | Converts an object to an integer value.
toLong | Converts an object to a long value.
toObject | Converts a boolean value to an object.
toShort | Converts an object to a short value.
toString | Converts a value to a string.
toVariant | Converts a Variant object of one type into another variant type.


 Value.assignVariant

Value.assignVariant

Assigns a value to a variant.

Syntax

public static void assignVariant( Variant v, Object value )

Parameters

v

The variant to assign a value to.

value

The value to assign to the variant.

Remarks

The following actions can occur:

  • If value is a variant, that variant is copied into v.
  • If value is a primitive wrapper object, a String, or a Time object, the appropriate type code and value are stored in the variant.
  • If value is an object of any other type, a Variant.VariantDispatch value is stored in the variant.
  • If value is null, the type code of the variant is set to Variant.VariantNull.

Variant objects should be treated as fixed entities. Once a variant is created, changing the value stored in the variant is not recommended. Whenever possible, avoid using the assignVariant method. Call the toVariant method instead.


 Value.format

Value.format

Formats a value using a format string.

Syntax

public static String format( double value, String format )

public static String format( int value, String format )

public static String format( Object value, String format )

public static String format( double value, String format )

Parameters

value

The value to format.

format

The user-defined format string or name of a predefined format.

Return Value

Returns a string containing the formatted value.


 Value.formatCurrency

Value.formatCurrency

Formats a numeric value using currency formatting.

Syntax

public static String formatCurrency( double value )

public static String formatCurrency( double value, int decimalPlaces )

public static String formatCurrency( double value, int decimalPlaces, int options )

Parameters

value

The value to format.

decimalPlaces

The number of decimal places in the resulting string or -1 for the default number of decimal places.

options

A combination of zero or more flags from the NumberFormat enumeration.

Return Value

Returns the string containing the formatted currency value.

Remarks

The resulting string is formatted according to the currency format settings of the current locale. Use the formatting options to selectively enable or disable the leading digit on values less than 1, the parentheses around negative numbers, and the use of thousands separators.


 Value.formatNumber

Value.formatNumber

Formats a numeric value using number formatting.

Syntax

public static String formatNumber( double value )

public static String formatNumber( double value, int decimalPlaces )

public static String formatNumber( double value, int decimalPlaces, int options )

Parameters

value

The value to format.

decimalPlaces

The number of decimal places in the resulting string or -1 for the default number of decimal places.

options

A combination of zero or more flags from the NumberFormat enumeration.

Return Value

Returns a string containing the formatted value.

Remarks

The resulting string is formatted according to the currency format settings of the current locale. Use the formatting options to selectively enable or disable the leading digit on values less than 1, the parentheses around negative numbers, and the use of the thousands separators.


 Value.isNull

Value.isNull

Determines whether a specified value is null.

Syntax

public static boolean isNull( Object value )

Parameters

value

The value to check.

Return Value

Returns true if the value is null, an empty variant, or a null variant; otherwise, returns false.


 Value.parseNumber

Value.parseNumber

Converts a string to a number.

Syntax

public static double parseNumber( String value )

Parameters

value

The string containing a numeric value.

Return Value

Returns a double value that represents the string.

Exceptions

WFCInvalidArgumentException thrown if the value parameter is null or if the string cannot be interpreted as a number.


 Value.toBoolean

Value.toBoolean

Converts an object to a boolean value.

Syntax

public static boolean toBoolean( Object value )

Parameters

value

The value to convert.

Return Value

Returns a boolean value that represents the object.

Exceptions

ClassCastException thrown if the argument cannot be converted.

Remarks

The following table lists the supported argument types and the resulting conversion.

Type | Conversion
null | Returns false.
Boolean | Returns the boolean value stored in the object. Produced by calling Boolean.booleanValue.
String | Returns true if the string is "true" (case insensitive); otherwise, returns false.
Variant | Returns the result of coercing the variant to a boolean value. Produced by calling Variant.Boolean.

See Also toObject


 Value.toByte

Value.toByte

Converts an object to a byte value.

Syntax

public static byte toByte( Object value )

Parameters

value

The value to convert.

Return Value

Returns a byte value that represents the object.

Exceptions

ClassCastException thrown if the argument cannot be converted.

Remarks

The following table lists the supported argument types and the resulting conversion.

Type | Conversion
null | Returns 0.
Character | Returns the low-order byte of the character stored in the object. Produced by calling Character.charValue.
Number | Returns the byte value of the object. Produced by calling Number.byteValue.
String | Returns the result of converting the numeric string to a byte value. Produced by calling Byte.parseByte.
Variant | Returns the result of coercing the variant to a byte value. Produced by calling Variant.toByte.

See Also toObject


 Value.toChar

Value.toChar

Converts an object to a character.

Syntax

public static char toChar( Object value )

Parameters

value

The value to convert.

Return Value

Returns a character that represents the object.

Exceptions

ClassCastException thrown if the argument cannot be converted.

Remarks

The following table lists the supported argument types and the resulting conversion.

Type | Conversion
null | Returns 0.
Character | Returns the character stored in the object. Produced by calling Character.charValue.
Number | Returns the character value of the object. Produced by calling Number.shortValue and coercing the result to char.
String | Returns the first character of the string, or returns zero if the length of the string is zero.
Variant | Returns the character value of the variant. Produced by calling Variant.toShort and coercing the result to char.

See Also toObject


 Value.toDouble

Value.toDouble

Converts an object to a double value.

Syntax

public static double toDouble( Object value )

Parameters

value

The value to convert.

Return Value

Returns a double value that represents the object.

Exceptions

ClassCastException thrown if the argument cannot be converted.

Remarks

The following table lists the supported argument types and the resulting conversion.

Type | Conversion
null | Returns 0.
Character | Returns the character stored in the object. Produced by calling Character.charValue.
Number | Returns the double value of the object. Produced by calling Number.doubleValue.
String | Returns the result of converting the numeric string to a double value. Produced by calling Double.valueOf.
Time | Returns the double value of the object. Produced by calling Time.toDouble.
Variant | Returns the result of coercing the variant to a double value. Produced by calling Variant.toDouble.

See Also toObject


 Value.toFloat

Value.toFloat

Converts an object to a float value.

Syntax

public static float toFloat( Object value )

Parameters

value

The value to convert.

Return Value

Returns a float value that represents the object.

Exceptions

ClassCastException thrown if the argument cannot be converted.

Remarks

The following table lists the supported argument types and the resulting conversion.

Type | Conversion
null | Returns 0.
Character | Returns the character stored in the object. Produced by calling Character.charValue.
Number | Returns the float value of the object. Produced by calling Number.floatValue.
String | Returns the result of converting the numeric string to a float value. Produced by calling Float.valueOf.
Variant | Returns the result of coercing the variant to a float value. Produced by calling Variant.toFloat.

See Also toObject


 Value.toInt

Value.toInt

Converts an object to an integer value.

Syntax

public static int toInt( Object value )

Parameters

value

The value to convert.

Return Value

Returns an integer value that represents the object.

Exceptions

ClassCastException thrown if the argument cannot be converted.

Remarks

The following table lists the supported argument types and the resulting conversion.

Type | Conversion
null | Returns 0.
Character | Returns the character stored in the object. Produced by calling Character.charValue.
Number | Returns the integer value of the object. Produced by calling Number.intValue.
String | Returns the result of converting the numeric string to an integer value. Produced by calling Integer.parseInt.
Variant | Returns the result of coercing the variant to an integer value. Produced by calling Variant.toInt.

See Also toObject


 Value.toLong

Value.toLong

Converts an object to a long value.

Syntax

public static long toLong( Object value )

Parameters

value

The value to convert.

Return Value

Returns a long value that represents the object.

Exceptions

ClassCastException thrown if the argument cannot be converted.

Remarks

The following table lists the supported argument types and the resulting conversion.

Type | Conversion
null | Returns 0.
Character | Returns the character stored in the object. Produced by calling Character.charValue.
Number | Returns the long value of the object. Produced by calling Number.longValue.
String | Returns the result of converting the numeric string to a long value. Produced by calling Long.parseLong.
Time | Returns the long value of the object. Produced by calling Time.toLong.
Variant | Returns the result of coercing the variant to a double value and then casting the result to long. Produced by calling Variant.toDouble.

See Also toObject


 Value.toObject

Value.toObject

Converts a boolean value to an object.

Syntax

public static Object toObject( boolean value )

Parameters

value

The value to convert.

Return Value

Returns a Boolean object that represents the specified value. This object is either Boolean.TRUE or Boolean.FALSE.

See Also toBoolean


 Value.toShort

Value.toShort

Converts an object to a short value.

Syntax

public static short toShort( Object value )

Parameters

value

The value to convert.

Return Value

Returns a short object that represents the specified value.

Exceptions

ClassCastException thrown if the argument cannot be converted.


 Value.toString

Value.toString

Converts a value to a string.

Syntax

public static String toString( boolean value )

public static String toString( byte value )

public static String toString( char value )

public static String toString( double value )

public static String toString( float value )

public static String toString( int value )

public static String toString( long value )

public static String toString( short value )

public static String toString( Object value )

Parameters

value

The value to convert.

Return Value

Returns a string that represents the specified value.


 Value.toVariant

Value.toVariant

Converts a Variant object of one type into another variant type.

Syntax

public static Variant toVariant( boolean value )

public static Variant toVariant( byte value )

public static Variant toVariant( char value )

public static Variant toVariant( double value )

public static Variant toVariant( float value )

public static Variant toVariant( int value )

public static Variant toVariant( long value )

public static Variant toVariant( short value )

public static Variant toVariant( Object value )

Parameters

value

The value to convert.

Return Value

Returns the converted value.


 Java API

Java API Packages

  • package java.applet
  • package java.awt
  • package java.awt.datatransfer
  • package java.awt.event
  • package java.awt.image
  • package java.beans
  • package java.io
  • package java.lang
  • package java.lang.reflect
  • package java.math
  • package java.net
  • package java.security
  • package java.security.acl
  • package java.security.interfaces
  • package java.sql
  • package java.text
  • package java.util
  • package java.util.zip


 Package java.applet

Package java.applet

All Packages

Interfaces

  • AppletContext
  • AppletStub
  • AudioClip

    • Classes

  • Applet


 Class Applet

Class java.applet.Applet

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.Component
           |
           +----java.awt.Container
                   |
                   +----java.awt.Panel
                           |
                           +----java.applet.Applet

public class Applet
extends Panel

An applet is a small program that is intended not to be run on its own, but rather to be embedded inside another application.

The Applet class must be the superclass of any applet that is to be embedded in a Web page or viewed by the Java Applet Viewer. The Applet class provides a standard interface between applets and their environment.


 Applet Members

Applet Members

Class Overview | This Package | All Packages

Constructors
Name | Description
Applet() |

Methods
Name | Description
destroy() | Called by the browser or applet viewer to inform this applet that it is being reclaimed and that it should destroy any resources that it has allocated.
getAppletContext() | Determines this applet's context, which allows the applet to query and affect the environment in which it runs.
getAppletInfo() | Returns information about this applet.
getAudioClip(URL) | Returns the AudioClip object specified by the URL argument.
getAudioClip(URL, String) | Returns the AudioClip object specified by the URL and name arguments.
getCodeBase() | Gets the base URL.
getDocumentBase() | Gets the document URL.
getImage(URL) | Returns an Image object that can then be painted on the screen.
getImage(URL, String) | Returns an Image object that can then be painted on the screen.
getLocale() | Gets the Locale for the applet, if it has been set.
getParameter(String) | Returns the value of the named parameter in the HTML tag.
getParameterInfo() | Returns information about the parameters than are understood by this applet.
init() | Called by the browser or applet viewer to inform this applet that it has been loaded into the system.
isActive() | Determines if this applet is active.
play(URL) | Plays the audio clip at the specified absolute URL.
play(URL, String) | Plays the audio clip given the URL and a specifier that is relative to it.
resize(Dimension) | Requests that this applet be resized.
resize(int, int) | Requests that this applet be resized.
setStub(AppletStub) | Sets this applet's stub.
showStatus(String) | Requests that the argument string be displayed in the "status window".
start() | Called by the browser or applet viewer to inform this applet that it should start its execution.
stop() | Called by the browser or applet viewer to inform this applet that it should stop its execution.


 Applet.Applet

Applet.Applet

Class Overview | Class Members | This Package | All Packages

Syntax
public Applet()


 Applet.destroy

Applet.destroy

Class Overview | Class Members | This Package | All Packages

Syntax
public void destroy()
Description
Called by the browser or applet viewer to inform this applet that it is being reclaimed and that it should destroy any resources that it has allocated. The stop method will always be called before destroy.

A subclass of Applet should override this method if it has any operation that it wants to perform before it is destroyed. For example, an applet with threads would use the init method to create the threads and the destroy method to kill them.

The implementation of this method provided by the Applet class does nothing.

See Also
init, start, stop


 Applet.getAppletContext

Applet.getAppletContext

Class Overview | Class Members | This Package | All Packages

Syntax
public AppletContext getAppletContext()
Returns
the applet's context.
Description
Determines this applet's context, which allows the applet to query and affect the environment in which it runs.

This environment of an applet represents the document that contains the applet.


 Applet.getAppletInfo

Applet.getAppletInfo

Class Overview | Class Members | This Package | All Packages

Syntax
public String getAppletInfo()
Returns
a string containing information about the author, version, and copyright of the applet.
Description
Returns information about this applet. An applet should override this method to return a String containing information about the author, version, and copyright of the applet.

The implementation of this method provided by the Applet class returns null.


 Applet.getAudioClip

Applet.getAudioClip

Class Overview | Class Members | This Package | All Packages

Syntax 1
public AudioClip getAudioClip( URL url )
Parameters
url
an absolute URL giving the location of the audio clip.
Returns
the audio clip at the specified URL.
Description
Returns the AudioClip object specified by the URL argument.

This method always returns immediately, whether or not the audio clip exists. When this applet attempts to play the audio clip, the data will be loaded.

See Also
AudioClip

Syntax 2
public AudioClip getAudioClip( URL url, String name )
Parameters
url
an absolute URL giving the base location of the audio clip.
name
the location of the audio clip, relative to the url argument.
Returns
the audio clip at the specified URL.
Description
Returns the AudioClip object specified by the URL and name arguments.

This method always returns immediately, whether or not the audio clip exists. When this applet attempts to play the audio clip, the data will be loaded.

See Also
AudioClip


 Applet.getCodeBase

Applet.getCodeBase

Class Overview | Class Members | This Package | All Packages

Syntax
public URL getCodeBase()
Returns
the URL of this applet.
Description
Gets the base URL. This is the URL of the applet itself.

See Also
getDocumentBase


 Applet.getDocumentBase

Applet.getDocumentBase

Class Overview | Class Members | This Package | All Packages

Syntax
public URL getDocumentBase()
Returns
the URL of the document that contains this applet.
Description
Gets the document URL. This is the URL of the document in which the applet is embedded.

See Also
getCodeBase


 Applet.getImage

Applet.getImage

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Image getImage( URL url )
Parameters
url
an absolute URL giving the location of the image.
Returns
the image at the specified URL.
Description
Returns an Image object that can then be painted on the screen. The url that is passed as an argument must specify an absolute URL.

This method always returns immediately, whether or not the image exists. When this 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.

See Also
Image

Syntax 2
public Image getImage( URL url, String name )
Parameters
url
an absolute URL giving the base location of the image.
name
the location of the image, relative to the url argument.
Returns
the image at the specified URL.
Description
Returns an Image object that can then be painted on the screen. The url argument must specify an absolute URL. The name argument is a specifier that is relative to the url argument.

This method always returns immediately, whether or not the image exists. When this 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.

See Also
Image


 Applet.getLocale

Applet.getLocale

Class Overview | Class Members | This Package | All Packages

Syntax
public Locale getLocale()
Returns
A Locale object.
Description
Gets the Locale for the applet, if it has been set. If no Locale has been set, then the default Locale is returned.

Overrides
getLocale in class Component


 Applet.getParameter

Applet.getParameter

Class Overview | Class Members | This Package | All Packages

Syntax
public String getParameter( String name )
Parameters
name
a parameter name.
Returns
the value of the named parameter.
Description
Returns the value of the named parameter in the HTML tag. For example, if this applet is specified as
    <applet code="Clock" width=50 height=50>
    <param name=Color value="blue">
    </applet>

then a call to getParameter("Color") returns the value "blue".

The name argument is case insensitive.


 Applet.getParameterInfo

Applet.getParameterInfo

Class Overview | Class Members | This Package | All Packages

Syntax
public String[][] getParameterInfo()
Returns
an array describing the parameters this applet looks for.
Description
Returns information about the parameters than are understood by this applet. An applet should override this method to return an array of Strings describing these parameters.

Each element of the array should be a set of three Strings containing the name, the type, and a description. For example:

 String pinfo[][] = {
     {"fps",    "1-10",    "frames per second"},
     {"repeat", "boolean", "repeat image loop"},
     {"imgs",   "url",     "images directory"}
 };

The implementation of this method provided by the Applet class returns null.


 Applet.init

Applet.init

Class Overview | Class Members | This Package | All Packages

Syntax
public void init()
Description
Called by the browser or applet viewer to inform this applet that it has been loaded into the system. It is always called before the first time that the start method is called.

A subclass of Applet should override this method if it has initialization to perform. For example, an applet with threads would use the init method to create the threads and the destroy method to kill them.

The implementation of this method provided by the Applet class does nothing.

See Also
destroy, start, stop


 Applet.isActive

Applet.isActive

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isActive()
Returns
true if the applet is active; false otherwise.
Description
Determines if this applet is active. An applet is marked active just before its start method is called. It becomes inactive immediately after its stop method is called.

See Also
start, stop


 Applet.play

Applet.play

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void play( URL url )
Parameters
url
an absolute URL giving the location of the audio clip.
Description
Plays the audio clip at the specified absolute URL. Nothing happens if the audio clip cannot be found.

Syntax 2
public void play( URL url, String name )
Parameters
url
an absolute URL giving the base location of the audio clip.
name
the location of the audio clip, relative to the url argument.
Description
Plays the audio clip given the URL and a specifier that is relative to it. Nothing happens if the audio clip cannot be found.


 Applet.resize

Applet.resize

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void resize( int width, int height )
Parameters
width
the new requested width for the applet.
height
the new requested height for the applet.
Description
Requests that this applet be resized.

Overrides
resize in class Component

Syntax 2
public void resize( Dimension d )
Parameters
d
an object giving the new width and height.
Description
Requests that this applet be resized.

Overrides
resize in class Component


 Applet.setStub

Applet.setStub

Class Overview | Class Members | This Package | All Packages

Syntax
public final void setStub( AppletStub stub )
Parameters
stub
the new stub.
Description
Sets this applet's stub. This is done automatically by the system.


 Applet.showStatus

Applet.showStatus

Class Overview | Class Members | This Package | All Packages

Syntax
public void showStatus( String msg )
Parameters
msg
a string to display in the status window.
Description
Requests that the argument string be displayed in the "status window". Many browsers and applet viewers provide such a window, where the application can inform users of its current state.


 Applet.start

Applet.start

Class Overview | Class Members | This Package | All Packages

Syntax
public void start()
Description
Called by the browser or applet viewer to inform this applet that it should start its execution. It is called after the init method and each time the applet is revisited in a Web page.

A subclass of Applet should override this method if it has any operation that it wants to perform each time the Web page containing it is visited. For example, an applet with animation might want to use the start method to resume animation, and the stop method to suspend the animation.

The implementation of this method provided by the Applet class does nothing.

See Also
destroy, init, stop


 Applet.stop

Applet.stop

Class Overview | Class Members | This Package | All Packages

Syntax
public void stop()
Description
Called by the browser or applet viewer to inform this applet that it should stop its execution. It is called when the Web page that contains this applet has been replaced by another page, and also just before the applet is to be destroyed.

A subclass of Applet should override this method if it has any operation that it wants to perform each time the Web page containing it is no longer visible. For example, an applet with animation might want to use the start method to resume animation, and the stop method to suspend the animation.

The implementation of this method provided by the Applet class does nothing.

See Also
destroy, init


 Interface AppletContext

Interface java.applet.AppletContext

Interface Members | This Package | All Packages

public interface AppletContext

This interface corresponds to an applet's environment: the document containing the applet and the other applets in the same document.

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


 AppletContext Members

AppletContext Members

Interface Overview | This Package | All Packages

Methods
Name | Description
getApplet(String) | Finds and returns the applet in the document represented by this applet context with the given name.
getApplets() | Finds all the applets in the document represented by this applet context.
getAudioClip(URL) | Creates an audio clip.
getImage(URL) | Returns an Image object that can then be painted on the screen.
showDocument(URL) | Replaces the Web page currently being viewed with the given URL.
showDocument(URL, String) | Requests that the browser or applet viewer show the Web page indicated by the url argument.
showStatus(String) | Requests that the argument string be displayed in the "status window".


 AppletContext.getApplet

AppletContext.getApplet

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Applet getApplet( String name )
Parameters
name
an applet name.
Returns
the applet with the given name, or null if not found.
Description
Finds and returns the applet in the document represented by this applet context with the given name. The name can be set in the HTML tag by setting the name attribute.


 AppletContext.getApplets

AppletContext.getApplets

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Enumeration getApplets()
Returns
an enumeration of all applets in the document represented by this applet context.
Description
Finds all the applets in the document represented by this applet context.


 AppletContext.getAudioClip

AppletContext.getAudioClip

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract AudioClip getAudioClip( URL url )
Parameters
url
an absolute URL giving the location of the audio clip.
Returns
the audio clip at the specified URL.
Description
Creates an audio clip.


 AppletContext.getImage

AppletContext.getImage

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Image getImage( URL url )
Parameters
url
an absolute URL giving the location of the image.
Returns
the image at the specified URL.
Description
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.

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.

See Also
Image


 AppletContext.showDocument

AppletContext.showDocument

Interface Overview | Interface Members | This Package | All Packages

Syntax 1
public abstract void showDocument( URL url )
Parameters
url
an absolute URL giving the location of the document.
Description
Replaces the Web page currently being viewed with the given URL. This method may be ignored by applet contexts that are not browsers.

Syntax 2
public abstract void showDocument( URL url, String target )
Parameters
url
an absolute URL giving the location of the document.
target
a String indicating where to display the page.
Description
Requests that the browser or applet viewer show the Web page indicated by the url argument. The target argument indicates where to display the frame. The target argument is interpreted as follows:

"_self" | show in the current frame
"_parent" | show in the parent frame
"_top" | show in the topmost frame
"_blank" | show in a new unnamed top-level window
name | show in a new top-level window named name

An applet viewer or browser is free to ignore showDocument.


 AppletContext.showStatus

AppletContext.showStatus

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void showStatus( String status )
Parameters
status
a string to display in the status window.
Description
Requests that the argument string be displayed in the "status window". Many browsers and applet viewers provide such a window, where the application can inform users of its current state.


 Interface AppletStub

Interface java.applet.AppletStub

Interface Members | This Package | All Packages

public interface AppletStub

When an applet is first created, an applet stub is attached to it using the applet's setStub method. This stub serves as the interface between the applet and the browser environment or applet viewer environment in which the application is running.

See Also:
setStub


 AppletStub Members

AppletStub Members

Interface Overview | This Package | All Packages

Methods
Name | Description
appletResize(int, int) | Called when the applet wants to be resized.
getAppletContext() | Gets a handler to the applet's context.
getCodeBase() | Gets the base URL.
getDocumentBase() | Gets the document URL.
getParameter(String) | Returns the value of the named parameter in the HTML tag.
isActive() | Determines if the applet is active.


 AppletStub.appletResize

AppletStub.appletResize

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void appletResize( int width, int height )
Parameters
width
the new requested width for the applet.
height
the new requested height for the applet.
Description
Called when the applet wants to be resized.


 AppletStub.getAppletContext

AppletStub.getAppletContext

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract AppletContext getAppletContext()
Returns
the applet's context.
Description
Gets a handler to the applet's context.


 AppletStub.getCodeBase

AppletStub.getCodeBase

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract URL getCodeBase()
Returns
the URL of the applet.
Description
Gets the base URL.


 AppletStub.getDocumentBase

AppletStub.getDocumentBase

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract URL getDocumentBase()
Returns
the URL of the document containing the applet.
Description
Gets the document URL.


 AppletStub.getParameter

AppletStub.getParameter

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getParameter( String name )
Parameters
name
a parameter name.
Returns
the value of the named parameter.
Description
Returns the value of the named parameter in the HTML tag. For example, if an applet is specified as
    <applet code="Clock" width=50 height=50>
    <param name=Color value="blue">
    </applet>

then a call to getParameter("Color") returns the value "blue".


 AppletStub.isActive

AppletStub.isActive

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean isActive()
Returns
true if the applet is active; false otherwise.
Description
Determines if the applet is active. An applet is active just before its start method is called. It becomes inactive immediately after its stop method is called.


 Interface AudioClip

Interface java.applet.AudioClip

Interface Members | This Package | All Packages

public interface AudioClip

The AudioClip interface is a simple abstraction for playing a sound clip. Multiple AudioClip items can be playing at the same time, and the resulting sound is mixed together to produce a composite.


 AudioClip Members

AudioClip Members

Interface Overview | This Package | All Packages

Methods
Name | Description
loop() | Starts playing this audio clip in a loop.
play() | Starts playing this audio clip.
stop() | Stops playing this audio clip.


 AudioClip.loop

AudioClip.loop

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void loop()
Description
Starts playing this audio clip in a loop.


 AudioClip.play

AudioClip.play

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void play()
Description
Starts playing this audio clip. Each time this method is called, the clip is restarted from the beginning.


 AudioClip.stop

AudioClip.stop

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void stop()
Description
Stops playing this audio clip.


 Package java.awt

Package java.awt

All Packages

Interfaces

  • Adjustable
  • ItemSelectable
  • LayoutManager
  • LayoutManager2
  • MenuContainer
  • PrintGraphics
  • Shape

    • Classes

  • AWTEvent
  • AWTEventMulticaster
  • BorderLayout
  • Button
  • Canvas
  • CardLayout
  • Checkbox
  • CheckboxGroup
  • CheckboxMenuItem
  • Choice
  • Color
  • Component
  • Container
  • Cursor
  • Dialog
  • Dimension
  • Event
  • EventQueue
  • FileDialog
  • FlowLayout
  • Font
  • FontMetrics
  • Frame
  • Graphics
  • GridBagConstraints
  • GridBagLayout
  • GridLayout
  • Image
  • Insets
  • Label
  • List
  • MediaTracker
  • Menu
  • MenuBar
  • MenuComponent
  • MenuItem
  • MenuShortcut
  • Panel
  • Point
  • Polygon
  • PopupMenu
  • PrintJob
  • Rectangle
  • ScrollPane
  • Scrollbar
  • SystemColor
  • TextArea
  • TextComponent
  • TextField
  • Toolkit
  • Window

    • Exceptions

  • AWTException
  • IllegalComponentStateException

    • Errors

  • AWTError


 Class AWTError

Class java.awt.AWTError

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Error
                   |
                   +----java.awt.AWTError

public class AWTError
extends Error

Thrown when a serious Abstract Window Toolkit error has occurred.


 AWTError Members

AWTError Members

Class Overview | This Package | All Packages

Constructors
Name | Description
AWTError(String) | Constructs an instance of AWTError with the specified detail message.


 AWTError.AWTError

AWTError.AWTError

Class Overview | Class Members | This Package | All Packages

Syntax
public AWTError( String msg )
Parameters
msg
the detail message.
Description
Constructs an instance of AWTError with the specified detail message.


 Class AWTEvent

Class java.awt.AWTEvent

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.EventObject
           |
           +----java.awt.AWTEvent

public abstract class AWTEvent
extends EventObject

The root event class for all AWT events. This class and its subclasses supercede the original java.awt.Event class. Subclasses of this root AWTEvent class defined outside of the java.awt.event package should define event ID values greater than the value defined by RESERVED_ID_MAX. The event masks defined in this class are needed ONLY by component subclasses which are using Component.enableEvents() to select for event types not selected by registered listeners. If a listener is registered on a component, the appropriate event mask is already set internally by the component.

See Also:
enableEvents, ComponentEvent, FocusEvent, KeyEvent, MouseEvent, WindowEvent, ActionEvent, AdjustmentEvent, ItemEvent, TextEvent


 AWTEvent Members

AWTEvent Members

Class Overview | This Package | All Packages

Fields
Name | Description
ACTION_EVENT_MASK | The event mask for selecting action events.
ADJUSTMENT_EVENT_MASK | The event mask for selecting adjustment events.
COMPONENT_EVENT_MASK | The event mask for selecting component events.
consumed |
CONTAINER_EVENT_MASK | The event mask for selecting container events.
FOCUS_EVENT_MASK | The event mask for selecting focus events.
id |
ITEM_EVENT_MASK | The event mask for selecting item events.
KEY_EVENT_MASK | The event mask for selecting key events.
MOUSE_EVENT_MASK | The event mask for selecting mouse events.
MOUSE_MOTION_EVENT_MASK | The event mask for selecting mouse motion events.
RESERVED_ID_MAX | The maximum value for reserved AWT event IDs.
TEXT_EVENT_MASK | The event mask for selecting text events.
WINDOW_EVENT_MASK | The event mask for selecting window events.

Constructors
Name | Description
AWTEvent(Event) | Constructs an AWTEvent object from the parameters of a 1.0-style event.
AWTEvent(Object, int) | Constructs an AWTEvent object with the specified source object and type.

Methods
Name | Description
consume() |
getID() | Returns the event type.
isConsumed() |
paramString() |
toString() | Returns a string representation of the object.


 AWTEvent.ACTION_EVENT_MASK

AWTEvent.ACTION_EVENT_MASK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final long ACTION_EVENT_MASK
Description
The event mask for selecting action events.


 AWTEvent.ADJUSTMENT_EVENT_MASK

AWTEvent.ADJUSTMENT_EVENT_MASK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final long ADJUSTMENT_EVENT_MASK
Description
The event mask for selecting adjustment events.


 AWTEvent.COMPONENT_EVENT_MASK

AWTEvent.COMPONENT_EVENT_MASK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final long COMPONENT_EVENT_MASK
Description
The event mask for selecting component events.


 AWTEvent.consumed

AWTEvent.consumed

Class Overview | Class Members | This Package | All Packages

Syntax
protected boolean consumed


 AWTEvent.CONTAINER_EVENT_MASK

AWTEvent.CONTAINER_EVENT_MASK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final long CONTAINER_EVENT_MASK
Description
The event mask for selecting container events.


 AWTEvent.FOCUS_EVENT_MASK

AWTEvent.FOCUS_EVENT_MASK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final long FOCUS_EVENT_MASK
Description
The event mask for selecting focus events.


 AWTEvent.id

AWTEvent.id

Class Overview | Class Members | This Package | All Packages

Syntax
protected int id


 AWTEvent.ITEM_EVENT_MASK

AWTEvent.ITEM_EVENT_MASK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final long ITEM_EVENT_MASK
Description
The event mask for selecting item events.


 AWTEvent.KEY_EVENT_MASK

AWTEvent.KEY_EVENT_MASK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final long KEY_EVENT_MASK
Description
The event mask for selecting key events.


 AWTEvent.MOUSE_EVENT_MASK

AWTEvent.MOUSE_EVENT_MASK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final long MOUSE_EVENT_MASK
Description
The event mask for selecting mouse events.


 AWTEvent.MOUSE_MOTION_EVENT_MASK

AWTEvent.MOUSE_MOTION_EVENT_MASK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final long MOUSE_MOTION_EVENT_MASK
Description
The event mask for selecting mouse motion events.


 AWTEvent.RESERVED_ID_MAX

AWTEvent.RESERVED_ID_MAX

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int RESERVED_ID_MAX
Description
The maximum value for reserved AWT event IDs. Programs defining their own event IDs should use IDs greater than this value.


 AWTEvent.TEXT_EVENT_MASK

AWTEvent.TEXT_EVENT_MASK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final long TEXT_EVENT_MASK
Description
The event mask for selecting text events.


 AWTEvent.WINDOW_EVENT_MASK

AWTEvent.WINDOW_EVENT_MASK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final long WINDOW_EVENT_MASK
Description
The event mask for selecting window events.


 AWTEvent.AWTEvent

AWTEvent.AWTEvent

Class Overview | Class Members | This Package | All Packages

Syntax 1
public AWTEvent( Event event )
Parameters
event
the old-style event
Description
Constructs an AWTEvent object from the parameters of a 1.0-style event.

Syntax 2
public AWTEvent( Object source, int id )
Parameters
source
the object where the event originated
Description
Constructs an AWTEvent object with the specified source object and type.


 AWTEvent.consume

AWTEvent.consume

Class Overview | Class Members | This Package | All Packages

Syntax
protected void consume()


 AWTEvent.getID

AWTEvent.getID

Class Overview | Class Members | This Package | All Packages

Syntax
public int getID()
Description
Returns the event type.


 AWTEvent.isConsumed

AWTEvent.isConsumed

Class Overview | Class Members | This Package | All Packages

Syntax
protected boolean isConsumed()


 AWTEvent.paramString

AWTEvent.paramString

Class Overview | Class Members | This Package | All Packages

Syntax
public String paramString()


 AWTEvent.toString

AWTEvent.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Description
Returns a string representation of the object.

Overrides
toString in class EventObject


 Class AWTEventMulticaster

Class java.awt.AWTEventMulticaster

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.AWTEventMulticaster

public class AWTEventMulticaster
extends Object
implements ComponentListener, ContainerListener, FocusListener, KeyListener, MouseListener, MouseMotionListener, WindowListener, ActionListener, ItemListener, AdjustmentListener, TextListener

A class which implements efficient and thread-safe multi-cast event dispatching for the AWT events defined in the java.awt.event package. This class will manage an immutable structure consisting of a chain of event listeners and will dispatch events to those listeners. Because the structure is immutable, it is safe to use this API to add/remove listeners during the process of an event dispatch operation. An example of how this class could be used to implement a new component which fires "action" events:

 public myComponent extends Component {
     ActionListener actionListener = null;
     public void addActionListener(ActionListener l) {
       actionListener = AWTEventMulticaster.add(actionListener, l);
     }
     public void removeActionListener(ActionListener l) {
         actionListener = AWTEventMulticaster.remove(actionListener, l);
     }
     public void processEvent(AWTEvent e) {
         // when event occurs which causes "action" semantic
         if (actionListener != null) {
             actionListener.actionPerformed(new ActionEvent());
         }
 }


 AWTEventMulticaster Members

AWTEventMulticaster Members

Class Overview | This Package | All Packages

Fields
Name | Description
a |
b |

Constructors
Name | Description
AWTEventMulticaster(EventListener, EventListener) | Creates an event multicaster instance which chains listener-a with listener-b.

Methods
Name | Description
actionPerformed(ActionEvent) | Handles the actionPerformed event by invoking the actionPerformed methods on listener-a and listener-b.
add(ActionListener, ActionListener) | Adds action-listener-a with action-listener-b and returns the resulting multicast listener.
add(AdjustmentListener, AdjustmentListener) | Adds adjustment-listener-a with adjustment-listener-b and returns the resulting multicast listener.
add(ComponentListener, ComponentListener) | Adds component-listener-a with component-listener-b and returns the resulting multicast listener.
add(ContainerListener, ContainerListener) | Adds container-listener-a with container-listener-b and returns the resulting multicast listener.
add(FocusListener, FocusListener) | Adds focus-listener-a with focus-listener-b and returns the resulting multicast listener.
add(ItemListener, ItemListener) | Adds item-listener-a with item-listener-b and returns the resulting multicast listener.
add(KeyListener, KeyListener) | Adds key-listener-a with key-listener-b and returns the resulting multicast listener.
add(MouseListener, MouseListener) | Adds mouse-listener-a with mouse-listener-b and returns the resulting multicast listener.
add(MouseMotionListener, MouseMotionListener) | Adds mouse-motion-listener-a with mouse-motion-listener-b and returns the resulting multicast listener.
add(TextListener, TextListener) |
add(WindowListener, WindowListener) | Adds window-listener-a with window-listener-b and returns the resulting multicast listener.
addInternal(EventListener, EventListener) | Returns the resulting multicast listener from adding listener-a and listener-b together.
adjustmentValueChanged(AdjustmentEvent) | Handles the adjustmentValueChanged event by invoking the adjustmentValueChanged methods on listener-a and listener-b.
componentAdded(ContainerEvent) | Handles the componentAdded container event by invoking the componentAdded methods on listener-a and listener-b.
componentHidden(ComponentEvent) | Handles the componentHidden event by invoking the componentHidden methods on listener-a and listener-b.
componentMoved(ComponentEvent) | Handles the componentMoved event by invoking the componentMoved methods on listener-a and listener-b.
componentRemoved(ContainerEvent) | Handles the componentRemoved container event by invoking the componentRemoved methods on listener-a and listener-b.
componentResized(ComponentEvent) | Handles the componentResized event by invoking the componentResized methods on listener-a and listener-b.
componentShown(ComponentEvent) | Handles the componentShown event by invoking the componentShown methods on listener-a and listener-b.
focusGained(FocusEvent) | Handles the focusGained event by invoking the focusGained methods on listener-a and listener-b.
focusLost(FocusEvent) | Handles the focusLost event by invoking the focusLost methods on listener-a and listener-b.
itemStateChanged(ItemEvent) | Handles the itemStateChanged event by invoking the itemStateChanged methods on listener-a and listener-b.
keyPressed(KeyEvent) | Handles the keyPressed event by invoking the keyPressed methods on listener-a and listener-b.
keyReleased(KeyEvent) | Handles the keyReleased event by invoking the keyReleased methods on listener-a and listener-b.
keyTyped(KeyEvent) | Handles the keyTyped event by invoking the keyTyped methods on listener-a and listener-b.
mouseClicked(MouseEvent) | Handles the mouseClicked event by invoking the mouseClicked methods on listener-a and listener-b.
mouseDragged(MouseEvent) | Handles the mouseDragged event by invoking the mouseDragged methods on listener-a and listener-b.
mouseEntered(MouseEvent) | Handles the mouseEntered event by invoking the mouseEntered methods on listener-a and listener-b.
mouseExited(MouseEvent) | Handles the mouseExited event by invoking the mouseExited methods on listener-a and listener-b.
mouseMoved(MouseEvent) | Handles the mouseMoved event by invoking the mouseMoved methods on listener-a and listener-b.
mousePressed(MouseEvent) | Handles the mousePressed event by invoking the mousePressed methods on listener-a and listener-b.
mouseReleased(MouseEvent) | Handles the mouseReleased event by invoking the mouseReleased methods on listener-a and listener-b.
remove(ActionListener, ActionListener) | Removes the old action-listener from action-listener-l and returns the resulting multicast listener.
remove(AdjustmentListener, AdjustmentListener) | Removes the old adjustment-listener from adjustment-listener-l and returns the resulting multicast listener.
remove(ComponentListener, ComponentListener) | Removes the old component-listener from component-listener-l and returns the resulting multicast listener.
remove(ContainerListener, ContainerListener) | Removes the old container-listener from container-listener-l and returns the resulting multicast listener.
remove(EventListener) | Removes a listener from this multicaster and returns the resulting multicast listener.
remove(FocusListener, FocusListener) | Removes the old focus-listener from focus-listener-l and returns the resulting multicast listener.
remove(ItemListener, ItemListener) | Removes the old item-listener from item-listener-l and returns the resulting multicast listener.
remove(KeyListener, KeyListener) | Removes the old key-listener from key-listener-l and returns the resulting multicast listener.
remove(MouseListener, MouseListener) | Removes the old mouse-listener from mouse-listener-l and returns the resulting multicast listener.
remove(MouseMotionListener, MouseMotionListener) | Removes the old mouse-motion-listener from mouse-motion-listener-l and returns the resulting multicast listener.
remove(TextListener, TextListener) |
remove(WindowListener, WindowListener) | Removes the old window-listener from window-listener-l and returns the resulting multicast listener.
removeInternal(EventListener, EventListener) | Returns the resulting multicast listener after removing the old listener from listener-l.
save(ObjectOutputStream, String, EventListener) |
saveInternal(ObjectOutputStream, String) |
textValueChanged(TextEvent) |
windowActivated(WindowEvent) | Handles the windowActivated event by invoking the windowActivated methods on listener-a and listener-b.
windowClosed(WindowEvent) | Handles the windowClosed event by invoking the windowClosed methods on listener-a and listener-b.
windowClosing(WindowEvent) | Handles the windowClosing event by invoking the windowClosing methods on listener-a and listener-b.
windowDeactivated(WindowEvent) | Handles the windowDeactivated event by invoking the windowDeactivated methods on listener-a and listener-b.
windowDeiconified(WindowEvent) | Handles the windowDeiconfied event by invoking the windowDeiconified methods on listener-a and listener-b.
windowIconified(WindowEvent) | Handles the windowIconified event by invoking the windowIconified methods on listener-a and listener-b.
windowOpened(WindowEvent) | Handles the windowOpened event by invoking the windowOpened methods on listener-a and listener-b.


 AWTEventMulticaster.a

AWTEventMulticaster.a

Class Overview | Class Members | This Package | All Packages

Syntax
protected final EventListener a


 AWTEventMulticaster.b

AWTEventMulticaster.b

Class Overview | Class Members | This Package | All Packages

Syntax
protected final EventListener b


 AWTEventMulticaster.AWTEventMulticaster

AWTEventMulticaster.AWTEventMulticaster

Class Overview | Class Members | This Package | All Packages

Syntax
protected AWTEventMulticaster( EventListener a, EventListener b )
Parameters
a
listener-a
b
listener-b
Description
Creates an event multicaster instance which chains listener-a with listener-b.


 AWTEventMulticaster.actionPerformed

AWTEventMulticaster.actionPerformed

Class Overview | Class Members | This Package | All Packages

Syntax
public void actionPerformed( ActionEvent e )
Parameters
e
the action event
Description
Handles the actionPerformed event by invoking the actionPerformed methods on listener-a and listener-b.


 AWTEventMulticaster.add

AWTEventMulticaster.add

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static ComponentListener add( ComponentListener a, ComponentListener b )
Parameters
a
component-listener-a
b
component-listener-b
Description
Adds component-listener-a with component-listener-b and returns the resulting multicast listener.

Syntax 2
public static ContainerListener add( ContainerListener a, ContainerListener b )
Parameters
a
container-listener-a
b
container-listener-b
Description
Adds container-listener-a with container-listener-b and returns the resulting multicast listener.

Syntax 3
public static FocusListener add( FocusListener a, FocusListener b )
Parameters
a
focus-listener-a
b
focus-listener-b
Description
Adds focus-listener-a with focus-listener-b and returns the resulting multicast listener.

Syntax 4
public static KeyListener add( KeyListener a, KeyListener b )
Parameters
a
key-listener-a
b
key-listener-b
Description
Adds key-listener-a with key-listener-b and returns the resulting multicast listener.

Syntax 5
public static MouseListener add( MouseListener a, MouseListener b )
Parameters
a
mouse-listener-a
b
mouse-listener-b
Description
Adds mouse-listener-a with mouse-listener-b and returns the resulting multicast listener.

Syntax 6
public static MouseMotionListener add( MouseMotionListener a, MouseMotionListener b )
Parameters
a
mouse-motion-listener-a
b
mouse-motion-listener-b
Description
Adds mouse-motion-listener-a with mouse-motion-listener-b and returns the resulting multicast listener.

Syntax 7
public static WindowListener add( WindowListener a, WindowListener b )
Parameters
a
window-listener-a
b
window-listener-b
Description
Adds window-listener-a with window-listener-b and returns the resulting multicast listener.

Syntax 8
public static ActionListener add( ActionListener a, ActionListener b )
Parameters
a
action-listener-a
b
action-listener-b
Description
Adds action-listener-a with action-listener-b and returns the resulting multicast listener.

Syntax 9
public static ItemListener add( ItemListener a, ItemListener b )
Parameters
a
item-listener-a
b
item-listener-b
Description
Adds item-listener-a with item-listener-b and returns the resulting multicast listener.

Syntax 10
public static AdjustmentListener add( AdjustmentListener a, AdjustmentListener b )
Parameters
a
adjustment-listener-a
b
adjustment-listener-b
Description
Adds adjustment-listener-a with adjustment-listener-b and returns the resulting multicast listener.

Syntax 11
public static TextListener add( TextListener a, TextListener b )


 AWTEventMulticaster.addInternal

AWTEventMulticaster.addInternal

Class Overview | Class Members | This Package | All Packages

Syntax
protected static EventListener addInternal( EventListener a, EventListener b )
Parameters
a
event listener-a
b
event listener-b
Description
Returns the resulting multicast listener from adding listener-a and listener-b together. If listener-a is null, it returns listener-b; If listener-b is null, it returns listener-a If neither are null, then it creates and returns a new AWTEventMulticaster instance which chains a with b.


 AWTEventMulticaster.adjustmentValueChanged

AWTEventMulticaster.adjustmentValueChanged

Class Overview | Class Members | This Package | All Packages

Syntax
public void adjustmentValueChanged( AdjustmentEvent e )
Parameters
e
the adjustment event
Description
Handles the adjustmentValueChanged event by invoking the adjustmentValueChanged methods on listener-a and listener-b.


 AWTEventMulticaster.componentAdded

AWTEventMulticaster.componentAdded

Class Overview | Class Members | This Package | All Packages

Syntax
public void componentAdded( ContainerEvent e )
Parameters
e
the component event
Description
Handles the componentAdded container event by invoking the componentAdded methods on listener-a and listener-b.


 AWTEventMulticaster.componentHidden

AWTEventMulticaster.componentHidden

Class Overview | Class Members | This Package | All Packages

Syntax
public void componentHidden( ComponentEvent e )
Parameters
e
the component event
Description
Handles the componentHidden event by invoking the componentHidden methods on listener-a and listener-b.


 AWTEventMulticaster.componentMoved

AWTEventMulticaster.componentMoved

Class Overview | Class Members | This Package | All Packages

Syntax
public void componentMoved( ComponentEvent e )
Parameters
e
the component event
Description
Handles the componentMoved event by invoking the componentMoved methods on listener-a and listener-b.


 AWTEventMulticaster.componentRemoved

AWTEventMulticaster.componentRemoved

Class Overview | Class Members | This Package | All Packages

Syntax
public void componentRemoved( ContainerEvent e )
Parameters
e
the component event
Description
Handles the componentRemoved container event by invoking the componentRemoved methods on listener-a and listener-b.


 AWTEventMulticaster.componentResized

AWTEventMulticaster.componentResized

Class Overview | Class Members | This Package | All Packages

Syntax
public void componentResized( ComponentEvent e )
Parameters
e
the component event
Description
Handles the componentResized event by invoking the componentResized methods on listener-a and listener-b.


 AWTEventMulticaster.componentShown

AWTEventMulticaster.componentShown

Class Overview | Class Members | This Package | All Packages

Syntax
public void componentShown( ComponentEvent e )
Parameters
e
the component event
Description
Handles the componentShown event by invoking the componentShown methods on listener-a and listener-b.


 AWTEventMulticaster.focusGained

AWTEventMulticaster.focusGained

Class Overview | Class Members | This Package | All Packages

Syntax
public void focusGained( FocusEvent e )
Parameters
e
the focus event
Description
Handles the focusGained event by invoking the focusGained methods on listener-a and listener-b.


 AWTEventMulticaster.focusLost

AWTEventMulticaster.focusLost

Class Overview | Class Members | This Package | All Packages

Syntax
public void focusLost( FocusEvent e )
Parameters
e
the focus event
Description
Handles the focusLost event by invoking the focusLost methods on listener-a and listener-b.


 AWTEventMulticaster.itemStateChanged

AWTEventMulticaster.itemStateChanged

Class Overview | Class Members | This Package | All Packages

Syntax
public void itemStateChanged( ItemEvent e )
Parameters
e
the item event
Description
Handles the itemStateChanged event by invoking the itemStateChanged methods on listener-a and listener-b.


 AWTEventMulticaster.keyPressed

AWTEventMulticaster.keyPressed

Class Overview | Class Members | This Package | All Packages

Syntax
public void keyPressed( KeyEvent e )
Parameters
e
the key event
Description
Handles the keyPressed event by invoking the keyPressed methods on listener-a and listener-b.


 AWTEventMulticaster.keyReleased

AWTEventMulticaster.keyReleased

Class Overview | Class Members | This Package | All Packages

Syntax
public void keyReleased( KeyEvent e )
Parameters
e
the key event
Description
Handles the keyReleased event by invoking the keyReleased methods on listener-a and listener-b.


 AWTEventMulticaster.keyTyped

AWTEventMulticaster.keyTyped

Class Overview | Class Members | This Package | All Packages

Syntax
public void keyTyped( KeyEvent e )
Parameters
e
the key event
Description
Handles the keyTyped event by invoking the keyTyped methods on listener-a and listener-b.


 AWTEventMulticaster.mouseClicked

AWTEventMulticaster.mouseClicked

Class Overview | Class Members | This Package | All Packages

Syntax
public void mouseClicked( MouseEvent e )
Parameters
e
the mouse event
Description
Handles the mouseClicked event by invoking the mouseClicked methods on listener-a and listener-b.


 AWTEventMulticaster.mouseDragged

AWTEventMulticaster.mouseDragged

Class Overview | Class Members | This Package | All Packages

Syntax
public void mouseDragged( MouseEvent e )
Parameters
e
the mouse event
Description
Handles the mouseDragged event by invoking the mouseDragged methods on listener-a and listener-b.


 AWTEventMulticaster.mouseEntered

AWTEventMulticaster.mouseEntered

Class Overview | Class Members | This Package | All Packages

Syntax
public void mouseEntered( MouseEvent e )
Parameters
e
the mouse event
Description
Handles the mouseEntered event by invoking the mouseEntered methods on listener-a and listener-b.


 AWTEventMulticaster.mouseExited

AWTEventMulticaster.mouseExited

Class Overview | Class Members | This Package | All Packages

Syntax
public void mouseExited( MouseEvent e )
Parameters
e
the mouse event
Description
Handles the mouseExited event by invoking the mouseExited methods on listener-a and listener-b.


 AWTEventMulticaster.mouseMoved

AWTEventMulticaster.mouseMoved

Class Overview | Class Members | This Package | All Packages

Syntax
public void mouseMoved( MouseEvent e )
Parameters
e
the mouse event
Description
Handles the mouseMoved event by invoking the mouseMoved methods on listener-a and listener-b.


 AWTEventMulticaster.mousePressed

AWTEventMulticaster.mousePressed

Class Overview | Class Members | This Package | All Packages

Syntax
public void mousePressed( MouseEvent e )
Parameters
e
the mouse event
Description
Handles the mousePressed event by invoking the mousePressed methods on listener-a and listener-b.


 AWTEventMulticaster.mouseReleased

AWTEventMulticaster.mouseReleased

Class Overview | Class Members | This Package | All Packages

Syntax
public void mouseReleased( MouseEvent e )
Parameters
e
the mouse event
Description
Handles the mouseReleased event by invoking the mouseReleased methods on listener-a and listener-b.


 AWTEventMulticaster.remove

AWTEventMulticaster.remove

Class Overview | Class Members | This Package | All Packages

Syntax
protected EventListener remove( EventListener oldl )
Parameters
oldl
the listener to be removed
Description
Removes a listener from this multicaster and returns the resulting multicast listener.


 AWTEventMulticaster.remove

AWTEventMulticaster.remove

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static ComponentListener remove( ComponentListener l, ComponentListener oldl )
Parameters
l
component-listener-l
oldl
the component-listener being removed
Description
Removes the old component-listener from component-listener-l and returns the resulting multicast listener.

Syntax 2
public static ContainerListener remove( ContainerListener l, ContainerListener oldl )
Parameters
l
container-listener-l
oldl
the container-listener being removed
Description
Removes the old container-listener from container-listener-l and returns the resulting multicast listener.

Syntax 3
public static FocusListener remove( FocusListener l, FocusListener oldl )
Parameters
l
focus-listener-l
oldl
the focus-listener being removed
Description
Removes the old focus-listener from focus-listener-l and returns the resulting multicast listener.

Syntax 4
public static KeyListener remove( KeyListener l, KeyListener oldl )
Parameters
l
key-listener-l
oldl
the key-listener being removed
Description
Removes the old key-listener from key-listener-l and returns the resulting multicast listener.

Syntax 5
public static MouseListener remove( MouseListener l, MouseListener oldl )
Parameters
l
mouse-listener-l
oldl
the mouse-listener being removed
Description
Removes the old mouse-listener from mouse-listener-l and returns the resulting multicast listener.

Syntax 6
public static MouseMotionListener remove( MouseMotionListener l, MouseMotionListener oldl )
Parameters
l
mouse-motion-listener-l
oldl
the mouse-motion-listener being removed
Description
Removes the old mouse-motion-listener from mouse-motion-listener-l and returns the resulting multicast listener.

Syntax 7
public static WindowListener remove( WindowListener l, WindowListener oldl )
Parameters
l
window-listener-l
oldl
the window-listener being removed
Description
Removes the old window-listener from window-listener-l and returns the resulting multicast listener.

Syntax 8
public static ActionListener remove( ActionListener l, ActionListener oldl )
Parameters
l
action-listener-l
oldl
the action-listener being removed
Description
Removes the old action-listener from action-listener-l and returns the resulting multicast listener.

Syntax 9
public static ItemListener remove( ItemListener l, ItemListener oldl )
Parameters
l
item-listener-l
oldl
the item-listener being removed
Description
Removes the old item-listener from item-listener-l and returns the resulting multicast listener.

Syntax 10
public static AdjustmentListener remove( AdjustmentListener l, AdjustmentListener oldl )
Parameters
l
adjustment-listener-l
oldl
the adjustment-listener being removed
Description
Removes the old adjustment-listener from adjustment-listener-l and returns the resulting multicast listener.

Syntax 11
public static TextListener remove( TextListener l, TextListener oldl )


 AWTEventMulticaster.removeInternal

AWTEventMulticaster.removeInternal

Class Overview | Class Members | This Package | All Packages

Syntax
protected static EventListener removeInternal( EventListener l, EventListener oldl )
Parameters
l
the listener being removed from
oldl
the listener being removed
Description
Returns the resulting multicast listener after removing the old listener from listener-l. If listener-l equals the old listener OR listener-l is null, returns null. Else if listener-l is an instance of AWTEventMulticaster, then it removes the old listener from it. Else, returns listener l.


 AWTEventMulticaster.save

AWTEventMulticaster.save

Class Overview | Class Members | This Package | All Packages

Syntax
protected static void save( ObjectOutputStream s, String k, EventListener l ) throws IOException


 AWTEventMulticaster.saveInternal

AWTEventMulticaster.saveInternal

Class Overview | Class Members | This Package | All Packages

Syntax
protected void saveInternal( ObjectOutputStream s, String k ) throws IOException


 AWTEventMulticaster.textValueChanged

AWTEventMulticaster.textValueChanged

Class Overview | Class Members | This Package | All Packages

Syntax
public void textValueChanged( TextEvent e )


 AWTEventMulticaster.windowActivated

AWTEventMulticaster.windowActivated

Class Overview | Class Members | This Package | All Packages

Syntax
public void windowActivated( WindowEvent e )
Parameters
e
the window event
Description
Handles the windowActivated event by invoking the windowActivated methods on listener-a and listener-b.


 AWTEventMulticaster.windowClosed

AWTEventMulticaster.windowClosed

Class Overview | Class Members | This Package | All Packages

Syntax
public void windowClosed( WindowEvent e )
Parameters
e
the window event
Description
Handles the windowClosed event by invoking the windowClosed methods on listener-a and listener-b.


 AWTEventMulticaster.windowClosing

AWTEventMulticaster.windowClosing

Class Overview | Class Members | This Package | All Packages

Syntax
public void windowClosing( WindowEvent e )
Parameters
e
the window event
Description
Handles the windowClosing event by invoking the windowClosing methods on listener-a and listener-b.


 AWTEventMulticaster.windowDeactivated

AWTEventMulticaster.windowDeactivated

Class Overview | Class Members | This Package | All Packages

Syntax
public void windowDeactivated( WindowEvent e )
Parameters
e
the window event
Description
Handles the windowDeactivated event by invoking the windowDeactivated methods on listener-a and listener-b.


 AWTEventMulticaster.windowDeiconified

AWTEventMulticaster.windowDeiconified

Class Overview | Class Members | This Package | All Packages

Syntax
public void windowDeiconified( WindowEvent e )
Parameters
e
the window event
Description
Handles the windowDeiconfied event by invoking the windowDeiconified methods on listener-a and listener-b.


 AWTEventMulticaster.windowIconified

AWTEventMulticaster.windowIconified

Class Overview | Class Members | This Package | All Packages

Syntax
public void windowIconified( WindowEvent e )
Parameters
e
the window event
Description
Handles the windowIconified event by invoking the windowIconified methods on listener-a and listener-b.


 AWTEventMulticaster.windowOpened

AWTEventMulticaster.windowOpened

Class Overview | Class Members | This Package | All Packages

Syntax
public void windowOpened( WindowEvent e )
Parameters
e
the window event
Description
Handles the windowOpened event by invoking the windowOpened methods on listener-a and listener-b.


 Class AWTException

Class java.awt.AWTException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.awt.AWTException

public class AWTException
extends Exception

Signals that an Absract Window Toolkit exception has occurred.


 AWTException Members

AWTException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
AWTException(String) | Constructs an instance of AWTException with the specified detail message.


 AWTException.AWTException

AWTException.AWTException

Class Overview | Class Members | This Package | All Packages

Syntax
public AWTException( String msg )
Parameters
msg
the detail message
Description
Constructs an instance of AWTException with the specified detail message. A detail message is an instance of String that describes this particular exception.


 Interface Adjustable

Interface java.awt.Adjustable

Interface Members | This Package | All Packages

public interface Adjustable

The interface for objects which have an adjustable numeric value contained within a bounded range of values.


 Adjustable Members

Adjustable Members

Interface Overview | This Package | All Packages

Fields
Name | Description
HORIZONTAL | The horizontal orientation.
VERTICAL | The vertical orientation.

Methods
Name | Description
addAdjustmentListener(AdjustmentListener) | Add a listener to recieve adjustment events when the value of the adjustable object changes.
getBlockIncrement() | Gets the block value increment for the adjustable object.
getMaximum() | Gets the maximum value of the adjustable object.
getMinimum() | Gets the minimum value of the adjustable object.
getOrientation() | Gets the orientation of the adjustable object.
getUnitIncrement() | Gets the unit value increment for the adjustable object.
getValue() | Gets the current value of the adjustable object.
getVisibleAmount() | Gets the length of the propertional indicator.
removeAdjustmentListener(AdjustmentListener) | Removes an adjustment listener.
setBlockIncrement(int) | Sets the block value increment for the adjustable object.
setMaximum(int) | Sets the maximum value of the adjustable object.
setMinimum(int) | Sets the minimum value of the adjustable object.
setUnitIncrement(int) | Sets the unit value increment for the adjustable object.
setValue(int) | Sets the current value of the adjustable object.
setVisibleAmount(int) | Sets the length of the proportionl indicator of the adjustable object.


 Adjustable.HORIZONTAL

Adjustable.HORIZONTAL

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int HORIZONTAL
Description
The horizontal orientation.


 Adjustable.VERTICAL

Adjustable.VERTICAL

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int VERTICAL
Description
The vertical orientation.


 Adjustable.addAdjustmentListener

Adjustable.addAdjustmentListener

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void addAdjustmentListener( AdjustmentListener l )
Parameters
l
the listener to recieve events
Description
Add a listener to recieve adjustment events when the value of the adjustable object changes.

See Also
AdjustmentEvent


 Adjustable.getBlockIncrement

Adjustable.getBlockIncrement

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getBlockIncrement()
Description
Gets the block value increment for the adjustable object.


 Adjustable.getMaximum

Adjustable.getMaximum

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getMaximum()
Description
Gets the maximum value of the adjustable object.


 Adjustable.getMinimum

Adjustable.getMinimum

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getMinimum()
Description
Gets the minimum value of the adjustable object.


 Adjustable.getOrientation

Adjustable.getOrientation

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getOrientation()
Description
Gets the orientation of the adjustable object.


 Adjustable.getUnitIncrement

Adjustable.getUnitIncrement

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getUnitIncrement()
Description
Gets the unit value increment for the adjustable object.


 Adjustable.getValue

Adjustable.getValue

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getValue()
Description
Gets the current value of the adjustable object.


 Adjustable.getVisibleAmount

Adjustable.getVisibleAmount

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getVisibleAmount()
Description
Gets the length of the propertional indicator.


 Adjustable.removeAdjustmentListener

Adjustable.removeAdjustmentListener

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void removeAdjustmentListener( AdjustmentListener l )
Parameters
l
the listener being removed
Description
Removes an adjustment listener.

See Also
AdjustmentEvent


 Adjustable.setBlockIncrement

Adjustable.setBlockIncrement

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setBlockIncrement( int b )
Parameters
b
the block increment
Description
Sets the block value increment for the adjustable object.


 Adjustable.setMaximum

Adjustable.setMaximum

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setMaximum( int max )
Parameters
max
the maximum value
Description
Sets the maximum value of the adjustable object.


 Adjustable.setMinimum

Adjustable.setMinimum

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setMinimum( int min )
Parameters
min
the minimum value
Description
Sets the minimum value of the adjustable object.


 Adjustable.setUnitIncrement

Adjustable.setUnitIncrement

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setUnitIncrement( int u )
Parameters
u
the unit increment
Description
Sets the unit value increment for the adjustable object.


 Adjustable.setValue

Adjustable.setValue

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setValue( int v )
Parameters
v
the current value
Description
Sets the current value of the adjustable object. This value must be within the range defined by the minimum and maximum values for this object.


 Adjustable.setVisibleAmount

Adjustable.setVisibleAmount

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setVisibleAmount( int v )
Parameters
v
the length of the indicator
Description
Sets the length of the proportionl indicator of the adjustable object.


 Class BorderLayout

Class java.awt.BorderLayout

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.BorderLayout

public class BorderLayout
extends Object
implements LayoutManager2, Serializable

A border layout lays out a container, arranging and resizing its components to fit in five regions: North, South, East, West, and Center. When adding a component to a container with a border layout, use one of these five names, for example:

    Panel p = new Panel();
    p.setLayout(new BorderLayout());
    p.add(new Button("Okay"), "South");
As a convenience, BorderLayout interprets the absence of a string specification the same as "Center":
    Panel p2 = new Panel();
    p2.setLayout(new BorderLayout());
    p2.add(new TextArea());  // Same as p.add(new TextArea(), "Center");

The components are laid out according to their preferred sizes and the constraints of the container's size. The North and South components may be stretched horizontally; the East and West components may be stretched vertically; the Center component may stretch both horizontally and vertically to fill any space left over.

Here is an example of five buttons in an applet laid out using the BorderLayout layout manager:

The code for this applet is as follows:

 import java.awt.*;
 import java.applet.Applet;
 public class buttonDir extends Applet {
   public void init() {
     setLayout(new BorderLayout());
     add("North",  new Button("North"));
     add("South",  new Button("South"));
     add("East",   new Button("East"));
     add("West",   new Button("West"));
     add("Center", new Button("Center"));
   }
 }

See Also:
add


 BorderLayout Members

BorderLayout Members

Class Overview | This Package | All Packages

Fields
Name | Description
CENTER | The center layout constraint (middle of container).
EAST | The east layout constraint (left side of container).
NORTH | The north layout constraint (top of container).
SOUTH | The south layout constraint (bottom of container).
WEST | The west layout constraint (right side of container).

Constructors
Name | Description
BorderLayout() | Constructs a new border layout with no gaps between components.
BorderLayout(int, int) | Constructs a border layout with the specified gaps between components.

Methods
Name | Description
addLayoutComponent(Component, Object) | Adds the specified component to the layout, using the specified constraint object.
addLayoutComponent(String, Component) | Deprecated.
getHgap() | Returns the horizontal gap between components.
getLayoutAlignmentX(Container) | Returns the alignment along the x axis.
getLayoutAlignmentY(Container) | Returns the alignment along the y axis.
getVgap() | Returns the vertical gap between components.
invalidateLayout(Container) | Invalidates the layout, indicating that if the layout manager has cached information it should be discarded.
layoutContainer(Container) | Lays out the container argument using this border layout.
maximumLayoutSize(Container) | Returns the maximum dimensions for this layout given the components in the specified target container.
minimumLayoutSize(Container) | Determines the minimum size of the target container using this layout manager.
preferredLayoutSize(Container) | Determines the preferred size of the target container using this layout manager, based on the components in the container.
removeLayoutComponent(Component) | Removes the specified component from this border layout.
setHgap(int) | Sets the horizontal gap between components.
setVgap(int) | Sets the vertical gap between components.
toString() | Returns a string representation of the state of this border layout.


 BorderLayout.CENTER

BorderLayout.CENTER

Class Overview | Class Members | This Package | All Packages

Syntax
public static final String CENTER
Description
The center layout constraint (middle of container).


 BorderLayout.EAST

BorderLayout.EAST

Class Overview | Class Members | This Package | All Packages

Syntax
public static final String EAST
Description
The east layout constraint (left side of container).


 BorderLayout.NORTH

BorderLayout.NORTH

Class Overview | Class Members | This Package | All Packages

Syntax
public static final String NORTH
Description
The north layout constraint (top of container).


 BorderLayout.SOUTH

BorderLayout.SOUTH

Class Overview | Class Members | This Package | All Packages

Syntax
public static final String SOUTH
Description
The south layout constraint (bottom of container).


 BorderLayout.WEST

BorderLayout.WEST

Class Overview | Class Members | This Package | All Packages

Syntax
public static final String WEST
Description
The west layout constraint (right side of container).


 BorderLayout.BorderLayout

BorderLayout.BorderLayout

Class Overview | Class Members | This Package | All Packages

Syntax 1
public BorderLayout()
Description
Constructs a new border layout with no gaps between components.

Syntax 2
public BorderLayout( int hgap, int vgap )
Parameters
hgap
the horizontal gap.
vgap
the vertical gap.
Description
Constructs a border layout with the specified gaps between components. The horizontal gap is specified by hgap and the vertical gap is specified by vgap.


 BorderLayout.addLayoutComponent

BorderLayout.addLayoutComponent

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void addLayoutComponent( Component comp, Object constraints )
Parameters
comp
the component to be added.
constraints
an object that specifies how and where the component is added to the layout.
Description
Adds the specified component to the layout, using the specified constraint object. For border layouts, the constraint must be one of the following strings: "North", "South", "East", "West", or "Center".

Most applications do not call this method directly. This method is called when a component is added to a container using the Container.add method with the same argument types.

Exceptions
IllegalArgumentException if the constraint object is not a string, or if it not one of the five specified strings.
See Also
add

Syntax 2
public void addLayoutComponent( String name, Component comp )
Description
Note: addLayoutComponent() is deprecated. replaced by addLayoutComponent(Component, Object).


 BorderLayout.getHgap

BorderLayout.getHgap

Class Overview | Class Members | This Package | All Packages

Syntax
public int getHgap()
Description
Returns the horizontal gap between components.


 BorderLayout.getLayoutAlignmentX

BorderLayout.getLayoutAlignmentX

Class Overview | Class Members | This Package | All Packages

Syntax
public float getLayoutAlignmentX( Container parent )
Description
Returns the alignment along the x axis. This specifies how the component would like to be aligned relative to other components. The value should be a number between 0 and 1 where 0 represents alignment along the origin, 1 is aligned the furthest away from the origin, 0.5 is centered, etc.


 BorderLayout.getLayoutAlignmentY

BorderLayout.getLayoutAlignmentY

Class Overview | Class Members | This Package | All Packages

Syntax
public float getLayoutAlignmentY( Container parent )
Description
Returns the alignment along the y axis. This specifies how the component would like to be aligned relative to other components. The value should be a number between 0 and 1 where 0 represents alignment along the origin, 1 is aligned the furthest away from the origin, 0.5 is centered, etc.


 BorderLayout.getVgap

BorderLayout.getVgap

Class Overview | Class Members | This Package | All Packages

Syntax
public int getVgap()
Description
Returns the vertical gap between components.


 BorderLayout.invalidateLayout

BorderLayout.invalidateLayout

Class Overview | Class Members | This Package | All Packages

Syntax
public void invalidateLayout( Container target )
Description
Invalidates the layout, indicating that if the layout manager has cached information it should be discarded.


 BorderLayout.layoutContainer

BorderLayout.layoutContainer

Class Overview | Class Members | This Package | All Packages

Syntax
public void layoutContainer( Container target )
Parameters
target
the container in which to do the layout.
Description
Lays out the container argument using this border layout.

This method actually reshapes the components in the specified container in order to satisfy the constraints of this BorderLayout object. The North and Southcomponents, if any, are placed at the top and bottom of the container, respectively. The West and East components are then placed on the left and right, respectively. Finally, the Center object is placed in any remaining space in the middle.

Most applications do not call this method directly. This method is called when a container calls its doLayout method.

See Also
Container, doLayout


 BorderLayout.maximumLayoutSize

BorderLayout.maximumLayoutSize

Class Overview | Class Members | This Package | All Packages

Syntax
public Dimension maximumLayoutSize( Container target )
Parameters
target
the component which needs to be laid out
Description
Returns the maximum dimensions for this layout given the components in the specified target container.

See Also
Container, minimumLayoutSize, preferredLayoutSize


 BorderLayout.minimumLayoutSize

BorderLayout.minimumLayoutSize

Class Overview | Class Members | This Package | All Packages

Syntax
public Dimension minimumLayoutSize( Container target )
Parameters
target
the container in which to do the layout.
Returns
the minimum dimensions needed to lay out the subcomponents of the specified container.
Description
Determines the minimum size of the target container using this layout manager.

This method is called when a container calls its getMinimumSize method. Most applications do not call this method directly.

See Also
Container, preferredLayoutSize, getMinimumSize


 BorderLayout.preferredLayoutSize

BorderLayout.preferredLayoutSize

Class Overview | Class Members | This Package | All Packages

Syntax
public Dimension preferredLayoutSize( Container target )
Parameters
target
the container in which to do the layout.
Returns
the preferred dimensions to lay out the subcomponents of the specified container.
Description
Determines the preferred size of the target container using this layout manager, based on the components in the container.

Most applications do not call this method directly. This method is called when a container calls its getPreferredSize method.

See Also
Container, minimumLayoutSize, getPreferredSize


 BorderLayout.removeLayoutComponent

BorderLayout.removeLayoutComponent

Class Overview | Class Members | This Package | All Packages

Syntax
public void removeLayoutComponent( Component comp )
Parameters
comp
the component to be removed.
Description
Removes the specified component from this border layout. This method is called when a container calls its remove or removeAll methods. Most applications do not call this method directly.

See Also
remove, removeAll


 BorderLayout.setHgap

BorderLayout.setHgap

Class Overview | Class Members | This Package | All Packages

Syntax
public void setHgap( int hgap )
Parameters
hgap
the horizontal gap between components
Description
Sets the horizontal gap between components.


 BorderLayout.setVgap

BorderLayout.setVgap

Class Overview | Class Members | This Package | All Packages

Syntax
public void setVgap( int vgap )
Parameters
vgap
the vertical gap between components
Description
Sets the vertical gap between components.


 BorderLayout.toString

BorderLayout.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string representation of this border layout.
Description
Returns a string representation of the state of this border layout.

Overrides
toString in class Object


 Class Button

Class java.awt.Button

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.Component
           |
           +----java.awt.Button

public class Button
extends Component

This class creates a labeled button. The application can cause some action to happen when the button is pushed. This image depicts three views of a "Quit" button as it appears under the Solaris operating system:

The first view shows the button as it appears normally. The second view shows the button when it has input focus. Its outline is darkened to let the user know that it is an active object. The third view shows the button when the user clicks the mouse over the button, and thus requests that an action be performed.

The gesture of clicking on a button with the mouse is associated with one instance of ActionEvent, which is sent out when the mouse is both pressed and released over the button. If an application is interested in knowing when the button has been pressed but not released, as a separate gesture, it can specialize processMouseEvent, or it can register itself as a listener for mouse events by calling addMouseListener. Both of these methods are defined by Component, the abstract superclass of all components.

When a button is pressed and released, AWT sends an instance of ActionEvent to the button, by calling processEvent on the button. The button's processEvent method receives all events for the button; it passes an action event along by calling its own processActionEvent method. The latter method passes the action event on to any action listeners that have registered an interest in action events generated by this button.

If an application wants to perform some action based on a button being pressed and released, it should implement ActionListener and register the new listener to receive events from this button, by calling the button's addActionListener method. The application can make use of the button's action command as a messaging protocol.

See Also:
ActionEvent, ActionListener, processMouseEvent, addMouseListener


 Button Members

Button Members

Class Overview | This Package | All Packages

Constructors
Name | Description
Button() | Constructs a Button with no label.
Button(String) | Constructs a Button with the specified label.

Methods
Name | Description
addActionListener(ActionListener) | Adds the specified action listener to receive action events from this button.
addNotify() | Creates the peer of the button.
getActionCommand() | Returns the command name of the action event fired by this button.
getLabel() | Gets the label of this button.
paramString() | Returns the parameter string representing the state of this button.
processActionEvent(ActionEvent) | Processes action events occurring on this button by dispatching them to any registered ActionListener objects.
processEvent(AWTEvent) | Processes events on this button.
removeActionListener(ActionListener) | Removes the specified action listener so that it no longer receives action events from this button.
setActionCommand(String) | Sets the command name for the action event fired by this button.
setLabel(String) | Sets the button's label to be the specified string.


 Button.Button

Button.Button

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Button()
Description
Constructs a Button with no label.

Syntax 2
public Button( String label )
Parameters
label
A string label for the button.
Description
Constructs a Button with the specified label.


 Button.addActionListener

Button.addActionListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void addActionListener( ActionListener l )
Parameters
l
the action listener.
Description
Adds the specified action listener to receive action events from this button. Action events occur when a user presses or releases the mouse over this button.

See Also
ActionListener, removeActionListener


 Button.addNotify

Button.addNotify

Class Overview | Class Members | This Package | All Packages

Syntax
public void addNotify()
Description
Creates the peer of the button. The button's peer allows the application to change the look of the button without changing its functionality.

Overrides
addNotify in class Component
See Also
createButton, getToolkit


 Button.getActionCommand

Button.getActionCommand

Class Overview | Class Members | This Package | All Packages

Syntax
public String getActionCommand()
Description
Returns the command name of the action event fired by this button.


 Button.getLabel

Button.getLabel

Class Overview | Class Members | This Package | All Packages

Syntax
public String getLabel()
Returns
the button's label, or null if the button has no label.
Description
Gets the label of this button.

See Also
setLabel


 Button.paramString

Button.paramString

Class Overview | Class Members | This Package | All Packages

Syntax
protected String paramString()
Returns
the parameter string of this button.
Description
Returns the parameter string representing the state of this button. This string is useful for debugging.

Overrides
paramString in class Component


 Button.processActionEvent

Button.processActionEvent

Class Overview | Class Members | This Package | All Packages

Syntax
protected void processActionEvent( ActionEvent e )
Parameters
e
the action event.
Description
Processes action events occurring on this button by dispatching them to any registered ActionListener objects.

This method is not called unless action events are enabled for this button. Action events are enabled when one of the following occurs:

  • An ActionListener object is registered via addActionListener.
  • Action events are enabled via enableEvents.

See Also
ActionListener, addActionListener, enableEvents


 Button.processEvent

Button.processEvent

Class Overview | Class Members | This Package | All Packages

Syntax
protected void processEvent( AWTEvent e )
Parameters
e
the event.
Description
Processes events on this button. If an event is an instance of ActionEvent, this method invokes the processActionEvent method. Otherwise, it invokes processEvent on the superclass.

Overrides
processEvent in class Component
See Also
ActionEvent, processActionEvent


 Button.removeActionListener

Button.removeActionListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void removeActionListener( ActionListener l )
Parameters
l
the action listener.
Description
Removes the specified action listener so that it no longer receives action events from this button. Action events occur when a user presses or releases the mouse over this button.

See Also
ActionListener, addActionListener


 Button.setActionCommand

Button.setActionCommand

Class Overview | Class Members | This Package | All Packages

Syntax
public void setActionCommand( String command )
Parameters
command
A string used to set the button's action command.
Description
Sets the command name for the action event fired by this button. By default this action command is set to match the label of the button.

See Also
ActionEvent


 Button.setLabel

Button.setLabel

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setLabel( String label )
Parameters
label
the new label, or null if the button has no label.
Description
Sets the button's label to be the specified string.

See Also
getLabel


 Class Canvas

Class java.awt.Canvas

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.Component
           |
           +----java.awt.Canvas

public class Canvas
extends Component

A Canvas component represents a blank rectangular area of the screen onto which the application can draw or from which the application can trap input events from the user.

An application must subclass the Canvas class in order to get useful functionality such as creating a custom component. The paint method must be overridden in order to perform custom graphics on the canvas.


 Canvas Members

Canvas Members

Class Overview | This Package | All Packages

Constructors
Name | Description
Canvas() | Constructs a new Canvas.

Methods
Name | Description
addNotify() | Creates the peer of the canvas.
paint(Graphics) | This method is called to repaint this canvas.


 Canvas.Canvas

Canvas.Canvas

Class Overview | Class Members | This Package | All Packages

Syntax
public Canvas()
Description
Constructs a new Canvas.


 Canvas.addNotify

Canvas.addNotify

Class Overview | Class Members | This Package | All Packages

Syntax
public void addNotify()
Description
Creates the peer of the canvas. This peer allows you to change the user interface of the canvas without changing its functionality.

Overrides
addNotify in class Component
See Also
createCanvas, getToolkit


 Canvas.paint

Canvas.paint

Class Overview | Class Members | This Package | All Packages

Syntax
public void paint( Graphics g )
Parameters
g
the graphics context.
Description
This method is called to repaint this canvas. Most applications that subclass Canvas should override this method in order to perform some useful operation.

The paint method provided by Canvas redraws this canvas's rectangle in the background color.

The graphics context's origin (0, 0) is the top-left corner of this canvas. Its clipping region is the area of the context.

Overrides
paint in class Component
See Also
Graphics


 Class CardLayout

Class java.awt.CardLayout

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.CardLayout

public class CardLayout
extends Object
implements LayoutManager2, Serializable

A CardLayout object is a layout manager for a container. It treats each component in the container as a card. Only one card is visible at a time, and the container acts as a stack of cards.

The ordering of cards is determined by the container's own internal ordering of its component objects. CardLayout defines a set of methods that allow an application to flip through these cards sequentially, or to show a specified card. The addLayoutComponent method can be used to associate a string identifier with a given card for fast random access.

See Also:
Container


 CardLayout Members

CardLayout Members

Class Overview | This Package | All Packages

Constructors
Name | Description
CardLayout() | Creates a new card layout with gaps of size zero.
CardLayout(int, int) | Creates a new card layout with the specified horizontal and vertical gaps.

Methods
Name | Description
addLayoutComponent(Component, Object) | Adds the specified component to this card layout's internal table of names.
addLayoutComponent(String, Component) | Deprecated.
first(Container) | Flips to the first card of the container.
getHgap() | Gets the horizontal gap between components.
getLayoutAlignmentX(Container) | Returns the alignment along the x axis.
getLayoutAlignmentY(Container) | Returns the alignment along the y axis.
getVgap() | Gets the vertical gap between components.
invalidateLayout(Container) | Invalidates the layout, indicating that if the layout manager has cached information it should be discarded.
last(Container) | Flips to the last card of the container.
layoutContainer(Container) | Lays out the specified container using this card layout.
maximumLayoutSize(Container) | Returns the maximum dimensions for this layout given the components in the specified target container.
minimumLayoutSize(Container) | Calculates the minimum size for the specified panel.
next(Container) | Flips to the next card of the specified container.
preferredLayoutSize(Container) | Determines the preferred size of the container argument using this card layout.
previous(Container) | Flips to the previous card of the specified container.
removeLayoutComponent(Component) | Removes the specified component from the layout.
setHgap(int) | Sets the horizontal gap between components.
setVgap(int) | Sets the vertical gap between components.
show(Container, String) | Flips to the component that was added to this layout with the specified name, using addLayoutComponent.
toString() | Returns a string representation of the state of this card layout.


 CardLayout.CardLayout

CardLayout.CardLayout

Class Overview | Class Members | This Package | All Packages

Syntax 1
public CardLayout()
Description
Creates a new card layout with gaps of size zero.

Syntax 2
public CardLayout( int hgap, int vgap )
Parameters
hgap
the horizontal gap.
vgap
the vertical gap.
Description
Creates a new card layout with the specified horizontal and vertical gaps. The horizontal gaps are placed at the left and right edges. The vertical gaps are placed at the top and bottom edges.


 CardLayout.addLayoutComponent

CardLayout.addLayoutComponent

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void addLayoutComponent( Component comp, Object constraints )
Parameters
comp
the component to be added.
constraints
a tag that identifies a particular card in the layout.
Description
Adds the specified component to this card layout's internal table of names. The object specified by constraints must be a string. The card layout stores this string as a key-value pair that can be used for random access to a particular card. By calling the show method, an application can display the component with the specified name.

Exceptions
IllegalArgumentException if the constraint is not a string.
See Also
show

Syntax 2
public void addLayoutComponent( String name, Component comp )
Description
Note: addLayoutComponent() is deprecated. replaced by addLayoutComponent(Component, Object).


 CardLayout.first

CardLayout.first

Class Overview | Class Members | This Package | All Packages

Syntax
public void first( Container parent )
Parameters
parent
the name of the parent container in which to do the layout.
Description
Flips to the first card of the container.

See Also
last


 CardLayout.getHgap

CardLayout.getHgap

Class Overview | Class Members | This Package | All Packages

Syntax
public int getHgap()
Returns
the horizontal gap between components.
Description
Gets the horizontal gap between components.

See Also
setHgap, getVgap


 CardLayout.getLayoutAlignmentX

CardLayout.getLayoutAlignmentX

Class Overview | Class Members | This Package | All Packages

Syntax
public float getLayoutAlignmentX( Container parent )
Description
Returns the alignment along the x axis. This specifies how the component would like to be aligned relative to other components. The value should be a number between 0 and 1 where 0 represents alignment along the origin, 1 is aligned the furthest away from the origin, 0.5 is centered, etc.


 CardLayout.getLayoutAlignmentY

CardLayout.getLayoutAlignmentY

Class Overview | Class Members | This Package | All Packages

Syntax
public float getLayoutAlignmentY( Container parent )
Description
Returns the alignment along the y axis. This specifies how the component would like to be aligned relative to other components. The value should be a number between 0 and 1 where 0 represents alignment along the origin, 1 is aligned the furthest away from the origin, 0.5 is centered, etc.


 CardLayout.getVgap

CardLayout.getVgap

Class Overview | Class Members | This Package | All Packages

Syntax
public int getVgap()
Returns
the vertical gap between components.
Description
Gets the vertical gap between components.

See Also
setVgap, getHgap


 CardLayout.invalidateLayout

CardLayout.invalidateLayout

Class Overview | Class Members | This Package | All Packages

Syntax
public void invalidateLayout( Container target )
Description
Invalidates the layout, indicating that if the layout manager has cached information it should be discarded.


 CardLayout.last

CardLayout.last

Class Overview | Class Members | This Package | All Packages

Syntax
public void last( Container parent )
Parameters
parent
the name of the parent container in which to do the layout.
Description
Flips to the last card of the container.

See Also
first


 CardLayout.layoutContainer

CardLayout.layoutContainer

Class Overview | Class Members | This Package | All Packages

Syntax
public void layoutContainer( Container parent )
Parameters
parent
the name of the parent container in which to do the layout.
Description
Lays out the specified container using this card layout.

Each component in the parent container is reshaped to be the size of the container, minus space for surrounding insets, horizontal gaps, and vertical gaps.

See Also
doLayout


 CardLayout.maximumLayoutSize

CardLayout.maximumLayoutSize

Class Overview | Class Members | This Package | All Packages

Syntax
public Dimension maximumLayoutSize( Container target )
Parameters
target
the component which needs to be laid out
Description
Returns the maximum dimensions for this layout given the components in the specified target container.

See Also
Container, minimumLayoutSize, preferredLayoutSize


 CardLayout.minimumLayoutSize

CardLayout.minimumLayoutSize

Class Overview | Class Members | This Package | All Packages

Syntax
public Dimension minimumLayoutSize( Container parent )
Parameters
parent
the name of the parent container in which to do the layout.
Returns
the minimum dimensions required to lay out the subcomponents of the specified container.
Description
Calculates the minimum size for the specified panel.

See Also
doLayout, preferredLayoutSize


 CardLayout.next

CardLayout.next

Class Overview | Class Members | This Package | All Packages

Syntax
public void next( Container parent )
Parameters
parent
the name of the parent container in which to do the layout.
Description
Flips to the next card of the specified container. If the currently visible card is the last one, this method flips to the first card in the layout.

See Also
previous


 CardLayout.preferredLayoutSize

CardLayout.preferredLayoutSize

Class Overview | Class Members | This Package | All Packages

Syntax
public Dimension preferredLayoutSize( Container parent )
Parameters
parent
the name of the parent container.
Returns
the preferred dimensions to lay out the subcomponents of the specified container.
Description
Determines the preferred size of the container argument using this card layout.

See Also
getPreferredSize, minimumLayoutSize


 CardLayout.previous

CardLayout.previous

Class Overview | Class Members | This Package | All Packages

Syntax
public void previous( Container parent )
Parameters
parent
the name of the parent container in which to do the layout.
Description
Flips to the previous card of the specified container. If the currently visible card is the first one, this method flips to the last card in the layout.

See Also
next


 CardLayout.removeLayoutComponent

CardLayout.removeLayoutComponent

Class Overview | Class Members | This Package | All Packages

Syntax
public void removeLayoutComponent( Component comp )
Parameters
comp
the component to be removed.
Description
Removes the specified component from the layout.

See Also
remove, removeAll


 CardLayout.setHgap

CardLayout.setHgap

Class Overview | Class Members | This Package | All Packages

Syntax
public void setHgap( int hgap )
Parameters
hgap
the horizontal gap between components.
Description
Sets the horizontal gap between components.

See Also
getHgap, setVgap


 CardLayout.setVgap

CardLayout.setVgap

Class Overview | Class Members | This Package | All Packages

Syntax
public void setVgap( int vgap )
Parameters
vgap
the vertical gap between components.
Description
Sets the vertical gap between components.

See Also
getVgap, setHgap


 CardLayout.show

CardLayout.show

Class Overview | Class Members | This Package | All Packages

Syntax
public void show( Container parent, String name )
Parameters
parent
the name of the parent container in which to do the layout.
name
the component name.
Description
Flips to the component that was added to this layout with the specified name, using addLayoutComponent. If no such component exists, then nothing happens.

See Also
addLayoutComponent


 CardLayout.toString

CardLayout.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string representation of this card layout.
Description
Returns a string representation of the state of this card layout.

Overrides
toString in class Object


 Class Checkbox

Class java.awt.Checkbox

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.Component
           |
           +----java.awt.Checkbox

public class Checkbox
extends Component
implements ItemSelectable

A check box is a graphical component that can be in either an "on" (true) or "off" (false) state. Clicking on a check box changes its state from "on" to "off," or from "off" to "on."

The following code example creates a set of check boxes in a grid layout:

 setLayout(new GridLayout(3, 1));
 add(new Checkbox("one", null, true));
 add(new Checkbox("two"));
 add(new Checkbox("three"));

This image depicts the check boxes and grid layout created by this code example:

The button labeled one is in the "on" state, and the other two are in the "off" state. In this example, which uses the GridLayout class, the states of the three check boxes are set independently.

Alternatively, several check boxes can be grouped together under the control of a single object, using the CheckboxGroup class. In a check box group, at most one button can be in the "on" state at any given time. Clicking on a check box to turn it on forces any other check box in the same group that is on into the "off" state.

See Also:
GridLayout, CheckboxGroup


 Checkbox Members

Checkbox Members

Class Overview | This Package | All Packages

Constructors
Name | Description
Checkbox() | Creates a check box with no label.
Checkbox(String) | Creates a check box with the specified label.
Checkbox(String, boolean) | Creates a check box with the specified label.
Checkbox(String, boolean, CheckboxGroup) | Creates a check box with the specified label, in the specified check box group, and set to the specified state.
Checkbox(String, CheckboxGroup, boolean) | Constructs a Checkbox with the specified label, set to the specified state, and in the specified check box group.

Methods
Name | Description
addItemListener(ItemListener) | Adds the specified item listener to receive item events from this check box.
addNotify() | Creates the peer of the Checkbox.
getCheckboxGroup() | Determines this check box's group.
getLabel() | Gets the label of this check box.
getSelectedObjects() | Returns the an array (length 1) containing the checkbox label or null if the checkbox is not selected.
getState() | Determines whether this check box is in the "on" or "off" state.
paramString() | Returns the parameter string representing the state of this check box.
processEvent(AWTEvent) | Processes events on this check box.
processItemEvent(ItemEvent) | Processes item events occurring on this check box by dispatching them to any registered ItemListener objects.
removeItemListener(ItemListener) | Removes the specified item listener so that the item listener no longer receives item events from this check box.
setCheckboxGroup(CheckboxGroup) | Sets this check box's group to be the specified check box group.
setLabel(String) | Sets this check box's label to be the string argument.
setState(boolean) | Sets the state of this check box to the specified state.


 Checkbox.Checkbox

Checkbox.Checkbox

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Checkbox()
Description
Creates a check box with no label. The state of this check box is set to "off," and it is not part of any check box group.

Syntax 2
public Checkbox( String label )
Parameters
label
a string label for this check box, or null for no label.
Description
Creates a check box with the specified label. The state of this check box is set to "off," and it is not part of any check box group.

Syntax 3
public Checkbox( String label, boolean state )
Parameters
label
a string label for this check box, or null for no label.
state
the initial state of this check box.
Description
Creates a check box with the specified label. The state of this check box is as specified by the state argument, and it is not part of any check box group.

Syntax 4
public Checkbox( String label, boolean state, CheckboxGroup group )
Parameters
label
a string label for this check box, or null for no label.
state
the initial state of this check box.
group
a check box group for this check box, or null for no group.
Description
Creates a check box with the specified label, in the specified check box group, and set to the specified state.

Syntax 5
public Checkbox( String label, CheckboxGroup group, boolean state )
Description
Constructs a Checkbox with the specified label, set to the specified state, and in the specified check box group.


 Checkbox.addItemListener

Checkbox.addItemListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void addItemListener( ItemListener l )
Parameters
l
the item listener.
Description
Adds the specified item listener to receive item events from this check box.

See Also
ItemEvent, ItemListener, removeItemListener


 Checkbox.addNotify

Checkbox.addNotify

Class Overview | Class Members | This Package | All Packages

Syntax
public void addNotify()
Description
Creates the peer of the Checkbox. The peer allows you to change the look of the Checkbox without changing its functionality.

Overrides
addNotify in class Component
See Also
createCheckbox, getToolkit


 Checkbox.getCheckboxGroup

Checkbox.getCheckboxGroup

Class Overview | Class Members | This Package | All Packages

Syntax
public CheckboxGroup getCheckboxGroup()
Returns
this check box's group, or null if the check box is not part of a check box group.
Description
Determines this check box's group.

See Also
setCheckboxGroup


 Checkbox.getLabel

Checkbox.getLabel

Class Overview | Class Members | This Package | All Packages

Syntax
public String getLabel()
Returns
the label of this check box, or null if this check box has no label.
Description
Gets the label of this check box.

See Also
setLabel


 Checkbox.getSelectedObjects

Checkbox.getSelectedObjects

Class Overview | Class Members | This Package | All Packages

Syntax
public Object[] getSelectedObjects()
Description
Returns the an array (length 1) containing the checkbox label or null if the checkbox is not selected.

See Also
ItemSelectable


 Checkbox.getState

Checkbox.getState

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean getState()
Returns
the state of this check box, as a boolean value.
Description
Determines whether this check box is in the "on" or "off" state. The boolean value true indicates the "on" state, and false indicates the "off" state.

See Also
setState


 Checkbox.paramString

Checkbox.paramString

Class Overview | Class Members | This Package | All Packages

Syntax
protected String paramString()
Returns
the parameter string of this check box.
Description
Returns the parameter string representing the state of this check box. This string is useful for debugging.

Overrides
paramString in class Component


 Checkbox.processEvent

Checkbox.processEvent

Class Overview | Class Members | This Package | All Packages

Syntax
protected void processEvent( AWTEvent e )
Parameters
e
the event.
Description
Processes events on this check box. If the event is an instance of ItemEvent, this method invokes the processItemEvent method. Otherwise, it calls its superclass's processEvent method.

Overrides
processEvent in class Component
See Also
ItemEvent, processItemEvent


 Checkbox.processItemEvent

Checkbox.processItemEvent

Class Overview | Class Members | This Package | All Packages

Syntax
protected void processItemEvent( ItemEvent e )
Parameters
e
the item event.
Description
Processes item events occurring on this check box by dispatching them to any registered ItemListener objects.

This method is not called unless item events are enabled for this component. Item events are enabled when one of the following occurs:

  • An ItemListener object is registered via addItemListener.
  • Item events are enabled via enableEvents.

See Also
ItemEvent, ItemListener, addItemListener, enableEvents


 Checkbox.removeItemListener

Checkbox.removeItemListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void removeItemListener( ItemListener l )
Parameters
l
the item listener.
Description
Removes the specified item listener so that the item listener no longer receives item events from this check box.

See Also
ItemEvent, ItemListener, addItemListener


 Checkbox.setCheckboxGroup

Checkbox.setCheckboxGroup

Class Overview | Class Members | This Package | All Packages

Syntax
public void setCheckboxGroup( CheckboxGroup g )
Parameters
g
the new check box group, or null to remove this check box from any check box group.
Description
Sets this check box's group to be the specified check box group. If this check box is already in a different check box group, it is first taken out of that group.

See Also
getCheckboxGroup


 Checkbox.setLabel

Checkbox.setLabel

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setLabel( String label )
Parameters
label
a string to set as the new label, or null for no label.
Description
Sets this check box's label to be the string argument.

See Also
getLabel


 Checkbox.setState

Checkbox.setState

Class Overview | Class Members | This Package | All Packages

Syntax
public void setState( boolean state )
Parameters
state
the boolean state of the check box.
Description
Sets the state of this check box to the specified state. The boolean value true indicates the "on" state, and false indicates the "off" state.

See Also
getState


 Class CheckboxGroup

Class java.awt.CheckboxGroup

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.CheckboxGroup

public class CheckboxGroup
extends Object
implements Serializable

The CheckboxGroup class is used to group together a set of Checkbox buttons.

Exactly one check box button in a CheckboxGroup can be in the "on" state at any given time. Pushing any button sets its state to "on" and forces any other button that is in the "on" state into the "off" state.

The following code example produces a new check box group, with three check boxes:

 setLayout(new GridLayout(3, 1));
 CheckboxGroup cbg = new CheckboxGroup();
 add(new Checkbox("one", cbg, true));
 add(new Checkbox("two", cbg, false));
 add(new Checkbox("three", cbg, false));

This image depicts the check box group created by this example:

See Also:
Checkbox


 CheckboxGroup Members

CheckboxGroup Members

Class Overview | This Package | All Packages

Constructors
Name | Description
CheckboxGroup() | Creates a new instance of CheckboxGroup.

Methods
Name | Description
getCurrent() | Deprecated.
getSelectedCheckbox() | Gets the current choice from this check box group.
setCurrent(Checkbox) | Deprecated.
setSelectedCheckbox(Checkbox) | Sets the currently selected check box in this group to be the specified check box.
toString() | Returns a string representation of this check box group, including the value of its current selection.


 CheckboxGroup.CheckboxGroup

CheckboxGroup.CheckboxGroup

Class Overview | Class Members | This Package | All Packages

Syntax
public CheckboxGroup()
Description
Creates a new instance of CheckboxGroup.


 CheckboxGroup.getCurrent

CheckboxGroup.getCurrent

Class Overview | Class Members | This Package | All Packages

Syntax
public Checkbox getCurrent()
Description
Note: getCurrent() is deprecated. As of JDK version 1.1, replaced by getSelectedCheckbox().


 CheckboxGroup.getSelectedCheckbox

CheckboxGroup.getSelectedCheckbox

Class Overview | Class Members | This Package | All Packages

Syntax
public Checkbox getSelectedCheckbox()
Returns
the check box that is currently in the "on" state, or null.
Description
Gets the current choice from this check box group. The current choice is the check box in this group that is currently in the "on" state, or null if all check boxes in the group are off.

See Also
Checkbox, setSelectedCheckbox


 CheckboxGroup.setCurrent

CheckboxGroup.setCurrent

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setCurrent( Checkbox box )
Description
Note: setCurrent() is deprecated. As of JDK version 1.1, replaced by setSelectedCheckbox(Checkbox).


 CheckboxGroup.setSelectedCheckbox

CheckboxGroup.setSelectedCheckbox

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setSelectedCheckbox( Checkbox box )
Parameters
box
the Checkbox to set as the current selection.
Description
Sets the currently selected check box in this group to be the specified check box. This method sets the state of that check box to "on" and sets all other check boxes in the group to be off.

If the check box argument is null or belongs to a different check box group, then this method does nothing.

See Also
Checkbox, getSelectedCheckbox


 CheckboxGroup.toString

CheckboxGroup.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string representation of this check box group.
Description
Returns a string representation of this check box group, including the value of its current selection.

Overrides
toString in class Object


 Class CheckboxMenuItem

Class java.awt.CheckboxMenuItem

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.MenuComponent
           |
           +----java.awt.MenuItem
                   |
                   +----java.awt.CheckboxMenuItem

public class CheckboxMenuItem
extends MenuItem
implements ItemSelectable

This class represents a check box that can be included in a menu. Clicking on the check box in the menu changes its state from "on" to "off" or from "off" to "on."

The following picture depicts a menu which contains an instance of CheckBoxMenuItem:

The item labeled Check shows a check box menu item in its "off" state.

When a check box menu item is selected, AWT sends an item event to the item. Since the event is an instance of ItemEvent, the processEvent method examines the event and passes it along to processItemEvent. The latter method redirects the event to any ItemListener objects that have registered an interest in item events generated by this menu item.

See Also:
ItemEvent, ItemListener


 CheckboxMenuItem Members

CheckboxMenuItem Members

Class Overview | This Package | All Packages

Constructors
Name | Description
CheckboxMenuItem() | Create a check box menu item with an empty label.
CheckboxMenuItem(String) | Create a check box menu item with the specified label.
CheckboxMenuItem(String, boolean) | Create a check box menu item with the specified label and state.

Methods
Name | Description
addItemListener(ItemListener) | Adds the specified item listener to receive item events from this check box menu item.
addNotify() | Creates the peer of the checkbox item.
getSelectedObjects() | Returns the an array (length 1) containing the checkbox menu item label or null if the checkbox is not selected.
getState() | Determines whether the state of this check box menu item is "on" or "off."
paramString() | Returns the parameter string representing the state of this check box menu item.
processEvent(AWTEvent) | Processes events on this check box menu item.
processItemEvent(ItemEvent) | Processes item events occurring on this check box menu item by dispatching them to any registered ItemListener objects.
removeItemListener(ItemListener) | Removes the specified item listener so that it no longer receives item events from this check box menu item.
setState(boolean) | Sets this check box menu item to the specifed state.


 CheckboxMenuItem.CheckboxMenuItem

CheckboxMenuItem.CheckboxMenuItem

Class Overview | Class Members | This Package | All Packages

Syntax 1
public CheckboxMenuItem()
Description
Create a check box menu item with an empty label. The item's state is initially set to "off."

Syntax 2
public CheckboxMenuItem( String label )
Parameters
label
a string label for the check box menu item, or null for an unlabeled menu item.
Description
Create a check box menu item with the specified label. The item's state is initially set to "off."

Syntax 3
public CheckboxMenuItem( String label, boolean state )
Parameters
label
the button label.
state
the initial state of the menu item, where true indicates "on" and false indicates "off."
Description
Create a check box menu item with the specified label and state.


 CheckboxMenuItem.addItemListener

CheckboxMenuItem.addItemListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void addItemListener( ItemListener l )
Parameters
l
the item listener.
Description
Adds the specified item listener to receive item events from this check box menu item.

See Also
ItemEvent, ItemListener, removeItemListener


 CheckboxMenuItem.addNotify

CheckboxMenuItem.addNotify

Class Overview | Class Members | This Package | All Packages

Syntax
public void addNotify()
Description
Creates the peer of the checkbox item. This peer allows us to change the look of the checkbox item without changing its functionality. Most applications do not call this method directly.

Overrides
addNotify in class MenuItem
See Also
createCheckboxMenuItem, getToolkit


 CheckboxMenuItem.getSelectedObjects

CheckboxMenuItem.getSelectedObjects

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized Object[] getSelectedObjects()
Description
Returns the an array (length 1) containing the checkbox menu item label or null if the checkbox is not selected.

See Also
ItemSelectable


 CheckboxMenuItem.getState

CheckboxMenuItem.getState

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean getState()
Returns
the state of this check box menu item, where true indicates "on" and false indicates "off."
Description
Determines whether the state of this check box menu item is "on" or "off."

See Also
setState


 CheckboxMenuItem.paramString

CheckboxMenuItem.paramString

Class Overview | Class Members | This Package | All Packages

Syntax
public String paramString()
Returns
the parameter string of this check box menu item.
Description
Returns the parameter string representing the state of this check box menu item. This string is useful for debugging.

Overrides
paramString in class MenuItem


 CheckboxMenuItem.processEvent

CheckboxMenuItem.processEvent

Class Overview | Class Members | This Package | All Packages

Syntax
protected void processEvent( AWTEvent e )
Parameters
e
the event
Description
Processes events on this check box menu item. If the event is an instance of ItemEvent, this method invokes the processItemEvent method. If the event is not an item event, it invokes processEvent on the superclass.

Check box menu items currently support only item events.

Overrides
processEvent in class MenuItem
See Also
ItemEvent, processItemEvent


 CheckboxMenuItem.processItemEvent

CheckboxMenuItem.processItemEvent

Class Overview | Class Members | This Package | All Packages

Syntax
protected void processItemEvent( ItemEvent e )
Parameters
e
the item event.
Description
Processes item events occurring on this check box menu item by dispatching them to any registered ItemListener objects.

This method is not called unless item events are enabled for this menu item. Item events are enabled when one of the following occurs:

  • An ItemListener object is registered via addItemListener.
  • Item events are enabled via enableEvents.

See Also
ItemEvent, ItemListener, addItemListener, enableEvents


 CheckboxMenuItem.removeItemListener

CheckboxMenuItem.removeItemListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void removeItemListener( ItemListener l )
Parameters
l
the item listener.
Description
Removes the specified item listener so that it no longer receives item events from this check box menu item.

See Also
ItemEvent, ItemListener, addItemListener


 CheckboxMenuItem.setState

CheckboxMenuItem.setState

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setState( boolean b )
Parameters
b
the boolean state of this check box menu item.
Description
Sets this check box menu item to the specifed state. The boolean value true indicates "on" while false indicates "off."

See Also
getState


 Class Choice

Class java.awt.Choice

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.Component
           |
           +----java.awt.Choice

public class Choice
extends Component
implements ItemSelectable

The Choice class presents a pop-up menu of choices. The current choice is displayed as the title of the menu.

The following code example produces a pop-up menu:

 Choice ColorChooser = new Choice();
 ColorChooser.add("Green");
 ColorChooser.add("Red");
 ColorChooser.add("Blue");

After this choice menu has been added to a panel, it appears as follows in its normal state:

In the picture, "Green" is the current choice. Pushing the mouse button down on the object causes a menu to appear with the current choice highlighted.


 Choice Members

Choice Members

Class Overview | This Package | All Packages

Constructors
Name | Description
Choice() | Creates a new choice menu.

Methods
Name | Description
add(String) | Adds an item to this Choice menu.
addItem(String) | Adds an item to this Choice.
addItemListener(ItemListener) | Adds the specified item listener to receive item events from this Choice menu.
addNotify() | Creates the Choice's peer.
countItems() | Deprecated.
getItem(int) | Gets the string at the specified index in this Choice menu.
getItemCount() | Returns the number of items in this Choice menu.
getSelectedIndex() | Returns the index of the currently selected item.
getSelectedItem() | Gets a representation of the current choice as a string.
getSelectedObjects() | Returns an array (length 1) containing the currently selected item.
insert(String, int) | Inserts the item into this choice at the specified position.
paramString() | Returns the parameter string representing the state of this choice menu.
processEvent(AWTEvent) | Processes events on this choice.
processItemEvent(ItemEvent) | Processes item events occurring on this Choice menu by dispatching them to any registered ItemListener objects.
remove(int) | Removes an item from the choice menu at the specified position.
remove(String) | Remove the first occurrence of item from the Choice menu.
removeAll() | Removes all items from the choice menu.
removeItemListener(ItemListener) | Removes the specified item listener so that it no longer receives item events from this Choice menu.
select(int) | Sets the selected item in this Choice menu to be the item at the specified position.
select(String) | Sets the selected item in this Choice menu to be the item whose name is equal to the specified string.


 Choice.Choice

Choice.Choice

Class Overview | Class Members | This Package | All Packages

Syntax
public Choice()
Description
Creates a new choice menu. The menu initially has no items in it.

By default, the first item added to the choice menu becomes the selected item, until a different selection is made by the user by calling one of the select methods.

See Also
select, select


 Choice.add

Choice.add

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void add( String item )
Parameters
item
the item to be added
Description
Adds an item to this Choice menu.

Exceptions
NullPointerException if the item's value is null.


 Choice.addItem

Choice.addItem

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void addItem( String item )
Parameters
item
the item to be added
Description
Adds an item to this Choice.

Exceptions
NullPointerException If the item's value is equal to null.


 Choice.addItemListener

Choice.addItemListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void addItemListener( ItemListener l )
Parameters
l
the item listener.
Description
Adds the specified item listener to receive item events from this Choice menu.

See Also
ItemEvent, ItemListener, removeItemListener


 Choice.addNotify

Choice.addNotify

Class Overview | Class Members | This Package | All Packages

Syntax
public void addNotify()
Description
Creates the Choice's peer. This peer allows us to change the look of the Choice without changing its functionality.

Overrides
addNotify in class Component
See Also
createChoice, getToolkit


 Choice.countItems

Choice.countItems

Class Overview | Class Members | This Package | All Packages

Syntax
public int countItems()
Description
Note: countItems() is deprecated. As of JDK version 1.1, replaced by getItemCount().


 Choice.getItem

Choice.getItem

Class Overview | Class Members | This Package | All Packages

Syntax
public String getItem( int index )
Parameters
index
the index at which to begin.
Description
Gets the string at the specified index in this Choice menu.

See Also
getItemCount


 Choice.getItemCount

Choice.getItemCount

Class Overview | Class Members | This Package | All Packages

Syntax
public int getItemCount()
Description
Returns the number of items in this Choice menu.

See Also
getItem


 Choice.getSelectedIndex

Choice.getSelectedIndex

Class Overview | Class Members | This Package | All Packages

Syntax
public int getSelectedIndex()
Description
Returns the index of the currently selected item.

See Also
getSelectedItem


 Choice.getSelectedItem

Choice.getSelectedItem

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized String getSelectedItem()
Returns
a string representation of the currently selected item in this choice menu.
Description
Gets a representation of the current choice as a string.

See Also
getSelectedIndex


 Choice.getSelectedObjects

Choice.getSelectedObjects

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized Object[] getSelectedObjects()
Description
Returns an array (length 1) containing the currently selected item. If this choice has no items, returns null.

See Also
ItemSelectable


 Choice.insert

Choice.insert

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void insert( String item, int index )
Parameters
item
the item to be inserted
index
the position at which the item should be inserted
Description
Inserts the item into this choice at the specified position.

Exceptions
IllegalArgumentException if index is less than 0.


 Choice.paramString

Choice.paramString

Class Overview | Class Members | This Package | All Packages

Syntax
protected String paramString()
Returns
the parameter string of this Choice menu.
Description
Returns the parameter string representing the state of this choice menu. This string is useful for debugging.

Overrides
paramString in class Component


 Choice.processEvent

Choice.processEvent

Class Overview | Class Members | This Package | All Packages

Syntax
protected void processEvent( AWTEvent e )
Parameters
e
the event.
Description
Processes events on this choice. If the event is an instance of ItemEvent, it invokes the processItemEvent method. Otherwise, it calls its superclass's processEvent method.

Overrides
processEvent in class Component
See Also
ItemEvent, processItemEvent


 Choice.processItemEvent

Choice.processItemEvent

Class Overview | Class Members | This Package | All Packages

Syntax
protected void processItemEvent( ItemEvent e )
Parameters
e
the item event.
Description
Processes item events occurring on this Choice menu by dispatching them to any registered ItemListener objects.

This method is not called unless item events are enabled for this component. Item events are enabled when one of the following occurs:

  • An ItemListener object is registered via addItemListener.
  • Item events are enabled via enableEvents.

See Also
ItemEvent, ItemListener, addItemListener, enableEvents


 Choice.remove

Choice.remove

Class Overview | Class Members | This Package | All Packages

Syntax 1
public synchronized void remove( String item )
Parameters
item
the item to remove from this Choice menu.
Description
Remove the first occurrence of item from the Choice menu.

Exceptions
IllegalArgumentException if the item doesn't exist in the choice menu.

Syntax 2
public synchronized void remove( int position )
Parameters
position
the position of the item.
Description
Removes an item from the choice menu at the specified position.


 Choice.removeAll

Choice.removeAll

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void removeAll()
Description
Removes all items from the choice menu.

See Also
remove


 Choice.removeItemListener

Choice.removeItemListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void removeItemListener( ItemListener l )
Parameters
l
the item listener.
Description
Removes the specified item listener so that it no longer receives item events from this Choice menu.

See Also
ItemEvent, ItemListener, addItemListener


 Choice.select

Choice.select

Class Overview | Class Members | This Package | All Packages

Syntax 1
public synchronized void select( int pos )
Parameters
pos
the positon of the selected item.
Description
Sets the selected item in this Choice menu to be the item at the specified position.

Exceptions
IllegalArgumentException if the specified position is invalid.
See Also
getSelectedItem, getSelectedIndex

Syntax 2
public synchronized void select( String str )
Parameters
str
the specified string
Description
Sets the selected item in this Choice menu to be the item whose name is equal to the specified string. If more than one item matches (is equal to) the specified string, the one with the smallest index is selected.

See Also
getSelectedItem, getSelectedIndex


 Class Color

Class java.awt.Color

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.Color

public class Color
extends Object
implements Serializable

This class encapsulates colors using the RGB format. In RGB format, the red, blue, and green components of a color are each represented by an integer in the range 0-255. The value 0 indicates no contribution from this primary color. The value 255 indicates the maximum intensity of this color component.

Although the Color class is based on the three-component RGB model, the class provides a set of convenience methods for converting between RGB and HSB colors. For a definition of the RGB and HSB color models, see Foley, van Dam, Feiner, and Hughes, Computer Graphics: Principles and Practice.


 Color Members

Color Members

Class Overview | This Package | All Packages

Fields
Name | Description
black | The color black.
blue | The color blue.
cyan | The color cyan.
darkGray | The color dark gray.
gray | The color gray.
green | The color green.
lightGray | The color light gray.
magenta | The color magneta.
orange | The color orange.
pink | The color pink.
red | The color red.
white | The color white.
yellow | The color yellow.

Constructors
Name | Description
Color(float, float, float) | Creates a color with the specified red, green, and blue values, where each of the values is in the range 0.0-1.0.
Color(int) | Creates a color with the specified RGB value, where the red component is in bits 16-23 of the argument, the green component is in bits 8-15 of the argument, and the blue component is in bits 0-7.
Color(int, int, int) | Creates a color with the specified red, green, and blue components.

Methods
Name | Description
brighter() | Creates a brighter version of this color.
darker() | Creates a darker version of this color.
decode(String) | Converts a string to an integer and returns the specified color.
equals(Object) | Determines whether another object is equal to this color.
getBlue() | Gets the blue component of this color.
getColor(String) | Finds a color in the system properties.
getColor(String, Color) | Finds a color in the system properties.
getColor(String, int) | Finds a color in the system properties.
getGreen() | Gets the green component of this color.
getHSBColor(float, float, float) | Creates a Color object based on values supplied for the HSB color model.
getRed() | Gets the red component of this color.
getRGB() | Gets the RGB value representing the color in the default RGB ColorModel.
hashCode() | Computes the hash code for this color.
HSBtoRGB(float, float, float) | Converts the components of a color, as specified by the HSB model, to an equivalent set of values for the RGB model.
RGBtoHSB(int, int, int, float[]) | Converts the components of a color, as specified by the RGB model, to an equivalent set of values for hue, saturation, and brightness, the three components of the HSB model.
toString() | Creates a string that represents this color and indicates the values of its RGB components.


 Color.black

Color.black

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Color black
Description
The color black.


 Color.blue

Color.blue

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Color blue
Description
The color blue.


 Color.cyan

Color.cyan

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Color cyan
Description
The color cyan.


 Color.darkGray

Color.darkGray

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Color darkGray
Description
The color dark gray.


 Color.gray

Color.gray

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Color gray
Description
The color gray.


 Color.green

Color.green

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Color green
Description
The color green.


 Color.lightGray

Color.lightGray

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Color lightGray
Description
The color light gray.


 Color.magenta

Color.magenta

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Color magenta
Description
The color magneta.


 Color.orange

Color.orange

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Color orange
Description
The color orange.


 Color.pink

Color.pink

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Color pink
Description
The color pink.


 Color.red

Color.red

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Color red
Description
The color red.


 Color.white

Color.white

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Color white
Description
The color white.


 Color.yellow

Color.yellow

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Color yellow
Description
The color yellow.


 Color.Color

Color.Color

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Color( int r, int g, int b )
Parameters
r
the red component.
g
the green component.
b
the blue component.
Description
Creates a color with the specified red, green, and blue components. The three arguments must each be in the range 0-255.

The actual color used in rendering depends on finding the best match given the color space available for a given output device.

See Also
getRed, getGreen, getBlue, getRGB

Syntax 2
public Color( int rgb )
Parameters
rgb
an integer giving the red, green, and blue components.
Description
Creates a color with the specified RGB value, where the red component is in bits 16-23 of the argument, the green component is in bits 8-15 of the argument, and the blue component is in bits 0-7. The value zero indicates no contribution from the primary color component.

The actual color used in rendering depends on finding the best match given the color space available for a given output device.

See Also
getRGBdefault, getRed, getGreen, getBlue, getRGB

Syntax 3
public Color( float r, float g, float b )
Parameters
r
the red component
g
the red component
b
the red component
Description
Creates a color with the specified red, green, and blue values, where each of the values is in the range 0.0-1.0. The value 0.0 indicates no contribution from the primary color component. The value 1.0 indicates the maximum intensity of the primary color component.

The actual color used in rendering depends on finding the best match given the color space available for a given output device.

See Also
getRed, getGreen, getBlue, getRGB


 Color.brighter

Color.brighter

Class Overview | Class Members | This Package | All Packages

Syntax
public Color brighter()
Returns
a new Color object, a brighter version of this color.
Description
Creates a brighter version of this color.

This method applies an arbitrary scale factor to each of the three RGB components of the color to create a brighter version of the same color. Although brighter and darker are inverse operations, the results of a series of invocations of these two methods may be inconsistent because of rounding errors.

See Also
darker


 Color.darker

Color.darker

Class Overview | Class Members | This Package | All Packages

Syntax
public Color darker()
Returns
a new Color object, a darker version of this color.
Description
Creates a darker version of this color.

This method applies an arbitrary scale factor to each of the three RGB components of the color to create a darker version of the same color. Although brighter and darker are inverse operations, the results of a series of invocations of these two methods may be inconsistent because of rounding errors.

See Also
brighter


 Color.decode

Color.decode

Class Overview | Class Members | This Package | All Packages

Syntax
public static Color decode( String nm ) throws NumberFormatException
Parameters
nm
a string that represents a color as a 24-bit integer.
Returns
the new color
Description
Converts a string to an integer and returns the specified color. This method handles string formats that are used to represent octal and hexidecimal numbers.

Exceptions
NumberFormatException if the specified string cannot be interpreted as a decimal, octal, or hexidecimal integer.
See Also
decode


 Color.equals

Color.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Parameters
obj
the object to compare with.
Returns
true if the objects are the same; false otherwise.
Description
Determines whether another object is equal to this color.

The result is true if and only if the argument is not null and is a Color object that has the same red, green, and blue values as this object.

Overrides
equals in class Object


 Color.getBlue

Color.getBlue

Class Overview | Class Members | This Package | All Packages

Syntax
public int getBlue()
Returns
the blue component of this color.
Description
Gets the blue component of this color. The result is an integer in the range 0 to 255.

See Also
getRGB


 Color.getColor

Color.getColor

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static Color getColor( String nm )
Parameters
nm
the name of the color property
Returns
the color value of the property.
Description
Finds a color in the system properties.

The argument is treated as the name of a system property to be obtained. The string value of this property is then interpreted as an integer which is then converted to a color.

If the specified property is not found, or could not be parsed as an integer, then null is returned.

See Also
getProperty, getInteger, Color

Syntax 2
public static Color getColor( String nm, Color v )
Parameters
nm
the name of the color property
v
the default color value.
Returns
the color value of the property.
Description
Finds a color in the system properties.

The first argument is treated as the name of a system property to be obtained. The string value of this property is then interpreted as an integer which is then converted to a color.

If the specified property is not found, or cannot be parsed as an integer, then the color specified by the second argument is returned instead.

See Also
getProperty, getInteger, Color

Syntax 3
public static Color getColor( String nm, int v )
Parameters
nm
the name of the color property.
v
the default color value, as an integer.
Returns
the color value of the property.
Description
Finds a color in the system properties.

The first argument is treated as the name of a system property to be obtained. The string value of this property is then interpreted as an integer which is then converted to a color.

If the specified property is not found, or could not be parsed as an integer, then the integer value v is used instead, and is converted to a color.

See Also
getProperty, getInteger, Color


 Color.getGreen

Color.getGreen

Class Overview | Class Members | This Package | All Packages

Syntax
public int getGreen()
Returns
the green component of this color.
Description
Gets the green component of this color. The result is an integer in the range 0 to 255.

See Also
getRGB


 Color.getHSBColor

Color.getHSBColor

Class Overview | Class Members | This Package | All Packages

Syntax
public static Color getHSBColor( float h, float s, float b )
Parameters
h
the hue component.
s
the saturation of the color.
b
the brightness of the color.
Returns
a Color object with the specified hue, saturation, and brightness.
Description
Creates a Color object based on values supplied for the HSB color model.

Each of the three components should be a floating-point value between zero and one (a number in the range 0.0 ≤ h, s, b ≤ 1.0).


 Color.getRed

Color.getRed

Class Overview | Class Members | This Package | All Packages

Syntax
public int getRed()
Returns
the red component of this color.
Description
Gets the red component of this color. The result is an integer in the range 0 to 255.

See Also
getRGB


 Color.getRGB

Color.getRGB

Class Overview | Class Members | This Package | All Packages

Syntax
public int getRGB()
Description
Gets the RGB value representing the color in the default RGB ColorModel. The red, green, and blue components of the color are each scaled to be a value between 0 (abscence of the color) and 255 (complete saturation). Bits 24-31 of the returned integer are 0xff, bits 16-23 are the red value, bit 8-15 are the green value, and bits 0-7 are the blue value.

See Also
getRGBdefault, getRed, getGreen, getBlue


 Color.hashCode

Color.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int hashCode()
Returns
a hash code value for this object.
Description
Computes the hash code for this color.

Overrides
hashCode in class Object


 Color.HSBtoRGB

Color.HSBtoRGB

Class Overview | Class Members | This Package | All Packages

Syntax
public static int HSBtoRGB( float hue, float saturation, float brightness )
Parameters
hue
the hue component of the color.
saturation
the saturation of the color.
brightness
the brightness of the color.
Returns
the RGB value of the color with the indicated hue, saturation, and brightness.
Description
Converts the components of a color, as specified by the HSB model, to an equivalent set of values for the RGB model.

The integer that is returned by HSBtoRGB encodes the value of a color in bits 0&endash;23 of an integer value, the same format used by the method getRGB. This integer can be supplied as an argument to the Color constructor that takes a single integer argument.

See Also
getRGB, Color


 Color.RGBtoHSB

Color.RGBtoHSB

Class Overview | Class Members | This Package | All Packages

Syntax
public static float[] RGBtoHSB( int r, int g, int b, float hsbvals[] )
Parameters
r
the red component of the color.
g
the green component of the color.
b
the blue component of the color.
hsbvals
the array to be used to return the three HSB values, or null.
Returns
an array of three elements containing the hue, saturation, and brightness (in that order), of the color with the indicated red, green, and blue components.
Description
Converts the components of a color, as specified by the RGB model, to an equivalent set of values for hue, saturation, and brightness, the three components of the HSB model.

If the hsbvals argument is null, then a new array is allocated to return the result. Otherwise, the method returns the array hsbvals, with the values put into that array.

See Also
getRGB, Color


 Color.toString

Color.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a representation of this color as a String object.
Description
Creates a string that represents this color and indicates the values of its RGB components.

Overrides
toString in class Object


 Class Component

Class java.awt.Component

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.Component

public abstract class Component
extends Object
implements ImageObserver, MenuContainer, Serializable

A component is an object having a graphical representation that can be displayed on the screen and that can interact with the user. Examples of components are the buttons, checkboxes, and scrollbars of a typical graphical user interface.

The Component class is the abstract superclass of the nonmenu-related Abstract Window Toolkit components. Class Component can also be extended directly to create a lightweight component. A lightweight component is a component that is not associated with a native opaque window.


 Component Members

Component Members

Class Overview | This Package | All Packages

Fields
Name | Description
BOTTOM_ALIGNMENT | Ease-of-use constant for getAlignmentY.
CENTER_ALIGNMENT | Ease-of-use constant for getAlignmentY and getAlignmentX().
LEFT_ALIGNMENT | Ease-of-use constant for getAlignmentX.
RIGHT_ALIGNMENT | Ease-of-use constant for getAlignmentX.
TOP_ALIGNMENT | Ease-of-use constant for getAlignmentY.

Constructors
Name | Description
Component() | Constructs a new component.

Methods
Name | Description
action(Event, Object) | Deprecated.
add(PopupMenu) | Adds the specified popup menu to the component.
addComponentListener(ComponentListener) | Adds the specified component listener to receive component events from this component.
addFocusListener(FocusListener) | Adds the specified focus listener to receive focus events from this component.
addKeyListener(KeyListener) | Adds the specified key listener to receive key events from this component.
addMouseListener(MouseListener) | Adds the specified mouse listener to receive mouse events from this component.
addMouseMotionListener(MouseMotionListener) | Adds the specified mouse motion listener to receive mouse motion events from this component.
addNotify() | Notifies this component that it has been added to a container and if a peer is required, it should be created.
bounds() | Deprecated.
checkImage(Image, ImageObserver) | Returns the status of the construction of a screen representation of the specified image.
checkImage(Image, int, int, ImageObserver) | Returns the status of the construction of a screen representation of the specified image.
contains(int, int) | Checks whether this component "contains" the specified point, where x and y are defined to be relative to the coordinate system of this component.
contains(Point) | Checks whether this component "contains" the specified point, where the point's x and y coordinates are defined to be relative to the coordinate system of this component.
createImage(ImageProducer) | Creates an image from the specified image producer.
createImage(int, int) | Creates an off-screen drawable image to be used for double buffering.
deliverEvent(Event) | Deprecated.
disable() | Deprecated.
disableEvents(long) | Disables the events defined by the specified event mask parameter from being delivered to this component.
dispatchEvent(AWTEvent) | Dispatches an event to this component or one of its sub components.
doLayout() | Prompts the layout manager to lay out this component.
enable() | Deprecated.
enable(boolean) | Deprecated.
enableEvents(long) | Enables the events defined by the specified event mask parameter to be delivered to this component.
getAlignmentX() | Returns the alignment along the x axis.
getAlignmentY() | Returns the alignment along the y axis.
getBackground() | Gets the background color of this component.
getBounds() | Gets the bounds of this component in the form of a Rectangle object.
getColorModel() | Gets the instance of ColorModel used to display the component on the output device.
getComponentAt(int, int) | Determines if this component or one of its immediate subcomponents contains the (x, y) location, and if so, returns the containing component.
getComponentAt(Point) | Returns the component or subcomponent that contains the specified point.
getCursor() | Gets the cursor set on this component.
getFont() | Gets the font of this component.
getFontMetrics(Font) | Gets the font metrics for the specified font.
getForeground() | Gets the foreground color of this component.
getGraphics() | Creates a graphics context for this component.
getLocale() | Gets the locale of this component.
getLocation() | Gets the location of this component in the form of a point specifying the component's top-left corner.
getLocationOnScreen() | Gets the location of this component in the form of a point specifying the component's top-left corner in the screen's coordinate space.
getMaximumSize() | Gets the maximum size of this component.
getMinimumSize() | Gets the mininimum size of this component.
getName() | Gets the name of the component.
getParent() | Gets the parent of this component.
getPeer() | Deprecated.
getPreferredSize() | Gets the preferred size of this component.
getSize() | Returns the size of this component in the form of a Dimension object.
getToolkit() | Gets the toolkit of this component.
getTreeLock() | Gets this component's locking object (the object that owns the thread sychronization monitor) for AWT component-tree and layout operations.
gotFocus(Event, Object) | Deprecated.
handleEvent(Event) | Deprecated.
hide() | Deprecated.
imageUpdate(Image, int, int, int, int, int) | Repaints the component when the image has changed.
inside(int, int) | Deprecated.
invalidate() | Invalidates this component.
isEnabled() | Determines whether this component is enabled.
isFocusTraversable() | Returns the value of a flag that indicates whether this component can be traversed using Tab or Shift-Tab keyboard focus traversal.
isShowing() | Determines whether this component is showing on screen.
isValid() | Determines whether this component is valid.
isVisible() | Determines whether this component is visible.
keyDown(Event, int) | Deprecated.
keyUp(Event, int) | Deprecated.
layout() | Deprecated.
list() | Prints a listing of this component to the standard system output stream System.out.
list(PrintStream) | Prints a listing of this component to the specified output stream.
list(PrintStream, int) | Prints out a list, starting at the specified indention, to the specified print stream.
list(PrintWriter) | Prints a listing to the specified print writer.
list(PrintWriter, int) | Prints out a list, starting at the specified indention, to the specified print writer.
locate(int, int) | Deprecated.
location() | Deprecated.
lostFocus(Event, Object) | Deprecated.
minimumSize() | Deprecated.
mouseDown(Event, int, int) | Deprecated.
mouseDrag(Event, int, int) | Deprecated.
mouseEnter(Event, int, int) | Deprecated.
mouseExit(Event, int, int) | Deprecated.
mouseMove(Event, int, int) | Deprecated.
mouseUp(Event, int, int) | Deprecated.
move(int, int) | Deprecated.
nextFocus() | Deprecated.
paint(Graphics) | Paints this component.
paintAll(Graphics) | Paints this component and all of its subcomponents.
paramString() | Returns the parameter string representing the state of this component.
postEvent(Event) | Deprecated.
preferredSize() | Deprecated.
prepareImage(Image, ImageObserver) | Prepares an image for rendering on this component.
prepareImage(Image, int, int, ImageObserver) | Prepares an image for rendering on this component at the specified width and height.
print(Graphics) | Prints this component.
printAll(Graphics) | Prints this component and all of its subcomponents.
processComponentEvent(ComponentEvent) | Processes component events occurring on this component by dispatching them to any registered ComponentListener objects.
processEvent(AWTEvent) | Processes events occurring on this component.
processFocusEvent(FocusEvent) | Processes focus events occurring on this component by dispatching them to any registered FocusListener objects.
processKeyEvent(KeyEvent) | Processes key events occurring on this component by dispatching them to any registered KeyListener objects.
processMouseEvent(MouseEvent) | Processes mouse events occurring on this component by dispatching them to any registered MouseListener objects.
processMouseMotionEvent(MouseEvent) | Processes mouse motion events occurring on this component by dispatching them to any registered MouseMotionListener objects.
remove(MenuComponent) | Removes the specified popup menu from the component.
removeComponentListener(ComponentListener) | Removes the specified component listener so that it no longer receives component events from this component.
removeFocusListener(FocusListener) | Removes the specified focus listener so that it no longer receives focus events from this component.
removeKeyListener(KeyListener) | Removes the specified key listener so that it no longer receives key events from this component.
removeMouseListener(MouseListener) | Removes the specified mouse listener so that it no longer receives mouse events from this component.
removeMouseMotionListener(MouseMotionListener) | Removes the specified mouse motion listener so that it no longer receives mouse motion events from this component.
removeNotify() | Notifies this component that it has been removed from its container and if a peers exists, it destroys it.
repaint() | Repaints this component.
repaint(int, int, int, int) | Repaints the specified rectangle of this component.
repaint(long) | Repaints the component.
repaint(long, int, int, int, int) | Repaints the specified rectangle of this component within tm milliseconds.
requestFocus() | Requests that this component get the input focus.
reshape(int, int, int, int) | Deprecated.
resize(Dimension) | Deprecated.
resize(int, int) | Deprecated.
setBackground(Color) | Sets the background color of this component.
setBounds(int, int, int, int) | Moves and resizes this component.
setBounds(Rectangle) | Moves and resizes this component to conform to the new bounding rectangle r.
setCursor(Cursor) | Set the cursor image to a predefined cursor.
setEnabled(boolean) | Enables or disables this component, depending on the value of the parameter b.
setFont(Font) | Sets the font of this component.
setForeground(Color) | Sets the foreground color of this component.
setLocale(Locale) | Sets the locale of this component.
setLocation(int, int) | Moves this component to a new location.
setLocation(Point) | Moves this component to a new location.
setName(String) | Sets the name of the component to the specified string.
setSize(Dimension) | Resizes this component so that it has width d.width and height d.height.
setSize(int, int) | Resizes this component so that it has width width and height.
setVisible(boolean) | Shows or hides this component depending on the value of parameter b.
show() | Deprecated.
show(boolean) | Deprecated.
size() | Deprecated.
toString() | Returns a string representation of this component and its values.
transferFocus() | Transfers the focus to the next component.
update(Graphics) | Updates this component.
validate() | Ensures that this component has a valid layout.


 Component.BOTTOM_ALIGNMENT

Component.BOTTOM_ALIGNMENT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final float BOTTOM_ALIGNMENT
Description
Ease-of-use constant for getAlignmentY. Specifies an alignment to the bottom of the component.

See Also
getAlignmentY


 Component.CENTER_ALIGNMENT

Component.CENTER_ALIGNMENT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final float CENTER_ALIGNMENT
Description
Ease-of-use constant for getAlignmentY and getAlignmentX. Specifies an alignment to the center of the component

See Also
getAlignmentX, getAlignmentY


 Component.LEFT_ALIGNMENT

Component.LEFT_ALIGNMENT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final float LEFT_ALIGNMENT
Description
Ease-of-use constant for getAlignmentX. Specifies an alignment to the left side of the component.

See Also
getAlignmentX


 Component.RIGHT_ALIGNMENT

Component.RIGHT_ALIGNMENT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final float RIGHT_ALIGNMENT
Description
Ease-of-use constant for getAlignmentX. Specifies an alignment to the right side of the component.

See Also
getAlignmentX


 Component.TOP_ALIGNMENT

Component.TOP_ALIGNMENT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final float TOP_ALIGNMENT
Description
Ease-of-use constant for getAlignmentY(). Specifies an alignment to the top of the component.

See Also
getAlignmentY


 Component.Component

Component.Component

Class Overview | Class Members | This Package | All Packages

Syntax
protected Component()
Description
Constructs a new component. Class Component can be extended directly to create a lightweight component that does not utilize an opaque native window. A lightweight component must be hosted by a native container somewhere higher up in the component tree (for example, by a Frame object).


 Component.action

Component.action

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean action( Event evt, Object what )
Description
Note: action() is deprecated. As of JDK version 1.1, should register this component as ActionListener on component which fires action events.


 Component.add

Component.add

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void add( PopupMenu popup )
Parameters
popup
the popup menu to be added to the component.
Description
Adds the specified popup menu to the component.

See Also
remove


 Component.addComponentListener

Component.addComponentListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void addComponentListener( ComponentListener l )
Parameters
l
the component listener.
Description
Adds the specified component listener to receive component events from this component.

See Also
ComponentEvent, ComponentListener, removeComponentListener


 Component.addFocusListener

Component.addFocusListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void addFocusListener( FocusListener l )
Parameters
l
the focus listener.
Description
Adds the specified focus listener to receive focus events from this component.

See Also
FocusEvent, FocusListener, removeFocusListener


 Component.addKeyListener

Component.addKeyListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void addKeyListener( KeyListener l )
Parameters
l
the key listener.
Description
Adds the specified key listener to receive key events from this component.

See Also
KeyEvent, KeyListener, removeKeyListener


 Component.addMouseListener

Component.addMouseListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void addMouseListener( MouseListener l )
Parameters
l
the mouse listener.
Description
Adds the specified mouse listener to receive mouse events from this component.

See Also
MouseEvent, MouseListener, removeMouseListener


 Component.addMouseMotionListener

Component.addMouseMotionListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void addMouseMotionListener( MouseMotionListener l )
Parameters
l
the mouse motion listener.
Description
Adds the specified mouse motion listener to receive mouse motion events from this component.

See Also
MouseMotionEvent, MouseMotionListener, removeMouseMotionListener


 Component.addNotify

Component.addNotify

Class Overview | Class Members | This Package | All Packages

Syntax
public void addNotify()
Description
Notifies this component that it has been added to a container and if a peer is required, it should be created. This method should be called by Container.add, and not by user code directly.

See Also
removeNotify


 Component.bounds

Component.bounds

Class Overview | Class Members | This Package | All Packages

Syntax
public Rectangle bounds()
Description
Note: bounds() is deprecated. As of JDK version 1.1, replaced by getBounds().


 Component.checkImage

Component.checkImage

Class Overview | Class Members | This Package | All Packages

Syntax 1
public int checkImage( Image image, ImageObserver observer )
Parameters
image
the Image object whose status is being checked.
observer
the ImageObserver object to be notified as the image is being prepared.
Returns
the bitwise inclusive OR of ImageObserver flags indicating what information about the image is currently available.
Description
Returns the status of the construction of a screen representation of the specified image.

This method does not cause the image to begin loading. An application must use the prepareImage method to force the loading of an image.

Information on the flags returned by this method can be found with the discussion of the ImageObserver interface.

See Also
prepareImage, checkImage, ImageObserver

Syntax 2
public int checkImage( Image image, int width, int height, ImageObserver observer )
Parameters
image
the Image object whose status is being checked.
width
the width of the scaled version whose status is to be checked.
height
the height of the scaled version whose status is to be checked.
observer
the ImageObserver object to be notified as the image is being prepared.
Returns
the bitwise inclusive OR of ImageObserver flags indicating what information about the image is currently available.
Description
Returns the status of the construction of a screen representation of the specified image.

This method does not cause the image to begin loading. An application must use the prepareImage method to force the loading of an image.

The checkImage method of Component calls its peer's checkImage method to calculate the flags. If this component does not yet have a peer, the component's toolkit's checkImage method is called instead.

Information on the flags returned by this method can be found with the discussion of the ImageObserver interface.

See Also
prepareImage, checkImage, _top_


 Component.contains

Component.contains

Class Overview | Class Members | This Package | All Packages

Syntax 1
public boolean contains( int x, int y )
Parameters
x
the x coordinate of the point.
y
the y coordinate of the point.
Description
Checks whether this component "contains" the specified point, where x and y are defined to be relative to the coordinate system of this component.

See Also
getComponentAt

Syntax 2
public boolean contains( Point p )
Parameters
p
the point.
Description
Checks whether this component "contains" the specified point, where the point's x and y coordinates are defined to be relative to the coordinate system of this component.

See Also
getComponentAt


 Component.createImage

Component.createImage

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Image createImage( ImageProducer producer )
Parameters
producer
the image producer
Returns
the image produced.
Description
Creates an image from the specified image producer.

Syntax 2
public Image createImage( int width, int height )
Parameters
width
the specified width.
height
the specified height.
Returns
an off-screen drawable image, which can be used for double buffering.
Description
Creates an off-screen drawable image to be used for double buffering.


 Component.deliverEvent

Component.deliverEvent

Class Overview | Class Members | This Package | All Packages

Syntax
public void deliverEvent( Event e )
Description
Note: deliverEvent() is deprecated. As of JDK version 1.1, replaced by dispatchEvent(AWTEvent e).


 Component.disable

Component.disable

Class Overview | Class Members | This Package | All Packages

Syntax
public void disable()
Description
Note: disable() is deprecated. As of JDK version 1.1, replaced by setEnabled(boolean).


 Component.disableEvents

Component.disableEvents

Class Overview | Class Members | This Package | All Packages

Syntax
protected final void disableEvents( long eventsToDisable )
Parameters
eventsToDisable
the event mask defining the event types
Description
Disables the events defined by the specified event mask parameter from being delivered to this component.

See Also
enableEvents


 Component.dispatchEvent

Component.dispatchEvent

Class Overview | Class Members | This Package | All Packages

Syntax
public final void dispatchEvent( AWTEvent e )
Parameters
e
the event
Description
Dispatches an event to this component or one of its sub components.


 Component.doLayout

Component.doLayout

Class Overview | Class Members | This Package | All Packages

Syntax
public void doLayout()
Description
Prompts the layout manager to lay out this component. This is usually called when the component (more specifically, container) is validated.

See Also
validate, LayoutManager


 Component.enable

Component.enable

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void enable()
Description
Note: enable() is deprecated. As of JDK version 1.1, replaced by setEnabled(boolean).

Syntax 2
public void enable( boolean b )
Description
Note: enable() is deprecated. As of JDK version 1.1, replaced by setEnabled(boolean).


 Component.enableEvents

Component.enableEvents

Class Overview | Class Members | This Package | All Packages

Syntax
protected final void enableEvents( long eventsToEnable )
Parameters
eventsToEnable
the event mask defining the event types.
Description
Enables the events defined by the specified event mask parameter to be delivered to this component.

Event types are automatically enabled when a listener for that event type is added to the component.

This method only needs to be invoked by subclasses of Component which desire to have the specified event types delivered to processEvent regardless of whether or not a listener is registered.

See Also
processEvent, disableEvents


 Component.getAlignmentX

Component.getAlignmentX

Class Overview | Class Members | This Package | All Packages

Syntax
public float getAlignmentX()
Description
Returns the alignment along the x axis. This specifies how the component would like to be aligned relative to other components. The value should be a number between 0 and 1 where 0 represents alignment along the origin, 1 is aligned the furthest away from the origin, 0.5 is centered, etc.


 Component.getAlignmentY

Component.getAlignmentY

Class Overview | Class Members | This Package | All Packages

Syntax
public float getAlignmentY()
Description
Returns the alignment along the y axis. This specifies how the component would like to be aligned relative to other components. The value should be a number between 0 and 1 where 0 represents alignment along the origin, 1 is aligned the furthest away from the origin, 0.5 is centered, etc.


 Component.getBackground

Component.getBackground

Class Overview | Class Members | This Package | All Packages

Syntax
public Color getBackground()
Returns
This component's background color. If this component does not have a background color, the background color of its parent is returned.
Description
Gets the background color of this component.

See Also
setBackground


 Component.getBounds

Component.getBounds

Class Overview | Class Members | This Package | All Packages

Syntax
public Rectangle getBounds()
Returns
A rectangle indicating this component's bounds.
Description
Gets the bounds of this component in the form of a Rectangle object. The bounds specify this component's width, height, and location relative to its parent.

See Also
setBounds, getLocation, getSize


 Component.getColorModel

Component.getColorModel

Class Overview | Class Members | This Package | All Packages

Syntax
public ColorModel getColorModel()
Returns
The color model used by this component.
Description
Gets the instance of ColorModel used to display the component on the output device.

See Also
ColorModel, getColorModel, getColorModel


 Component.getComponentAt

Component.getComponentAt

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Component getComponentAt( int x, int y )
Parameters
x
the x coordinate.
y
the y coordinate.
Returns
the component or subcomponent that contains the (x, y) location; null if the location is outside this component.
Description
Determines if this component or one of its immediate subcomponents contains the (x, y) location, and if so, returns the containing component. This method only looks one level deep. If the point (x, y) is inside a subcomponent that itself has subcomponents, it does not go looking down the subcomponent tree.

The locate method of Component simply returns the component itself if the (x, y) coordinate location is inside its bounding box, and null otherwise.

See Also
contains

Syntax 2
public Component getComponentAt( Point p )
Parameters
p
the point.
Description
Returns the component or subcomponent that contains the specified point.

See Also
contains


 Component.getCursor

Component.getCursor

Class Overview | Class Members | This Package | All Packages

Syntax
public Cursor getCursor()
Returns
The cursor for this component.
Description
Gets the cursor set on this component.

See Also
setCursor, Cursor


 Component.getFont

Component.getFont

Class Overview | Class Members | This Package | All Packages

Syntax
public Font getFont()
Returns
This component's font. If a font has not been set for this component, the font of its parent is returned.
Description
Gets the font of this component.

See Also
setFont


 Component.getFontMetrics

Component.getFontMetrics

Class Overview | Class Members | This Package | All Packages

Syntax
public FontMetrics getFontMetrics( Font font )
Parameters
font
The font for which font metrics is to be obtained.
font
the font.
Returns
The font metrics for font.
Description
Gets the font metrics for the specified font.

See Also
getFont, getPeer, getFontMetrics, getFontMetrics


 Component.getForeground

Component.getForeground

Class Overview | Class Members | This Package | All Packages

Syntax
public Color getForeground()
Returns
This component's foreground color. If this component does not have a foreground color, the foreground color of its parent is returned.
Description
Gets the foreground color of this component.

See Also
java.awt.Component#setForeground


 Component.getGraphics

Component.getGraphics

Class Overview | Class Members | This Package | All Packages

Syntax
public Graphics getGraphics()
Returns
A graphics context for this component, or null if it has none.
Description
Creates a graphics context for this component. This method will return null if this component is currently not on the screen.

See Also
paint


 Component.getLocale

Component.getLocale

Class Overview | Class Members | This Package | All Packages

Syntax
public Locale getLocale()
Returns
This component's locale. If this component does not have a locale, the locale of its parent is returned.
Description
Gets the locale of this component.

Exceptions
IllegalComponentStateException If the Component does not have its own locale and has not yet been added to a containment hierarchy such that the locale can be determined from the containing parent.
See Also
setLocale


 Component.getLocation

Component.getLocation

Class Overview | Class Members | This Package | All Packages

Syntax
public Point getLocation()
Returns
An instance of Point representing the top-left corner of the component's bounds in the coordinate space of the component's parent.
Description
Gets the location of this component in the form of a point specifying the component's top-left corner. The location will be relative to the parent's coordinate space.

See Also
setLocation, getLocationOnScreen


 Component.getLocationOnScreen

Component.getLocationOnScreen

Class Overview | Class Members | This Package | All Packages

Syntax
public Point getLocationOnScreen()
Returns
An instance of Point representing the top-left corner of the component's bounds in the coordinate space of the screen.
Description
Gets the location of this component in the form of a point specifying the component's top-left corner in the screen's coordinate space.

See Also
setLocation, getLocation


 Component.getMaximumSize

Component.getMaximumSize

Class Overview | Class Members | This Package | All Packages

Syntax
public Dimension getMaximumSize()
Returns
A dimension object indicating this component's maximum size.
Description
Gets the maximum size of this component.

See Also
getMinimumSize, getPreferredSize, LayoutManager


 Component.getMinimumSize

Component.getMinimumSize

Class Overview | Class Members | This Package | All Packages

Syntax
public Dimension getMinimumSize()
Returns
A dimension object indicating this component's minimum size.
Description
Gets the mininimum size of this component.

See Also
getPreferredSize, awtLayoutManager


 Component.getName

Component.getName

Class Overview | Class Members | This Package | All Packages

Syntax
public String getName()
Returns
This component's name.
Description
Gets the name of the component.

See Also
setName


 Component.getParent

Component.getParent

Class Overview | Class Members | This Package | All Packages

Syntax
public Container getParent()
Returns
The parent container of this component.
Description
Gets the parent of this component.


 Component.getPeer

Component.getPeer

Class Overview | Class Members | This Package | All Packages

Syntax
public ComponentPeer getPeer()
Description
Note: getPeer() is deprecated. As of JDK version 1.1, programs should not directly manipulate peers.


 Component.getPreferredSize

Component.getPreferredSize

Class Overview | Class Members | This Package | All Packages

Syntax
public Dimension getPreferredSize()
Returns
A dimension object indicating this component's preferred size.
Description
Gets the preferred size of this component.

See Also
getMinimumSize, LayoutManager


 Component.getSize

Component.getSize

Class Overview | Class Members | This Package | All Packages

Syntax
public Dimension getSize()
Returns
A Dimension object that indicates the size of this component.
Description
Returns the size of this component in the form of a Dimension object. The height field of the Dimension object contains this component's height, and the width field of the Dimension object contains this component's width.

See Also
setSize


 Component.getToolkit

Component.getToolkit

Class Overview | Class Members | This Package | All Packages

Syntax
public Toolkit getToolkit()
Returns
The toolkit of this component.
Description
Gets the toolkit of this component. Note that the frame that contains a component controls which toolkit is used by that component. Therefore if the component is moved from one frame to another, the toolkit it uses may change.


 Component.getTreeLock

Component.getTreeLock

Class Overview | Class Members | This Package | All Packages

Syntax
public final Object getTreeLock()
Returns
This component's locking object.
Description
Gets this component's locking object (the object that owns the thread sychronization monitor) for AWT component-tree and layout operations.


 Component.gotFocus

Component.gotFocus

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean gotFocus( Event evt, Object what )
Description
Note: gotFocus() is deprecated. As of JDK version 1.1, replaced by processFocusEvent(FocusEvent).


 Component.handleEvent

Component.handleEvent

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean handleEvent( Event evt )
Description
Note: handleEvent() is deprecated. As of JDK version 1.1 replaced by processEvent(AWTEvent).


 Component.hide

Component.hide

Class Overview | Class Members | This Package | All Packages

Syntax
public void hide()
Description
Note: hide() is deprecated. As of JDK version 1.1, replaced by setVisible(boolean).


 Component.imageUpdate

Component.imageUpdate

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean imageUpdate( Image img, int flags, int x, int y, int w, int h )
Parameters
img
the image being observed.
infoflags
see imageUpdate for more information.
x
the x coordinate.
y
the y coordinate.
width
the width.
height
the height.
Returns
true if the flags indicate that the image is completely loaded; false otherwise.
Description
Repaints the component when the image has changed. This imageUpdate method of an ImageObserver is called when more information about an image which had been previously requested using an asynchronous routine such as the drawImage method of Graphics becomes available. See the definition of imageUpdate for more information on this method and its arguments.

The imageUpdate method of Component incrementally draws an image on the component as more of the bits of the image are available.

If the system property awt.image.incrementalDraw is missing or has the value true, the image is incrementally drawn, If the system property has any other value, then the image is not drawn until it has been completely loaded.

Also, if incremental drawing is in effect, the value of the system property awt.image.redrawrate is interpreted as an integer to give the maximum redraw rate, in milliseconds. If the system property is missing or cannot be interpreted as an integer, the redraw rate is once every 100ms.

The interpretation of the x, y, width, and height arguments depends on the value of the infoflags argument.

See Also
ImageObserver, drawImage, drawImage, drawImage, drawImage, imageUpdate


 Component.inside

Component.inside

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean inside( int x, int y )
Description
Note: inside() is deprecated. As of JDK version 1.1, replaced by contains(int, int).


 Component.invalidate

Component.invalidate

Class Overview | Class Members | This Package | All Packages

Syntax
public void invalidate()
Description
Invalidates this component. This component and all parents above it are marked as needing to be laid out. This method can be called often, so it needs to execute quickly.

See Also
validate, doLayout, LayoutManager


 Component.isEnabled

Component.isEnabled

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isEnabled()
Returns
true if the component is enabled; false otherwise.
Description
Determines whether this component is enabled. An enabled component can respond to user input and generate events. Components are enabled initially by default. A component may be enabled or disabled by calling its setEnabled method.

See Also
setEnabled


 Component.isFocusTraversable

Component.isFocusTraversable

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isFocusTraversable()
Returns
true if this component is focus-traverable; false otherwise.
Description
Returns the value of a flag that indicates whether this component can be traversed using Tab or Shift-Tab keyboard focus traversal. If this method returns "false", this component may still request the keyboard focus using requestFocus(), but it will not automatically be assigned focus during tab traversal.


 Component.isShowing

Component.isShowing

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isShowing()
Returns
true if the component is showing; false otherwise.
Description
Determines whether this component is showing on screen. This means that the component must be visible, and it must be in a container that is visible and showing.

See Also
setVisible


 Component.isValid

Component.isValid

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isValid()
Returns
true if the component is valid; false otherwise.
Description
Determines whether this component is valid. Components are invalidated when they are first shown on the screen.

See Also
validate, invalidate


 Component.isVisible

Component.isVisible

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isVisible()
Returns
true if the component is visible; false otherwise.
Description
Determines whether this component is visible. Components are initially visible, with the exception of top level components such as Frame objects.

See Also
setVisible


 Component.keyDown

Component.keyDown

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean keyDown( Event evt, int key )
Description
Note: keyDown() is deprecated. As of JDK version 1.1, replaced by processKeyEvent(KeyEvent).


 Component.keyUp

Component.keyUp

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean keyUp( Event evt, int key )
Description
Note: keyUp() is deprecated. As of JDK version 1.1, replaced by processKeyEvent(KeyEvent).


 Component.layout

Component.layout

Class Overview | Class Members | This Package | All Packages

Syntax
public void layout()
Description
Note: layout() is deprecated. As of JDK version 1.1, replaced by doLayout().


 Component.list

Component.list

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void list()
Description
Prints a listing of this component to the standard system output stream System.out.

See Also
out

Syntax 2
public void list( PrintStream out )
Parameters
out
a print stream.
Description
Prints a listing of this component to the specified output stream.

Syntax 3
public void list( PrintStream out, int indent )
Parameters
out
a print stream.
indent
number of spaces to indent.
Description
Prints out a list, starting at the specified indention, to the specified print stream.

See Also
println

Syntax 4
public void list( PrintWriter out )
Parameters
out
The print writer to print to.
Description
Prints a listing to the specified print writer.

Syntax 5
public void list( PrintWriter out, int indent )
Parameters
out
The print writer to print to.
indent
The number of spaces to indent.
Description
Prints out a list, starting at the specified indention, to the specified print writer.

See Also
println


 Component.locate

Component.locate

Class Overview | Class Members | This Package | All Packages

Syntax
public Component locate( int x, int y )
Description
Note: locate() is deprecated. As of JDK version 1.1, replaced by getComponentAt(int, int).


 Component.location

Component.location

Class Overview | Class Members | This Package | All Packages

Syntax
public Point location()
Description
Note: location() is deprecated. As of JDK version 1.1, replaced by getLocation().


 Component.lostFocus

Component.lostFocus

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean lostFocus( Event evt, Object what )
Description
Note: lostFocus() is deprecated. As of JDK version 1.1, replaced by processFocusEvent(FocusEvent).


 Component.minimumSize

Component.minimumSize

Class Overview | Class Members | This Package | All Packages

Syntax
public Dimension minimumSize()
Description
Note: minimumSize() is deprecated. As of JDK version 1.1, replaced by getMinimumSize().


 Component.mouseDown

Component.mouseDown

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean mouseDown( Event evt, int x, int y )
Description
Note: mouseDown() is deprecated. As of JDK version 1.1, replaced by processMouseEvent(MouseEvent).


 Component.mouseDrag

Component.mouseDrag

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean mouseDrag( Event evt, int x, int y )
Description
Note: mouseDrag() is deprecated. As of JDK version 1.1, replaced by processMouseMotionEvent(MouseEvent).


 Component.mouseEnter

Component.mouseEnter

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean mouseEnter( Event evt, int x, int y )
Description
Note: mouseEnter() is deprecated. As of JDK version 1.1, replaced by processMouseEvent(MouseEvent).


 Component.mouseExit

Component.mouseExit

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean mouseExit( Event evt, int x, int y )
Description
Note: mouseExit() is deprecated. As of JDK version 1.1, replaced by processMouseEvent(MouseEvent).


 Component.mouseMove

Component.mouseMove

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean mouseMove( Event evt, int x, int y )
Description
Note: mouseMove() is deprecated. As of JDK version 1.1, replaced by processMouseMotionEvent(MouseEvent).


 Component.mouseUp

Component.mouseUp

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean mouseUp( Event evt, int x, int y )
Description
Note: mouseUp() is deprecated. As of JDK version 1.1, replaced by processMouseEvent(MouseEvent).


 Component.move

Component.move

Class Overview | Class Members | This Package | All Packages

Syntax
public void move( int x, int y )
Description
Note: move() is deprecated. As of JDK version 1.1, replaced by setLocation(int, int).


 Component.nextFocus

Component.nextFocus

Class Overview | Class Members | This Package | All Packages

Syntax
public void nextFocus()
Description
Note: nextFocus() is deprecated. As of JDK version 1.1, replaced by transferFocus().


 Component.paint

Component.paint

Class Overview | Class Members | This Package | All Packages

Syntax
public void paint( Graphics g )
Parameters
g
The graphics context to use for painting.
Description
Paints this component. This method is called when the contents of the component should be painted in response to the component first being shown or damage needing repair. The clip rectangle in the Graphics parameter will be set to the area which needs to be painted.

See Also
update


 Component.paintAll

Component.paintAll

Class Overview | Class Members | This Package | All Packages

Syntax
public void paintAll( Graphics g )
Parameters
g
the graphics context to use for painting.
Description
Paints this component and all of its subcomponents.

The origin of the graphics context, its (0, 0) coordinate point, is the top-left corner of this component. The clipping region of the graphics context is the bounding rectangle of this component.

See Also
paint


 Component.paramString

Component.paramString

Class Overview | Class Members | This Package | All Packages

Syntax
protected String paramString()
Returns
the parameter string of this component.
Description
Returns the parameter string representing the state of this component. This string is useful for debugging.


 Component.postEvent

Component.postEvent

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean postEvent( Event e )
Description
Note: postEvent() is deprecated. As of JDK version 1.1, replaced by dispatchEvent(AWTEvent).


 Component.preferredSize

Component.preferredSize

Class Overview | Class Members | This Package | All Packages

Syntax
public Dimension preferredSize()
Description
Note: preferredSize() is deprecated. As of JDK version 1.1, replaced by getPreferredSize().


 Component.prepareImage

Component.prepareImage

Class Overview | Class Members | This Package | All Packages

Syntax 1
public boolean prepareImage( Image image, ImageObserver observer )
Parameters
image
the Image for which to prepare a screen representation.
observer
the ImageObserver object to be notified as the image is being prepared.
Returns
true if the image has already been fully prepared; false otherwise.
Description
Prepares an image for rendering on this component. The image data is downloaded asynchronously in another thread and the appropriate screen representation of the image is generated.

Syntax 2
public boolean prepareImage( Image image, int width, int height, ImageObserver observer )
Parameters
image
the instance of Image for which to prepare a screen representation.
width
the width of the desired screen representation.
height
the height of the desired screen representation.
observer
the ImageObserver object to be notified as the image is being prepared.
Returns
true if the image has already been fully prepared; false otherwise.
Description
Prepares an image for rendering on this component at the specified width and height.

The image data is downloaded asynchronously in another thread, and an appropriately scaled screen representation of the image is generated.

See Also
ImageObserver


 Component.print

Component.print

Class Overview | Class Members | This Package | All Packages

Syntax
public void print( Graphics g )
Parameters
g
the graphics context to use for printing.
Description
Prints this component. Applications should override this method for components that must do special processing before being printed or should be printed differently than they are painted.

The default implementation of this method calls the paint method.

The origin of the graphics context, its (0, 0) coordinate point, is the top-left corner of this component. The clipping region of the graphics context is the bounding rectangle of this component.

See Also
paint


 Component.printAll

Component.printAll

Class Overview | Class Members | This Package | All Packages

Syntax
public void printAll( Graphics g )
Parameters
g
the graphics context to use for printing.
Description
Prints this component and all of its subcomponents.

The origin of the graphics context, its (0, 0) coordinate point, is the top-left corner of this component. The clipping region of the graphics context is the bounding rectangle of this component.

See Also
print


 Component.processComponentEvent

Component.processComponentEvent

Class Overview | Class Members | This Package | All Packages

Syntax
protected void processComponentEvent( ComponentEvent e )
Parameters
e
the component event.
Description
Processes component events occurring on this component by dispatching them to any registered ComponentListener objects.

This method is not called unless component events are enabled for this component. Component events are enabled when one of the following occurs:

  • A ComponentListener object is registered via addComponentListener.
  • Component events are enabled via enableEvents.

See Also
ComponentEvent, ComponentListener, addComponentListener, enableEvents


 Component.processEvent

Component.processEvent

Class Overview | Class Members | This Package | All Packages

Syntax
protected void processEvent( AWTEvent e )
Parameters
e
the event.
Description
Processes events occurring on this component. By default this method calls the appropriate process<event type>Event method for the given class of event.

See Also
processComponentEvent, processFocusEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent


 Component.processFocusEvent

Component.processFocusEvent

Class Overview | Class Members | This Package | All Packages

Syntax
protected void processFocusEvent( FocusEvent e )
Parameters
e
the focus event.
Description
Processes focus events occurring on this component by dispatching them to any registered FocusListener objects.

This method is not called unless focus events are enabled for this component. Focus events are enabled when one of the following occurs:

  • A FocusListener object is registered via addFocusListener.
  • Focus events are enabled via enableEvents.

See Also
FocusEvent, FocusListener, addFocusListener, enableEvents


 Component.processKeyEvent

Component.processKeyEvent

Class Overview | Class Members | This Package | All Packages

Syntax
protected void processKeyEvent( KeyEvent e )
Parameters
e
the key event.
Description
Processes key events occurring on this component by dispatching them to any registered KeyListener objects.

This method is not called unless key events are enabled for this component. Key events are enabled when one of the following occurs:

  • A KeyListener object is registered via addKeyListener.
  • Key events are enabled via enableEvents.

See Also
KeyEvent, KeyListener, addKeyListener, enableEvents


 Component.processMouseEvent

Component.processMouseEvent

Class Overview | Class Members | This Package | All Packages

Syntax
protected void processMouseEvent( MouseEvent e )
Parameters
e
the mouse event.
Description
Processes mouse events occurring on this component by dispatching them to any registered MouseListener objects.

This method is not called unless mouse events are enabled for this component. Mouse events are enabled when one of the following occurs:

  • A MouseListener object is registered via addMouseListener.
  • Mouse events are enabled via enableEvents.

See Also
MouseEvent, MouseListener, addMouseListener, enableEvents


 Component.processMouseMotionEvent

Component.processMouseMotionEvent

Class Overview | Class Members | This Package | All Packages

Syntax
protected void processMouseMotionEvent( MouseEvent e )
Parameters
e
the mouse motion event.
Description
Processes mouse motion events occurring on this component by dispatching them to any registered MouseMotionListener objects.

This method is not called unless mouse motion events are enabled for this component. Mouse motion events are enabled when one of the following occurs:

  • A MouseMotionListener object is registered via addMouseMotionListener.
  • Mouse motion events are enabled via enableEvents.

See Also
MouseMotionEvent, MouseMotionListener, addMouseMotionListener, enableEvents


 Component.remove

Component.remove

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void remove( MenuComponent popup )
Parameters
popup
the popup menu to be removed.
Description
Removes the specified popup menu from the component.

See Also
add


 Component.removeComponentListener

Component.removeComponentListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void removeComponentListener( ComponentListener l )
Parameters
l
the component listener.
Description
Removes the specified component listener so that it no longer receives component events from this component.

See Also
ComponentEvent, ComponentListener, addComponentListener


 Component.removeFocusListener

Component.removeFocusListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void removeFocusListener( FocusListener l )
Parameters
l
the focus listener.
Description
Removes the specified focus listener so that it no longer receives focus events from this component.

See Also
FocusEvent, FocusListener, addFocusListener


 Component.removeKeyListener

Component.removeKeyListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void removeKeyListener( KeyListener l )
Parameters
l
the key listener.
Description
Removes the specified key listener so that it no longer receives key events from this component.

See Also
KeyEvent, KeyListener, addKeyListener


 Component.removeMouseListener

Component.removeMouseListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void removeMouseListener( MouseListener l )
Parameters
l
the mouse listener.
Description
Removes the specified mouse listener so that it no longer receives mouse events from this component.

See Also
MouseEvent, MouseListener, addMouseListener


 Component.removeMouseMotionListener

Component.removeMouseMotionListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void removeMouseMotionListener( MouseMotionListener l )
Parameters
l
the mouse motion listener.
Description
Removes the specified mouse motion listener so that it no longer receives mouse motion events from this component.

See Also
MouseMotionEvent, MouseMotionListener, addMouseMotionListener


 Component.removeNotify

Component.removeNotify

Class Overview | Class Members | This Package | All Packages

Syntax
public void removeNotify()
Description
Notifies this component that it has been removed from its container and if a peers exists, it destroys it. This method should be called by Container.remove, and not by user code directly.

See Also
addNotify


 Component.repaint

Component.repaint

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void repaint()
Description
Repaints this component.

This method causes a call to this component's update method as soon as possible.

See Also
update

Syntax 2
public void repaint( long tm )
Parameters
tm
maximum time in milliseconds before update
Description
Repaints the component. This will result in a call to update within tm milliseconds.

See Also
paint, update

Syntax 3
public void repaint( int x, int y, int width, int height )
Parameters
x
the x coordinate.
y
the y coordinate.
width
the width.
height
the height.
Description
Repaints the specified rectangle of this component.

This method causes a call to this component's update method as soon as possible.

See Also
update

Syntax 4
public void repaint( long tm, int x, int y, int width, int height )
Parameters
tm
maximum time in milliseconds before update.
x
the x coordinate.
y
the y coordinate.
width
the width.
height
the height.
Description
Repaints the specified rectangle of this component within tm milliseconds.

This method causes a call to this component's update method.

See Also
update


 Component.requestFocus

Component.requestFocus

Class Overview | Class Members | This Package | All Packages

Syntax
public void requestFocus()
Description
Requests that this component get the input focus.

This component's gotFocus method is called when this method is successful. The component must be visible on the screen for this request to be granted

See Also
FocusEvent, addFocusListener, processFocusEvent, isFocusTraversable


 Component.reshape

Component.reshape

Class Overview | Class Members | This Package | All Packages

Syntax
public void reshape( int x, int y, int width, int height )
Description
Note: reshape() is deprecated. As of JDK version 1.1, replaced by setBounds(int, int, int, int).


 Component.resize

Component.resize

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void resize( int width, int height )
Description
Note: resize() is deprecated. As of JDK version 1.1, replaced by setSize(int, int).

Syntax 2
public void resize( Dimension d )
Description
Note: resize() is deprecated. As of JDK version 1.1, replaced by setSize(Dimension).


 Component.setBackground

Component.setBackground

Class Overview | Class Members | This Package | All Packages

Syntax
public void setBackground( Color c )
Parameters
c
The color to become this component's background color.
Description
Sets the background color of this component.

See Also
getBackground


 Component.setBounds

Component.setBounds

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void setBounds( int x, int y, int width, int height )
Parameters
x
The new x-coordinate of this component.
y
The new y-coordinate of this component.
width
The new width of this component.
height
The new height of this component.
Description
Moves and resizes this component. The new location of the top-left corner is specified by x and y, and the new size is specified by width and height.

See Also
getBounds, setLocation, setLocation, setSize, setSize

Syntax 2
public void setBounds( Rectangle r )
Parameters
r
The new bounding rectangle for this component.
Description
Moves and resizes this component to conform to the new bounding rectangle r. This component's new position is specified by r.x and r.y, and its new size is specified by r.width and r.height.

See Also
getBounds, setLocation, setLocation, setSize, setSize


 Component.setCursor

Component.setCursor

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setCursor( Cursor cursor )
Parameters
cursor
One of the constants defined by the Cursor class.
Description
Set the cursor image to a predefined cursor.

See Also
getCursor, Cursor


 Component.setEnabled

Component.setEnabled

Class Overview | Class Members | This Package | All Packages

Syntax
public void setEnabled( boolean b )
Parameters
b
If true, this component is enabled; otherwise this component is disabled.
Description
Enables or disables this component, depending on the value of the parameter b. An enabled component can respond to user input and generate events. Components are enabled initially by default.

See Also
isEnabled


 Component.setFont

Component.setFont

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setFont( Font f )
Parameters
f
The font to become this component's font.
Description
Sets the font of this component.

See Also
getFont


 Component.setForeground

Component.setForeground

Class Overview | Class Members | This Package | All Packages

Syntax
public void setForeground( Color c )
Parameters
c
The color to become this component's foreground color.
Description
Sets the foreground color of this component.

See Also
getForeground


 Component.setLocale

Component.setLocale

Class Overview | Class Members | This Package | All Packages

Syntax
public void setLocale( Locale l )
Parameters
l
The locale to become this component's locale.
Description
Sets the locale of this component.

See Also
getLocale


 Component.setLocation

Component.setLocation

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void setLocation( int x, int y )
Parameters
x
The x-coordinate of the new location's top-left corner in the parent's coordinate space.
y
The y-coordinate of the new location's top-left corner in the parent's coordinate space.
Description
Moves this component to a new location. The top-left corner of the new location is specified by the x and y parameters in the coordinate space of this component's parent.

See Also
getLocation, setBounds

Syntax 2
public void setLocation( Point p )
Parameters
p
The point defining the top-left corner of the new location, given in the coordinate space of this component's parent.
Description
Moves this component to a new location. The top-left corner of the new location is specified by point p. Point p is given in the parent's coordinate space.

See Also
getLocation, setBounds


 Component.setName

Component.setName

Class Overview | Class Members | This Package | All Packages

Syntax
public void setName( String name )
Parameters
name
The string that is to be this component's name.
Description
Sets the name of the component to the specified string.

See Also
getName


 Component.setSize

Component.setSize

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void setSize( int width, int height )
Parameters
width
The new width of this component in pixels.
height
The new height of this component in pixels.
Description
Resizes this component so that it has width width and height.

See Also
getSize, setBounds

Syntax 2
public void setSize( Dimension d )
Parameters
d
The dimension specifying the new size of this component.
Description
Resizes this component so that it has width d.width and height d.height.

See Also
setSize, setBounds


 Component.setVisible

Component.setVisible

Class Overview | Class Members | This Package | All Packages

Syntax
public void setVisible( boolean b )
Parameters
b
If true, shows this component; otherwise, hides this component.
Description
Shows or hides this component depending on the value of parameter b.

See Also
isVisible


 Component.show

Component.show

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void show()
Description
Note: show() is deprecated. As of JDK version 1.1, replaced by setVisible(boolean).

Syntax 2
public void show( boolean b )
Description
Note: show() is deprecated. As of JDK version 1.1, replaced by setVisible(boolean).


 Component.size

Component.size

Class Overview | Class Members | This Package | All Packages

Syntax
public Dimension size()
Description
Note: size() is deprecated. As of JDK version 1.1, replaced by getSize().


 Component.toString

Component.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string representation of this component.
Description
Returns a string representation of this component and its values.

Overrides
toString in class Object


 Component.transferFocus

Component.transferFocus

Class Overview | Class Members | This Package | All Packages

Syntax
public void transferFocus()
Description
Transfers the focus to the next component.

See Also
requestFocus, gotFocus


 Component.update

Component.update

Class Overview | Class Members | This Package | All Packages

Syntax
public void update( Graphics g )
Parameters
g
the specified context to use for updating.
Description
Updates this component.

The AWT calls the update method in response to a call to repaint. The appearance of the component on the screen has not changed since the last call to update or paint. You can assume that the background is not cleared.

The updatemethod of Component does the following:

  • Clears this component by filling it with the background color.
  • Sets the color of the graphics context to be the foreground color of this component.
  • Calls this component's paint method to completely redraw this component.

The origin of the graphics context, its (0, 0) coordinate point, is the top-left corner of this component. The clipping region of the graphics context is the bounding rectangle of this component.

See Also
paint, repaint


 Component.validate

Component.validate

Class Overview | Class Members | This Package | All Packages

Syntax
public void validate()
Description
Ensures that this component has a valid layout. This method is primarily intended to operate on instances of Container.

See Also
invalidate, doLayout, LayoutManager, validate


 Class Container

Class java.awt.Container

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.Component
           |
           +----java.awt.Container

public abstract class Container
extends Component

A generic Abstract Window Toolkit(AWT) container object is a component that can contain other AWT components.

Components added to a container are tracked in a list. The order of the list will define the components' front-to-back stacking order within the container. If no index is specified when adding a component to a container, it will be added to the end of the list (and hence to the bottom of the stacking order).

See Also:
add, getComponent, LayoutManager


 Container Members

Container Members

Class Overview | This Package | All Packages

Constructors
Name | Description
Container() | Constructs a new Container.

Methods
Name | Description
add(Component) | Adds the specified component to the end of this container.
add(Component, int) | Adds the specified component to this container at the given position.
add(Component, Object) | Adds the specified component to the end of this container.
add(Component, Object, int) | Adds the specified component to this container with the specified constraints at the specified index.
add(String, Component) | Adds the specified component to this container.
addContainerListener(ContainerListener) | Adds the specified container listener to receive container events from this container.
addImpl(Component, Object, int) | Adds the specified component to this container at the specified index.
addNotify() | Notifies the container to create a peer.
countComponents() | Deprecated.
deliverEvent(Event) | Deprecated.
doLayout() | Causes this container to lay out its components.
getAlignmentX() | Returns the alignment along the x axis.
getAlignmentY() | Returns the alignment along the y axis.
getComponent(int) | Gets the nth component in this container.
getComponentAt(int, int) | Locates the component that contains the x,y position.
getComponentAt(Point) | Gets the component that contains the specified point.
getComponentCount() | Gets the number of components in this panel.
getComponents() | Gets all the components in this container.
getInsets() | Determines the insets of this container, which indicate the size of the container's border.
getLayout() | Gets the layout manager for this container.
getMaximumSize() | Returns the maximum size of this container.
getMinimumSize() | Returns the minimum size of this container.
getPreferredSize() | Returns the preferred size of this container.
insets() | Deprecated.
invalidate() | Invalidates the container.
isAncestorOf(Component) | Checks if the component is contained in the component hierarchy of this container.
layout() | Deprecated.
list(PrintStream, int) | Prints a listing of this container to the specified output stream.
list(PrintWriter, int) | Prints out a list, starting at the specified indention, to the specified print writer.
locate(int, int) | Deprecated.
minimumSize() | Deprecated.
paint(Graphics) | Paints the container.
paintComponents(Graphics) | Paints each of the components in this container.
paramString() | Returns the parameter string representing the state of this container.
preferredSize() | Deprecated.
print(Graphics) | Prints the container.
printComponents(Graphics) | Prints each of the components in this container.
processContainerEvent(ContainerEvent) | Processes container events occurring on this container by dispatching them to any registered ContainerListener objects.
processEvent(AWTEvent) | Processes events on this container.
remove(Component) | Removes the specified component from this container.
remove(int) | Removes the component, specified by index, from this container.
removeAll() | Removes all the components from this container.
removeContainerListener(ContainerListener) | Removes the specified container listener so it no longer receives container events from this container.
removeNotify() | Notifies this container and all of its subcomponents to remove their peers.
setLayout(LayoutManager) | Sets the layout manager for this container.
validate() | Validates this container and all of its subcomponents.
validateTree() | Recursively descends the container tree and recomputes the layout for any subtrees marked as needing it (those marked as invalid).


 Container.Container

Container.Container

Class Overview | Class Members | This Package | All Packages

Syntax
protected Container()
Description
Constructs a new Container. Containers can be extended directly, but are lightweight in this case and must be contained by a parent somewhere higher up in the component tree that is native. (such as Frame for example).


 Container.add

Container.add

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Component add( Component comp )
Parameters
comp
the component to be added.
Returns
the component argument.
Description
Adds the specified component to the end of this container.

Syntax 2
public Component add( String name, Component comp )
Description
Adds the specified component to this container. It is strongly advised to use the 1.1 method, add(Component, Object), in place of this method.

Syntax 3
public Component add( Component comp, int index )
Parameters
comp
the component to be added.
index
the position at which to insert the component, or -1 to insert the component at the end.
Returns
the component comp
Description
Adds the specified component to this container at the given position.

See Also
remove

Syntax 4
public void add( Component comp, Object constraints )
Parameters
comp
the component to be added
constraints
an object expressing layout contraints for this component
Description
Adds the specified component to the end of this container. Also notifies the layout manager to add the component to this container's layout using the specified constraints object.

See Also
LayoutManager

Syntax 5
public void add( Component comp, Object constraints, int index )
Parameters
comp
the component to be added
constraints
an object expressing layout contraints for this
index
the position in the container's list at which to insert the component. -1 means insert at the end. component
Description
Adds the specified component to this container with the specified constraints at the specified index. Also notifies the layout manager to add the component to the this container's layout using the specified constraints object.

See Also
remove, LayoutManager


 Container.addContainerListener

Container.addContainerListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void addContainerListener( ContainerListener l )
Parameters
l
the container listener
Description
Adds the specified container listener to receive container events from this container.


 Container.addImpl

Container.addImpl

Class Overview | Class Members | This Package | All Packages

Syntax
protected void addImpl( Component comp, Object constraints, int index )
Parameters
comp
the component to be added.
constraints
an object expressing layout contraints for this component.
index
the position in the container's list at which to insert the component, where -1 means insert at the end.
Description
Adds the specified component to this container at the specified index. This method also notifies the layout manager to add the component to this container's layout using the specified constraints object.

This is the method to override if a program needs to track every add request to a container. An overriding method should usually include a call to the superclass's version of the method:

super.addImpl(comp, constraints, index)

See Also
add, add, add, LayoutManager


 Container.addNotify

Container.addNotify

Class Overview | Class Members | This Package | All Packages

Syntax
public void addNotify()
Description
Notifies the container to create a peer. It will also notify the components contained in this container. This method should be called by Container.add, and not by user code directly.

Overrides
addNotify in class Component
See Also
removeNotify


 Container.countComponents

Container.countComponents

Class Overview | Class Members | This Package | All Packages

Syntax
public int countComponents()
Description
Note: countComponents() is deprecated. As of JDK version 1.1, replaced by getComponentCount().


 Container.deliverEvent

Container.deliverEvent

Class Overview | Class Members | This Package | All Packages

Syntax
public void deliverEvent( Event e )
Description
Note: deliverEvent() is deprecated. As of JDK version 1.1, replaced by dispatchEvent(AWTEvent e)

Overrides
deliverEvent in class Component


 Container.doLayout

Container.doLayout

Class Overview | Class Members | This Package | All Packages

Syntax
public void doLayout()
Description
Causes this container to lay out its components. Most programs should not call this method directly, but should invoke the validate method instead.

Overrides
doLayout in class Component
See Also
layoutContainer, setLayout, validate


 Container.getAlignmentX

Container.getAlignmentX

Class Overview | Class Members | This Package | All Packages

Syntax
public float getAlignmentX()
Description
Returns the alignment along the x axis. This specifies how the component would like to be aligned relative to other components. The value should be a number between 0 and 1 where 0 represents alignment along the origin, 1 is aligned the furthest away from the origin, 0.5 is centered, etc.

Overrides
getAlignmentX in class Component


 Container.getAlignmentY

Container.getAlignmentY

Class Overview | Class Members | This Package | All Packages

Syntax
public float getAlignmentY()
Description
Returns the alignment along the y axis. This specifies how the component would like to be aligned relative to other components. The value should be a number between 0 and 1 where 0 represents alignment along the origin, 1 is aligned the furthest away from the origin, 0.5 is centered, etc.

Overrides
getAlignmentY in class Component


 Container.getComponent

Container.getComponent

Class Overview | Class Members | This Package | All Packages

Syntax
public Component getComponent( int n )
Parameters
n
the index of the component to get.
Returns
the nth component in this container.
Description
Gets the nth component in this container.

Exceptions
ArrayIndexOutOfBoundsException if the nth value does not exist.


 Container.getComponentAt

Container.getComponentAt

Class Overview | Class Members | This Package | All Packages

Syntax
public Component getComponentAt( int x, int y )
Parameters
x
the x coordinate
y
the y coordinate
Returns
null if the component does not contain the position. If there is no child component at the requested point and the point is within the bounds of the container the container itself is returned; otherwise the top-most child is returned.
Description
Locates the component that contains the x,y position. The top-most child component is returned in the case where there is overlap in the components. This is determined by finding the component closest to the index 0 that claims to contain the given point via Component.contains().

Overrides
getComponentAt in class Component
See Also
contains


 Container.getComponentAt

Container.getComponentAt

Class Overview | Class Members | This Package | All Packages

Syntax
public Component getComponentAt( Point p )
Parameters
p
the point.
Returns
returns the component that contains the point, or null if the component does not contain the point.
Description
Gets the component that contains the specified point.

Overrides
getComponentAt in class Component
See Also
contains


 Container.getComponentCount

Container.getComponentCount

Class Overview | Class Members | This Package | All Packages

Syntax
public int getComponentCount()
Returns
the number of components in this panel.
Description
Gets the number of components in this panel.

See Also
getComponent


 Container.getComponents

Container.getComponents

Class Overview | Class Members | This Package | All Packages

Syntax
public Component[] getComponents()
Returns
an array of all the components in this container.
Description
Gets all the components in this container.


 Container.getInsets

Container.getInsets

Class Overview | Class Members | This Package | All Packages

Syntax
public Insets getInsets()
Returns
the insets of this container.
Description
Determines the insets of this container, which indicate the size of the container's border.

A Frame object, for example, has a top inset that corresponds to the height of the frame's title bar.

See Also
Insets, LayoutManager


 Container.getLayout

Container.getLayout

Class Overview | Class Members | This Package | All Packages

Syntax
public LayoutManager getLayout()
Description
Gets the layout manager for this container.

See Also
doLayout, setLayout


 Container.getMaximumSize

Container.getMaximumSize

Class Overview | Class Members | This Package | All Packages

Syntax
public Dimension getMaximumSize()
Description
Returns the maximum size of this container.

Overrides
getMaximumSize in class Component
See Also
getPreferredSize


 Container.getMinimumSize

Container.getMinimumSize

Class Overview | Class Members | This Package | All Packages

Syntax
public Dimension getMinimumSize()
Returns
an instance of Dimension that represents the minimum size of this container.
Description
Returns the minimum size of this container.

Overrides
getMinimumSize in class Component
See Also
getPreferredSize, getLayout, minimumLayoutSize, getMinimumSize


 Container.getPreferredSize

Container.getPreferredSize

Class Overview | Class Members | This Package | All Packages

Syntax
public Dimension getPreferredSize()
Returns
an instance of Dimension that represents the preferred size of this container.
Description
Returns the preferred size of this container.

Overrides
getPreferredSize in class Component
See Also
getMinimumSize, getLayout, preferredLayoutSize, getPreferredSize


 Container.insets

Container.insets

Class Overview | Class Members | This Package | All Packages

Syntax
public Insets insets()
Description
Note: insets() is deprecated. As of JDK version 1.1, replaced by getInsets().


 Container.invalidate

Container.invalidate

Class Overview | Class Members | This Package | All Packages

Syntax
public void invalidate()
Description
Invalidates the container. The container and all parents above it are marked as needing to be laid out. This method can be called often, so it needs to execute quickly.

Overrides
invalidate in class Component
See Also
validate, layout, LayoutManager


 Container.isAncestorOf

Container.isAncestorOf

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isAncestorOf( Component c )
Parameters
c
the component
Returns
true if it is an ancestor; true otherwise.
Description
Checks if the component is contained in the component hierarchy of this container.


 Container.layout

Container.layout

Class Overview | Class Members | This Package | All Packages

Syntax
public void layout()
Description
Note: layout() is deprecated. As of JDK version 1.1, replaced by doLayout().

Overrides
layout in class Component


 Container.list

Container.list

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void list( PrintStream out, int indent )
Parameters
out
a print stream.
indent
the number of spaces to indent.
Description
Prints a listing of this container to the specified output stream. The listing starts at the specified indentation.

Overrides
list in class Component
See Also
list

Syntax 2
public void list( PrintWriter out, int indent )
Description
Prints out a list, starting at the specified indention, to the specified print writer.

Overrides
list in class Component


 Container.locate

Container.locate

Class Overview | Class Members | This Package | All Packages

Syntax
public Component locate( int x, int y )
Description
Note: locate() is deprecated. As of JDK version 1.1, replaced by getComponentAt(int, int).

Overrides
locate in class Component


 Container.minimumSize

Container.minimumSize

Class Overview | Class Members | This Package | All Packages

Syntax
public Dimension minimumSize()
Description
Note: minimumSize() is deprecated. As of JDK version 1.1, replaced by getMinimumSize().

Overrides
minimumSize in class Component


 Container.paint

Container.paint

Class Overview | Class Members | This Package | All Packages

Syntax
public void paint( Graphics g )
Parameters
g
the specified Graphics window
Description
Paints the container. This forwards the paint to any lightweight components that are children of this container. If this method is reimplemented, super.paint(g) should be called so that lightweight components are properly rendered. If a child component is entirely clipped by the current clipping setting in g, paint() will not be forwarded to that child.

Overrides
paint in class Component
See Also
update


 Container.paintComponents

Container.paintComponents

Class Overview | Class Members | This Package | All Packages

Syntax
public void paintComponents( Graphics g )
Parameters
g
the graphics context.
Description
Paints each of the components in this container.

See Also
paint, paintAll


 Container.paramString

Container.paramString

Class Overview | Class Members | This Package | All Packages

Syntax
protected String paramString()
Returns
the parameter string of this container.
Description
Returns the parameter string representing the state of this container. This string is useful for debugging.

Overrides
paramString in class Component


 Container.preferredSize

Container.preferredSize

Class Overview | Class Members | This Package | All Packages

Syntax
public Dimension preferredSize()
Description
Note: preferredSize() is deprecated. As of JDK version 1.1, replaced by getPreferredSize().

Overrides
preferredSize in class Component


 Container.print

Container.print

Class Overview | Class Members | This Package | All Packages

Syntax
public void print( Graphics g )
Parameters
g
the specified Graphics window
Description
Prints the container. This forwards the print to any lightweight components that are children of this container. If this method is reimplemented, super.print(g) should be called so that lightweight components are properly rendered. If a child component is entirely clipped by the current clipping setting in g, print() will not be forwarded to that child.

Overrides
print in class Component
See Also
update


 Container.printComponents

Container.printComponents

Class Overview | Class Members | This Package | All Packages

Syntax
public void printComponents( Graphics g )
Parameters
g
the graphics context.
Description
Prints each of the components in this container.

See Also
print, printAll


 Container.processContainerEvent

Container.processContainerEvent

Class Overview | Class Members | This Package | All Packages

Syntax
protected void processContainerEvent( ContainerEvent e )
Parameters
e
the container event
Description
Processes container events occurring on this container by dispatching them to any registered ContainerListener objects. NOTE: This method will not be called unless container events are enabled for this component; this happens when one of the following occurs: a) A ContainerListener object is registered via addContainerListener() b) Container events are enabled via enableEvents()

See Also
enableEvents


 Container.processEvent

Container.processEvent

Class Overview | Class Members | This Package | All Packages

Syntax
protected void processEvent( AWTEvent e )
Parameters
e
the event
Description
Processes events on this container. If the event is a ContainerEvent, it invokes the processContainerEvent method, else it invokes its superclass's processEvent.

Overrides
processEvent in class Component


 Container.remove

Container.remove

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void remove( int index )
Parameters
index
the index of the component to be removed.
Description
Removes the component, specified by index, from this container.

See Also
add

Syntax 2
public void remove( Component comp )
Parameters
comp
the component to be removed
Description
Removes the specified component from this container.

See Also
add


 Container.removeAll

Container.removeAll

Class Overview | Class Members | This Package | All Packages

Syntax
public void removeAll()
Description
Removes all the components from this container.

See Also
add, remove


 Container.removeContainerListener

Container.removeContainerListener

Class Overview | Class Members | This Package | All Packages

Syntax
public void removeContainerListener( ContainerListener l )
Parameters
l
the container listener
Description
Removes the specified container listener so it no longer receives container events from this container.


 Container.removeNotify

Container.removeNotify

Class Overview | Class Members | This Package | All Packages

Syntax
public void removeNotify()
Description
Notifies this container and all of its subcomponents to remove their peers. This method should be invoked by the container's remove method, and not directly by user code.

Overrides
removeNotify in class Component
See Also
remove, remove


 Container.setLayout

Container.setLayout

Class Overview | Class Members | This Package | All Packages

Syntax
public void setLayout( LayoutManager mgr )
Parameters
mgr
the specified layout manager
Description
Sets the layout manager for this container.

See Also
doLayout, getLayout


 Container.validate

Container.validate

Class Overview | Class Members | This Package | All Packages

Syntax
public void validate()
Description
Validates this container and all of its subcomponents.

AWT uses validate to cause a container to lay out its subcomponents again after the components it contains have been added to or modified.

Overrides
validate in class Component
See Also
validate, invalidate


 Container.validateTree

Container.validateTree

Class Overview | Class Members | This Package | All Packages

Syntax
protected void validateTree()
Description
Recursively descends the container tree and recomputes the layout for any subtrees marked as needing it (those marked as invalid). Synchronization should be provided by the method that calls this one: validate.


 Class Cursor

Class java.awt.Cursor

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.Cursor

public class Cursor
extends Object
implements Serializable

A class to encapsulate the bitmap representation of the mouse cursor.

See Also:
setCursor


 Cursor Members

Cursor Members

Class Overview | This Package | All Packages

Fields
Name | Description
CROSSHAIR_CURSOR | The crosshair cursor type.
DEFAULT_CURSOR | The default cursor type (gets set if no cursor is defined).
E_RESIZE_CURSOR | The east-resize cursor type.
HAND_CURSOR | The hand cursor type.
MOVE_CURSOR | The move cursor type.
N_RESIZE_CURSOR | The north-resize cursor type.
NE_RESIZE_CURSOR | The north-east-resize cursor type.
NW_RESIZE_CURSOR | The north-west-resize cursor type.
predefined |
S_RESIZE_CURSOR | The south-resize cursor type.
SE_RESIZE_CURSOR | The south-east-resize cursor type.
SW_RESIZE_CURSOR | The south-west-resize cursor type.
TEXT_CURSOR | The text cursor type.
W_RESIZE_CURSOR | The west-resize cursor type.
WAIT_CURSOR | The wait cursor type.

Constructors
Name | Description
Cursor(int) | Creates a new cursor object with the specified type.

Methods
Name | Description
getDefaultCursor() | Return the system default cursor.
getPredefinedCursor(int) | Returns a cursor object with the specified predefined type.
getType() | Returns the type for this cursor.


 Cursor.CROSSHAIR_CURSOR

Cursor.CROSSHAIR_CURSOR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int CROSSHAIR_CURSOR
Description
The crosshair cursor type.


 Cursor.DEFAULT_CURSOR

Cursor.DEFAULT_CURSOR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int DEFAULT_CURSOR
Description
The default cursor type (gets set if no cursor is defined).


 Cursor.E_RESIZE_CURSOR

Cursor.E_RESIZE_CURSOR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int E_RESIZE_CURSOR
Description
The east-resize cursor type.


 Cursor.HAND_CURSOR

Cursor.HAND_CURSOR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HAND_CURSOR
Description
The hand cursor type.


 Cursor.MOVE_CURSOR

Cursor.MOVE_CURSOR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int MOVE_CURSOR
Description
The move cursor type.


 Cursor.N_RESIZE_CURSOR

Cursor.N_RESIZE_CURSOR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int N_RESIZE_CURSOR
Description
The north-resize cursor type.


 Cursor.NE_RESIZE_CURSOR

Cursor.NE_RESIZE_CURSOR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int NE_RESIZE_CURSOR
Description
The north-east-resize cursor type.


 Cursor.NW_RESIZE_CURSOR

Cursor.NW_RESIZE_CURSOR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int NW_RESIZE_CURSOR
Description
The north-west-resize cursor type.


 Cursor.predefined

Cursor.predefined

Class Overview | Class Members | This Package | All Packages

Syntax
protected static Cursor predefined[]


 Cursor.S_RESIZE_CURSOR

Cursor.S_RESIZE_CURSOR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int S_RESIZE_CURSOR
Description
The south-resize cursor type.


 Cursor.SE_RESIZE_CURSOR

Cursor.SE_RESIZE_CURSOR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SE_RESIZE_CURSOR
Description
The south-east-resize cursor type.


 Cursor.SW_RESIZE_CURSOR

Cursor.SW_RESIZE_CURSOR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SW_RESIZE_CURSOR
Description
The south-west-resize cursor type.


 Cursor.TEXT_CURSOR

Cursor.TEXT_CURSOR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int TEXT_CURSOR
Description
The text cursor type.


 Cursor.W_RESIZE_CURSOR

Cursor.W_RESIZE_CURSOR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int W_RESIZE_CURSOR
Description
The west-resize cursor type.


 Cursor.WAIT_CURSOR

Cursor.WAIT_CURSOR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int WAIT_CURSOR
Description
The wait cursor type.


 Cursor.Cursor

Cursor.Cursor

Class Overview | Class Members | This Package | All Packages

Syntax
public Cursor( int type )
Parameters
type
the type of cursor
Description
Creates a new cursor object with the specified type.


 Cursor.getDefaultCursor

Cursor.getDefaultCursor

Class Overview | Class Members | This Package | All Packages

Syntax
public static Cursor getDefaultCursor()
Description
Return the system default cursor.


 Cursor.getPredefinedCursor

Cursor.getPredefinedCursor

Class Overview | Class Members | This Package | All Packages

Syntax
public static Cursor getPredefinedCursor( int type )
Parameters
type
the type of predefined cursor
Description
Returns a cursor object with the specified predefined type.


 Cursor.getType

Cursor.getType

Class Overview | Class Members | This Package | All Packages

Syntax
public int getType()
Description
Returns the type for this cursor.


 Class Dialog

Class java.awt.Dialog

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.Component
           |
           +----java.awt.Container
                   |
                   +----java.awt.Window
                           |
                           +----java.awt.Dialog

public class Dialog
extends Window

A class that produces a dialog - a window that takes input from the user. The default layout for a dialog is BorderLayout.

Dialogs are capable of generating the following window events: WindowOpened, WindowClosing, WindowClosed, WindowActivated, WindowDeactivated.

See Also:
WindowEvent, addWindowListener


 Dialog Members

Dialog Members

Class Overview | This Package | All Packages

Constructors
Name | Description
Dialog(Frame) | Constructs an initially invisible Dialog with an empty title.
Dialog(Frame, boolean) | Constructs an initially invisible Dialog with an empty title.
Dialog(Frame, String) | Constructs an initially invisible Dialog with a title.
Dialog(Frame, String, boolean) | Constructs an initially invisible Dialog with a title.

Methods
Name | Description
addNotify() | Creates the dialog's peer.
getTitle() | Gets the title of the dialog.
isModal() | Indicates whether the dialog is modal.
isResizable() | Indicates whether this dialog window is resizable.
paramString() | Returns the parameter string representing the state of this dialog window.
setModal(boolean) | Specifies whether this dialog is modal.
setResizable(boolean) | Sets the resizable flag.
setTitle(String) | Sets the title of the Dialog.
show() | Shows the dialog.


 Dialog.Dialog

Dialog.Dialog

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Dialog( Frame parent )
Parameters
parent
the owner of the dialog
Description
Constructs an initially invisible Dialog with an empty title.

See Also
setSize, setVisible

Syntax 2
public Dialog( Frame parent, boolean modal )
Parameters
parent
the owner of the dialog
modal
if true, dialog blocks input to the parent window when shown
Description
Constructs an initially invisible Dialog with an empty title. A modal Dialog grabs all the input to the parent frame from the user.

Syntax 3
public Dialog( Frame parent, String title )
Parameters
parent
the owner of the dialog
title
the title of the dialog
Description
Constructs an initially invisible Dialog with a title.

See Also
setSize, setVisible

Syntax 4
public Dialog( Frame parent, String title, boolean modal )
Parameters
parent
the owner of the dialog
title
the title of the dialog
modal
if true, dialog blocks input to the parent window when shown
Description
Constructs an initially invisible Dialog with a title. A modal Dialog grabs all the input to the parent frame from the user.

See Also
setSize, setVisible


 Dialog.addNotify

Dialog.addNotify

Class Overview | Class Members | This Package | All Packages

Syntax
public void addNotify()
Description
Creates the dialog's peer. The peer allows us to change the appearance of the frame without changing its functionality.

Overrides
addNotify in class Window


 Dialog.getTitle

Dialog.getTitle

Class Overview | Class Members | This Package | All Packages

Syntax
public String getTitle()
Returns
the title of this dialog window.
Description
Gets the title of the dialog.

See Also
setTitle


 Dialog.isModal

Dialog.isModal

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isModal()
Returns
true if this dialog window is modal; false otherwise.
Description
Indicates whether the dialog is modal. A modal dialog grabs all input from the user.

See Also
setModal


 Dialog.isResizable

Dialog.isResizable

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isResizable()
Returns
true if the user can resize the dialog; false otherwise.
Description
Indicates whether this dialog window is resizable.

See Also
setResizable


 Dialog.paramString

Dialog.paramString

Class Overview | Class Members | This Package | All Packages

Syntax
protected String paramString()
Returns
the parameter string of this dialog window.
Description
Returns the parameter string representing the state of this dialog window. This string is useful for debugging.

Overrides
paramString in class Container


 Dialog.setModal

Dialog.setModal

Class Overview | Class Members | This Package | All Packages

Syntax
public void setModal( boolean b )
Description
Specifies whether this dialog is modal. A modal Dialog grabs all the input to the parent frame from the user.

See Also
isModal


 Dialog.setResizable

Dialog.setResizable

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setResizable( boolean resizable )
Parameters
resizable
true if the user can resize this dialog; false otherwise.
Description
Sets the resizable flag.

See Also
isResizable


 Dialog.setTitle

Dialog.setTitle

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setTitle( String title )
Parameters
title
the new title being given to the dialog
Description
Sets the title of the Dialog.

See Also
getTitle


 Dialog.show

Dialog.show

Class Overview | Class Members | This Package | All Packages

Syntax
public void show()
Description
Shows the dialog. This will bring the dialog to the front if the dialog is already visible. If the dialog is modal, this call will block input to the parent window until the dialog is taken down by calling hide or dispose. It is permissible to show modal dialogs from the event dispatching thread because the toolkit will ensure that another dispatching thread will run while the one which invoked show is blocked.

Overrides
show in class Window
See Also
hide


 Class Dimension

Class java.awt.Dimension

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.Dimension

public class Dimension
extends Object
implements Serializable

The Dimension class encapsulates the width and height of a component in a single object. The class is associated with certain properties of components. Several methods defined by the Component class and the LayoutManager interface return a Dimension object.

Normally the values of width and height are non-negative integers. The constructors that allow you to create a dimension do not prevent you from setting a negative value for these properties. If the value of width or height is negative, the behavior of some methods defined by other objects is undefined.

See Also:
Component, LayoutManager


 Dimension Members

Dimension Members

Class Overview | This Package | All Packages

Fields
Name | Description
height | The height dimension.
width | The width dimension.

Constructors
Name | Description
Dimension() | Creates an instance of Dimension with a width of zero and a height of zero.
Dimension(Dimension) | Creates an instance of Dimension whose width and height are the same as for the specified dimension.
Dimension(int, int) | Constructs a Dimension and initializes it to the specified width and specified height.

Methods
Name | Description
equals(Object) | Checks whether two dimension objects have equal values.
getSize() | Gets the size of this Dimension object.
setSize(Dimension) | Set the size of this Dimension object to the specified size.
setSize(int, int) | Set the size of this Dimension object to the specified width and height.
toString() | Returns a string that represents this Dimension object's values.


 Dimension.height

Dimension.height

Class Overview | Class Members | This Package | All Packages

Syntax
public int height
Description
The height dimension.


 Dimension.width

Dimension.width

Class Overview | Class Members | This Package | All Packages

Syntax
public int width
Description
The width dimension.


 Dimension.Dimension

Dimension.Dimension

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Dimension()
Description
Creates an instance of Dimension with a width of zero and a height of zero.

Syntax 2
public Dimension( Dimension d )
Parameters
d
the specified dimension for the width and height values.
Description
Creates an instance of Dimension whose width and height are the same as for the specified dimension.

Syntax 3
public Dimension( int width, int height )
Parameters
width
the specified width dimension
height
the specified height dimension
Description
Constructs a Dimension and initializes it to the specified width and specified height.


 Dimension.equals

Dimension.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Description
Checks whether two dimension objects have equal values.

Overrides
equals in class Object


 Dimension.getSize

Dimension.getSize

Class Overview | Class Members | This Package | All Packages

Syntax
public Dimension getSize()
Returns
the size of this dimension, a new instance of Dimension with the same width and height.
Description
Gets the size of this Dimension object. This method is included for completeness, to parallel the getSize method defined by Component.

See Also
setSize, getSize


 Dimension.setSize

Dimension.setSize

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void setSize( Dimension d )
Parameters
d
the new size for this Dimension object.
Description
Set the size of this Dimension object to the specified size. This method is included for completeness, to parallel the setSize method defined by Component.

See Also
getSize, setSize

Syntax 2
public void setSize( int width, int height )
Parameters
width
the new width for this Dimension object.
height
the new height for this Dimension object.
Description
Set the size of this Dimension object to the specified width and height. This method is included for completeness, to parallel the setSize method defined by Component.

See Also
getSize, setSize


 Dimension.toString

Dimension.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string representation of this dimension, including the values of width and height.
Description
Returns a string that represents this Dimension object's values.

Overrides
toString in class Object


 Class Event

Class java.awt.Event

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.Event

public class Event
extends Object
implements Serializable

Event is a platform-independent class that encapsulates events from the platform's Graphical User Interface in the Java 1.0 event model. In Java 1.1 and later versions, the Event class is maintained only for backwards compatibilty. The information in this class description is provided to assist programmers in converting Java 1.0 programs to the new event model.

In the Java 1.0 event model, an event contains an id field that indicates what type of event it is and which other Event variables are relevant for the event.

For keyboard events, key contains a value indicating which key was activated, and modifiers contains the modifiers for that event. For the KEY_PRESS and KEY_RELEASE event ids, the value of key is the unicode character code for the key. For KEY_ACTION and KEY_ACTION_RELEASE, the value of key is one of the defined action-key identifiers in the Event class (PGUP, PGDN, F1, F2, etc).


 Event Members

Event Members

Class Overview | This Package | All Packages

Fields
Name | Description
ACTION_EVENT | This event indicates that the user wants some action to occur.
ALT_MASK | This flag indicates that the Alt key was down when the event occurred.
arg | An arbitrary argument of the event.
BACK_SPACE | The BackSpace key.
CAPS_LOCK | The Caps Lock key, a non-ASCII action key.
clickCount | For MOUSE_DOWN events, this field indicates the number of consecutive clicks.
CTRL_MASK | This flag indicates that the Control key was down when the event occurred.
DELETE | The Delete key.
DOWN | The Down Arrow key, a non-ASCII action key.
END | The End key, a non-ASCII action key.
ENTER | The Enter key.
ESCAPE | The Escape key.
evt | The next event.
F1 | The F1 function key, a non-ASCII action key.
F10 | The F10 function key, a non-ASCII action key.
F11 | The F11 function key, a non-ASCII action key.
F12 | The F12 function key, a non-ASCII action key.
F2 | The F2 function key, a non-ASCII action key.
F3 | The F3 function key, a non-ASCII action key.
F4 | The F4 function key, a non-ASCII action key.
F5 | The F5 function key, a non-ASCII action key.
F6 | The F6 function key, a non-ASCII action key.
F7 | The F7 function key, a non-ASCII action key.
F8 | The F8 function key, a non-ASCII action key.
F9 | The F9 function key, a non-ASCII action key.
GOT_FOCUS | A component gained the focus.
HOME | The Home key, a non-ASCII action key.
id | Indicates which type of event the event is, and which other Event variables are relevant for the event.
INSERT | The Insert key, a non-ASCII action key.
key | The key code of the key that was pressed in a keyboard event.
KEY_ACTION | The user has pressed a non-ASCII action key.
KEY_ACTION_RELEASE | The user has released a non-ASCII action key.
KEY_PRESS | The user has pressed a normal key.
KEY_RELEASE | The user has released a normal key.
LEFT | The Left Arrow key, a non-ASCII action key.
LIST_DESELECT | An item in a list has been deselected.
LIST_SELECT | An item in a list has been selected.
LOAD_FILE | A file loading event.
LOST_FOCUS | A component lost the focus.
META_MASK | This flag indicates that the Meta key was down when the event occurred.
modifiers | The state of the modifier keys.
MOUSE_DOWN | The user has pressed the mouse button.
MOUSE_DRAG | The user has moved the mouse with a button pressed.
MOUSE_ENTER | The mouse has entered a component.
MOUSE_EXIT | The mouse has exited a component.
MOUSE_MOVE | The mouse has moved with no button pressed.
MOUSE_UP | The user has released the mouse button.
NUM_LOCK | The Num Lock key, a non-ASCII action key.
PAUSE | The Pause key, a non-ASCII action key.
PGDN | The Page Down key, a non-ASCII action key.
PGUP | The Page Up key, a non-ASCII action key.
PRINT_SCREEN | The Print Screen key, a non-ASCII action key.
RIGHT | The Right Arrow key, a non-ASCII action key.
SAVE_FILE | A file saving event.
SCROLL_ABSOLUTE | The user has moved the bubble (thumb) in a scroll bar, moving to an "absolute" position, rather than to an offset from the last postion.
SCROLL_BEGIN | The scroll begin event.
SCROLL_END | The scroll end event.
SCROLL_LINE_DOWN | The user has activated the line down area of a scroll bar.
SCROLL_LINE_UP | The user has activated the line up area of a scroll bar.
SCROLL_LOCK | The Scroll Lock key, a non-ASCII action key.
SCROLL_PAGE_DOWN | The user has activated the page down area of a scroll bar.
SCROLL_PAGE_UP | The user has activated the page up area of a scroll bar.
SHIFT_MASK | This flag indicates that the Shift key was down when the event occurred.
TAB | The Tab key.
target | The target component.
UP | The Up Arrow key, a non-ASCII action key.
when | The time stamp.
WINDOW_DEICONIFY | The user has asked the window manager to de-iconify the window.
WINDOW_DESTROY | The user has asked the window manager to kill the window.
WINDOW_EXPOSE | The user has asked the window manager to expose the window.
WINDOW_ICONIFY | The user has asked the window manager to iconify the window.
WINDOW_MOVED | The user has asked the window manager to move the window.
x | The x coordinate of the event.
y | The y coordinate of the event.

Constructors
Name | Description
Event(Object, int, Object) | Creates an instance of Event with the specified target component, event type, and argument.
Event(Object, long, int, int, int, int, int) | Creates an instance of Event, with the specified target component, time stamp, event type, x and y coordinates, keyboard key, state of the modifier keys, and an argument set to null.
Event(Object, long, int, int, int, int, int, Object) | Creates an instance of Event with the specified target component, time stamp, event type, x and y coordinates, keyboard key, state of the modifier keys, and argument.

Methods
Name | Description
controlDown() | Checks if the Control key is down.
metaDown() | Checks if the Meta key is down.
paramString() | Returns the parameter string representing this event.
shiftDown() | Checks if the Shift key is down.
toString() | Returns a representation of this event's values as a string.
translate(int, int) | Translates this event so that its x and y coordinates are increased by dx and dy, respectively.


 Event.ACTION_EVENT

Event.ACTION_EVENT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int ACTION_EVENT
Description
This event indicates that the user wants some action to occur.


 Event.ALT_MASK

Event.ALT_MASK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int ALT_MASK
Description
This flag indicates that the Alt key was down when the event occurred. For mouse events, this flag indicates that the middle mouse button was pressed or released.


 Event.arg

Event.arg

Class Overview | Class Members | This Package | All Packages

Syntax
public Object arg
Description
An arbitrary argument of the event. The value of this field depends on the type of event.


 Event.BACK_SPACE

Event.BACK_SPACE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int BACK_SPACE
Description
The BackSpace key.


 Event.CAPS_LOCK

Event.CAPS_LOCK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int CAPS_LOCK
Description
The Caps Lock key, a non-ASCII action key.


 Event.clickCount

Event.clickCount

Class Overview | Class Members | This Package | All Packages

Syntax
public int clickCount
Description
For MOUSE_DOWN events, this field indicates the number of consecutive clicks. For other events, its value is 0.


 Event.CTRL_MASK

Event.CTRL_MASK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int CTRL_MASK
Description
This flag indicates that the Control key was down when the event occurred.


 Event.DELETE

Event.DELETE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int DELETE
Description
The Delete key.


 Event.DOWN

Event.DOWN

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int DOWN
Description
The Down Arrow key, a non-ASCII action key.


 Event.END

Event.END

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int END
Description
The End key, a non-ASCII action key.


 Event.ENTER

Event.ENTER

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int ENTER
Description
The Enter key.


 Event.ESCAPE

Event.ESCAPE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int ESCAPE
Description
The Escape key.


 Event.evt

Event.evt

Class Overview | Class Members | This Package | All Packages

Syntax
public Event evt
Description
The next event. This field is set when putting events into a linked list.


 Event.F1

Event.F1

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int F1
Description
The F1 function key, a non-ASCII action key.


 Event.F10

Event.F10

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int F10
Description
The F10 function key, a non-ASCII action key.


 Event.F11

Event.F11

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int F11
Description
The F11 function key, a non-ASCII action key.


 Event.F12

Event.F12

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int F12
Description
The F12 function key, a non-ASCII action key.


 Event.F2

Event.F2

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int F2
Description
The F2 function key, a non-ASCII action key.


 Event.F3

Event.F3

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int F3
Description
The F3 function key, a non-ASCII action key.


 Event.F4

Event.F4

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int F4
Description
The F4 function key, a non-ASCII action key.


 Event.F5

Event.F5

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int F5
Description
The F5 function key, a non-ASCII action key.


 Event.F6

Event.F6

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int F6
Description
The F6 function key, a non-ASCII action key.


 Event.F7

Event.F7

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int F7
Description
The F7 function key, a non-ASCII action key.


 Event.F8

Event.F8

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int F8
Description
The F8 function key, a non-ASCII action key.


 Event.F9

Event.F9

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int F9
Description
The F9 function key, a non-ASCII action key.


 Event.GOT_FOCUS

Event.GOT_FOCUS

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int GOT_FOCUS
Description
A component gained the focus.


 Event.HOME

Event.HOME

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HOME
Description
The Home key, a non-ASCII action key.


 Event.id

Event.id

Class Overview | Class Members | This Package | All Packages

Syntax
public int id
Description
Indicates which type of event the event is, and which other Event variables are relevant for the event.


 Event.INSERT

Event.INSERT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int INSERT
Description
The Insert key, a non-ASCII action key.


 Event.key

Event.key

Class Overview | Class Members | This Package | All Packages

Syntax
public int key
Description
The key code of the key that was pressed in a keyboard event.


 Event.KEY_ACTION

Event.KEY_ACTION

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int KEY_ACTION
Description
The user has pressed a non-ASCII action key. The key field contains a value that indicates that the event occurred on one of the action keys, which comprise the 12 function keys, the arrow (cursor) keys, Page Up, Page Down, Home, End, Print Screen, Scroll Lock, Caps Lock, Num Lock, Pause, and Insert.


 Event.KEY_ACTION_RELEASE

Event.KEY_ACTION_RELEASE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int KEY_ACTION_RELEASE
Description
The user has released a non-ASCII action key. The key field contains a value that indicates that the event occurred on one of the action keys, which comprise the 12 function keys, the arrow (cursor) keys, Page Up, Page Down, Home, End, Print Screen, Scroll Lock, Caps Lock, Num Lock, Pause, and Insert.


 Event.KEY_PRESS

Event.KEY_PRESS

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int KEY_PRESS
Description
The user has pressed a normal key.


 Event.KEY_RELEASE

Event.KEY_RELEASE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int KEY_RELEASE
Description
The user has released a normal key.


 Event.LEFT

Event.LEFT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int LEFT
Description
The Left Arrow key, a non-ASCII action key.


 Event.LIST_DESELECT

Event.LIST_DESELECT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int LIST_DESELECT
Description
An item in a list has been deselected.


 Event.LIST_SELECT

Event.LIST_SELECT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int LIST_SELECT
Description
An item in a list has been selected.


 Event.LOAD_FILE

Event.LOAD_FILE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int LOAD_FILE
Description
A file loading event.


 Event.LOST_FOCUS

Event.LOST_FOCUS

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int LOST_FOCUS
Description
A component lost the focus.


 Event.META_MASK

Event.META_MASK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int META_MASK
Description
This flag indicates that the Meta key was down when the event occurred. For mouse events, this flag indicates that the right button was pressed or released.


 Event.modifiers

Event.modifiers

Class Overview | Class Members | This Package | All Packages

Syntax
public int modifiers
Description
The state of the modifier keys.


 Event.MOUSE_DOWN

Event.MOUSE_DOWN

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int MOUSE_DOWN
Description
The user has pressed the mouse button. The ALT_MASK flag indicates that the middle button has been pressed. The META_MASKflag indicates that the right button has been pressed.

See Also
ALT_MASK, META_MASK


 Event.MOUSE_DRAG

Event.MOUSE_DRAG

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int MOUSE_DRAG
Description
The user has moved the mouse with a button pressed. The ALT_MASK flag indicates that the middle button is being pressed. The META_MASK flag indicates that the right button is being pressed.

See Also
ALT_MASK, META_MASK


 Event.MOUSE_ENTER

Event.MOUSE_ENTER

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int MOUSE_ENTER
Description
The mouse has entered a component.


 Event.MOUSE_EXIT

Event.MOUSE_EXIT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int MOUSE_EXIT
Description
The mouse has exited a component.


 Event.MOUSE_MOVE

Event.MOUSE_MOVE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int MOUSE_MOVE
Description
The mouse has moved with no button pressed.


 Event.MOUSE_UP

Event.MOUSE_UP

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int MOUSE_UP
Description
The user has released the mouse button. The ALT_MASK flag indicates that the middle button has been released. The META_MASKflag indicates that the right button has been released.

See Also
ALT_MASK, META_MASK


 Event.NUM_LOCK

Event.NUM_LOCK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int NUM_LOCK
Description
The Num Lock key, a non-ASCII action key.


 Event.PAUSE

Event.PAUSE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int PAUSE
Description
The Pause key, a non-ASCII action key.


 Event.PGDN

Event.PGDN

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int PGDN
Description
The Page Down key, a non-ASCII action key.


 Event.PGUP

Event.PGUP

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int PGUP
Description
The Page Up key, a non-ASCII action key.


 Event.PRINT_SCREEN

Event.PRINT_SCREEN

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int PRINT_SCREEN
Description
The Print Screen key, a non-ASCII action key.


 Event.RIGHT

Event.RIGHT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int RIGHT
Description
The Right Arrow key, a non-ASCII action key.


 Event.SAVE_FILE

Event.SAVE_FILE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SAVE_FILE
Description
A file saving event.


 Event.SCROLL_ABSOLUTE

Event.SCROLL_ABSOLUTE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SCROLL_ABSOLUTE
Description
The user has moved the bubble (thumb) in a scroll bar, moving to an "absolute" position, rather than to an offset from the last postion.


 Event.SCROLL_BEGIN

Event.SCROLL_BEGIN

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SCROLL_BEGIN
Description
The scroll begin event.


 Event.SCROLL_END

Event.SCROLL_END

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SCROLL_END
Description
The scroll end event.


 Event.SCROLL_LINE_DOWN

Event.SCROLL_LINE_DOWN

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SCROLL_LINE_DOWN
Description
The user has activated the line down area of a scroll bar.


 Event.SCROLL_LINE_UP

Event.SCROLL_LINE_UP

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SCROLL_LINE_UP
Description
The user has activated the line up area of a scroll bar.


 Event.SCROLL_LOCK

Event.SCROLL_LOCK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SCROLL_LOCK
Description
The Scroll Lock key, a non-ASCII action key.


 Event.SCROLL_PAGE_DOWN

Event.SCROLL_PAGE_DOWN

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SCROLL_PAGE_DOWN
Description
The user has activated the page down area of a scroll bar.


 Event.SCROLL_PAGE_UP

Event.SCROLL_PAGE_UP

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SCROLL_PAGE_UP
Description
The user has activated the page up area of a scroll bar.


 Event.SHIFT_MASK

Event.SHIFT_MASK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SHIFT_MASK
Description
This flag indicates that the Shift key was down when the event occurred.


 Event.TAB

Event.TAB

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int TAB
Description
The Tab key.


 Event.target

Event.target

Class Overview | Class Members | This Package | All Packages

Syntax
public Object target
Description
The target component. This indicates the component over which the event occurred or with which the event is associated.


 Event.UP

Event.UP

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int UP
Description
The Up Arrow key, a non-ASCII action key.


 Event.when

Event.when

Class Overview | Class Members | This Package | All Packages

Syntax
public long when
Description
The time stamp.


 Event.WINDOW_DEICONIFY

Event.WINDOW_DEICONIFY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int WINDOW_DEICONIFY
Description
The user has asked the window manager to de-iconify the window.


 Event.WINDOW_DESTROY

Event.WINDOW_DESTROY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int WINDOW_DESTROY
Description
The user has asked the window manager to kill the window.


 Event.WINDOW_EXPOSE

Event.WINDOW_EXPOSE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int WINDOW_EXPOSE
Description
The user has asked the window manager to expose the window.


 Event.WINDOW_ICONIFY

Event.WINDOW_ICONIFY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int WINDOW_ICONIFY
Description
The user has asked the window manager to iconify the window.


 Event.WINDOW_MOVED

Event.WINDOW_MOVED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int WINDOW_MOVED
Description
The user has asked the window manager to move the window.


 Event.x

Event.x

Class Overview | Class Members | This Package | All Packages

Syntax
public int x
Description
The x coordinate of the event.


 Event.y

Event.y

Class Overview | Class Members | This Package | All Packages

Syntax
public int y
Description
The y coordinate of the event.


 Event.Event

Event.Event

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Event( Object target, long when, int id, int x, int y, int key, int modifiers, Object arg )
Parameters
target
the target component.
when
the time stamp.
id
the event type.
x
the x coordinate.
y
the y coordinate.
key
the key pressed in a keyboard event.
modifiers
the state of the modifier keys.
arg
the specified argument.
Description
Creates an instance of Event with the specified target component, time stamp, event type, x and y coordinates, keyboard key, state of the modifier keys, and argument.

Syntax 2
public Event( Object target, long when, int id, int x, int y, int key, int modifiers )
Parameters
target
the target component.
when
the time stamp.
id
the event type.
x
the x coordinate.
y
the y coordinate.
key
the key pressed in a keyboard event.
modifiers
the state of the modifier keys.
Description
Creates an instance of Event, with the specified target component, time stamp, event type, x and y coordinates, keyboard key, state of the modifier keys, and an argument set to null.

Syntax 3
public Event( Object target, int id, Object arg )
Parameters
target
the target component.
id
the event type.
arg
the specified argument.
Description
Creates an instance of Event with the specified target component, event type, and argument.


 Event.controlDown

Event.controlDown

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean controlDown()
Returns
true if the key is down; false otherwise.
Description
Checks if the Control key is down.

See Also
modifiers, shiftDown, metaDown


 Event.metaDown

Event.metaDown

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean metaDown()
Returns
true if the key is down; false otherwise.
Description
Checks if the Meta key is down.

See Also
modifiers, shiftDown, controlDown


 Event.paramString

Event.paramString

Class Overview | Class Members | This Package | All Packages

Syntax
protected String paramString()
Returns
the parameter string of this event.
Description
Returns the parameter string representing this event. This string is useful for debugging.


 Event.shiftDown

Event.shiftDown

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean shiftDown()
Returns
true if the key is down; false otherwise.
Description
Checks if the Shift key is down.

See Also
modifiers, controlDown, metaDown


 Event.toString

Event.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string that represents the event and the values of its member fields.
Description
Returns a representation of this event's values as a string.

Overrides
toString in class Object
See Also
paramString


 Event.translate

Event.translate

Class Overview | Class Members | This Package | All Packages

Syntax
public void translate( int x, int y )
Parameters
dx
the distance to translate the x coordinate.
dy
the distance to translate the y coordinate.
Description
Translates this event so that its x and y coordinates are increased by dx and dy, respectively.

This method translates an event relative to the given component. This involves, at a minimum, translating the coordinates into the local coordinate system of the given component. It may also involve translating a region in the case of an expose event.


 Class EventQueue

Class java.awt.EventQueue

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.EventQueue

public class EventQueue
extends Object

EventQueue is a platform-independent class that queues events, both from the underlying peer classes and from trusted application classes. There is only one EventQueue for the system.


 EventQueue Members

EventQueue Members

Class Overview | This Package | All Packages

Constructors
Name | Description
EventQueue() |

Methods
Name | Description
getNextEvent() | Remove an event from the queue and return it.
peekEvent() | Return the first event without removing it.
peekEvent(int) |
postEvent(AWTEvent) | Post a 1.1-style event to the EventQueue.


 EventQueue.EventQueue

EventQueue.EventQueue

Class Overview | Class Members | This Package | All Packages

Syntax
public EventQueue()


 EventQueue.getNextEvent

EventQueue.getNextEvent

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized AWTEvent getNextEvent() throws InterruptedException
Returns
the next AWTEvent
Description
Remove an event from the queue and return it. This method will block until an event has been posted by another thread.

Exceptions
InterruptedException if another thread has interrupted this thread.


 EventQueue.peekEvent

EventQueue.peekEvent

Class Overview | Class Members | This Package | All Packages

Syntax 1
public synchronized AWTEvent peekEvent()
Returns
the first event, which is either an instance of java.awt.Event or java.awt.AWTEvent.
Description
Return the first event without removing it.

Syntax 2
public synchronized AWTEvent peekEvent( int id )


 EventQueue.postEvent

EventQueue.postEvent

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void postEvent( AWTEvent theEvent )
Parameters
theEvent
an instance of java.awt.AWTEvent, or a subclass of it.
Description
Post a 1.1-style event to the EventQueue.


 Class FileDialog

Class java.awt.FileDialog

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.Component
           |
           +----java.awt.Container
                   |
                   +----java.awt.Window
                           |
                           +----java.awt.Dialog
                                   |
                                   +----java.awt.FileDialog

public class FileDialog
extends Dialog

The FileDialog class displays a dialog window from which the user can select a file.

Since it is a modal dialog, when the application calls its show method to display the dialog, it blocks the rest of the application until the user has chosen a file.

See Also:
show


 FileDialog Members

FileDialog Members

Class Overview | This Package | All Packages

Fields
Name | Description
LOAD | This constant value indicates that the purpose of the file dialog window is to locate a file from which to read.
SAVE | This constant value indicates that the purpose of the file dialog window is to locate a file to which to write.

Constructors
Name | Description
FileDialog(Frame) | Creates a file dialog for loading a file.
FileDialog(Frame, String) | Creates a file dialog window with the specified title for loading a file.
FileDialog(Frame, String, int) | Creates a file dialog window with the specified title for loading or saving a file.

Methods
Name | Description
addNotify() | Creates the file dialog's peer.
getDirectory() | Gets the directory of this file dialog.
getFile() | Gets the selected file of this file dialog.
getFilenameFilter() | Determines this file dialog's filename filter.
getMode() | Indicates whether this file dialog box is for loading from a file or for saving to a file.
paramString() | Returns the parameter string representing the state of this file dialog window.
setDirectory(String) | Sets the directory of this file dialog window to be the specified directory.
setFile(String) | Sets the selected file for this file dialog window to be the specified file.
setFilenameFilter(FilenameFilter) | Sets the filename filter for this file dialog window to the specified filter.
setMode(int) | Sets the mode of the file dialog.


 FileDialog.LOAD

FileDialog.LOAD

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int LOAD
Description
This constant value indicates that the purpose of the file dialog window is to locate a file from which to read.


 FileDialog.SAVE

FileDialog.SAVE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SAVE
Description
This constant value indicates that the purpose of the file dialog window is to locate a file to which to write.


 FileDialog.FileDialog

FileDialog.FileDialog

Class Overview | Class Members | This Package | All Packages

Syntax 1
public FileDialog( Frame parent )
Parameters
parent
the owner of the dialog
Description
Creates a file dialog for loading a file. The title of the file dialog is initially empty.

Syntax 2
public FileDialog( Frame parent, String title )
Parameters
parent
the owner of the dialog.
title
the title of the dialog.
Description
Creates a file dialog window with the specified title for loading a file. The files shown are those in the current directory.

Syntax 3
public FileDialog( Frame parent, String title, int mode )
Parameters
parent
the owner of the dialog.
title
the title of the dialog.
mode
the mode of the dialog.
Description
Creates a file dialog window with the specified title for loading or saving a file.

If the value of mode is LOAD, then the file dialog is finding a file to read. If the value of mode is SAVE, the file dialog is finding a place to write a file.

See Also
LOAD, SAVE


 FileDialog.addNotify

FileDialog.addNotify

Class Overview | Class Members | This Package | All Packages

Syntax
public void addNotify()
Description
Creates the file dialog's peer. The peer allows us to change the look of the file dialog without changing its functionality.

Overrides
addNotify in class Dialog


 FileDialog.getDirectory

FileDialog.getDirectory

Class Overview | Class Members | This Package | All Packages

Syntax
public String getDirectory()
Returns
the directory of this file dialog.
Description
Gets the directory of this file dialog.

See Also
setDirectory


 FileDialog.getFile

FileDialog.getFile

Class Overview | Class Members | This Package | All Packages

Syntax
public String getFile()
Returns
the currently selected file of this file dialog window, or null if none is selected.
Description
Gets the selected file of this file dialog.

See Also
setFile


 FileDialog.getFilenameFilter

FileDialog.getFilenameFilter

Class Overview | Class Members | This Package | All Packages

Syntax
public FilenameFilter getFilenameFilter()
Returns
this file dialog's filename filter.
Description
Determines this file dialog's filename filter. A filename filter allows the user to specify which files appear in the file dialog window.

See Also
FilenameFilter, setFilenameFilter


 FileDialog.getMode

FileDialog.getMode

Class Overview | Class Members | This Package | All Packages

Syntax
public int getMode()
Returns
the mode of this file dialog window, either FileDialog.LOAD or FileDialog.SAVE.
Description
Indicates whether this file dialog box is for loading from a file or for saving to a file.

See Also
LOAD, SAVE, setMode


 FileDialog.paramString

FileDialog.paramString

Class Overview | Class Members | This Package | All Packages

Syntax
protected String paramString()
Returns
the parameter string of this file dialog window.
Description
Returns the parameter string representing the state of this file dialog window. This string is useful for debugging.

Overrides
paramString in class Dialog


 FileDialog.setDirectory

FileDialog.setDirectory

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setDirectory( String dir )
Parameters
dir
the specific directory.
Description
Sets the directory of this file dialog window to be the specified directory.

See Also
getDirectory


 FileDialog.setFile

FileDialog.setFile

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setFile( String file )
Parameters
file
the file being set.
Description
Sets the selected file for this file dialog window to be the specified file. This file becomes the default file if it is set before the file dialog window is first shown.

See Also
getFile


 FileDialog.setFilenameFilter

FileDialog.setFilenameFilter

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setFilenameFilter( FilenameFilter filter )
Parameters
filter
the specified filter.
Description
Sets the filename filter for this file dialog window to the specified filter.

See Also
FilenameFilter, getFilenameFilter


 FileDialog.setMode

FileDialog.setMode

Class Overview | Class Members | This Package | All Packages

Syntax
public void setMode( int mode )
Parameters
mode
the mode for this file dialog, either FileDialog.LOAD or FileDialog.SAVE.
Description
Sets the mode of the file dialog.

Exceptions
IllegalArgumentException if an illegal file dialog mode is used.
See Also
LOAD, SAVE, getMode


 Class FlowLayout

Class java.awt.FlowLayout

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.FlowLayout

public class FlowLayout
extends Object
implements LayoutManager, Serializable

A flow layout arranges components in a left-to-right flow, much like lines of text in a paragraph. Flow layouts are typically used to arrange buttons in a panel. It will arrange buttons left to right until no more buttons fit on the same line. Each line is centered.

For example, the following picture shows an applet using the flow layout manager (its default layout manager) to position three buttons:

Graphic of Layout for Three Buttons

Here is the code for this applet:

 import java.awt.*;
 import java.applet.Applet;
 public class myButtons extends Applet {
     Button button1, button2, button3;
     public void init() {
         button1 = new Button("Ok");
         button2 = new Button("Open");
         button3 = new Button("Close");
         add(button1);
         add(button2);
         add(button3);
     }
 }

A flow layout lets each component assume its natural (preferred) size.


 FlowLayout Members

FlowLayout Members

Class Overview | This Package | All Packages

Fields
Name | Description
CENTER | This value indicates that each row of components should be centered.
LEFT | This value indicates that each row of components should be left-justified.
RIGHT | This value indicates that each row of components should be right-justified.

Constructors
Name | Description
FlowLayout() | Constructs a new Flow Layout with a centered alignment and a default 5-unit horizontal and vertical gap.
FlowLayout(int) | Constructs a new Flow Layout with the specified alignment and a default 5-unit horizontal and vertical gap.
FlowLayout(int, int, int) | Creates a new flow layout manager with the indicated alignment and the indicated horizontal and vertical gaps.

Methods
Name | Description
addLayoutComponent(String, Component) | Adds the specified component to the layout.
getAlignment() | Gets the alignment for this layout.
getHgap() | Gets the horizontal gap between components.
getVgap() | Gets the vertical gap between components.
layoutContainer(Container) | Lays out the container.
minimumLayoutSize(Container) | Returns the minimum dimensions needed to layout the components contained in the specified target container.
preferredLayoutSize(Container) | Returns the preferred dimensions for this layout given the components in the specified target container.
removeLayoutComponent(Component) | Removes the specified component from the layout.
setAlignment(int) | Sets the alignment for this layout.
setHgap(int) | Sets the horizontal gap between components.
setVgap(int) | Sets the vertical gap between components.
toString() | Returns a string representation of this FlowLayout object and its values.


 FlowLayout.CENTER

FlowLayout.CENTER

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int CENTER
Description
This value indicates that each row of components should be centered.


 FlowLayout.LEFT

FlowLayout.LEFT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int LEFT
Description
This value indicates that each row of components should be left-justified.


 FlowLayout.RIGHT

FlowLayout.RIGHT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int RIGHT
Description
This value indicates that each row of components should be right-justified.


 FlowLayout.FlowLayout

FlowLayout.FlowLayout

Class Overview | Class Members | This Package | All Packages

Syntax 1
public FlowLayout()
Description
Constructs a new Flow Layout with a centered alignment and a default 5-unit horizontal and vertical gap.

Syntax 2
public FlowLayout( int align )
Parameters
align
the alignment value
Description
Constructs a new Flow Layout with the specified alignment and a default 5-unit horizontal and vertical gap. The value of the alignment argument must be one of FlowLayout.LEFT, FlowLayout.RIGHT, or FlowLayout.CENTER.

Syntax 3
public FlowLayout( int align, int hgap, int vgap )
Parameters
align
the alignment value.
hgap
the horizontal gap between components.
vgap
the vertical gap between components.
Description
Creates a new flow layout manager with the indicated alignment and the indicated horizontal and vertical gaps.

The value of the alignment argument must be one of FlowLayout.LEFT, FlowLayout.RIGHT, or FlowLayout.CENTER.


 FlowLayout.addLayoutComponent

FlowLayout.addLayoutComponent

Class Overview | Class Members | This Package | All Packages

Syntax
public void addLayoutComponent( String name, Component comp )
Parameters
name
the name of the component
comp
the component to be added
Description
Adds the specified component to the layout. Not used by this class.


 FlowLayout.getAlignment

FlowLayout.getAlignment

Class Overview | Class Members | This Package | All Packages

Syntax
public int getAlignment()
Returns
the alignment value for this layout.
Description
Gets the alignment for this layout. Possible values are FlowLayout.LEFT, FlowLayout.RIGHT, or FlowLayout.CENTER.

See Also
setAlignment


 FlowLayout.getHgap

FlowLayout.getHgap

Class Overview | Class Members | This Package | All Packages

Syntax
public int getHgap()
Returns
the horizontal gap between components.
Description
Gets the horizontal gap between components.

See Also
setHgap


 FlowLayout.getVgap

FlowLayout.getVgap

Class Overview | Class Members | This Package | All Packages

Syntax
public int getVgap()
Returns
the vertical gap between components.
Description
Gets the vertical gap between components.

See Also
setVgap


 FlowLayout.layoutContainer

FlowLayout.layoutContainer

Class Overview | Class Members | This Package | All Packages

Syntax
public void layoutContainer( Container target )
Parameters
target
the specified component being laid out.
Description
Lays out the container. This method lets each component take its preferred size by reshaping the components in the target container in order to satisfy the constraints of this FlowLayout object.

See Also
Container, doLayout


 FlowLayout.minimumLayoutSize

FlowLayout.minimumLayoutSize

Class Overview | Class Members | This Package | All Packages

Syntax
public Dimension minimumLayoutSize( Container target )
Parameters
target
the component which needs to be laid out
Returns
the minimum dimensions to lay out the subcomponents of the specified container.
Description
Returns the minimum dimensions needed to layout the components contained in the specified target container.

See Also
preferredLayoutSize, Container, doLayout


 FlowLayout.preferredLayoutSize

FlowLayout.preferredLayoutSize

Class Overview | Class Members | This Package | All Packages

Syntax
public Dimension preferredLayoutSize( Container target )
Parameters
target
the component which needs to be laid out
Returns
the preferred dimensions to lay out the subcomponents of the specified container.
Description
Returns the preferred dimensions for this layout given the components in the specified target container.

See Also
Container, minimumLayoutSize, getPreferredSize


 FlowLayout.removeLayoutComponent

FlowLayout.removeLayoutComponent

Class Overview | Class Members | This Package | All Packages

Syntax
public void removeLayoutComponent( Component comp )
Parameters
comp
the component to remove
Description
Removes the specified component from the layout. Not used by this class.

See Also
removeAll


 FlowLayout.setAlignment

FlowLayout.setAlignment

Class Overview | Class Members | This Package | All Packages

Syntax
public void setAlignment( int align )
Parameters
align
the alignment value.
Description
Sets the alignment for this layout. Possible values are FlowLayout.LEFT, FlowLayout.RIGHT, and FlowLayout.CENTER.

See Also
getAlignment


 FlowLayout.setHgap

FlowLayout.setHgap

Class Overview | Class Members | This Package | All Packages

Syntax
public void setHgap( int hgap )
Parameters
hgap
the horizontal gap between components
Description
Sets the horizontal gap between components.

See Also
getHgap


 FlowLayout.setVgap

FlowLayout.setVgap

Class Overview | Class Members | This Package | All Packages

Syntax
public void setVgap( int vgap )
Parameters
vgap
the vertical gap between components
Description
Sets the vertical gap between components.

See Also
getVgap


 FlowLayout.toString

FlowLayout.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string representation of this layout.
Description
Returns a string representation of this FlowLayout object and its values.

Overrides
toString in class Object


 Class Font

Class java.awt.Font

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.Font

public class Font
extends Object
implements Serializable

A class that produces font objects.


 Font Members

Font Members

Class Overview | This Package | All Packages

Fields
Name | Description
BOLD | The bold style constant.
ITALIC | The italicized style constant.
name | The logical name of this font.
PLAIN | The plain style constant.
size | The point size of this font.
style | The style of the font.

Constructors
Name | Description
Font(String, int, int) | Creates a new font with the specified name, style and point size.

Methods
Name | Description
decode(String) | Gets the specified font using the name passed in.
equals(Object) | Compares this object to the specifed object.
getFamily() | Gets the platform specific family name of the font.
getFont(String) | Gets a font from the system properties list.
getFont(String, Font) | Gets the specified font from the system properties list.
getName() | Gets the logical name of the font.
getPeer() | Gets the peer of the font.
getSize() | Gets the point size of the font.
getStyle() | Gets the style of the font.
hashCode() | Returns a hashcode for this font.
isBold() | Indicates whether the font's style is bold.
isItalic() | Indicates whether the font's style is italic.
isPlain() | Indicates whether the font's style is plain.
toString() | Converts this object to a String representation.


 Font.BOLD

Font.BOLD

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int BOLD
Description
The bold style constant. This style can be combined with the other style constants for mixed styles.


 Font.ITALIC

Font.ITALIC

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int ITALIC
Description
The italicized style constant. This style can be combined with the other style constants for mixed styles.


 Font.name

Font.name

Class Overview | Class Members | This Package | All Packages

Syntax
protected String name
Description
The logical name of this font.


 Font.PLAIN

Font.PLAIN

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int PLAIN
Description
The plain style constant. This style can be combined with the other style constants for mixed styles.


 Font.size

Font.size

Class Overview | Class Members | This Package | All Packages

Syntax
protected int size
Description
The point size of this font.


 Font.style

Font.style

Class Overview | Class Members | This Package | All Packages

Syntax
protected int style
Description
The style of the font. This is the sum of the constants PLAIN, BOLD, or ITALIC.


 Font.Font

Font.Font

Class Overview | Class Members | This Package | All Packages

Syntax
public Font( String name, int style, int size )
Parameters
name
the font name
style
the constant style used
size
the point size of the font
Description
Creates a new font with the specified name, style and point size.

See Also
getFontList


 Font.decode

Font.decode

Class Overview | Class Members | This Package | All Packages

Syntax
public static Font decode( String str )
Parameters
str
the name
Description
Gets the specified font using the name passed in.


 Font.equals

Font.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Parameters
obj
the object to compare this font with.
Returns
true if the objects are equal; false otherwise.
Description
Compares this object to the specifed object. The result is true if and only if the argument is not null and is a Font object with the same name, style, and point size as this font.

Overrides
equals in class Object


 Font.getFamily

Font.getFamily

Class Overview | Class Members | This Package | All Packages

Syntax
public String getFamily()
Returns
a string, the platform specific family name.
Description
Gets the platform specific family name of the font. Use the getName method to get the logical name of the font.

See Also
getName


 Font.getFont

Font.getFont

Class Overview | Class Members | This Package | All Packages

Syntax
public static Font getFont( String nm )
Parameters
nm
the property name
Description
Gets a font from the system properties list.

See Also
getFont


 Font.getFont

Font.getFont

Class Overview | Class Members | This Package | All Packages

Syntax
public static Font getFont( String nm, Font font )
Parameters
nm
the property name
font
a default font to return if property nm is not defined
Returns
the Font value of the property.
Description
Gets the specified font from the system properties list. The first argument is treated as the name of a system property to be obtained as if by the method System.getProperty. The string value of this property is then interpreted as a font.

The property value should be one of the following forms:

  • fontname-style-pointsize
  • fontname-pointsize
  • fontname-style
  • fontname
where style is one of the three strings "BOLD", "BOLDITALIC", or "ITALIC", and point size is a decimal representation of the point size.

The default style is PLAIN. The default point size is 12.

If the specified property is not found, the font argument is returned instead.


 Font.getName

Font.getName

Class Overview | Class Members | This Package | All Packages

Syntax
public String getName()
Returns
a string, the logical name of the font.
Description
Gets the logical name of the font.

See Also
getFamily


 Font.getPeer

Font.getPeer

Class Overview | Class Members | This Package | All Packages

Syntax
public FontPeer getPeer()
Returns
the peer of the font.
Description
Gets the peer of the font.


 Font.getSize

Font.getSize

Class Overview | Class Members | This Package | All Packages

Syntax
public int getSize()
Returns
the point size of this font.
Description
Gets the point size of the font.


 Font.getStyle

Font.getStyle

Class Overview | Class Members | This Package | All Packages

Syntax
public int getStyle()
Returns
the style of this font.
Description
Gets the style of the font.

See Also
isPlain, isBold, isItalic


 Font.hashCode

Font.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int hashCode()
Returns
a hashcode value for this font.
Description
Returns a hashcode for this font.

Overrides
hashCode in class Object


 Font.isBold

Font.isBold

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isBold()
Returns
true if the font is bold; false otherwise.
Description
Indicates whether the font's style is bold.

See Also
getStyle


 Font.isItalic

Font.isItalic

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isItalic()
Returns
true if the font is italic; false otherwise.
Description
Indicates whether the font's style is italic.

See Also
getStyle


 Font.isPlain

Font.isPlain

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isPlain()
Returns
true if the font is neither bold nor italic; false otherwise.
Description
Indicates whether the font's style is plain.

See Also
getStyle


 Font.toString

Font.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string representation of this object
Description
Converts this object to a String representation.

Overrides
toString in class Object


 Class FontMetrics

Class java.awt.FontMetrics

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.FontMetrics

public abstract class FontMetrics
extends Object
implements Serializable

A font metrics object, which gives information about the rendering of a particular font on a particular screen. Note that the implementations of these methods are inefficient, they are usually overridden with more efficient toolkit-specific implementations.

Note to subclassers: Since many of these methods form closed mutually recursive loops, you must take care that you implement at least one of the methods in each such loop in order to prevent infinite recursion when your subclass is used. In particular, the following is the minimal suggested set of methods to override in order to ensure correctness and prevent infinite recursion (though other subsets are equally feasible):

  • getAscent()
  • getDescent()
  • getLeading()
  • getMaxAdvance()
  • charWidth(char ch)
  • charsWidth(char data[], int off, int len)

When an application asks AWT to place a character at the position (x, y), the character is placed so that its reference point (shown as the dot in the accompanying image) is put at that position. The reference point specifies a horizontal line called the baseline of the character. In normal printing, the baselines of characters should align.

In addition, every character in a font has an ascent, a descent, and an advance width. The ascent is the amount by which the character ascends above the baseline. The descent is the amount by which the character descends below the baseline. The advance width indicates the position at which AWT should place the next character.

If the current character is placed with its reference point at the position (x, y), and the character's advance width is w, then the following character is placed with its reference point at the position (x + w, y). The advance width is often the same as the width of character's bounding box, but need not be so. In particular, oblique and italic fonts often have characters whose top-right corner extends slightly beyond the advance width.

An array of characters or a string can also have an ascent, a descent, and an advance width. The ascent of the array is the maximum ascent of any character in the array. The descent is the maximum descent of any character in the array. The advance width is the sum of the advance widths of each of the characters in the array.

See Also:
Font


 FontMetrics Members

FontMetrics Members

Class Overview | This Package | All Packages

Fields
Name | Description
font | The actual font.

Constructors
Name | Description
FontMetrics(Font) | Creates a new FontMetrics object for finding out height and width information about the specified font and specific character glyphs in that font.

Methods
Name | Description
bytesWidth(byte[], int, int) | Returns the total advance width for showing the specified array of bytes in this Font.
charsWidth(char[], int, int) | Returns the total advance width for showing the specified array of characters in this Font.
charWidth(char) | Returns the advance width of the specified character in this Font.
charWidth(int) | Returns the advance width of the specified character in this Font.
getAscent() | Determines the font ascent of the font described by this font metric.
getDescent() | Determines the font descent of the font described by this font metric.
getFont() | Gets the font described by this font metric.
getHeight() | Gets the standard height of a line of text in this font.
getLeading() | Determines the standard leading of the font described by this font metric.
getMaxAdvance() | Gets the maximum advance width of any character in this Font.
getMaxAscent() | Determines the maximum ascent of the font described by this font metric.
getMaxDecent() | For backward compatibility only. Deprecated.
getMaxDescent() | Determines the maximum descent of the font described by this font metric.
getWidths() | Gets the advance widths of the first 256 characters in the Font.
stringWidth(String) | Returns the total advance width for showing the specified String in this Font.
toString() | Returns a representation of this FontMetric object's values as a string.


 FontMetrics.font

FontMetrics.font

Class Overview | Class Members | This Package | All Packages

Syntax
protected Font font
Description
The actual font.

See Also
getFont


 FontMetrics.FontMetrics

FontMetrics.FontMetrics

Class Overview | Class Members | This Package | All Packages

Syntax
protected FontMetrics( Font font )
Parameters
font
the font
Description
Creates a new FontMetrics object for finding out height and width information about the specified font and specific character glyphs in that font.

See Also
Font


 FontMetrics.bytesWidth

FontMetrics.bytesWidth

Class Overview | Class Members | This Package | All Packages

Syntax
public int bytesWidth( byte data[], int off, int len )
Parameters
data
the array of bytes to be measured
off
the start offset of the bytes in the array
len
the number of bytes to be measured from the array
Returns
the advance width of the subarray of the specified byte array in the font described by this font metric.
Description
Returns the total advance width for showing the specified array of bytes in this Font. The advance width is the amount by which the current point is moved from one character to the next in a line of text.

See Also
charsWidth, stringWidth


 FontMetrics.charsWidth

FontMetrics.charsWidth

Class Overview | Class Members | This Package | All Packages

Syntax
public int charsWidth( char data[], int off, int len )
Parameters
data
the array of characters to be measured
off
the start offset of the characters in the array
len
the number of characters to be measured from the array
Returns
the advance width of the subarray of the specified char array in the font described by this font metric.
Description
Returns the total advance width for showing the specified array of characters in this Font. The advance width is the amount by which the current point is moved from one character to the next in a line of text.

See Also
charWidth, charWidth, bytesWidth, stringWidth


 FontMetrics.charWidth

FontMetrics.charWidth

Class Overview | Class Members | This Package | All Packages

Syntax 1
public int charWidth( int ch )
Parameters
ch
the character to be measured
Returns
the advance width of the specified char in the font described by this font metric.
Description
Returns the advance width of the specified character in this Font. The advance width is the amount by which the current point is moved from one character to the next in a line of text.

See Also
charsWidth, stringWidth

Syntax 2
public int charWidth( char ch )
Parameters
ch
the character to be measured
Returns
the advance width of the specified char > in the font described by this font metric.
Description
Returns the advance width of the specified character in this Font. The advance width is the amount by which the current point is moved from one character to the next in a line of text.

See Also
charsWidth, stringWidth


 FontMetrics.getAscent

FontMetrics.getAscent

Class Overview | Class Members | This Package | All Packages

Syntax
public int getAscent()
Returns
the font ascent of the font.
Description
Determines the font ascent of the font described by this font metric. The font ascent is the distance from the font's baseline to the top of most alphanumeric characters. Some characters in the font may extend above the font ascent line.

See Also
getMaxAscent


 FontMetrics.getDescent

FontMetrics.getDescent

Class Overview | Class Members | This Package | All Packages

Syntax
public int getDescent()
Returns
the font descent of the font.
Description
Determines the font descent of the font described by this font metric. The font descent is the distance from the font's baseline to the bottom of most alphanumeric characters with descenders. Some characters in the font may extend below the font descent line.

See Also
getMaxDescent


 FontMetrics.getFont

FontMetrics.getFont

Class Overview | Class Members | This Package | All Packages

Syntax
public Font getFont()
Returns
the font described by this font metric.
Description
Gets the font described by this font metric.


 FontMetrics.getHeight

FontMetrics.getHeight

Class Overview | Class Members | This Package | All Packages

Syntax
public int getHeight()
Returns
the standard height of the font.
Description
Gets the standard height of a line of text in this font. This is the distance between the baseline of adjacent lines of text. It is the sum of the leading + ascent + descent. There is no guarantee that lines of text spaced at this distance will be disjoint; such lines may overlap if some characters overshoot either the standard ascent or the standard descent metric.

See Also
getLeading, getAscent, getDescent


 FontMetrics.getLeading

FontMetrics.getLeading

Class Overview | Class Members | This Package | All Packages

Syntax
public int getLeading()
Returns
the standard leading of the font.
Description
Determines the standard leading of the font described by this font metric. The standard leading (interline spacing) is the logical amount of space to be reserved between the descent of one line of text and the ascent of the next line. The height metric is calculated to include this extra space.

See Also
getHeight, getAscent, getDescent


 FontMetrics.getMaxAdvance

FontMetrics.getMaxAdvance

Class Overview | Class Members | This Package | All Packages

Syntax
public int getMaxAdvance()
Returns
the maximum advance width of any character in the font, or -1 if the maximum advance width is not known.
Description
Gets the maximum advance width of any character in this Font. The advance width is the amount by which the current point is moved from one character to the next in a line of text.


 FontMetrics.getMaxAscent

FontMetrics.getMaxAscent

Class Overview | Class Members | This Package | All Packages

Syntax
public int getMaxAscent()
Returns
the maximum ascent of any character in the font.
Description
Determines the maximum ascent of the font described by this font metric. No character extends further above the font's baseline than this height.

See Also
getAscent


 FontMetrics.getMaxDecent

FontMetrics.getMaxDecent

Class Overview | Class Members | This Package | All Packages

Syntax
public int getMaxDecent()
Description
Note: getMaxDecent() is deprecated. As of JDK version 1.1.1, replaced by getMaxDescent().

For backward compatibility only.

See Also
getMaxDescent


 FontMetrics.getMaxDescent

FontMetrics.getMaxDescent

Class Overview | Class Members | This Package | All Packages

Syntax
public int getMaxDescent()
Returns
the maximum descent of any character in the font.
Description
Determines the maximum descent of the font described by this font metric. No character extends further below the font's baseline than this height.

See Also
getDescent


 FontMetrics.getWidths

FontMetrics.getWidths

Class Overview | Class Members | This Package | All Packages

Syntax
public int[] getWidths()
Returns
an array giving the advance widths of the characters in the font described by this font metric.
Description
Gets the advance widths of the first 256 characters in the Font. The advance width is the amount by which the current point is moved from one character to the next in a line of text.


 FontMetrics.stringWidth

FontMetrics.stringWidth

Class Overview | Class Members | This Package | All Packages

Syntax
public int stringWidth( String str )
Parameters
str
the String to be measured
Returns
the advance width of the specified string in the font described by this font metric.
Description
Returns the total advance width for showing the specified String in this Font. The advance width is the amount by which the current point is moved from one character to the next in a line of text.

See Also
bytesWidth, charsWidth


 FontMetrics.toString

FontMetrics.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string representation of this font metric.
Description
Returns a representation of this FontMetric object's values as a string.

Overrides
toString in class Object


 Class Frame

Class java.awt.Frame

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.Component
           |
           +----java.awt.Container
                   |
                   +----java.awt.Window
                           |
                           +----java.awt.Frame

public class Frame
extends Window
implements MenuContainer

A Frame is a top-level window with a title and a border. The default layout for a frame is BorderLayout. Frames are capable of generating the following types of window events: WindowOpened, WindowClosing, WindowClosed, WindowIconified, WindowDeiconified, WindowActivated, WindowDeactivated.

See Also:
WindowEvent, addWindowListener


 Frame Members

Frame Members

Class Overview | This Package | All Packages

Fields
Name | Description
CROSSHAIR_CURSOR | Deprecated.
DEFAULT_CURSOR | Deprecated.
E_RESIZE_CURSOR | Deprecated.
HAND_CURSOR | Deprecated.
MOVE_CURSOR | Deprecated.
N_RESIZE_CURSOR | Deprecated.
NE_RESIZE_CURSOR | Deprecated.
NW_RESIZE_CURSOR | Deprecated.
S_RESIZE_CURSOR | Deprecated.
SE_RESIZE_CURSOR | Deprecated.
SW_RESIZE_CURSOR | Deprecated.
TEXT_CURSOR | Deprecated.
W_RESIZE_CURSOR | Deprecated.
WAIT_CURSOR | Deprecated.

Constructors
Name | Description
Frame() | Constructs a new instance of Frame that is initially invisible.
Frame(String) | Constructs a new, initially invisible Frame object with the specified title.

Methods
Name | Description
addNotify() | Creates the Frame's peer.
dispose() | Disposes of the Frame.
getCursorType() | Deprecated.
getIconImage() | Gets the icon image for this frame.
getMenuBar() | Gets the menu bar for this frame.
getTitle() | Gets the title of the frame.
isResizable() | Indicates whether this frame is resizable.
paramString() | Returns the parameter String of this Frame.
remove(MenuComponent) | Removes the specified menu bar from this frame.
setCursor(int) | Deprecated.
setIconImage(Image) | Sets the image to display when this frame is iconized.
setMenuBar(MenuBar) | Sets the menu bar for this frame to the specified menu bar.
setResizable(boolean) | Sets the resizable flag, which determines whether this frame is resizable.
setTitle(String) | Sets the title for this frame to the specified title.


 Frame.CROSSHAIR_CURSOR

Frame.CROSSHAIR_CURSOR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int CROSSHAIR_CURSOR
Description
Note: CROSSHAIR_CURSOR is deprecated. replaced by Cursor.CROSSHAIR_CURSOR.


 Frame.DEFAULT_CURSOR

Frame.DEFAULT_CURSOR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int DEFAULT_CURSOR
Description
Note: DEFAULT_CURSOR is deprecated. replaced by Cursor.DEFAULT_CURSOR.


 Frame.E_RESIZE_CURSOR

Frame.E_RESIZE_CURSOR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int E_RESIZE_CURSOR
Description
Note: E_RESIZE_CURSOR is deprecated. replaced by Cursor.E_RESIZE_CURSOR.


 Frame.HAND_CURSOR

Frame.HAND_CURSOR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HAND_CURSOR
Description
Note: HAND_CURSOR is deprecated. replaced by Cursor.HAND_CURSOR.


 Frame.MOVE_CURSOR

Frame.MOVE_CURSOR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int MOVE_CURSOR
Description
Note: MOVE_CURSOR is deprecated. replaced by Cursor.MOVE_CURSOR.


 Frame.N_RESIZE_CURSOR

Frame.N_RESIZE_CURSOR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int N_RESIZE_CURSOR
Description
Note: N_RESIZE_CURSOR is deprecated. replaced by Cursor.N_RESIZE_CURSOR.


 Frame.NE_RESIZE_CURSOR

Frame.NE_RESIZE_CURSOR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int NE_RESIZE_CURSOR
Description
Note: NE_RESIZE_CURSOR is deprecated. replaced by Cursor.NE_RESIZE_CURSOR.


 Frame.NW_RESIZE_CURSOR

Frame.NW_RESIZE_CURSOR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int NW_RESIZE_CURSOR
Description
Note: NW_RESIZE_CURSOR is deprecated. replaced by Cursor.NW_RESIZE_CURSOR.


 Frame.S_RESIZE_CURSOR

Frame.S_RESIZE_CURSOR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int S_RESIZE_CURSOR
Description
Note: S_RESIZE_CURSOR is deprecated. replaced by Cursor.S_RESIZE_CURSOR.


 Frame.SE_RESIZE_CURSOR

Frame.SE_RESIZE_CURSOR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SE_RESIZE_CURSOR
Description
Note: SE_RESIZE_CURSOR is deprecated. replaced by Cursor.SE_RESIZE_CURSOR.


 Frame.SW_RESIZE_CURSOR

Frame.SW_RESIZE_CURSOR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SW_RESIZE_CURSOR
Description
Note: SW_RESIZE_CURSOR is deprecated. replaced by Cursor.SW_RESIZE_CURSOR.


 Frame.TEXT_CURSOR

Frame.TEXT_CURSOR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int TEXT_CURSOR
Description
Note: TEXT_CURSOR is deprecated. replaced by Cursor.TEXT_CURSOR.


 Frame.W_RESIZE_CURSOR

Frame.W_RESIZE_CURSOR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int W_RESIZE_CURSOR
Description
Note: W_RESIZE_CURSOR is deprecated. replaced by Cursor.W_RESIZE_CURSOR.


 Frame.WAIT_CURSOR

Frame.WAIT_CURSOR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int WAIT_CURSOR
Description
Note: WAIT_CURSOR is deprecated. replaced by Cursor.WAIT_CURSOR.


 Frame.Frame

Frame.Frame

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Frame()
Description
Constructs a new instance of Frame that is initially invisible.

See Also
setSize, setVisible

Syntax 2
public Frame( String title )
Parameters
title
the title for the frame
Description
Constructs a new, initially invisible Frame object with the specified title.

See Also
setSize, setVisible


 Frame.addNotify

Frame.addNotify

Class Overview | Class Members | This Package | All Packages

Syntax
public void addNotify()
Description
Creates the Frame's peer. The peer allows us to change the look of the Frame without changing its functionality.

Overrides
addNotify in class Window


 Frame.dispose

Frame.dispose

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void dispose()
Description
Disposes of the Frame. This method must be called to release the resources that are used for the frame. All components contained by the frame and all windows owned by the frame will also be destroyed.

Overrides
dispose in class Window


 Frame.getCursorType

Frame.getCursorType

Class Overview | Class Members | This Package | All Packages

Syntax
public int getCursorType()
Description
Note: getCursorType() is deprecated. As of JDK version 1.1, replaced by Component.getCursor().


 Frame.getIconImage

Frame.getIconImage

Class Overview | Class Members | This Package | All Packages

Syntax
public Image getIconImage()
Returns
the icon image for this frame, or null if this frame doesn't have an icon image.
Description
Gets the icon image for this frame.

See Also
setIconImage


 Frame.getMenuBar

Frame.getMenuBar

Class Overview | Class Members | This Package | All Packages

Syntax
public MenuBar getMenuBar()
Returns
the menu bar for this frame, or null if this frame doesn't have a menu bar.
Description
Gets the menu bar for this frame.

See Also
setMenuBar


 Frame.getTitle

Frame.getTitle

Class Overview | Class Members | This Package | All Packages

Syntax
public String getTitle()
Returns
the title of this frame, or null if this frame doesn't have a title.
Description
Gets the title of the frame.

See Also
setTitle


 Frame.isResizable

Frame.isResizable

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isResizable()
Returns
true if the user can resize this frame; false otherwise.
Description
Indicates whether this frame is resizable. By default, all frames are initially resizable.

See Also
setResizable


 Frame.paramString

Frame.paramString

Class Overview | Class Members | This Package | All Packages

Syntax
protected String paramString()
Description
Returns the parameter String of this Frame.

Overrides
paramString in class Container


 Frame.remove

Frame.remove

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void remove( MenuComponent m )
Parameters
m
the menu component to remove.
Description
Removes the specified menu bar from this frame.

Overrides
remove in class Component


 Frame.setCursor

Frame.setCursor

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setCursor( int cursorType )
Description
Note: setCursor() is deprecated. As of JDK version 1.1, replaced by Component.setCursor(Cursor).


 Frame.setIconImage

Frame.setIconImage

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setIconImage( Image image )
Parameters
image
the icon image to be displayed
Description
Sets the image to display when this frame is iconized. Not all platforms support the concept of iconizing a window.

See Also
getIconImage


 Frame.setMenuBar

Frame.setMenuBar

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setMenuBar( MenuBar mb )
Parameters
mb
the menu bar being set
Description
Sets the menu bar for this frame to the specified menu bar.

See Also
getMenuBar


 Frame.setResizable

Frame.setResizable

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setResizable( boolean resizable )
Parameters
resizable
true if this frame is resizable; false otherwise.
Description
Sets the resizable flag, which determines whether this frame is resizable. By default, all frames are initially resizable.

See Also
isResizable


 Frame.setTitle

Frame.setTitle

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setTitle( String title )
Parameters
title
the specified title of this frame.
Description
Sets the title for this frame to the specified title.

See Also
getTitle


 Class Graphics

Class java.awt.Graphics

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.Graphics

public abstract class Graphics
extends Object

The Graphics class is the abstract base class for all graphics contexts that allow an application to draw onto components that are realized on various devices, as well as onto off-screen images.

A Graphics object encapsulates state information needed for the basic rendering operations that Java supports. This state information includes the following properties:

  • The Component object on which to draw.
  • A translation origin for rendering and clipping coordinates.
  • The current clip.
  • The current color.
  • The current font.
  • The current logical pixel operation function (XOR or Paint).
  • The current XOR alternation color (see setXORMode).

Coordinates are infinitely thin and lie between the pixels of the output device. Operations which draw the outline of a figure operate by traversing an infinitely thin path between pixels with a pixel-sized pen that hangs down and to the right of the anchor point on the path. Operations which fill a figure operate by filling the interior of that infinitely thin path. Operations which render horizontal text render the ascending portion of character glyphs entirely above the baseline coordinate.

The graphics pen hangs down and to the right from the path it traverses. This has the following implications:

  • If you draw a figure that covers a given rectangle, that figure occupies one extra row of pixels on the right and bottom edges as compared to filling a figure that is bounded by that same rectangle.
  • If you draw a horizontal line along the same y coordinate as the baseline of a line of text, that line is drawn entirely below the text, except for any descenders.

All coordinates which appear as arguments to the methods of this Graphics object are considered relative to the translation origin of this Graphics object prior to the invocation of the method. All rendering operations modify only pixels which lie within the area bounded by both the current clip of the graphics context and the extents of the component used to create the Graphics object. All drawing or writing is done in the current color, using the current paint mode, and in the current font.

See Also:
Component, clipRect, setColor, setPaintMode, setXORMode, setFont


 Graphics Members

Graphics Members

Class Overview | This Package | All Packages

Constructors
Name | Description
Graphics() | Constructs a new Graphics object.

Methods
Name | Description
clearRect(int, int, int, int) | Clears the specified rectangle by filling it with the background color of the current drawing surface.
clipRect(int, int, int, int) | Intersects the current clip with the specified rectangle.
copyArea(int, int, int, int, int, int) | Copies an area of the component by a distance specified by dx and dy.
create() | Creates a new Graphics object that is a copy of this Graphics object.
create(int, int, int, int) | Creates a new Graphics object based on this Graphics object, but with a new translation and clip area.
dispose() | Disposes of this graphics context and releases any system resources that it is using.
draw3DRect(int, int, int, int, boolean) | Draws a 3-D highlighted outline of the specified rectangle.
drawArc(int, int, int, int, int, int) | Draws the outline of a circular or elliptical arc covering the specified rectangle.
drawBytes(byte[], int, int, int, int) | Draws the text given by the specified byte array, using this graphics context's current font and color.
drawChars(char[], int, int, int, int) | Draws the text given by the specified character array, using this graphics context's current font and color.
drawImage(Image, int, int, Color, ImageObserver) | Draws as much of the specified image as is currently available.
drawImage(Image, int, int, ImageObserver) | Draws as much of the specified image as is currently available.
drawImage(Image, int, int, int, int, Color, ImageObserver) | Draws as much of the specified image as has already been scaled to fit inside the specified rectangle.
drawImage(Image, int, int, int, int, ImageObserver) | Draws as much of the specified image as has already been scaled to fit inside the specified rectangle.
drawImage(Image, int, int, int, int, int, int, int, int, Color, ImageObserver) | Draws as much of the specified area of the specified image as is currently available, scaling it on the fly to fit inside the specified area of the destination drawable surface.
drawImage(Image, int, int, int, int, int, int, int, int, ImageObserver) | Draws as much of the specified area of the specified image as is currently available, scaling it on the fly to fit inside the specified area of the destination drawable surface.
drawLine(int, int, int, int) | Draws a line, using the current color, between the points (x1, y1) and (x2, y2) in this graphics context's coordinate system.
drawOval(int, int, int, int) | Draws the outline of an oval.
drawPolygon(int[], int[], int) | Draws a closed polygon defined by arrays of x and y coordinates.
drawPolygon(Polygon) | Draws the outline of a polygon defined by the specified Polygon object.
drawPolyline(int[], int[], int) | Draws a sequence of connected lines defined by arrays of x and y coordinates.
drawRect(int, int, int, int) | Draws the outline of the specified rectangle.
drawRoundRect(int, int, int, int, int, int) | Draws an outlined round-cornered rectangle using this graphics context's current color.
drawString(String, int, int) | Draws the text given by the specified string, using this graphics context's current font and color.
fill3DRect(int, int, int, int, boolean) | Paints a 3-D highlighted rectangle filled with the current color.
fillArc(int, int, int, int, int, int) | Fills a circular or elliptical arc covering the specified rectangle.
fillOval(int, int, int, int) | Fills an oval bounded by the specified rectangle with the current color.
fillPolygon(int[], int[], int) | Fills a closed polygon defined by arrays of x and y coordinates.
fillPolygon(Polygon) | Fills the polygon defined by the specified Polygon object with the graphics context's current color.
fillRect(int, int, int, int) | Fills the specified rectangle.
fillRoundRect(int, int, int, int, int, int) | Fills the specified rounded corner rectangle with the current color.
finalize() | Disposes of this graphics context once it is no longer referenced.
getClip() | Gets the current clipping area.
getClipBounds() | Returns the bounding rectangle of the current clipping area.
getClipRect() | Deprecated.
getColor() | Gets this graphics context's current color.
getFont() | Gets the current font.
getFontMetrics() | Gets the font metrics of the current font.
getFontMetrics(Font) | Gets the font metrics for the specified font.
setClip(int, int, int, int) | Sets the current clip to the rectangle specified by the given coordinates.
setClip(Shape) | Sets the current clipping area to an arbitrary clip shape.
setColor(Color) | Sets this graphics context's current color to the specified color.
setFont(Font) | Sets this graphics context's font to the specified font.
setPaintMode() | Sets the paint mode of this graphics context to overwrite the destination with this graphics context's current color.
setXORMode(Color) | Sets the paint mode of this graphics context to alternate between this graphics context's current color and the new specified color.
toString() | Returns a String object representing this Graphics object's value.
translate(int, int) | Translates the origin of the graphics context to the point (x, y) in the current coordinate system.


 Graphics.Graphics

Graphics.Graphics

Class Overview | Class Members | This Package | All Packages

Syntax
protected Graphics()
Description
Constructs a new Graphics object. This constructor is the default contructor for a graphics context.

Since Graphics is an abstract class, applications cannot call this constructor directly. Graphics contexts are obtained from other graphics contexts or are created by calling getGraphics on a component.

See Also
create, getGraphics


 Graphics.clearRect

Graphics.clearRect

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void clearRect( int x, int y, int width, int height )
Parameters
x
the x coordinate of the rectangle to clear.
y
the y coordinate of the rectangle to clear.
width
the width of the rectangle to clear.
height
the height of the rectangle to clear.
Description
Clears the specified rectangle by filling it with the background color of the current drawing surface. This operation does not use the current paint mode.

Beginning with Java 1.1, the background color of offscreen images may be system dependent. Applications should use setColor followed by fillRect to ensure that an offscreen image is cleared to a specific color.

See Also
fillRect, drawRect, setColor, setPaintMode, setXORMode


 Graphics.clipRect

Graphics.clipRect

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void clipRect( int x, int y, int width, int height )
Parameters
x
the x coordinate of the rectangle to intersect the clip with
y
the y coordinate of the rectangle to intersect the clip with
width
the width of the rectangle to intersect the clip with
height
the height of the rectangle to intersect the clip with
Description
Intersects the current clip with the specified rectangle. The resulting clipping area is the intersection of the current clipping area and the specified rectangle. This method can only be used to make the current clip smaller. To set the current clip larger, use any of the setClip methods. Rendering operations have no effect outside of the clipping area.

See Also
setClip, setClip


 Graphics.copyArea

Graphics.copyArea

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void copyArea( int x, int y, int width, int height, int dx, int dy )
Parameters
x
the x coordinate of the source rectangle.
y
the y coordinate of the source rectangle.
width
the width of the source rectangle.
height
the height of the source rectangle.
dx
the horizontal distance to copy the pixels.
dy
the vertical distance to copy the pixels.
Description
Copies an area of the component by a distance specified by dx and dy. From the point specified by x and y, this method copies downwards and to the right. To copy an area of the component to the left or upwards, specify a negative value for dx or dy. If a portion of the source rectangle lies outside the bounds of the component, or is obscured by another window or component, copyArea will be unable to copy the associated pixels. The area that is omitted can be refreshed by calling the component's paint method.


 Graphics.create

Graphics.create

Class Overview | Class Members | This Package | All Packages

Syntax 1
public abstract Graphics create()
Returns
a new graphics context that is a copy of this graphics context.
Description
Creates a new Graphics object that is a copy of this Graphics object.

Syntax 2
public Graphics create( int x, int y, int width, int height )
Parameters
x
the x coordinate.
y
the y coordinate.
width
the width of the clipping rectangle.
height
the height of the clipping rectangle.
Returns
a new graphics context.
Description
Creates a new Graphics object based on this Graphics object, but with a new translation and clip area. The new Graphics object has its origin translated to the specified point (x, y). Its clip area is determined by the intersection of the original clip area with the specified rectangle. The arguments are all interpreted in the coordinate system of the original Graphics object. The new graphics context is identical to the original, except in two respects:

  • The new graphics context is translated by (x, y). That is to say, the point (0, 0) in the new graphics context is the same as (x, y) in the original graphics context.
  • The new graphics context has an additional clipping rectangle, in addition to whatever (translated) clipping rectangle it inherited from the original graphics context. The origin of the new clipping rectangle is at (0, 0), and its size is specified by the width and height arguments.

See Also
translate, clipRect


 Graphics.dispose

Graphics.dispose

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void dispose()
Description
Disposes of this graphics context and releases any system resources that it is using. A Graphics object cannot be used after disposehas been called.

When a Java program runs, a large number of Graphics objects can be created within a short time frame. Although the finalization process of the garbage collector also disposes of the same system resources, it is preferable to manually free the associated resources by calling this method rather than to rely on a finalization process which may not run to completion for a long period of time.

Graphics objects which are provided as arguments to the paint and update methods of components are automatically released by the system when those methods return. For efficiency, programmers should call dispose when finished using a Graphics object only if it was created directly from a component or another Graphics object.

See Also
finalize, paint, update, getGraphics, create


 Graphics.draw3DRect

Graphics.draw3DRect

Class Overview | Class Members | This Package | All Packages

Syntax
public void draw3DRect( int x, int y, int width, int height, boolean raised )
Parameters
x
the x coordinate of the rectangle to be drawn.
y
the y coordinate of the rectangle to be drawn.
width
the width of the rectangle to be drawn.
height
the height of the rectangle to be drawn.
raised
a boolean that determines whether the rectangle appears to be raised above the surface or sunk into the surface.
Description
Draws a 3-D highlighted outline of the specified rectangle. The edges of the rectangle are highlighted so that they appear to be beveled and lit from the upper left corner.

The colors used for the highlighting effect are determined based on the current color. The resulting rectangle covers an area that is width + 1 pixels wide by height + 1 pixels tall.

See Also
fill3DRect


 Graphics.drawArc

Graphics.drawArc

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void drawArc( int x, int y, int width, int height, int startAngle, int arcAngle )
Parameters
x
the x coordinate of the upper-left corner of the arc to be drawn.
y
the y coordinate of the upper-left corner of the arc to be drawn.
width
the width of the arc to be drawn.
height
the height of the arc to be drawn.
startAngle
the beginning angle.
arcAngle
the angular extent of the arc, relative to the start angle.
Description
Draws the outline of a circular or elliptical arc covering the specified rectangle.

The resulting arc begins at startAngle and extends for arcAngle degrees, using the current color. Angles are interpreted such that 0 degrees is at the 3 o'clock position. A positive value indicates a counter-clockwise rotation while a negative value indicates a clockwise rotation.

The center of the arc is the center of the rectangle whose origin is (x, y) and whose size is specified by the width and height arguments.

The resulting arc covers an area width + 1 pixels wide by height + 1 pixels tall.

See Also
fillArc


 Graphics.drawBytes

Graphics.drawBytes

Class Overview | Class Members | This Package | All Packages

Syntax
public void drawBytes( byte data[], int offset, int length, int x, int y )
Parameters
data
the data to be drawn
offset
the start offset in the data
length
the number of bytes that are drawn
x
the x coordinate of the baseline of the text
y
the y coordinate of the baseline of the text
Description
Draws the text given by the specified byte array, using this graphics context's current font and color. The baseline of the first character is at position (x, y) in this graphics context's coordinate system.

See Also
drawChars, drawString


 Graphics.drawChars

Graphics.drawChars

Class Overview | Class Members | This Package | All Packages

Syntax
public void drawChars( char data[], int offset, int length, int x, int y )
Parameters
data
the array of characters to be drawn
offset
the start offset in the data
length
the number of characters to be drawn
x
the x coordinate of the baseline of the text
y
the y coordinate of the baseline of the text
Description
Draws the text given by the specified character array, using this graphics context's current font and color. The baseline of the first character is at position (x, y) in this graphics context's coordinate system.

See Also
drawBytes, drawString


 Graphics.drawImage

Graphics.drawImage

Class Overview | Class Members | This Package | All Packages

Syntax 1
public abstract boolean drawImage( Image img, int x, int y, ImageObserver observer )
Parameters
img
the specified image to be drawn.
x
the x coordinate.
y
the y coordinate.
observer
object to be notified as more of the image is converted.
Description
Draws as much of the specified image as is currently available. The image is drawn with its top-left corner at (x, y) in this graphics context's coordinate space. Transparent pixels in the image do not affect whatever pixels are already there.

This method returns immediately in all cases, even if the complete image has not yet been loaded, and it has not been dithered and converted for the current output device.

If the image has not yet been completely loaded, then drawImage returns false. As more of the image becomes available, the process that draws the image notifies the specified image observer.

See Also
Image, ImageObserver, imageUpdate

Syntax 2
public abstract boolean drawImage( Image img, int x, int y, int width, int height, ImageObserver observer )
Parameters
img
the specified image to be drawn.
x
the x coordinate.
y
the y coordinate.
width
the width of the rectangle.
height
the height of the rectangle.
observer
object to be notified as more of the image is converted.
Description
Draws as much of the specified image as has already been scaled to fit inside the specified rectangle.

The image is drawn inside the specified rectangle of this graphics context's coordinate space, and is scaled if necessary. Transparent pixels do not affect whatever pixels are already there.

This method returns immediately in all cases, even if the entire image has not yet been scaled, dithered, and converted for the current output device. If the current output representation is not yet complete, then drawImage returns false. As more of the image becomes available, the process that draws the image notifies the image observer by calling its imageUpdate method.

A scaled version of an image will not necessarily be available immediately just because an unscaled version of the image has been constructed for this output device. Each size of the image may be cached separately and generated from the original data in a separate image production sequence.

See Also
Image, ImageObserver, imageUpdate

Syntax 3
public abstract boolean drawImage( Image img, int x, int y, Color bgcolor, ImageObserver observer )
Parameters
img
the specified image to be drawn.
x
the x coordinate.
y
the y coordinate.
bgcolor
the background color to paint under the non-opaque portions of the image.
observer
object to be notified as more of the image is converted.
Description
Draws as much of the specified image as is currently available. The image is drawn with its top-left corner at (x, y) in this graphics context's coordinate space. Transparent pixels are drawn in the specified background color.

This operation is equivalent to filling a rectangle of the width and height of the specified image with the given color and then drawing the image on top of it, but possibly more efficient.

This method returns immediately in all cases, even if the complete image has not yet been loaded, and it has not been dithered and converted for the current output device.

If the image has not yet been completely loaded, then drawImage returns false. As more of the image becomes available, the process that draws the image notifies the specified image observer.

See Also
Image, ImageObserver, imageUpdate

Syntax 4
public abstract boolean drawImage( Image img, int x, int y, int width, int height, Color bgcolor, ImageObserver observer )
Parameters
img
the specified image to be drawn.
x
the x coordinate.
y
the y coordinate.
width
the width of the rectangle.
height
the height of the rectangle.
bgcolor
the background color to paint under the non-opaque portions of the image.
observer
object to be notified as more of the image is converted.
Description
Draws as much of the specified image as has already been scaled to fit inside the specified rectangle.

The image is drawn inside the specified rectangle of this graphics context's coordinate space, and is scaled if necessary. Transparent pixels are drawn in the specified background color. This operation is equivalent to filling a rectangle of the width and height of the specified image with the given color and then drawing the image on top of it, but possibly more efficient.

This method returns immediately in all cases, even if the entire image has not yet been scaled, dithered, and converted for the current output device. If the current output representation is not yet complete then drawImage returns false. As more of the image becomes available, the process that draws the image notifies the specified image observer.

A scaled version of an image will not necessarily be available immediately just because an unscaled version of the image has been constructed for this output device. Each size of the image may be cached separately and generated from the original data in a separate image production sequence.

See Also
Image, ImageObserver, imageUpdate

Syntax 5
public abstract boolean drawImage( Image img, int dx1, int dy1, int dx2, int dy2, int sx1, int sy1, int sx2, int sy2, ImageObserver observer )
Parameters
img
the specified image to be drawn
dx1
the x coordinate of the first corner of the destination rectangle.
dy1
the y coordinate of the first corner of the destination rectangle.
dx2
the x coordinate of the second corner of the destination rectangle.
dy2
the y coordinate of the second corner of the destination rectangle.
sx1
the x coordinate of the first corner of the source rectangle.
sy1
the y coordinate of the first corner of the source rectangle.
sx2
the x coordinate of the second corner of the source rectangle.
sy2
the y coordinate of the second corner of the source rectangle.
observer
object to be notified as more of the image is scaled and converted.
Description
Draws as much of the specified area of the specified image as is currently available, scaling it on the fly to fit inside the specified area of the destination drawable surface. Transparent pixels do not affect whatever pixels are already there.

This method returns immediately in all cases, even if the image area to be drawn has not yet been scaled, dithered, and converted for the current output device. If the current output representation is not yet complete then drawImage returns false. As more of the image becomes available, the process that draws the image notifies the specified image observer.

This method always uses the unscaled version of the image to render the scaled rectangle and performs the required scaling on the fly. It does not use a cached, scaled version of the image for this operation. Scaling of the image from source to destination is performed such that the first coordinate of the source rectangle is mapped to the first coordinate of the destination rectangle, and the second source coordinate is mapped to the second destination coordinate. The subimage is scaled and flipped as needed to preserve those mappings.

See Also
Image, ImageObserver, imageUpdate

Syntax 6
public abstract boolean drawImage( Image img, int dx1, int dy1, int dx2, int dy2, int sx1, int sy1, int sx2, int sy2, Color bgcolor, ImageObserver observer )
Parameters
img
the specified image to be drawn
dx1
the x coordinate of the first corner of the destination rectangle.
dy1
the y coordinate of the first corner of the destination rectangle.
dx2
the x coordinate of the second corner of the destination rectangle.
dy2
the y coordinate of the second corner of the destination rectangle.
sx1
the x coordinate of the first corner of the source rectangle.
sy1
the y coordinate of the first corner of the source rectangle.
sx2
the x coordinate of the second corner of the source rectangle.
sy2
the y coordinate of the second corner of the source rectangle.
bgcolor
the background color to paint under the non-opaque portions of the image.
observer
object to be notified as more of the image is scaled and converted.
Description
Draws as much of the specified area of the specified image as is currently available, scaling it on the fly to fit inside the specified area of the destination drawable surface.

Transparent pixels are drawn in the specified background color. This operation is equivalent to filling a rectangle of the width and height of the specified image with the given color and then drawing the image on top of it, but possibly more efficient.

This method returns immediately in all cases, even if the image area to be drawn has not yet been scaled, dithered, and converted for the current output device. If the current output representation is not yet complete then drawImage returns false. As more of the image becomes available, the process that draws the image notifies the specified image observer.

This method always uses the unscaled version of the image to render the scaled rectangle and performs the required scaling on the fly. It does not use a cached, scaled version of the image for this operation. Scaling of the image from source to destination is performed such that the first coordinate of the source rectangle is mapped to the first coordinate of the destination rectangle, and the second source coordinate is mapped to the second destination coordinate. The subimage is scaled and flipped as needed to preserve those mappings.

See Also
Image, ImageObserver, imageUpdate


 Graphics.drawLine

Graphics.drawLine

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void drawLine( int x1, int y1, int x2, int y2 )
Parameters
x1
the first point's x coordinate.
y1
the first point's y coordinate.
x2
the second point's x coordinate.
y2
the second point's y coordinate.
Description
Draws a line, using the current color, between the points (x1, y1) and (x2, y2) in this graphics context's coordinate system.


 Graphics.drawOval

Graphics.drawOval

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void drawOval( int x, int y, int width, int height )
Parameters
x
the x coordinate of the upper left corner of the oval to be drawn.
y
the y coordinate of the upper left corner of the oval to be drawn.
width
the width of the oval to be drawn.
height
the height of the oval to be drawn.
Description
Draws the outline of an oval. The result is a circle or ellipse that fits within the rectangle specified by the x, y, width, and height arguments.

The oval covers an area that is width + 1 pixels wide and height + 1 pixels tall.

See Also
fillOval


 Graphics.drawPolygon

Graphics.drawPolygon

Class Overview | Class Members | This Package | All Packages

Syntax 1
public abstract void drawPolygon( int xPoints[], int yPoints[], int nPoints )
Parameters
xPoints
a an array of x coordinates.
yPoints
a an array of y coordinates.
nPoints
a the total number of points.
Description
Draws a closed polygon defined by arrays of x and y coordinates. Each pair of (x, y) coordinates defines a point.

This method draws the polygon defined by nPoint line segments, where the first nPoint - 1 line segments are line segments from (xPoints[i - 1], yPoints[i - 1]) to (xPoints[i], yPoints[i]), for 1 ≤ i ≤ nPoints. The figure is automatically closed by drawing a line connecting the final point to the first point, if those points are different.

See Also
fillPolygon, drawPolyline

Syntax 2
public void drawPolygon( Polygon p )
Parameters
p
the polygon to draw.
Description
Draws the outline of a polygon defined by the specified Polygon object.

See Also
fillPolygon, drawPolyline


 Graphics.drawPolyline

Graphics.drawPolyline

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void drawPolyline( int xPoints[], int yPoints[], int nPoints )
Parameters
xPoints
an array of x points
yPoints
an array of y points
nPoints
the total number of points
Description
Draws a sequence of connected lines defined by arrays of x and y coordinates. Each pair of (x, y) coordinates defines a point. The figure is not closed if the first point differs from the last point.

See Also
drawPolygon


 Graphics.drawRect

Graphics.drawRect

Class Overview | Class Members | This Package | All Packages

Syntax
public void drawRect( int x, int y, int width, int height )
Parameters
x
the x coordinate of the rectangle to be drawn.
y
the y coordinate of the rectangle to be drawn.
width
the width of the rectangle to be drawn.
height
the height of the rectangle to be drawn.
Description
Draws the outline of the specified rectangle. The left and right edges of the rectangle are at x and x + width. The top and bottom edges are at y and y + height. The rectangle is drawn using the graphics context's current color.

See Also
fillRect, clearRect


 Graphics.drawRoundRect

Graphics.drawRoundRect

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void drawRoundRect( int x, int y, int width, int height, int arcWidth, int arcHeight )
Parameters
x
the x coordinate of the rectangle to be drawn.
y
the y coordinate of the rectangle to be drawn.
width
the width of the rectangle to be drawn.
height
the height of the rectangle to be drawn.
arcWidth
the horizontal diameter of the arc at the four corners.
arcHeight
the vertical diameter of the arc at the four corners.
Description
Draws an outlined round-cornered rectangle using this graphics context's current color. The left and right edges of the rectangle are at x and x + width, respectively. The top and bottom edges of the rectangle are at y and y + height.

See Also
fillRoundRect


 Graphics.drawString

Graphics.drawString

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void drawString( String str, int x, int y )
Parameters
str
the string to be drawn.
x
the x coordinate.
y
the y coordinate.
Description
Draws the text given by the specified string, using this graphics context's current font and color. The baseline of the first character is at position (x, y) in this graphics context's coordinate system.

See Also
drawBytes, drawChars


 Graphics.fill3DRect

Graphics.fill3DRect

Class Overview | Class Members | This Package | All Packages

Syntax
public void fill3DRect( int x, int y, int width, int height, boolean raised )
Parameters
x
the x coordinate of the rectangle to be filled.
y
the y coordinate of the rectangle to be filled.
width
the width of the rectangle to be filled.
height
the height of the rectangle to be filled.
raised
a boolean value that determines whether the rectangle appears to be raised above the surface or etched into the surface.
Description
Paints a 3-D highlighted rectangle filled with the current color. The edges of the rectangle will be highlighted so that it appears as if the edges were beveled and lit from the upper left corner. The colors used for the highlighting effect will be determined from the current color.

See Also
draw3DRect


 Graphics.fillArc

Graphics.fillArc

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void fillArc( int x, int y, int width, int height, int startAngle, int arcAngle )
Parameters
x
the x coordinate of the upper-left corner of the arc to be filled.
y
the y coordinate of the upper-left corner of the arc to be filled.
width
the width of the arc to be filled.
height
the height of the arc to be filled.
startAngle
the beginning angle.
arcAngle
the angular extent of the arc, relative to the start angle.
Description
Fills a circular or elliptical arc covering the specified rectangle.

The resulting arc begins at startAngle and extends for arcAngle degrees. Angles are interpreted such that 0 degrees is at the 3 o'clock position. A positive value indicates a counter-clockwise rotation while a negative value indicates a clockwise rotation.

The center of the arc is the center of the rectangle whose origin is (x, y) and whose size is specified by the width and height arguments.

The resulting arc covers an area width + 1 pixels wide by height + 1 pixels tall.

See Also
drawArc


 Graphics.fillOval

Graphics.fillOval

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void fillOval( int x, int y, int width, int height )
Parameters
x
the x coordinate of the upper left corner of the oval to be filled.
y
the y coordinate of the upper left corner of the oval to be filled.
width
the width of the oval to be filled.
height
the height of the oval to be filled.
Description
Fills an oval bounded by the specified rectangle with the current color.

See Also
drawOval


 Graphics.fillPolygon

Graphics.fillPolygon

Class Overview | Class Members | This Package | All Packages

Syntax 1
public abstract void fillPolygon( int xPoints[], int yPoints[], int nPoints )
Parameters
xPoints
a an array of x coordinates.
yPoints
a an array of y coordinates.
nPoints
a the total number of points.
Description
Fills a closed polygon defined by arrays of x and y coordinates.

This method draws the polygon defined by nPoint line segments, where the first nPoint - 1 line segments are line segments from (xPoints[i - 1], yPoints[i - 1]) to (xPoints[i], yPoints[i]), for 1 ≤ i ≤ nPoints. The figure is automatically closed by drawing a line connecting the final point to the first point, if those points are different.

The area inside the polygon is defined using an even-odd fill rule, also known as the alternating rule.

See Also
drawPolygon

Syntax 2
public void fillPolygon( Polygon p )
Parameters
p
the polygon to fill.
Description
Fills the polygon defined by the specified Polygon object with the graphics context's current color.

The area inside the polygon is defined using an even-odd fill rule, also known as the alternating rule.

See Also
drawPolygon


 Graphics.fillRect

Graphics.fillRect

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void fillRect( int x, int y, int width, int height )
Parameters
x
the x coordinate of the rectangle to be filled.
y
the y coordinate of the rectangle to be filled.
width
the width of the rectangle to be filled.
height
the height of the rectangle to be filled.
Description
Fills the specified rectangle. The left and right edges of the rectangle are at x and x + width - 1. The top and bottom edges are at y and y + height - 1. The resulting rectangle covers an area width pixels wide by height pixels tall. The rectangle is filled using the graphics context's current color.

See Also
fillRect, clearRect


 Graphics.fillRoundRect

Graphics.fillRoundRect

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void fillRoundRect( int x, int y, int width, int height, int arcWidth, int arcHeight )
Parameters
x
the x coordinate of the rectangle to be filled.
y
the y coordinate of the rectangle to be filled.
width
the width of the rectangle to be filled.
height
the height of the rectangle to be filled.
arcWidth
the horizontal diameter of the arc at the four corners.
arcHeight
the vertical diameter of the arc at the four corners.
Description
Fills the specified rounded corner rectangle with the current color. The left and right edges of the rectangle are at x and x + width - 1, respectively. The top and bottom edges of the rectangle are at y and y + height - 1.

See Also
drawRoundRect


 Graphics.finalize

Graphics.finalize

Class Overview | Class Members | This Package | All Packages

Syntax
public void finalize()
Description
Disposes of this graphics context once it is no longer referenced.

Overrides
finalize in class Object
See Also
dispose


 Graphics.getClip

Graphics.getClip

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract Shape getClip()
Returns
a Shape object representing the current clipping area.
Description
Gets the current clipping area.

See Also
getClipBounds, clipRect, setClip, setClip


 Graphics.getClipBounds

Graphics.getClipBounds

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract Rectangle getClipBounds()
Returns
the bounding rectangle of the current clipping area.
Description
Returns the bounding rectangle of the current clipping area. The coordinates in the rectangle are relative to the coordinate system origin of this graphics context.

See Also
getClip, clipRect, setClip, setClip


 Graphics.getClipRect

Graphics.getClipRect

Class Overview | Class Members | This Package | All Packages

Syntax
public Rectangle getClipRect()
Description
Note: getClipRect() is deprecated. As of JDK version 1.1, replaced by getClipBounds().


 Graphics.getColor

Graphics.getColor

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract Color getColor()
Returns
this graphics context's current color.
Description
Gets this graphics context's current color.

See Also
Color, setColor


 Graphics.getFont

Graphics.getFont

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract Font getFont()
Returns
this graphics context's current font.
Description
Gets the current font.

See Also
Font, setFont


 Graphics.getFontMetrics

Graphics.getFontMetrics

Class Overview | Class Members | This Package | All Packages

Syntax 1
public FontMetrics getFontMetrics()
Returns
the font metrics of this graphics context's current font.
Description
Gets the font metrics of the current font.

See Also
getFont, FontMetrics, getFontMetrics

Syntax 2
public abstract FontMetrics getFontMetrics( Font f )
Parameters
f
the specified font
Returns
the font metrics for the specified font.
Description
Gets the font metrics for the specified font.

See Also
getFont, FontMetrics, getFontMetrics


 Graphics.setClip

Graphics.setClip

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void setClip( int x, int y, int width, int height )
Parameters
x
the x coordinate of the new clip rectangle.
y
the y coordinate of the new clip rectangle.
width
the width of the new clip rectangle.
height
the height of the new clip rectangle.
Description
Sets the current clip to the rectangle specified by the given coordinates. Rendering operations have no effect outside of the clipping area.

See Also
clipRect, setClip


 Graphics.setClip

Graphics.setClip

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void setClip( Shape clip )
Description
Sets the current clipping area to an arbitrary clip shape. Not all objects which implement the Shape interface can be used to set the clip. The only Shape objects which are guaranteed to be supported are Shape objects which are obtained via the getClip method and via Rectangle objects.

See Also
getClip, clipRect, setClip


 Graphics.setColor

Graphics.setColor

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void setColor( Color c )
Parameters
c
the new rendering color.
Description
Sets this graphics context's current color to the specified color. All subsequent graphics operations using this graphics context use this specified color.

See Also
Color, getColor


 Graphics.setFont

Graphics.setFont

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void setFont( Font font )
Parameters
font
the font.
Description
Sets this graphics context's font to the specified font. All subsequent text operations using this graphics context use this font.

See Also
getFont, drawChars, drawString, drawBytes


 Graphics.setPaintMode

Graphics.setPaintMode

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void setPaintMode()
Description
Sets the paint mode of this graphics context to overwrite the destination with this graphics context's current color. This sets the logical pixel operation function to the paint or overwrite mode. All subsequent rendering operations will overwrite the destination with the current color.


 Graphics.setXORMode

Graphics.setXORMode

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void setXORMode( Color c1 )
Parameters
c1
the XOR alternation color
Description
Sets the paint mode of this graphics context to alternate between this graphics context's current color and the new specified color. This specifies that logical pixel operations are performed in the XOR mode, which alternates pixels between the current color and a specified XOR color.

When drawing operations are performed, pixels which are the current color are changed to the specified color, and vice versa.

Pixels that are of colors other than those two colors are changed in an unpredictable but reversible manner; if the same figure is drawn twice, then all pixels are restored to their original values.


 Graphics.toString

Graphics.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string representation of this graphics context.
Description
Returns a String object representing this Graphics object's value.

Overrides
toString in class Object


 Graphics.translate

Graphics.translate

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void translate( int x, int y )
Parameters
x
the x coordinate.
y
the y coordinate.
Description
Translates the origin of the graphics context to the point (x, y) in the current coordinate system. Modifies this graphics context so that its new origin corresponds to the point (x, y) in this graphics context's original coordinate system. All coordinates used in subsequent rendering operations on this graphics context will be relative to this new origin.


 Class GridBagConstraints

Class java.awt.GridBagConstraints

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.GridBagConstraints

public class GridBagConstraints
extends Object
implements Cloneable, Serializable

The GridBagConstraints class specifies constraints for components that are laid out using the GridBagLayout class.

See Also:
GridBagLayout


 GridBagConstraints Members

GridBagConstraints Members

Class Overview | This Package | All Packages

Fields
Name | Description
anchor | This field is used when the component is smaller than its display area.
BOTH | Resize the component both horizontally and vertically.
CENTER | Put the component in the center of its display area.
EAST | Put the component on the left side of its display area, centered vertically.
fill | This field is used when the component's display area is larger than the component's requested size.
gridheight | Specifies the number of cells in a column for the component's display area.
gridwidth | Specifies the number of cells in a row for the component's display area.
gridx | Specifies the cell at the left of the component's display area, where the leftmost cell has gridx = 0.
gridy | Specifies the cell at the top of the component's display area, where the topmost cell has gridy = 0.
HORIZONTAL | Resize the component horizontally but not vertically.
insets | This field specifies the external padding of the component, the minimum amount of space between the component and the edges of its display area.
ipadx | This field specifies the internal padding of the component, how much space to add to the minimum width of the component.
ipady | This field specifies the internal padding, that is, how much space to add to the minimum height of the component.
NONE | Do not resize the component.
NORTH | Put the component at the top of its display area, centered horizontally.
NORTHEAST | Put the component at the top-right corner of its display area.
NORTHWEST | Put the component at the top-left corner of its display area.
RELATIVE | Specify that this component is the next-to-last component in its column or row (gridwidth, gridheight), or that this component be placed next to the previously added component (gridx, gridy).
REMAINDER | Specify that this component is the last component in its column or row.
SOUTH | Put the component at the bottom of its display area, centered horizontally.
SOUTHEAST | Put the component at the bottom-right corner of its display area.
SOUTHWEST | Put the component at the bottom-left corner of its display area.
VERTICAL | Resize the component vertically but not horizontally.
weightx | Specifies how to distribute extra horizontal space.
weighty | Specifies how to distribute extra vertical space.
WEST | Put the component on the left side of its display area, centered vertically.

Constructors
Name | Description
GridBagConstraints() | Creates a GridBagConstraint object with all of its fields set to their default value.

Methods
Name | Description
clone() | Creates a copy of this grid bag constraint.


 GridBagConstraints.anchor

GridBagConstraints.anchor

Class Overview | Class Members | This Package | All Packages

Syntax
public int anchor
Description
This field is used when the component is smaller than its display area. It determines where, within the display area, to place the component. Possible values are CENTER, NORTH, NORTHEAST, EAST, SOUTHEAST, SOUTH, SOUTHWEST, WEST, and NORTHWEST. The default value is CENTER.


 GridBagConstraints.BOTH

GridBagConstraints.BOTH

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int BOTH
Description
Resize the component both horizontally and vertically.


 GridBagConstraints.CENTER

GridBagConstraints.CENTER

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int CENTER
Description
Put the component in the center of its display area.


 GridBagConstraints.EAST

GridBagConstraints.EAST

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int EAST
Description
Put the component on the left side of its display area, centered vertically.


 GridBagConstraints.fill

GridBagConstraints.fill

Class Overview | Class Members | This Package | All Packages

Syntax
public int fill
Description
This field is used when the component's display area is larger than the component's requested size. It determines whether to resize the component, and if so, how.

The following values are valid for fill:

  • NONE: Do not resize the component.
  • HORIZONTAL: Make the component wide enough to fill its display area horizontally, but do not change its height.
  • VERTICAL: Make the component tall enough to fill its display area vertically, but do not change its width.
  • BOTH: Make the component fill its display area entirely.

The default value is NONE.


 GridBagConstraints.gridheight

GridBagConstraints.gridheight

Class Overview | Class Members | This Package | All Packages

Syntax
public int gridheight
Description
Specifies the number of cells in a column for the component's display area.

Use REMAINDER to specify that the component be the last one in its column. Use RELATIVE to specify that the component be the next-to-last one in its column.

The default value is 1.

See Also
gridwidth


 GridBagConstraints.gridwidth

GridBagConstraints.gridwidth

Class Overview | Class Members | This Package | All Packages

Syntax
public int gridwidth
Description
Specifies the number of cells in a row for the component's display area.

Use REMAINDER to specify that the component be the last one in its row. Use RELATIVE to specify that the component be the next-to-last one in its row.

The default value is 1.

See Also
gridheight


 GridBagConstraints.gridx

GridBagConstraints.gridx

Class Overview | Class Members | This Package | All Packages

Syntax
public int gridx
Description
Specifies the cell at the left of the component's display area, where the leftmost cell has gridx = 0. The value RELATIVE specifies that the component be placed just to the right of the component that was added to the container just before this component was added.

The default value is RELATIVE.

See Also
gridy


 GridBagConstraints.gridy

GridBagConstraints.gridy

Class Overview | Class Members | This Package | All Packages

Syntax
public int gridy
Description
Specifies the cell at the top of the component's display area, where the topmost cell has gridy = 0. The value RELATIVE specifies that the component be placed just below the component that was added to the container just before this component was added.

The default value is RELATIVE.

See Also
gridx


 GridBagConstraints.HORIZONTAL

GridBagConstraints.HORIZONTAL

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HORIZONTAL
Description
Resize the component horizontally but not vertically.


 GridBagConstraints.insets

GridBagConstraints.insets

Class Overview | Class Members | This Package | All Packages

Syntax
public Insets insets
Description
This field specifies the external padding of the component, the minimum amount of space between the component and the edges of its display area.

The default value is new Insets(0, 0, 0, 0).


 GridBagConstraints.ipadx

GridBagConstraints.ipadx

Class Overview | Class Members | This Package | All Packages

Syntax
public int ipadx
Description
This field specifies the internal padding of the component, how much space to add to the minimum width of the component. The width of the component is at least its minimum width plus (ipadx * 2) pixels.

The default value is 0.

See Also
ipady


 GridBagConstraints.ipady

GridBagConstraints.ipady

Class Overview | Class Members | This Package | All Packages

Syntax
public int ipady
Description
This field specifies the internal padding, that is, how much space to add to the minimum height of the component. The height of the component is at least its minimum height plus (ipady * 2) pixels.

The default value is 0.

See Also
ipadx


 GridBagConstraints.NONE

GridBagConstraints.NONE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int NONE
Description
Do not resize the component.


 GridBagConstraints.NORTH

GridBagConstraints.NORTH

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int NORTH
Description
Put the component at the top of its display area, centered horizontally.


 GridBagConstraints.NORTHEAST

GridBagConstraints.NORTHEAST

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int NORTHEAST
Description
Put the component at the top-right corner of its display area.


 GridBagConstraints.NORTHWEST

GridBagConstraints.NORTHWEST

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int NORTHWEST
Description
Put the component at the top-left corner of its display area.


 GridBagConstraints.RELATIVE

GridBagConstraints.RELATIVE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int RELATIVE
Description
Specify that this component is the next-to-last component in its column or row (gridwidth, gridheight), or that this component be placed next to the previously added component (gridx, gridy).

See Also
gridwidth, gridheight, gridx, gridy


 GridBagConstraints.REMAINDER

GridBagConstraints.REMAINDER

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int REMAINDER
Description
Specify that this component is the last component in its column or row.


 GridBagConstraints.SOUTH

GridBagConstraints.SOUTH

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SOUTH
Description
Put the component at the bottom of its display area, centered horizontally.


 GridBagConstraints.SOUTHEAST

GridBagConstraints.SOUTHEAST

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SOUTHEAST
Description
Put the component at the bottom-right corner of its display area.


 GridBagConstraints.SOUTHWEST

GridBagConstraints.SOUTHWEST

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SOUTHWEST
Description
Put the component at the bottom-left corner of its display area.


 GridBagConstraints.VERTICAL

GridBagConstraints.VERTICAL

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VERTICAL
Description
Resize the component vertically but not horizontally.


 GridBagConstraints.weightx

GridBagConstraints.weightx

Class Overview | Class Members | This Package | All Packages

Syntax
public double weightx
Description
Specifies how to distribute extra horizontal space.

The grid bag layout manager calculates the weight of a column to be the maximum weighty of all the components in a row. If the resulting layout is smaller horizontally than the area it needs to fill, the extra space is distributed to each column in proportion to its weight. A column that has a weight zero receives no extra space.

If all the weights are zero, all the extra space appears between the grids of the cell and the left and right edges.

The default value of this field is 0.

See Also
weighty


 GridBagConstraints.weighty

GridBagConstraints.weighty

Class Overview | Class Members | This Package | All Packages

Syntax
public double weighty
Description
Specifies how to distribute extra vertical space.

The grid bag layout manager calculates the weight of a row to be the maximum weightx of all the components in a row. If the resulting layout is smaller vertically than the area it needs to fill, the extra space is distributed to each row in proportion to its weight. A row that has a weight of zero receives no extra space.

If all the weights are zero, all the extra space appears between the grids of the cell and the top and bottom edges.

The default value of this field is 0.

See Also
weightx


 GridBagConstraints.WEST

GridBagConstraints.WEST

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int WEST
Description
Put the component on the left side of its display area, centered vertically.


 GridBagConstraints.GridBagConstraints

GridBagConstraints.GridBagConstraints

Class Overview | Class Members | This Package | All Packages

Syntax
public GridBagConstraints()
Description
Creates a GridBagConstraint object with all of its fields set to their default value.


 GridBagConstraints.clone

GridBagConstraints.clone

Class Overview | Class Members | This Package | All Packages

Syntax
public Object clone()
Returns
a copy of this grid bag constraint
Description
Creates a copy of this grid bag constraint.

Overrides
clone in class Object


 Class GridBagLayout

Class java.awt.GridBagLayout

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.GridBagLayout

public class GridBagLayout
extends Object
implements LayoutManager2, Serializable

The GridBagLayout class is a flexible layout manager that aligns components vertically and horizontally, without requiring that the components be of the same size. Each GridBagLayout object maintains a dynamic rectangular grid of cells, with each component occupying one or more cells, called its display area.

Each component managed by a grid bag layout is associated with an instance of GridBagConstraints that specifies how the component is laid out within its display area.

How a GridBagLayout object places a set of components depends on the GridBagConstraints object associated with each component, and on the minimum size and the preferred size of the components' containers.

To use a grid bag layout effectively, you must customize one or more of the GridBagConstraints objects that are associated with its components. You customize a GridBagConstraints object by setting one or more of its instance variables:

gridx, gridy
Specifies the cell at the upper left of the component's display area, where the upper-left-most cell has address gridx = 0, gridy = 0. Use GridBagConstraints.RELATIVE (the default value) to specify that the component be just placed just to the right of (for gridx) or just below (for gridy) the component that was added to the container just before this component was added.
gridwidth, gridheight
Specifies the number of cells in a row (for gridwidth) or column (for gridheight) in the component's display area. The default value is 1. Use GridBagConstraints.REMAINDER to specify that the component be the last one in its row (for gridwidth) or column (for gridheight). Use GridBagConstraints.RELATIVE to specify that the component be the next to last one in its row (for gridwidth) or column (for gridheight).
fill
Used when the component's display area is larger than the component's requested size to determine whether (and how) to resize the component. Possible values are GridBagConstraints.NONE (the default), GridBagConstraints.HORIZONTAL (make the component wide enough to fill its display area horizontally, but don't change its height), GridBagConstraints.VERTICAL (make the component tall enough to fill its display area vertically, but don't change its width), and GridBagConstraints.BOTH (make the component fill its display area entirely).
ipadx, ipady
Specifies the component's internal padding within the layout, how much to add to the minimum size of the component. The width of the component will be at least its minimum width plus (ipadx * 2) pixels (since the padding applies to both sides of the component). Similarly, the height of the component will be at least the minimum height plus (ipady * 2) pixels.
insets
Specifies the component's external padding, the minimum amount of space between the component and the edges of its display area.
anchor
Used when the component is smaller than its display area to determine where (within the display area) to place the component. Valid values are GridBagConstraints.CENTER (the default), GridBagConstraints.NORTH, GridBagConstraints.NORTHEAST, GridBagConstraints.EAST, GridBagConstraints.SOUTHEAST, GridBagConstraints.SOUTH, GridBagConstraints.SOUTHWEST, GridBagConstraints.WEST, and GridBagConstraints.NORTHWEST.
weightx, weighty
Used to determine how to distribute space, which is important for specifying resizing behavior. Unless you specify a weight for at least one component in a row (weightx) and column (weighty), all the components clump together in the center of their container. This is because when the weight is zero (the default), the GridBagLayout object puts any extra space between its grid of cells and the edges of the container.

The following figure shows ten components (all buttons) managed by a grid bag layout:

Each of the ten components has the fill field of its associated GridBagConstraints object set to GridBagConstraints.BOTH. In addition, the components have the following non-default constraints:

  • Button1, Button2, Button3: weightx = 1.0
  • Button4: weightx = 1.0, gridwidth = GridBagConstraints.REMAINDER
  • Button5: gridwidth = GridBagConstraints.REMAINDER
  • Button6: gridwidth = GridBagConstraints.RELATIVE
  • Button7: gridwidth = GridBagConstraints.REMAINDER
  • Button8: gridheight = 2, weighty = 1.0
  • Button9, Button 10: gridwidth = GridBagConstraints.REMAINDER

Here is the code that implements the example shown above:

 import java.awt.*;
 import java.util.*;
 import java.applet.Applet;
 public class GridBagEx1 extends Applet {
     protected void makebutton(String name,
                               GridBagLayout gridbag,
                               GridBagConstraints c) {
         Button button = new Button(name);
         gridbag.setConstraints(button, c);
         add(button);
     }
     public void init() {
         GridBagLayout gridbag = new GridBagLayout();
         GridBagConstraints c = new GridBagConstraints();
         setFont(new Font("Helvetica", Font.PLAIN, 14));
         setLayout(gridbag);
         c.fill = GridBagConstraints.BOTH;
         c.weightx = 1.0;
         makebutton("Button1", gridbag, c);
         makebutton("Button2", gridbag, c);
         makebutton("Button3", gridbag, c);
            c.gridwidth = GridBagConstraints.REMAINDER; //end row
         makebutton("Button4", gridbag, c);
         c.weightx = 0.0;		   //reset to the default
         makebutton("Button5", gridbag, c); //another row
        c.gridwidth = GridBagConstraints.RELATIVE; //next-to-last in row
         makebutton("Button6", gridbag, c);
        c.gridwidth = GridBagConstraints.REMAINDER; //end row
         makebutton("Button7", gridbag, c);
        c.gridwidth = 1;	   	   //reset to the default
        c.gridheight = 2;
         c.weighty = 1.0;
         makebutton("Button8", gridbag, c);
         c.weighty = 0.0;		   //reset to the default
        c.gridwidth = GridBagConstraints.REMAINDER; //end row
        c.gridheight = 1;		   //reset to the default
         makebutton("Button9", gridbag, c);
         makebutton("Button10", gridbag, c);
         setSize(300, 100);
     }
     public static void main(String args[]) {
        Frame f = new Frame("GridBag Layout Example");
        GridBagEx1 ex1 = new GridBagEx1();
        ex1.init();
        f.add("Center", ex1);
        f.pack();
        f.setSize(f.getPreferredSize());
        f.show();
     }
 }

See Also:
GridBagConstraints


 GridBagLayout Members

GridBagLayout Members

Class Overview | This Package | All Packages

Fields
Name | Description
columnWeights |
columnWidths |
comptable |
defaultConstraints |
layoutInfo |
MAXGRIDSIZE | The maximum number of grid positions (both horizontally and vertically) that can be laid out by the grid bag layout.
MINSIZE | The smallest grid that can be laid out by the grid bag layout.
PREFERREDSIZE |
rowHeights |
rowWeights |

Constructors
Name | Description
GridBagLayout() | Creates a grid bag layout manager.

Methods
Name | Description
addLayoutComponent(Component, Object) | Adds the specified component to the layout, using the specified constraint object.
addLayoutComponent(String, Component) | Adds the specified component with the specified name to the layout.
AdjustForGravity(GridBagConstraints, Rectangle) |
ArrangeGrid(Container) |
getConstraints(Component) | Gets the constraints for the specified component.
getLayoutAlignmentX(Container) | Returns the alignment along the x axis.
getLayoutAlignmentY(Container) | Returns the alignment along the y axis.
getLayoutDimensions() | Determines column widths and row heights for the layout grid.
GetLayoutInfo(Container, int) | Print the layout constraints.
getLayoutOrigin() | Determines the origin of the layout grid.
getLayoutWeights() | Determines the weights of the layout grid's columns and rows.
GetMinSize(Container, GridBagLayoutInfo) |
invalidateLayout(Container) | Invalidates the layout, indicating that if the layout manager has cached information it should be discarded.
layoutContainer(Container) | Lays out the specified container using this grid bag layout.
location(int, int) | Determines which cell in the layout grid contains the point specified by (x, y).
lookupConstraints(Component) | Retrieves the constraints for the specified component.
maximumLayoutSize(Container) | Returns the maximum dimensions for this layout given the components in the specified target container.
minimumLayoutSize(Container) | Determines the minimum size of the target container using this grid bag layout.
preferredLayoutSize(Container) | Determines the preferred size of the target container using this grid bag layout.
removeLayoutComponent(Component) | Removes the specified component from this layout.
setConstraints(Component, GridBagConstraints) | Sets the constraints for the specified component in this layout.
toString() | Returns a string representation of this grid bag layout's values.


 GridBagLayout.columnWeights

GridBagLayout.columnWeights

Class Overview | Class Members | This Package | All Packages

Syntax
public double columnWeights[]


 GridBagLayout.columnWidths

GridBagLayout.columnWidths

Class Overview | Class Members | This Package | All Packages

Syntax
public int columnWidths[]


 GridBagLayout.comptable

GridBagLayout.comptable

Class Overview | Class Members | This Package | All Packages

Syntax
protected Hashtable comptable


 GridBagLayout.defaultConstraints

GridBagLayout.defaultConstraints

Class Overview | Class Members | This Package | All Packages

Syntax
protected GridBagConstraints defaultConstraints


 GridBagLayout.layoutInfo

GridBagLayout.layoutInfo

Class Overview | Class Members | This Package | All Packages

Syntax
protected GridBagLayoutInfo layoutInfo


 GridBagLayout.MAXGRIDSIZE

GridBagLayout.MAXGRIDSIZE

Class Overview | Class Members | This Package | All Packages

Syntax
protected static final int MAXGRIDSIZE
Description
The maximum number of grid positions (both horizontally and vertically) that can be laid out by the grid bag layout.


 GridBagLayout.MINSIZE

GridBagLayout.MINSIZE

Class Overview | Class Members | This Package | All Packages

Syntax
protected static final int MINSIZE
Description
The smallest grid that can be laid out by the grid bag layout.


 GridBagLayout.PREFERREDSIZE

GridBagLayout.PREFERREDSIZE

Class Overview | Class Members | This Package | All Packages

Syntax
protected static final int PREFERREDSIZE


 GridBagLayout.rowHeights

GridBagLayout.rowHeights

Class Overview | Class Members | This Package | All Packages

Syntax
public int rowHeights[]


 GridBagLayout.rowWeights

GridBagLayout.rowWeights

Class Overview | Class Members | This Package | All Packages

Syntax
public double rowWeights[]


 GridBagLayout.GridBagLayout

GridBagLayout.GridBagLayout

Class Overview | Class Members | This Package | All Packages

Syntax
public GridBagLayout()
Description
Creates a grid bag layout manager.


 GridBagLayout.addLayoutComponent

GridBagLayout.addLayoutComponent

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void addLayoutComponent( String name, Component comp )
Parameters
name
the name of the component.
comp
the component to be added.
Description
Adds the specified component with the specified name to the layout.

Syntax 2
public void addLayoutComponent( Component comp, Object constraints )
Parameters
comp
the component to be added.
constraints
an object that determines how the component is added to the layout.
Description
Adds the specified component to the layout, using the specified constraint object.


 GridBagLayout.AdjustForGravity

GridBagLayout.AdjustForGravity

Class Overview | Class Members | This Package | All Packages

Syntax
protected void AdjustForGravity( GridBagConstraints constraints, Rectangle r )


 GridBagLayout.ArrangeGrid

GridBagLayout.ArrangeGrid

Class Overview | Class Members | This Package | All Packages

Syntax
protected void ArrangeGrid( Container parent )


 GridBagLayout.getConstraints

GridBagLayout.getConstraints

Class Overview | Class Members | This Package | All Packages

Syntax
public GridBagConstraints getConstraints( Component comp )
Parameters
comp
the component to be queried.
Returns
the constraint for the specified component in this grid bag layout; a copy of the actual constraint object is returned.
Description
Gets the constraints for the specified component. A copy of the actual GridBagConstraints object is returned.


 GridBagLayout.getLayoutAlignmentX

GridBagLayout.getLayoutAlignmentX

Class Overview | Class Members | This Package | All Packages

Syntax
public float getLayoutAlignmentX( Container parent )
Description
Returns the alignment along the x axis. This specifies how the component would like to be aligned relative to other components. The value should be a number between 0 and 1 where 0 represents alignment along the origin, 1 is aligned the furthest away from the origin, 0.5 is centered, etc.


 GridBagLayout.getLayoutAlignmentY

GridBagLayout.getLayoutAlignmentY

Class Overview | Class Members | This Package | All Packages

Syntax
public float getLayoutAlignmentY( Container parent )
Description
Returns the alignment along the y axis. This specifies how the component would like to be aligned relative to other components. The value should be a number between 0 and 1 where 0 represents alignment along the origin, 1 is aligned the furthest away from the origin, 0.5 is centered, etc.


 GridBagLayout.getLayoutDimensions

GridBagLayout.getLayoutDimensions

Class Overview | Class Members | This Package | All Packages

Syntax
public int[][] getLayoutDimensions()
Returns
an array of two arrays, containing the widths of the layout columns and the heights of the layout rows.
Description
Determines column widths and row heights for the layout grid.

Most applications do not call this method directly.


 GridBagLayout.GetLayoutInfo

GridBagLayout.GetLayoutInfo

Class Overview | Class Members | This Package | All Packages

Syntax
protected GridBagLayoutInfo GetLayoutInfo( Container parent, int sizeflag )
Description
Print the layout constraints. Useful for debugging.


 GridBagLayout.getLayoutOrigin

GridBagLayout.getLayoutOrigin

Class Overview | Class Members | This Package | All Packages

Syntax
public Point getLayoutOrigin()
Returns
the origin of the cell in the top-left corner of the layout grid.
Description
Determines the origin of the layout grid. Most applications do not call this method directly.


 GridBagLayout.getLayoutWeights

GridBagLayout.getLayoutWeights

Class Overview | Class Members | This Package | All Packages

Syntax
public double[][] getLayoutWeights()
Returns
an array of two arrays, representing the horizontal weights of the layout columns and the vertical weights of the layout rows.
Description
Determines the weights of the layout grid's columns and rows. Weights are used to calculate how much a given column or row stretches beyond its preferred size, if the layout has extra room to fill.

Most applications do not call this method directly.


 GridBagLayout.GetMinSize

GridBagLayout.GetMinSize

Class Overview | Class Members | This Package | All Packages

Syntax
protected Dimension GetMinSize( Container parent, GridBagLayoutInfo info )


 GridBagLayout.invalidateLayout

GridBagLayout.invalidateLayout

Class Overview | Class Members | This Package | All Packages

Syntax
public void invalidateLayout( Container target )
Description
Invalidates the layout, indicating that if the layout manager has cached information it should be discarded.


 GridBagLayout.layoutContainer

GridBagLayout.layoutContainer

Class Overview | Class Members | This Package | All Packages

Syntax
public void layoutContainer( Container parent )
Parameters
parent
the container in which to do the layout.
Description
Lays out the specified container using this grid bag layout. This method reshapes components in the specified container in order to satisfy the contraints of this GridBagLayout object.

Most applications do not call this method directly.

See Also
Container, doLayout


 GridBagLayout.location

GridBagLayout.location

Class Overview | Class Members | This Package | All Packages

Syntax
public Point location( int x, int y )
Parameters
x
the x coordinate of a point.
y
the y coordinate of a point.
Returns
an ordered pair of indexes that indicate which cell in the layout grid contains the point (x, y).
Description
Determines which cell in the layout grid contains the point specified by (x, y). Each cell is identified by its column index (ranging from 0 to the number of columns minus 1) and its row index (ranging from 0 to the number of rows minus 1).

If the (x, y) point lies outside the grid, the following rules are used. The column index is returned as zero if x lies to the left of the layout, and as the number of columns if x lies to the right of the layout. The row index is returned as zero if y lies above the layout, and as the number of rows if y lies below the layout.


 GridBagLayout.lookupConstraints

GridBagLayout.lookupConstraints

Class Overview | Class Members | This Package | All Packages

Syntax
protected GridBagConstraints lookupConstraints( Component comp )
Parameters
comp
the component to be queried
Returns
the contraints for the specified component.
Description
Retrieves the constraints for the specified component. The return value is not a copy, but is the actual GridBagConstraints object used by the layout mechanism.


 GridBagLayout.maximumLayoutSize

GridBagLayout.maximumLayoutSize

Class Overview | Class Members | This Package | All Packages

Syntax
public Dimension maximumLayoutSize( Container target )
Parameters
target
the component which needs to be laid out
Description
Returns the maximum dimensions for this layout given the components in the specified target container.

See Also
Container, minimumLayoutSize, preferredLayoutSize


 GridBagLayout.minimumLayoutSize

GridBagLayout.minimumLayoutSize

Class Overview | Class Members | This Package | All Packages

Syntax
public Dimension minimumLayoutSize( Container parent )
Parameters
target
the container in which to do the layout.
Description
Determines the minimum size of the target container using this grid bag layout.

Most applications do not call this method directly.

See Also
doLayout


 GridBagLayout.preferredLayoutSize

GridBagLayout.preferredLayoutSize

Class Overview | Class Members | This Package | All Packages

Syntax
public Dimension preferredLayoutSize( Container parent )
Parameters
target
the container in which to do the layout.
Description
Determines the preferred size of the target container using this grid bag layout.

Most applications do not call this method directly.

See Also
getPreferredSize


 GridBagLayout.removeLayoutComponent

GridBagLayout.removeLayoutComponent

Class Overview | Class Members | This Package | All Packages

Syntax
public void removeLayoutComponent( Component comp )
Parameters
comp
the component to be removed.
Description
Removes the specified component from this layout.

Most applications do not call this method directly.

See Also
remove, removeAll


 GridBagLayout.setConstraints

GridBagLayout.setConstraints

Class Overview | Class Members | This Package | All Packages

Syntax
public void setConstraints( Component comp, GridBagConstraints constraints )
Parameters
comp
the component to be modified.
constraints
the constraints to be applied.
Description
Sets the constraints for the specified component in this layout.


 GridBagLayout.toString

GridBagLayout.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string representation of this grid bag layout.
Description
Returns a string representation of this grid bag layout's values.

Overrides
toString in class Object


 Class GridLayout

Class java.awt.GridLayout

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.GridLayout

public class GridLayout
extends Object
implements LayoutManager, Serializable

The GridLayout class is a layout manager that lays out a container's components in a rectangular grid.

The container is divided into equal-sized rectangles, and one component is placed in each rectangle.

For example, the following is an applet that lays out six buttons into three rows and two columns:

 import java.awt.*;
 import java.applet.Applet;
 public class ButtonGrid extends Applet {
     public void init() {
         setLayout(new GridLayout(3,2));
         add(new Button("1"));
         add(new Button("2"));
         add(new Button("3"));
         add(new Button("4"));
         add(new Button("5"));
         add(new Button("6"));
     }
 }

It produces the following output:


 GridLayout Members

GridLayout Members

Class Overview | This Package | All Packages

Constructors
Name | Description
GridLayout() | Creates a grid layout with a default of one column per component, in a single row.
GridLayout(int, int) | Creates a grid layout with the specified number of rows and columns.
GridLayout(int, int, int, int) | Creates a grid layout with the specified number of rows and columns.

Methods
Name | Description
addLayoutComponent(String, Component) | Adds the specified component with the specified name to the layout.
getColumns() | Gets the number of columns in this layout.
getHgap() | Gets the horizontal gap between components.
getRows() | Gets the number of rows in this layout.
getVgap() | Gets the vertical gap between components.
layoutContainer(Container) | Lays out the specified container using this layout.
minimumLayoutSize(Container) | Determines the minimum size of the container argument using this grid layout.
preferredLayoutSize(Container) | Determines the preferred size of the container argument using this grid layout.
removeLayoutComponent(Component) | Removes the specified component from the layout.
setColumns(int) | Sets the number of columns in this layout to the specified value.
setHgap(int) | Sets the horizontal gap between components to the specified value.
setRows(int) | Sets the number of rows in this layout to the specified value.
setVgap(int) | Sets the vertical gap between components to the specified value.
toString() | Returns the string representation of this grid layout's values.


 GridLayout.GridLayout

GridLayout.GridLayout

Class Overview | Class Members | This Package | All Packages

Syntax 1
public GridLayout()
Description
Creates a grid layout with a default of one column per component, in a single row.

Syntax 2
public GridLayout( int rows, int cols )
Parameters
rows
the rows, with the value zero meaning any number of rows.
cols
the columns, with the value zero meaning any number of columns.
Description
Creates a grid layout with the specified number of rows and columns. All components in the layout are given equal size.

One, but not both, of rows and cols can be zero, which means that any number of objects can be placed in a row or in a column.

Syntax 3
public GridLayout( int rows, int cols, int hgap, int vgap )
Parameters
rows
the rows, with the value zero meaning any number of rows.
cols
the columns, with the value zero meaning any number of columns.
hgap
the horizontal gap.
vgap
the vertical gap.
Description
Creates a grid layout with the specified number of rows and columns. All components in the layout are given equal size.

In addition, the horizontal and vertical gaps are set to the specified values. Horizontal gaps are placed at the left and right edges, and between each of the columns. Vertical gaps are placed at the top and bottom edges, and between each of the rows.

One, but not both, of rows and cols can be zero, which means that any number of objects can be placed in a row or in a column.

Exceptions
IllegalArgumentException if the of rows or cols is invalid.


 GridLayout.addLayoutComponent

GridLayout.addLayoutComponent

Class Overview | Class Members | This Package | All Packages

Syntax
public void addLayoutComponent( String name, Component comp )
Parameters
name
the name of the component.
comp
the component to be added.
Description
Adds the specified component with the specified name to the layout.


 GridLayout.getColumns

GridLayout.getColumns

Class Overview | Class Members | This Package | All Packages

Syntax
public int getColumns()
Returns
the number of columns in this layout.
Description
Gets the number of columns in this layout.


 GridLayout.getHgap

GridLayout.getHgap

Class Overview | Class Members | This Package | All Packages

Syntax
public int getHgap()
Returns
the horizontal gap between components.
Description
Gets the horizontal gap between components.


 GridLayout.getRows

GridLayout.getRows

Class Overview | Class Members | This Package | All Packages

Syntax
public int getRows()
Returns
the number of rows in this layout.
Description
Gets the number of rows in this layout.


 GridLayout.getVgap

GridLayout.getVgap

Class Overview | Class Members | This Package | All Packages

Syntax
public int getVgap()
Returns
the vertical gap between components.
Description
Gets the vertical gap between components.


 GridLayout.layoutContainer

GridLayout.layoutContainer

Class Overview | Class Members | This Package | All Packages

Syntax
public void layoutContainer( Container parent )
Parameters
target
the container in which to do the layout.
Description
Lays out the specified container using this layout.

This method reshapes the components in the specified target container in order to satisfy the constraints of the GridLayout object.

The grid layout manager determines the size of individual components by dividing the free space in the container into equal-sized portions according to the number of rows and columns in the layout. The container's free space equals the container's size minus any insets and any specified horizontal or vertical gap. All components in a grid layout are given the same size.

See Also
Container, doLayout


 GridLayout.minimumLayoutSize

GridLayout.minimumLayoutSize

Class Overview | Class Members | This Package | All Packages

Syntax
public Dimension minimumLayoutSize( Container parent )
Parameters
target
the container in which to do the layout.
Returns
the minimum dimensions needed to lay out the subcomponents of the specified container.
Description
Determines the minimum size of the container argument using this grid layout.

The minimum width of a grid layout is the largest minimum width of any of the widths in the container times the number of columns, plus the horizontal padding times the number of columns plus one, plus the left and right insets of the target container.

The minimum height of a grid layout is the largest minimum height of any of the widths in the container times the number of rows, plus the vertical padding times the number of rows plus one, plus the top and left insets of the target container.

See Also
preferredLayoutSize, doLayout


 GridLayout.preferredLayoutSize

GridLayout.preferredLayoutSize

Class Overview | Class Members | This Package | All Packages

Syntax
public Dimension preferredLayoutSize( Container parent )
Parameters
target
the container in which to do the layout.
Returns
the preferred dimensions to lay out the subcomponents of the specified container.
Description
Determines the preferred size of the container argument using this grid layout.

The preferred width of a grid layout is the largest preferred width of any of the widths in the container times the number of columns, plus the horizontal padding times the number of columns plus one, plus the left and right insets of the target container.

The preferred height of a grid layout is the largest preferred height of any of the widths in the container times the number of rows, plus the vertical padding times the number of rows plus one, plus the top and left insets of the target container.

See Also
minimumLayoutSize, getPreferredSize


 GridLayout.removeLayoutComponent

GridLayout.removeLayoutComponent

Class Overview | Class Members | This Package | All Packages

Syntax
public void removeLayoutComponent( Component comp )
Parameters
comp
the component to be removed.
Description
Removes the specified component from the layout.


 GridLayout.setColumns

GridLayout.setColumns

Class Overview | Class Members | This Package | All Packages

Syntax
public void setColumns( int cols )
Parameters
cols
the number of columns in this layout.
Description
Sets the number of columns in this layout to the specified value.

Exceptions
IllegalArgumentException if the value of both rows and cols is set to zero.


 GridLayout.setHgap

GridLayout.setHgap

Class Overview | Class Members | This Package | All Packages

Syntax
public void setHgap( int hgap )
Parameters
hgap
the horizontal gap between components.
Description
Sets the horizontal gap between components to the specified value.


 GridLayout.setRows

GridLayout.setRows

Class Overview | Class Members | This Package | All Packages

Syntax
public void setRows( int rows )
Parameters
rows
the number of rows in this layout.
Description
Sets the number of rows in this layout to the specified value.

Exceptions
IllegalArgumentException if the value of both rows and cols is set to zero.


 GridLayout.setVgap

GridLayout.setVgap

Class Overview | Class Members | This Package | All Packages

Syntax
public void setVgap( int vgap )
Parameters
vgap
the vertical gap between components.
Description
Sets the vertical gap between components to the specified value.


 GridLayout.toString

GridLayout.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string representation of this grid layout.
Description
Returns the string representation of this grid layout's values.

Overrides
toString in class Object


 Class IllegalComponentStateException

Class java.awt.IllegalComponentStateException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.lang.RuntimeException
                           |
                           +----java.lang.IllegalStateException
                                   |
                                   +----java.awt.IllegalComponentStateException

public class IllegalComponentStateException
extends IllegalStateException

Signals that an AWT component is not in an appropriate state for the requested operation.


 IllegalComponentStateException Members

IllegalComponentStateException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
IllegalComponentStateException() | Constructs an IllegalComponentStateException with no detail message.
IllegalComponentStateException(String) | Constructs an IllegalComponentStateException with the specified detail message.


 IllegalComponentStateException.IllegalComponentStateException

IllegalComponentStateException.IllegalComponentStateException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public IllegalComponentStateException()
Description
Constructs an IllegalComponentStateException with no detail message. A detail message is a String that describes this particular exception.

Syntax 2
public IllegalComponentStateException( String s )
Parameters
s
the String that contains a detailed message
Description
Constructs an IllegalComponentStateException with the specified detail message. A detail message is a String that describes this particular exception.


 Class Image

Class java.awt.Image

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.Image

public abstract class Image
extends Object

The abstract class Image is the superclass of all classes that represent graphical images. The image must be obtained in a platform-specific manner.


 Image Members

Image Members

Class Overview | This Package | All Packages

Fields
Name | Description
SCALE_AREA_AVERAGING | Use the Area Averaging image scaling algorithm.
SCALE_DEFAULT | Use the default image-scaling algorithm.
SCALE_FAST | Choose an image-scaling algorithm that gives higher priority to scaling speed than smoothness of the scaled image.
SCALE_REPLICATE | Use the image scaling algorithm embodied in the ReplicateScaleFilter class.
SCALE_SMOOTH | Choose an image-scaling algorithm that gives higher priority to image smoothness than scaling speed.
UndefinedProperty | The UndefinedProperty object should be returned whenever a property which was not defined for a particular image is fetched.

Constructors
Name | Description
Image() |

Methods
Name | Description
flush() | Flushes all resources being used by this Image object.
getGraphics() | Creates a graphics context for drawing to an off-screen image.
getHeight(ImageObserver) | Determines the height of the image.
getProperty(String, ImageObserver) | Gets a property of this image by name.
getScaledInstance(int, int, int) | Creates a scaled version of this image.
getSource() | Gets the object that produces the pixels for the image.
getWidth(ImageObserver) | Determines the width of the image.


 Image.SCALE_AREA_AVERAGING

Image.SCALE_AREA_AVERAGING

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SCALE_AREA_AVERAGING
Description
Use the Area Averaging image scaling algorithm. The image object is free to substitute a different filter that performs the same algorithm yet integrates more efficiently into the image infrastructure supplied by the toolkit.

See Also
AreaAveragingScaleFilter


 Image.SCALE_DEFAULT

Image.SCALE_DEFAULT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SCALE_DEFAULT
Description
Use the default image-scaling algorithm.


 Image.SCALE_FAST

Image.SCALE_FAST

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SCALE_FAST
Description
Choose an image-scaling algorithm that gives higher priority to scaling speed than smoothness of the scaled image.


 Image.SCALE_REPLICATE

Image.SCALE_REPLICATE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SCALE_REPLICATE
Description
Use the image scaling algorithm embodied in the ReplicateScaleFilter class. The Image object is free to substitute a different filter that performs the same algorithm yet integrates more efficiently into the imaging infrastructure supplied by the toolkit.

See Also
ReplicateScaleFilter


 Image.SCALE_SMOOTH

Image.SCALE_SMOOTH

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SCALE_SMOOTH
Description
Choose an image-scaling algorithm that gives higher priority to image smoothness than scaling speed.


 Image.UndefinedProperty

Image.UndefinedProperty

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Object UndefinedProperty
Description
The UndefinedProperty object should be returned whenever a property which was not defined for a particular image is fetched.


 Image.Image

Image.Image

Class Overview | Class Members | This Package | All Packages

Syntax
public Image()


 Image.flush

Image.flush

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void flush()
Description
Flushes all resources being used by this Image object. This includes any pixel data that is being cached for rendering to the screen as well as any system resources that are being used to store data or pixels for the image. The image is reset to a state similar to when it was first created so that if it is again rendered, the image data will have to be recreated or fetched again from its source.


 Image.getGraphics

Image.getGraphics

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract Graphics getGraphics()
Returns
a graphics context to draw to the off-screen image.
Description
Creates a graphics context for drawing to an off-screen image. This method can only be called for off-screen images.

See Also
Graphics, createImage


 Image.getHeight

Image.getHeight

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract int getHeight( ImageObserver observer )
Parameters
observer
an object waiting for the image to be loaded.
Returns
the height of this image, or -1 if the height is not yet known.
Description
Determines the height of the image. If the height is not yet known, this method returns -1 and the specified ImageObserver object is notified later.

See Also
getWidth, ImageObserver


 Image.getProperty

Image.getProperty

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract Object getProperty( String name, ImageObserver observer )
Parameters
name
a property name.
observer
an object waiting for this image to be loaded.
Returns
the value of the named property.
Description
Gets a property of this image by name.

Individual property names are defined by the various image formats. If a property is not defined for a particular image, this method returns the UndefinedProperty object.

If the properties for this image are not yet known, this method returns null, and the ImageObserver object is notified later.

The property name "comment" should be used to store an optional comment which can be presented to the application as a description of the image, its source, or its author.

See Also
ImageObserver, UndefinedProperty


 Image.getScaledInstance

Image.getScaledInstance

Class Overview | Class Members | This Package | All Packages

Syntax
public Image getScaledInstance( int width, int height, int hints )
Parameters
width
the width to which to scale the image.
height
the height to which to scale the image.
hints
flags to indicate the type of algorithm to use for image resampling.
Returns
a scaled version of the image.
Description
Creates a scaled version of this image. A new Image object is returned which will render the image at the specified width and height by default. The new Image object may be loaded asynchronously even if the original source image has already been loaded completely. If either the width or height is a negative number then a value is substituted to maintain the aspect ratio of the original image dimensions.

See Also
SCALE_DEFAULT, SCALE_FAST, SCALE_SMOOTH, SCALE_REPLICATE, SCALE_AREA_AVERAGING


 Image.getSource

Image.getSource

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract ImageProducer getSource()
Returns
the image producer that produces the pixels for this image.
Description
Gets the object that produces the pixels for the image. This method is called by the image filtering classes and by methods that perform image conversion and scaling.

See Also
ImageProducer


 Image.getWidth

Image.getWidth

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract int getWidth( ImageObserver observer )
Parameters
observer
an object waiting for the image to be loaded.
Returns
the width of this image, or -1 if the width is not yet known.
Description
Determines the width of the image. If the width is not yet known, this method returns -1 and the specified ImageObserver object is notified later.

See Also
getHeight, ImageObserver


 Class Insets

Class java.awt.Insets

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.Insets

public class Insets
extends Object
implements Cloneable, Serializable

An Insets object is a representation of the borders of a container. It specifies the space that a container must leave at each of its edges. The space can be a border, a blank space, or a title.

See Also:
LayoutManager, Container


 Insets Members

Insets Members

Class Overview | This Package | All Packages

Fields
Name | Description
bottom | The inset from the bottom.
left | The inset from the left.
right | The inset from the right.
top | The inset from the top.

Constructors
Name | Description
Insets(int, int, int, int) | Creates and initializes a new Insets object with the specified top, left, bottom, and right insets.

Methods
Name | Description
clone() | Create a copy of this object.
equals(Object) | Checks whether two insets objects are equal.
toString() | Returns a String object representing this Insets object's values.


 Insets.bottom

Insets.bottom

Class Overview | Class Members | This Package | All Packages

Syntax
public int bottom
Description
The inset from the bottom.


 Insets.left

Insets.left

Class Overview | Class Members | This Package | All Packages

Syntax
public int left
Description
The inset from the left.


 Insets.right

Insets.right

Class Overview | Class Members | This Package | All Packages

Syntax
public int right
Description
The inset from the right.


 Insets.top

Insets.top

Class Overview | Class Members | This Package | All Packages

Syntax
public int top
Description
The inset from the top.


 Insets.Insets

Insets.Insets

Class Overview | Class Members | This Package | All Packages

Syntax
public Insets( int top, int left, int bottom, int right )
Parameters
top
the inset from the top.
left
the inset from the left.
bottom
the inset from the bottom.
right
the inset from the right.
Description
Creates and initializes a new Insets object with the specified top, left, bottom, and right insets.


 Insets.clone

Insets.clone

Class Overview | Class Members | This Package | All Packages

Syntax
public Object clone()
Returns
a copy of this Insets object.
Description
Create a copy of this object.

Overrides
clone in class Object


 Insets.equals

Insets.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Returns
true if the two insets are equal; otherwise false.
Description
Checks whether two insets objects are equal. Two instances of Insets are equal if the four integer values of the fields top, left, bottom, and right are all equal.

Overrides
equals in class Object


 Insets.toString

Insets.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string representation of this Insets object, including the values of its member fields.
Description
Returns a String object representing this Insets object's values.

Overrides
toString in class Object


 Interface ItemSelectable

Interface java.awt.ItemSelectable

Interface Members | This Package | All Packages

public interface ItemSelectable

The interface for objects which contain a set of items for which zero or more can be selected.


 ItemSelectable Members

ItemSelectable Members

Interface Overview | This Package | All Packages

Methods
Name | Description
addItemListener(ItemListener) | Add a listener to recieve item events when the state of an item changes.
getSelectedObjects() | Returns the selected items or null if no items are selected.
removeItemListener(ItemListener) | Removes an item listener.


 ItemSelectable.addItemListener

ItemSelectable.addItemListener

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void addItemListener( ItemListener l )
Parameters
l
the listener to recieve events
Description
Add a listener to recieve item events when the state of an item changes.

See Also
ItemEvent


 ItemSelectable.getSelectedObjects

ItemSelectable.getSelectedObjects

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Object[] getSelectedObjects()
Description
Returns the selected items or null if no items are selected.


 ItemSelectable.removeItemListener

ItemSelectable.removeItemListener

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void removeItemListener( ItemListener l )
Parameters
l
the listener being removed
Description
Removes an item listener.

See Also
ItemEvent


 Class Label

Class java.awt.Label

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.Component
           |
           +----java.awt.Label

public class Label
extends Component

A Label object is a component for placing text in a container. A label displays a single line of read-only text. The text can be changed by the application, but a user cannot edit it directly.

For example, the code . . .

 setLayout(new FlowLayout(FlowLayout.CENTER, 10, 10));
 add(new Label("Hi There!"));
 add(new Label("Another Label"));

produces the following label:


 Label Members

Label Members

Class Overview | This Package | All Packages

Fields
Name | Description
CENTER | Indicates that the label should be centered.
LEFT | Indicates that the label should be left justified.
RIGHT | Indicates that the label should be right justified.

Constructors
Name | Description
Label() | Constructs an empty label.
Label(String) | Constructs a new label with the specified string of text, left justified.
Label(String, int) | Constructs a new label that presents the specified string of text with the specified alignment.

Methods
Name | Description
addNotify() | Creates the peer for this label.
getAlignment() | Gets the current alignment of this label.
getText() | Gets the text of this label.
paramString() | Returns the parameter string representing the state of this label.
setAlignment(int) | Sets the alignment for this label to the specified alignment.
setText(String) | Sets the text for this label to the specified text.


 Label.CENTER

Label.CENTER

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int CENTER
Description
Indicates that the label should be centered.


 Label.LEFT

Label.LEFT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int LEFT
Description
Indicates that the label should be left justified.


 Label.RIGHT

Label.RIGHT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int RIGHT
Description
Indicates that the label should be right justified.


 Label.Label

Label.Label

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Label()
Description
Constructs an empty label.

Syntax 2
public Label( String text )
Parameters
text
the string that the label presents.
Description
Constructs a new label with the specified string of text, left justified.

Syntax 3
public Label( String text, int alignment )
Parameters
text
the string that the label presents.
alignment
the alignment value.
Description
Constructs a new label that presents the specified string of text with the specified alignment.

Possible values for alignment are Label.LEFT, Label.RIGHT, and Label.CENTER.


 Label.addNotify

Label.addNotify

Class Overview | Class Members | This Package | All Packages

Syntax
public void addNotify()
Description
Creates the peer for this label. The peer allows us to modify the appearance of the label without changing its functionality.

Overrides
addNotify in class Component


 Label.getAlignment

Label.getAlignment

Class Overview | Class Members | This Package | All Packages

Syntax
public int getAlignment()
Description
Gets the current alignment of this label. Possible values are Label.LEFT, Label.RIGHT, and Label.CENTER.

See Also
setAlignment


 Label.getText

Label.getText

Class Overview | Class Members | This Package | All Packages

Syntax
public String getText()
Returns
the text of this label.
Description
Gets the text of this label.

See Also
setText


 Label.paramString

Label.paramString

Class Overview | Class Members | This Package | All Packages

Syntax
protected String paramString()
Returns
the parameter string of this label.
Description
Returns the parameter string representing the state of this label. This string is useful for debugging.

Overrides
paramString in class Component


 Label.setAlignment

Label.setAlignment

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setAlignment( int alignment )
Parameters
alignment
the alignment to be set.
Description
Sets the alignment for this label to the specified alignment. Possible values are Label.LEFT, Label.RIGHT, and Label.CENTER.

Exceptions
IllegalArgumentException if an improper value for alignment is given.
See Also
getAlignment


 Label.setText

Label.setText

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setText( String text )
Parameters
text
the text that this label presents.
Description
Sets the text for this label to the specified text.

See Also
getText


 Interface LayoutManager

Interface java.awt.LayoutManager

Interface Members | This Package | All Packages

public interface LayoutManager

Defines the interface for classes that know how to layout Containers.

See Also:
Container


 LayoutManager Members

LayoutManager Members

Interface Overview | This Package | All Packages

Methods
Name | Description
addLayoutComponent(String, Component) | Adds the specified component with the specified name to the layout.
layoutContainer(Container) | Lays out the container in the specified panel.
minimumLayoutSize(Container) | Calculates the minimum size dimensions for the specified panel given the components in the specified parent container.
preferredLayoutSize(Container) | Calculates the preferred size dimensions for the specified panel given the components in the specified parent container.
removeLayoutComponent(Component) | Removes the specified component from the layout.


 LayoutManager.addLayoutComponent

LayoutManager.addLayoutComponent

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void addLayoutComponent( String name, Component comp )
Parameters
name
the component name
comp
the component to be added
Description
Adds the specified component with the specified name to the layout.


 LayoutManager.layoutContainer

LayoutManager.layoutContainer

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void layoutContainer( Container parent )
Parameters
parent
the component which needs to be laid out
Description
Lays out the container in the specified panel.


 LayoutManager.minimumLayoutSize

LayoutManager.minimumLayoutSize

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Dimension minimumLayoutSize( Container parent )
Parameters
parent
the component to be laid out
Description
Calculates the minimum size dimensions for the specified panel given the components in the specified parent container.

See Also
preferredLayoutSize


 LayoutManager.preferredLayoutSize

LayoutManager.preferredLayoutSize

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Dimension preferredLayoutSize( Container parent )
Parameters
parent
the component to be laid out
Description
Calculates the preferred size dimensions for the specified panel given the components in the specified parent container.

See Also
minimumLayoutSize


 LayoutManager.removeLayoutComponent

LayoutManager.removeLayoutComponent

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void removeLayoutComponent( Component comp )
Parameters
comp
the component ot be removed
Description
Removes the specified component from the layout.


 Interface LayoutManager2

Interface java.awt.LayoutManager2

Interface Members | This Package | All Packages

public interface LayoutManager2
extends LayoutManager

Defines an interface for classes that know how to layout Containers based on a layout constraints object. This interface extends the LayoutManager interface to deal with layouts explicitly in terms of constraint objects that specify how and where components should be added to the layout.

This minimal extension to LayoutManager is intended for tool providers who wish to the creation of constraint-based layouts. It does not yet provide full, general support for custom constraint-based layout managers.

See Also:
LayoutManager, Container


 LayoutManager2 Members

LayoutManager2 Members

Interface Overview | This Package | All Packages

Methods
Name | Description
addLayoutComponent(Component, Object) | Adds the specified component to the layout, using the specified constraint object.
getLayoutAlignmentX(Container) | Returns the alignment along the x axis.
getLayoutAlignmentY(Container) | Returns the alignment along the y axis.
invalidateLayout(Container) | Invalidates the layout, indicating that if the layout manager has cached information it should be discarded.
maximumLayoutSize(Container) | Returns the maximum size of this component.


 LayoutManager2.addLayoutComponent

LayoutManager2.addLayoutComponent

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void addLayoutComponent( Component comp, Object constraints )
Parameters
comp
the component to be added
constraints
where/how the component is added to the layout.
Description
Adds the specified component to the layout, using the specified constraint object.


 LayoutManager2.getLayoutAlignmentX

LayoutManager2.getLayoutAlignmentX

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract float getLayoutAlignmentX( Container target )
Description
Returns the alignment along the x axis. This specifies how the component would like to be aligned relative to other components. The value should be a number between 0 and 1 where 0 represents alignment along the origin, 1 is aligned the furthest away from the origin, 0.5 is centered, etc.


 LayoutManager2.getLayoutAlignmentY

LayoutManager2.getLayoutAlignmentY

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract float getLayoutAlignmentY( Container target )
Description
Returns the alignment along the y axis. This specifies how the component would like to be aligned relative to other components. The value should be a number between 0 and 1 where 0 represents alignment along the origin, 1 is aligned the furthest away from the origin, 0.5 is centered, etc.


 LayoutManager2.invalidateLayout

LayoutManager2.invalidateLayout

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void invalidateLayout( Container target )
Description
Invalidates the layout, indicating that if the layout manager has cached information it should be discarded.


 LayoutManager2.maximumLayoutSize

LayoutManager2.maximumLayoutSize

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Dimension maximumLayoutSize( Container target )
Description
Returns the maximum size of this component.

See Also
getMinimumSize, getPreferredSize, LayoutManager


 Class List

Class java.awt.List

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.Component
           |
           +----java.awt.List

public class List
extends Component
implements ItemSelectable

The List component presents the user with a scrolling list of text items. The list can be set up so that the user can choose either one item or multiple items.

For example, the code . . .

 List lst = new List(4, false);
 lst.add("Mercury");
 lst.add("Venus");
 lst.add("Earth");
 lst.add("JavaSoft");
 lst.add("Mars");
 lst.add("Jupiter");
 lst.add("Saturn");
 lst.add("Uranus");
 lst.add("Neptune");
 lst.add("Pluto");
 cnt.add(lst);

where cnt is a container, produces the following scrolling list:

Clicking on an item that isn't selected selects it. Clicking on an item that is already selected deselects it. In the preceding example, only one item from the scrolling list can be selected at a time, since the second argument when creating the new scrolling list is false. Selecting an item causes any other selected item to be automatically deselected.

Beginning with Java 1.1, the Abstract Window Toolkit sends the List object all mouse, keyboard, and focus events that occur over it. (The old AWT event model is being maintained only for backwards compatibility, and its use is discouraged.)

When an item is selected or deselected, AWT sends an instance of ItemEvent to the list. When the user double-clicks on an item in a scrolling list, AWT sends an instance of ActionEvent to the list following the item event. AWT also generates an action event when the user presses the return key while an item in the list is selected.

If an application wants to perform some action based on an item in this list being selected or activated, it should implement ItemListener or ActionListener as appropriate and register the new listener to receive events from this list.

For multiple-selection scrolling lists, it is considered a better user interface to use an external gesture (such as clicking on a button) to trigger the action.

See Also:
ItemEvent, ItemListener, ActionEvent, ActionListener


 List Members

List Members

Class Overview | This Package | All Packages

Constructors
Name | Description
List() | Creates a new scrolling list.
List(int) | Creates a new scrolling list initialized with the specified number of visible lines.
List(int, boolean) | Creates a new scrolling list initialized to display the specified number of rows.

Methods
Name | Description
add(String) | Adds the specified item to the end of scrolling list.
add(String, int) | Adds the specified item to the end of the scrolling list.
addActionListener(ActionListener) | Adds the specified action listener to receive action events from this list.
addItem(String) | Deprecated.
addItem(String, int) | Deprecated.
addItemListener(ItemListener) | Adds the specified item listener to receive item events from this list.
addNotify() | Creates the peer for the list.
allowsMultipleSelections() | Deprecated.
clear() | Deprecated.
countItems() | Deprecated.
delItem(int) | Deprecated.
delItems(int, int) | Deprecated.
deselect(int) | Deselects the item at the specified index.
getItem(int) | Gets the item associated with the specified index.
getItemCount() | Gets the number of items in the list.
getItems() | Gets the items in the list.
getMinimumSize() | Determines the minimum size of this scrolling list.
getMinimumSize(int) | Gets the minumum dimensions for a list with the specified number of rows.
getPreferredSize() | Gets the preferred size of this scrolling list.
getPreferredSize(int) | Gets the preferred dimensions for a list with the specified number of rows.
getRows() | Get the number of visible lines in this list.
getSelectedIndex() | Gets the index of the selected item on the list,
getSelectedIndexes() | Gets the selected indexes on the list.
getSelectedItem() | Get the selected item on this scrolling list.
getSelectedItems() | Get the selected items on this scrolling list.
getSelectedObjects() | Returns the selected items on the list in an array of Objects.
getVisibleIndex() | Gets the index of the item that was last made visible by the method makeVisible.
isIndexSelected(int) | Determines if the specified item in this scrolling list is selected.
isMultipleMode() | Determines whether this list allows multiple selections.
isSelected(int) | Deprecated.
makeVisible(int) | Makes the item at the specified index visible.
minimumSize() | Deprecated.
minimumSize(int) | Deprecated.
paramString() | Returns the parameter string representing the state of this scrolling list.
preferredSize() | Deprecated.
preferredSize(int) | Deprecated.
processActionEvent(ActionEvent) | Processes action events occurring on this component by dispatching them to any registered ActionListener objects.
processEvent(AWTEvent) | Processes events on this scrolling list.
processItemEvent(ItemEvent) | Processes item events occurring on this list by dispatching them to any registered ItemListener objects.
remove(int) | Remove the item at the specified position from this scrolling list.
remove(String) | Removes the first occurrence of an item from the list.
removeActionListener(ActionListener) | Removes the specified action listener so that it no longer receives action events from this list.
removeAll() | Removes all items from this list.
removeItemListener(ItemListener) | Removes the specified item listener so that it no longer receives item events from this list.
removeNotify() | Removes the peer for this list.
replaceItem(String, int) | Replaces the item at the specified index in the scrolling list with the new string.
select(int) | Selects the item at the specified index in the scrolling list.
setMultipleMode(boolean) | Sets the flag that determines whether this list allows multiple selections.
setMultipleSelections(boolean) | Deprecated.


 List.List

List.List

Class Overview | Class Members | This Package | All Packages

Syntax 1
public List()
Description
Creates a new scrolling list. Initially there are no visible lines, and only one item can be selected from the list.

Syntax 2
public List( int rows )
Parameters
rows
the number of items to show.
Description
Creates a new scrolling list initialized with the specified number of visible lines. By default, multiple selections are not allowed.

Syntax 3
public List( int rows, boolean multipleMode )
Parameters
rows
the number of items to show.
multipleMode
if true, then multiple selections are allowed; otherwise, only one item can be selected at a time.
Description
Creates a new scrolling list initialized to display the specified number of rows. If the value of multipleMode is true, then the user can select multiple items from the list. If it is false, only one item at a time can be selected.


 List.add

List.add

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void add( String item )
Parameters
item
the item to be added.
Description
Adds the specified item to the end of scrolling list.

Syntax 2
public synchronized void add( String item, int index )
Parameters
item
the item to be added.
index
the position at which to add the item.
Description
Adds the specified item to the end of the scrolling list. The index is zero-based. If value of the index is -1 then the item is added to the end. If value of the index is greater than the number of items in the list, the item is added at the end.


 List.addActionListener

List.addActionListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void addActionListener( ActionListener l )
Parameters
l
the action listener.
Description
Adds the specified action listener to receive action events from this list. Action events occur when a user double-clicks on a list item.

See Also
ActionEvent, ActionListener, removeActionListener


 List.addItem

List.addItem

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void addItem( String item )
Description
Note: addItem() is deprecated. replaced by add(String).

Syntax 2
public synchronized void addItem( String item, int index )
Description
Note: addItem() is deprecated. replaced by add(String, int).


 List.addItemListener

List.addItemListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void addItemListener( ItemListener l )
Parameters
l
the item listener.
Description
Adds the specified item listener to receive item events from this list.

See Also
ItemEvent, ItemListener, removeItemListener


 List.addNotify

List.addNotify

Class Overview | Class Members | This Package | All Packages

Syntax
public void addNotify()
Description
Creates the peer for the list. The peer allows us to modify the list's appearance without changing its functionality.

Overrides
addNotify in class Component


 List.allowsMultipleSelections

List.allowsMultipleSelections

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean allowsMultipleSelections()
Description
Note: allowsMultipleSelections() is deprecated. As of JDK version 1.1, replaced by isMultipleMode().


 List.clear

List.clear

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void clear()
Description
Note: clear() is deprecated. As of JDK version 1.1, replaced by removeAll().


 List.countItems

List.countItems

Class Overview | Class Members | This Package | All Packages

Syntax
public int countItems()
Description
Note: countItems() is deprecated. As of JDK version 1.1, replaced by getItemCount().


 List.delItem

List.delItem

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void delItem( int position )
Description
Note: delItem() is deprecated. replaced by remove(String) and remove(int).


 List.delItems

List.delItems

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void delItems( int start, int end )
Description
Note: delItems() is deprecated. As of JDK version 1.1, Not for public use in the future. This method is expected to be retained only as a package private method.


 List.deselect

List.deselect

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void deselect( int index )
Parameters
index
the position of the item to deselect.
Description
Deselects the item at the specified index.

If the item at the specified index is not selected, or if the index is out of range, then the operation is ignored.

See Also
select, getSelectedItem, isIndexSelected


 List.getItem

List.getItem

Class Overview | Class Members | This Package | All Packages

Syntax
public String getItem( int index )
Parameters
index
the position of the item.
Returns
an item that is associated with the specified index.
Description
Gets the item associated with the specified index.

See Also
getItemCount


 List.getItemCount

List.getItemCount

Class Overview | Class Members | This Package | All Packages

Syntax
public int getItemCount()
Returns
the number of items in the list.
Description
Gets the number of items in the list.

See Also
getItem


 List.getItems

List.getItems

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized String[] getItems()
Returns
a string array containing items of the list.
Description
Gets the items in the list.

See Also
select, deselect, isIndexSelected


 List.getMinimumSize

List.getMinimumSize

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Dimension getMinimumSize( int rows )
Parameters
rows
number of rows in the list.
Returns
the minimum dimensions for displaying this scrolling list.
Description
Gets the minumum dimensions for a list with the specified number of rows.

See Also
getMinimumSize

Syntax 2
public Dimension getMinimumSize()
Returns
the minimum dimensions needed to display this scrolling list.
Description
Determines the minimum size of this scrolling list.

Overrides
getMinimumSize in class Component
See Also
getMinimumSize


 List.getPreferredSize

List.getPreferredSize

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Dimension getPreferredSize( int rows )
Parameters
rows
number of rows in the list.
Returns
the preferred dimensions for displaying this scrolling list.
Description
Gets the preferred dimensions for a list with the specified number of rows.

See Also
getPreferredSize

Syntax 2
public Dimension getPreferredSize()
Returns
the preferred dimensions for displaying this scrolling list.
Description
Gets the preferred size of this scrolling list.

Overrides
getPreferredSize in class Component
See Also
getPreferredSize


 List.getRows

List.getRows

Class Overview | Class Members | This Package | All Packages

Syntax
public int getRows()
Returns
the number of visible lines in this scrolling list.
Description
Get the number of visible lines in this list.


 List.getSelectedIndex

List.getSelectedIndex

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized int getSelectedIndex()
Returns
the index of the selected item, or -1 if no item is selected, or if more that one item is selected.
Description
Gets the index of the selected item on the list,

See Also
select, deselect, isIndexSelected


 List.getSelectedIndexes

List.getSelectedIndexes

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized int[] getSelectedIndexes()
Returns
an array of the selected indexes of this scrolling list.
Description
Gets the selected indexes on the list.

See Also
select, deselect, isIndexSelected


 List.getSelectedItem

List.getSelectedItem

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized String getSelectedItem()
Returns
the selected item on the list, or null if no item is selected.
Description
Get the selected item on this scrolling list.

See Also
select, deselect, isIndexSelected


 List.getSelectedItems

List.getSelectedItems

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized String[] getSelectedItems()
Returns
an array of the selected items on this scrolling list.
Description
Get the selected items on this scrolling list.

See Also
select, deselect, isIndexSelected


 List.getSelectedObjects

List.getSelectedObjects

Class Overview | Class Members | This Package | All Packages

Syntax
public Object[] getSelectedObjects()
Description
Returns the selected items on the list in an array of Objects.

See Also
ItemSelectable


 List.getVisibleIndex

List.getVisibleIndex

Class Overview | Class Members | This Package | All Packages

Syntax
public int getVisibleIndex()
Returns
the index of the item that was last made visible.
Description
Gets the index of the item that was last made visible by the method makeVisible.

See Also
makeVisible


 List.isIndexSelected

List.isIndexSelected

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isIndexSelected( int index )
Parameters
index
the item to be checked.
Returns
true if the specified item has been selected; false otherwise.
Description
Determines if the specified item in this scrolling list is selected.

See Also
select, deselect


 List.isMultipleMode

List.isMultipleMode

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isMultipleMode()
Returns
true if this list allows multiple selections; otherwise, false.
Description
Determines whether this list allows multiple selections.

See Also
setMultipleMode


 List.isSelected

List.isSelected

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isSelected( int index )
Description
Note: isSelected() is deprecated. As of JDK version 1.1, replaced by isIndexSelected(int).


 List.makeVisible

List.makeVisible

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void makeVisible( int index )
Parameters
index
the position of the item.
Description
Makes the item at the specified index visible.

See Also
getVisibleIndex


 List.minimumSize

List.minimumSize

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Dimension minimumSize( int rows )
Description
Note: minimumSize() is deprecated. As of JDK version 1.1, replaced by getMinimumSize(int).

Syntax 2
public Dimension minimumSize()
Description
Note: minimumSize() is deprecated. As of JDK version 1.1, replaced by getMinimumSize().

Overrides
minimumSize in class Component


 List.paramString

List.paramString

Class Overview | Class Members | This Package | All Packages

Syntax
protected String paramString()
Returns
the parameter string of this scrolling list.
Description
Returns the parameter string representing the state of this scrolling list. This string is useful for debugging.

Overrides
paramString in class Component


 List.preferredSize

List.preferredSize

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Dimension preferredSize( int rows )
Description
Note: preferredSize() is deprecated. As of JDK version 1.1, replaced by getPreferredSize(int).

Syntax 2
public Dimension preferredSize()
Description
Note: preferredSize() is deprecated. As of JDK version 1.1, replaced by getPreferredSize().

Overrides
preferredSize in class Component


 List.processActionEvent

List.processActionEvent

Class Overview | Class Members | This Package | All Packages

Syntax
protected void processActionEvent( ActionEvent e )
Parameters
e
the action event.
Description
Processes action events occurring on this component by dispatching them to any registered ActionListener objects.

This method is not called unless action events are enabled for this component. Action events are enabled when one of the following occurs:

  • An ActionListener object is registered via addActionListener.
  • Action events are enabled via enableEvents.

See Also
ActionEvent, ActionListener, addActionListener, enableEvents


 List.processEvent

List.processEvent

Class Overview | Class Members | This Package | All Packages

Syntax
protected void processEvent( AWTEvent e )
Parameters
e
the event.
Description
Processes events on this scrolling list. If an event is an instance of ItemEvent, it invokes the processItemEvent method. Else, if the event is an instance of ActionEvent, it invokes processActionEvent. If the event is not an item event or an action event, it invokes processEvent on the superclass.

Overrides
processEvent in class Component
See Also
ActionEvent, ItemEvent, processActionEvent, processItemEvent


 List.processItemEvent

List.processItemEvent

Class Overview | Class Members | This Package | All Packages

Syntax
protected void processItemEvent( ItemEvent e )
Parameters
e
the item event.
Description
Processes item events occurring on this list by dispatching them to any registered ItemListener objects.

This method is not called unless item events are enabled for this component. Item events are enabled when one of the following occurs:

  • An ItemListener object is registered via addItemListener.
  • Item events are enabled via enableEvents.

See Also
ItemEvent, ItemListener, addItemListener, enableEvents


 List.remove

List.remove

Class Overview | Class Members | This Package | All Packages

Syntax 1
public synchronized void remove( String item )
Parameters
item
the item to remove from the list.
Description
Removes the first occurrence of an item from the list.

Exceptions
IllegalArgumentException if the item doesn't exist in the list.

Syntax 2
public synchronized void remove( int position )
Parameters
position
the index of the item to delete.
Description
Remove the item at the specified position from this scrolling list.

See Also
add


 List.removeActionListener

List.removeActionListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void removeActionListener( ActionListener l )
Parameters
l
the action listener.
Description
Removes the specified action listener so that it no longer receives action events from this list. Action events occur when a user double-clicks on a list item.

See Also
ActionEvent, ActionListener, addActionListener


 List.removeAll

List.removeAll

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void removeAll()
Description
Removes all items from this list.

See Also
remove, delItems


 List.removeItemListener

List.removeItemListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void removeItemListener( ItemListener l )
Parameters
l
the item listener.
Description
Removes the specified item listener so that it no longer receives item events from this list.

See Also
ItemEvent, ItemListener, addItemListener


 List.removeNotify

List.removeNotify

Class Overview | Class Members | This Package | All Packages

Syntax
public void removeNotify()
Description
Removes the peer for this list. The peer allows us to modify the list's appearance without changing its functionality.

Overrides
removeNotify in class Component


 List.replaceItem

List.replaceItem

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void replaceItem( String newValue, int index )
Parameters
newValue
a new string to replace an existing item.
index
the position of the item to replace.
Description
Replaces the item at the specified index in the scrolling list with the new string.


 List.select

List.select

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void select( int index )
Parameters
index
the position of the item to select.
Description
Selects the item at the specified index in the scrolling list.

See Also
getSelectedItem, deselect, isIndexSelected


 List.setMultipleMode

List.setMultipleMode

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setMultipleMode( boolean b )
Parameters
b
if true then multiple selections are allowed; otherwise, only one item from the list can be selected at once.
Description
Sets the flag that determines whether this list allows multiple selections.

See Also
isMultipleMode


 List.setMultipleSelections

List.setMultipleSelections

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setMultipleSelections( boolean b )
Description
Note: setMultipleSelections() is deprecated. As of JDK version 1.1, replaced by setMultipleMode(boolean).


 Class MediaTracker

Class java.awt.MediaTracker

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.MediaTracker

public class MediaTracker
extends Object
implements Serializable

The MediaTracker class is a utility class to track the status of a number of media objects. Media objects could include audio clips as well as images, though currently only images are supported.

To use a media tracker, create an instance of MediaTracker and call its addImage method for each image to be tracked. In addition, each image can be assigned a unique identifier. This identifier controls the priority order in which the images are fetched. It can also be used to identify unique subsets of the images that can be waited on independently. Images with a lower ID are loaded in preference to those with a higher ID number.

Here is an example:

 import java.applet.Applet;
 import java.awt.Color;
 import java.awt.Image;
 import java.awt.Graphics;
 import java.awt.MediaTracker;
 public class ImageBlaster extends Applet implements Runnable {
    MediaTracker tracker;
    Image bg;
    Image anim[] = new Image[5];
    int index;
    Thread animator;
    // Get the images for the background (id == 0)
    // and the animation frames (id == 1)
      // and add them to the MediaTracker
    public void init() {
        tracker = new MediaTracker(this);
        bg = getImage(getDocumentBase(),
                  "images/background.gif");
        tracker.addImage(bg, 0);
        for (int i = 0; i < 5; i++) {
        anim[i] = getImage(getDocumentBase(),
                      "images/anim"+i+".gif");
        tracker.addImage(anim[i], 1);
        }
    }
    // Start the animation thread.
    public void start() {
        animator = new Thread(this);
        animator.start();
    }
    // Stop the animation thread.
    public void stop() {
        animator.stop();
        animator = null;
    }
    // Run the animation thread.
    // First wait for the background image to fully load
      // and paint.  Then wait for all of the animation
    // frames to finish loading. Finally, loop and
    // increment the animation frame index.
    public void run() {
        try {
        tracker.waitForID(0);
        tracker.waitForID(1);
        } catch (InterruptedException e) {
        return;
        }
        Thread me = Thread.currentThread();
        while (animator == me) {
        try {
            Thread.sleep(100);
        } catch (InterruptedException e) {
            break;
        }
        synchronized (this) {
            index++;
            if (index >= anim.length) {
            index = 0;
            }
        }
        repaint();
        }
    }
    // The background image fills the frame so we
    // don't need to clear the applet on repaints.
      // Just call the paint method.
    public void update(Graphics g) {
        paint(g);
    }
    // Paint a large red rectangle if there are any errors
    // loading the images.  Otherwise always paint the
    // background so that it appears incrementally as it
      // is loading.  Finally, only paint the current animation
    // frame if all of the frames (id == 1) are done loading,
    // so that we don't get partial animations.
    public void paint(Graphics g) {
        if ((tracker.statusAll(false) & MediaTracker.ERRORED) != 0) {
        g.setColor(Color.red);
        g.fillRect(0, 0, size().width, size().height);
        return;
        }
        g.drawImage(bg, 0, 0, this);
        if (tracker.statusID(1, false) == MediaTracker.COMPLETE) {
        g.drawImage(anim[index], 10, 10, this);
        }
    }
 }


 MediaTracker Members

MediaTracker Members

Class Overview | This Package | All Packages

Fields
Name | Description
ABORTED | Flag indicating that the downloading of some media was aborted.
COMPLETE | Flag indicating that the downloading of media was completed successfully.
ERRORED | Flag indicating that the downloading of some media encountered an error.
LOADING | Flag indicating some media is currently being loaded.

Constructors
Name | Description
MediaTracker(Component) | Creates a media tracker to track images for a given component.

Methods
Name | Description
addImage(Image, int) | Adds an image to the list of images being tracked by this media tracker.
addImage(Image, int, int, int) | Adds a scaled image to the list of images being tracked by this media tracker.
checkAll() | Checks to see if all images being tracked by this media tracker have finished loading.
checkAll(boolean) | Checks to see if all images being tracked by this media tracker have finished loading.
checkID(int) | Checks to see if all images tracked by this media tracker that are tagged with the specified identifier have finished loading.
checkID(int, boolean) | Checks to see if all images tracked by this media tracker that are tagged with the specified identifier have finished loading.
getErrorsAny() | Returns a list of all media that have encountered an error.
getErrorsID(int) | Returns a list of media with the specified ID that have encountered an error.
isErrorAny() | Checks the error status of all of the images.
isErrorID(int) | Checks the error status of all of the images tracked by this media tracker with the specified identifier.
removeImage(Image) | Remove the specified image from this media tracker.
removeImage(Image, int) | Remove the specified image from the specified tracking ID of this media tracker.
removeImage(Image, int, int, int) | Remove the specified image with the specified width, height, and ID from this media tracker.
statusAll(boolean) | Calculates and returns the bitwise inclusive OR of the status of all media that are tracked by this media tracker.
statusID(int, boolean) | Calculates and returns the bitwise inclusive OR of the status of all media with the specified identifier that are tracked by this media tracker.
waitForAll() | Starts loading all images tracked by this media tracker.
waitForAll(long) | Starts loading all images tracked by this media tracker.
waitForID(int) | Starts loading all images tracked by this media tracker with the specified identifier.
waitForID(int, long) | Starts loading all images tracked by this media tracker with the specified identifier.


 MediaTracker.ABORTED

MediaTracker.ABORTED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int ABORTED
Description
Flag indicating that the downloading of some media was aborted.

See Also
statusAll, statusID


 MediaTracker.COMPLETE

MediaTracker.COMPLETE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int COMPLETE
Description
Flag indicating that the downloading of media was completed successfully.

See Also
statusAll, statusID


 MediaTracker.ERRORED

MediaTracker.ERRORED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int ERRORED
Description
Flag indicating that the downloading of some media encountered an error.

See Also
statusAll, statusID


 MediaTracker.LOADING

MediaTracker.LOADING

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int LOADING
Description
Flag indicating some media is currently being loaded.

See Also
statusAll, statusID


 MediaTracker.MediaTracker

MediaTracker.MediaTracker

Class Overview | Class Members | This Package | All Packages

Syntax
public MediaTracker( Component comp )
Parameters
comp
the component on which the images will eventually be drawn.
Description
Creates a media tracker to track images for a given component.


 MediaTracker.addImage

MediaTracker.addImage

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void addImage( Image image, int id )
Parameters
image
the image to be tracked.
id
an identifier used to track this image.
Description
Adds an image to the list of images being tracked by this media tracker. The image will eventually be rendered at its default (unscaled) size.

Syntax 2
public synchronized void addImage( Image image, int id, int w, int h )
Parameters
image
the image to be tracked.
id
an identifier that can be used to track this image.
w
the width at which the image is rendered.
h
the height at which the image is rendered.
Description
Adds a scaled image to the list of images being tracked by this media tracker. The image will eventually be rendered at the indicated width and height.


 MediaTracker.checkAll

MediaTracker.checkAll

Class Overview | Class Members | This Package | All Packages

Syntax 1
public boolean checkAll()
Returns
true if all images have finished loading, have been aborted, or have encountered an error; false otherwise.
Description
Checks to see if all images being tracked by this media tracker have finished loading.

This method does not start loading the images if they are not already loading.

If there is an error while loading or scaling an image, then that image is considered to have finished loading. Use the isErrorAny or isErrorID methods to check for errors.

See Also
checkAll, checkID, isErrorAny, isErrorID

Syntax 2
public boolean checkAll( boolean load )
Parameters
load
if true, start loading any images that are not yet being loaded.
Returns
true if all images have finished loading, have been aborted, or have encountered an error; false otherwise.
Description
Checks to see if all images being tracked by this media tracker have finished loading.

If the value of the load flag is true, then this method starts loading any images that are not yet being loaded.

If there is an error while loading or scaling an image, that image is considered to have finished loading. Use the isErrorAny and isErrorID methods to check for errors.

See Also
checkID, checkAll, isErrorAny, isErrorID


 MediaTracker.checkID

MediaTracker.checkID

Class Overview | Class Members | This Package | All Packages

Syntax 1
public boolean checkID( int id )
Parameters
id
the identifier of the images to check.
Returns
true if all images have finished loading, have been aborted, or have encountered an error; false otherwise.
Description
Checks to see if all images tracked by this media tracker that are tagged with the specified identifier have finished loading.

This method does not start loading the images if they are not already loading.

If there is an error while loading or scaling an image, then that image is considered to have finished loading. Use the isErrorAny or isErrorID methods to check for errors.

See Also
checkID, checkAll, isErrorAny, isErrorID

Syntax 2
public boolean checkID( int id, boolean load )
Parameters
id
the identifier of the images to check.
load
if true, start loading any images that are not yet being loaded.
Returns
true if all images have finished loading, have been aborted, or have encountered an error; false otherwise.
Description
Checks to see if all images tracked by this media tracker that are tagged with the specified identifier have finished loading.

If the value of the load flag is true, then this method starts loading any images that are not yet being loaded.

If there is an error while loading or scaling an image, then that image is considered to have finished loading. Use the isErrorAny or isErrorID methods to check for errors.

See Also
checkID, checkAll, isErrorAny, isErrorID


 MediaTracker.getErrorsAny

MediaTracker.getErrorsAny

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized Object[] getErrorsAny()
Returns
an array of media objects tracked by this media tracker that have encountered an error, or null if there are none with errors.
Description
Returns a list of all media that have encountered an error.

See Also
isErrorAny, getErrorsID


 MediaTracker.getErrorsID

MediaTracker.getErrorsID

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized Object[] getErrorsID( int id )
Parameters
id
the identifier of the images to check.
Returns
an array of media objects tracked by this media tracker with the specified identifier that have encountered an error, or null if there are none with errors.
Description
Returns a list of media with the specified ID that have encountered an error.

See Also
isErrorID, isErrorAny, getErrorsAny


 MediaTracker.isErrorAny

MediaTracker.isErrorAny

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized boolean isErrorAny()
Returns
true if any of the images tracked by this media tracker had an error during loading; false otherwise.
Description
Checks the error status of all of the images.

See Also
isErrorID, getErrorsAny


 MediaTracker.isErrorID

MediaTracker.isErrorID

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized boolean isErrorID( int id )
Parameters
id
the identifier of the images to check.
Returns
true if any of the images with the specified identifier had an error during loading; false otherwise.
Description
Checks the error status of all of the images tracked by this media tracker with the specified identifier.

See Also
isErrorAny, getErrorsID


 MediaTracker.removeImage

MediaTracker.removeImage

Class Overview | Class Members | This Package | All Packages

Syntax 1
public synchronized void removeImage( Image image )
Parameters
image
the image to be removed
Description
Remove the specified image from this media tracker. All instances of the specified image are removed, regardless of scale or ID.

See Also
removeImage, removeImage

Syntax 2
public synchronized void removeImage( Image image, int id )
Parameters
image
the image to be removed.
id
the tracking ID frrom which to remove the image.
Description
Remove the specified image from the specified tracking ID of this media tracker. All instances of Image being tracked under the specified ID are removed regardless of scale.

See Also
removeImage, removeImage

Syntax 3
public synchronized void removeImage( Image image, int id, int width, int height )
Parameters
image
the image to be removed
id
the tracking ID from which to remove the image.
width
the width to remove (-1 for unscaled).
height
the height to remove (-1 for unscaled).
Description
Remove the specified image with the specified width, height, and ID from this media tracker. Only the specified instance (with any duplicates) is removed.

See Also
removeImage, removeImage


 MediaTracker.statusAll

MediaTracker.statusAll

Class Overview | Class Members | This Package | All Packages

Syntax
public int statusAll( boolean load )
Parameters
load
if true, start loading any images that are not yet being loaded.
Returns
the bitwise inclusive OR of the status of all of the media being tracked.
Description
Calculates and returns the bitwise inclusive OR of the status of all media that are tracked by this media tracker.

Possible flags defined by the MediaTracker class are LOADING, ABORTED, ERRORED, and COMPLETE. An image that hasn't started loading has zero as its status.

If the value of load is true, then this method starts loading any images that are not yet being loaded.

See Also
statusID, LOADING, ABORTED, ERRORED, COMPLETE


 MediaTracker.statusID

MediaTracker.statusID

Class Overview | Class Members | This Package | All Packages

Syntax
public int statusID( int id, boolean load )
Parameters
id
the identifier of the images to check.
load
if true, start loading any images that are not yet being loaded.
Returns
the bitwise inclusive OR of the status of all of the media with the specified identifier that are being tracked.
Description
Calculates and returns the bitwise inclusive OR of the status of all media with the specified identifier that are tracked by this media tracker.

Possible flags defined by the MediaTracker class are LOADING, ABORTED, ERRORED, and COMPLETE. An image that hasn't started loading has zero as its status.

If the value of load is true, then this method starts loading any images that are not yet being loaded.

See Also
statusAll, LOADING, ABORTED, ERRORED, COMPLETE


 MediaTracker.waitForAll

MediaTracker.waitForAll

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void waitForAll() throws InterruptedException
Description
Starts loading all images tracked by this media tracker. This method waits until all the images being tracked have finished loading.

If there is an error while loading or scaling an image, then that image is considered to have finished loading. Use the isErrorAny or isErrorID methods to check for errors.

Exceptions
InterruptedException if another thread has interrupted this thread.
See Also
waitForID, waitForAll, isErrorAny, isErrorID

Syntax 2
public synchronized boolean waitForAll( long ms ) throws InterruptedException
Parameters
ms
the number of milliseconds to wait for the loading to complete.
Returns
true if all images were successfully loaded; false otherwise.
Description
Starts loading all images tracked by this media tracker. This method waits until all the images being tracked have finished loading, or until the length of time specified in milliseconds by the ms argument has passed.

If there is an error while loading or scaling an image, then that image is considered to have finished loading. Use the isErrorAny or isErrorID methods to check for errors.

Exceptions
InterruptedException if another thread has interrupted this thread.
See Also
waitForID, waitForAll, isErrorAny, isErrorID


 MediaTracker.waitForID

MediaTracker.waitForID

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void waitForID( int id ) throws InterruptedException
Parameters
id
the identifier of the images to check.
Description
Starts loading all images tracked by this media tracker with the specified identifier. This method waits until all the images with the specified identifier have finished loading.

If there is an error while loading or scaling an image, then that image is considered to have finished loading. Use the isErrorAny and isErrorID methods to check for errors.

Exceptions
InterruptedException if another thread has interrupted this thread.
See Also
waitForAll, isErrorAny, isErrorID

Syntax 2
public synchronized boolean waitForID( int id, long ms ) throws InterruptedException
Parameters
id
the identifier of the images to check.
ms
the length of time, in milliseconds, to wait for the loading to complete.
Description
Starts loading all images tracked by this media tracker with the specified identifier. This method waits until all the images with the specified identifier have finished loading, or until the length of time specified in milliseconds by the ms argument has passed.

If there is an error while loading or scaling an image, then that image is considered to have finished loading. Use the statusID, isErrorID, and isErrorAny methods to check for errors.

Exceptions
InterruptedException if another thread has interrupted this thread.
See Also
waitForAll, waitForID, statusID, isErrorAny, isErrorID


 Class Menu

Class java.awt.Menu

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.MenuComponent
           |
           +----java.awt.MenuItem
                   |
                   +----java.awt.Menu

public class Menu
extends MenuItem
implements MenuContainer

A Menu object is a pull-down menu component that is deployed from a menu bar.

A menu can optionally be a tear-off menu. A tear-off menu can be opened and dragged away from its parent menu bar or menu. It remains on the screen after the mouse button has been released. The mechanism for tearing off a menu is platform dependent, since the look and feel of the tear-off menu is determined by its peer. On platforms that do not support tear-off menus, the tear-off property is ignored.

Each item in a menu must belong to the MenuItem class. It can be an instance of MenuItem, a submenu (an instance of Menu), or a check box (an instance of CheckboxMenuItem).

See Also:
MenuItem, CheckboxMenuItem


 Menu Members

Menu Members

Class Overview | This Package | All Packages

Constructors
Name | Description
Menu() | Constructs a new menu with an empty label.
Menu(String) | Constructs a new menu with the specified label.
Menu(String, boolean) | Constructs a new menu with the specified label.

Methods
Name | Description
add(MenuItem) | Adds the specified menu item to this menu.
add(String) | Adds an item with the specified label to this menu.
addNotify() | Creates the menu's peer.
addSeparator() | Adds a separator line, or a hypen, to the menu at the current position.
countItems() | Deprecated.
getItem(int) | Gets the item located at the specified index of this menu.
getItemCount() | Get the number of items in this menu.
insert(MenuItem, int) | Inserts a menu item into this menu at the specified position.
insert(String, int) | Inserts a menu item with the specified label into this menu at the specified position.
insertSeparator(int) | Inserts a separator at the specified position.
isTearOff() | Indicates whether this menu is a tear-off menu.
paramString() | Gets the parameter string representing the state of this menu.
remove(int) | Removes the menu item at the specified index from this menu.
remove(MenuComponent) | Removes the specified menu item from this menu.
removeAll() | Removes all items from this menu.
removeNotify() | Removes the menu's peer.


 Menu.Menu

Menu.Menu

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Menu()
Description
Constructs a new menu with an empty label. This menu is not a tear-off menu.

Syntax 2
public Menu( String label )
Parameters
label
the menu's label in the menu bar, or in another menu of which this menu is a submenu.
Description
Constructs a new menu with the specified label. This menu is not a tear-off menu.

Syntax 3
public Menu( String label, boolean tearOff )
Parameters
label
the menu's label in the menu bar, or in another menu of which this menu is a submenu.
tearOff
if true, the menu is a tear-off menu.
Description
Constructs a new menu with the specified label. If the value of tearOff is true, the menu can be torn off.

Tear-off functionality may not be supported by all implementations of AWT. If a particular implementation doesn't support tear-off menus, this value is silently ignored.


 Menu.add

Menu.add

Class Overview | Class Members | This Package | All Packages

Syntax 1
public synchronized MenuItem add( MenuItem mi )
Parameters
mi
the menu item to be added.
Returns
the menu item added.
Description
Adds the specified menu item to this menu. If the menu item has been part of another menu, remove it from that menu.

See Also
insert, insert

Syntax 2
public void add( String label )
Parameters
label
the text on the item.
Description
Adds an item with the specified label to this menu.

See Also
insert, insert


 Menu.addNotify

Menu.addNotify

Class Overview | Class Members | This Package | All Packages

Syntax
public void addNotify()
Description
Creates the menu's peer. The peer allows us to modify the appearance of the menu without changing its functionality.

Overrides
addNotify in class MenuItem


 Menu.addSeparator

Menu.addSeparator

Class Overview | Class Members | This Package | All Packages

Syntax
public void addSeparator()
Description
Adds a separator line, or a hypen, to the menu at the current position.

See Also
insertSeparator


 Menu.countItems

Menu.countItems

Class Overview | Class Members | This Package | All Packages

Syntax
public int countItems()
Description
Note: countItems() is deprecated. As of JDK version 1.1, replaced by getItemCount().


 Menu.getItem

Menu.getItem

Class Overview | Class Members | This Package | All Packages

Syntax
public MenuItem getItem( int index )
Parameters
index
the position of the item to be returned.
Returns
the item located at the specified index.
Description
Gets the item located at the specified index of this menu.


 Menu.getItemCount

Menu.getItemCount

Class Overview | Class Members | This Package | All Packages

Syntax
public int getItemCount()
Returns
the number of items in this menu.
Description
Get the number of items in this menu.


 Menu.insert

Menu.insert

Class Overview | Class Members | This Package | All Packages

Syntax 1
public synchronized void insert( MenuItem menuitem, int index )
Parameters
menuitem
the menu item to be inserted.
index
the position at which the menu item should be inserted.
Description
Inserts a menu item into this menu at the specified position.

Exceptions
IllegalArgumentException if the value of index is less than zero.
See Also
add, add

Syntax 2
public void insert( String label, int index )
Parameters
label
the text on the item.
index
the position at which the menu item should be inserted.
Description
Inserts a menu item with the specified label into this menu at the specified position.

See Also
add, add


 Menu.insertSeparator

Menu.insertSeparator

Class Overview | Class Members | This Package | All Packages

Syntax
public void insertSeparator( int index )
Parameters
index
the position at which the menu separator should be inserted.
Description
Inserts a separator at the specified position.

Exceptions
IllegalArgumentException if the value of index is less than 0.
See Also
addSeparator


 Menu.isTearOff

Menu.isTearOff

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isTearOff()
Returns
true if this is a tear-off menu; false otherwise.
Description
Indicates whether this menu is a tear-off menu.

Tear-off functionality may not be supported by all implementations of AWT. If a particular implementation doesn't support tear-off menus, this value is silently ignored.


 Menu.paramString

Menu.paramString

Class Overview | Class Members | This Package | All Packages

Syntax
public String paramString()
Description
Gets the parameter string representing the state of this menu. This string is useful for debugging.

Overrides
paramString in class MenuItem


 Menu.remove

Menu.remove

Class Overview | Class Members | This Package | All Packages

Syntax 1
public synchronized void remove( int index )
Parameters
index
the position of the item to be removed.
Description
Removes the menu item at the specified index from this menu.

Syntax 2
public synchronized void remove( MenuComponent item )
Parameters
item
the item to be removed from the menu
Description
Removes the specified menu item from this menu.


 Menu.removeAll

Menu.removeAll

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void removeAll()
Description
Removes all items from this menu.


 Menu.removeNotify

Menu.removeNotify

Class Overview | Class Members | This Package | All Packages

Syntax
public void removeNotify()
Description
Removes the menu's peer. The peer allows us to modify the appearance of the menu without changing its functionality.

Overrides
removeNotify in class MenuComponent


 Class MenuBar

Class java.awt.MenuBar

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.MenuComponent
           |
           +----java.awt.MenuBar

public class MenuBar
extends MenuComponent
implements MenuContainer

The MenuBar class encapsulates the platform's concept of a menu bar bound to a frame. In order to associate the menu bar with a Frame object, call the frame's setMenuBar method.

This is what a menu bar might look like:

A menu bar handles keyboard shortcuts for menu items, passing them along to its child menus. (Keyboard shortcuts, which are optional, provide the user with an alternative to the mouse for invoking a menu item and the action that is associated with it.) Each menu item can maintain an instance of MenuShortcut. The MenuBar class defines several methods, shortCuts and getShortcutMenuItem that retrieve information about the shortcuts a given menu bar is managing.

See Also:
Frame, setMenuBar, Menu, MenuItem, MenuShortcut


 MenuBar Members

MenuBar Members

Class Overview | This Package | All Packages

Constructors
Name | Description
MenuBar() | Creates a new menu bar.

Methods
Name | Description
add(Menu) | Adds the specified menu to the menu bar.
addNotify() | Creates the menu bar's peer.
countMenus() | Deprecated.
deleteShortcut(MenuShortcut) | Deletes the specified menu shortcut.
getHelpMenu() | Gets the help menu on the menu bar.
getMenu(int) | Gets the specified menu.
getMenuCount() | Gets the number of menus on the menu bar.
getShortcutMenuItem(MenuShortcut) | Gets the instance of MenuItem associated with the specified MenuShortcut object, or null if none has been specified.
remove(int) | Removes the menu located at the specified index from this menu bar.
remove(MenuComponent) | Removes the specified menu component from this menu bar.
removeNotify() | Removes the menu bar's peer.
setHelpMenu(Menu) | Sets the help menu on this menu bar to be the specified menu.
shortcuts() | Gets an enumeration of all menu shortcuts this menu bar is managing.


 MenuBar.MenuBar

MenuBar.MenuBar

Class Overview | Class Members | This Package | All Packages

Syntax
public MenuBar()
Description
Creates a new menu bar.


 MenuBar.add

MenuBar.add

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized Menu add( Menu m )
Parameters
m
the menu to be added.
Returns
the menu added.
Description
Adds the specified menu to the menu bar.

See Also
remove, remove


 MenuBar.addNotify

MenuBar.addNotify

Class Overview | Class Members | This Package | All Packages

Syntax
public void addNotify()
Description
Creates the menu bar's peer. The peer allows us to change the appearance of the menu bar without changing any of the menu bar's functionality.


 MenuBar.countMenus

MenuBar.countMenus

Class Overview | Class Members | This Package | All Packages

Syntax
public int countMenus()
Description
Note: countMenus() is deprecated. As of JDK version 1.1, replaced by getMenuCount().


 MenuBar.deleteShortcut

MenuBar.deleteShortcut

Class Overview | Class Members | This Package | All Packages

Syntax
public void deleteShortcut( MenuShortcut s )
Parameters
s
the menu shortcut to delete.
Description
Deletes the specified menu shortcut.


 MenuBar.getHelpMenu

MenuBar.getHelpMenu

Class Overview | Class Members | This Package | All Packages

Syntax
public Menu getHelpMenu()
Returns
the help menu on this menu bar.
Description
Gets the help menu on the menu bar.


 MenuBar.getMenu

MenuBar.getMenu

Class Overview | Class Members | This Package | All Packages

Syntax
public Menu getMenu( int i )
Parameters
i
the index position of the menu to be returned.
Returns
the menu at the specified index of this menu bar.
Description
Gets the specified menu.


 MenuBar.getMenuCount

MenuBar.getMenuCount

Class Overview | Class Members | This Package | All Packages

Syntax
public int getMenuCount()
Returns
the number of menus on the menu bar.
Description
Gets the number of menus on the menu bar.


 MenuBar.getShortcutMenuItem

MenuBar.getShortcutMenuItem

Class Overview | Class Members | This Package | All Packages

Syntax
public MenuItem getShortcutMenuItem( MenuShortcut s )
Parameters
s
the specified menu shortcut.
Description
Gets the instance of MenuItem associated with the specified MenuShortcut object, or null if none has been specified.

See Also
MenuItem, MenuShortcut


 MenuBar.remove

MenuBar.remove

Class Overview | Class Members | This Package | All Packages

Syntax 1
public synchronized void remove( int index )
Parameters
index
the position of the menu to be removed.
Description
Removes the menu located at the specified index from this menu bar.

See Also
add

Syntax 2
public synchronized void remove( MenuComponent m )
Parameters
m
the menu component to be removed.
Description
Removes the specified menu component from this menu bar.

See Also
add


 MenuBar.removeNotify

MenuBar.removeNotify

Class Overview | Class Members | This Package | All Packages

Syntax
public void removeNotify()
Description
Removes the menu bar's peer. The peer allows us to change the appearance of the menu bar without changing any of the menu bar's functionality.

Overrides
removeNotify in class MenuComponent


 MenuBar.setHelpMenu

MenuBar.setHelpMenu

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setHelpMenu( Menu m )
Parameters
m
the menu to be set as the help menu.
Description
Sets the help menu on this menu bar to be the specified menu.


 MenuBar.shortcuts

MenuBar.shortcuts

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized Enumeration shortcuts()
Returns
an enumeration of menu shortcuts that this menu bar is managing.
Description
Gets an enumeration of all menu shortcuts this menu bar is managing.

See Also
MenuShortcut


 Class MenuComponent

Class java.awt.MenuComponent

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.MenuComponent

public abstract class MenuComponent
extends Object
implements Serializable

The abstract class MenuComponent is the superclass of all menu-related components. In this respect, the class MenuComponent is analogous to the abstract superclass Component for AWT components.

Menu components receive and process AWT events, just as components do, through the method processEvent.


 MenuComponent Members

MenuComponent Members

Class Overview | This Package | All Packages

Constructors
Name | Description
MenuComponent() |

Methods
Name | Description
dispatchEvent(AWTEvent) |
getFont() | Gets the font used for this menu component.
getName() | Gets the name of the menu component.
getParent() | Returns the parent container for this menu component.
getPeer() | Deprecated.
paramString() | Returns the parameter string representing the state of this menu component.
postEvent(Event) | Posts the specified event to the menu. Deprecated.
processEvent(AWTEvent) | Processes events occurring on this menu component.
removeNotify() | Removes the menu component's peer.
setFont(Font) | Sets the font to be used for this menu component to the specified font.
setName(String) | Sets the name of the component to the specified string.
toString() | Returns a representation of this menu component as a string.


 MenuComponent.MenuComponent

MenuComponent.MenuComponent

Class Overview | Class Members | This Package | All Packages

Syntax
public MenuComponent()


 MenuComponent.dispatchEvent

MenuComponent.dispatchEvent

Class Overview | Class Members | This Package | All Packages

Syntax
public final void dispatchEvent( AWTEvent e )


 MenuComponent.getFont

MenuComponent.getFont

Class Overview | Class Members | This Package | All Packages

Syntax
public Font getFont()
Returns
the font used in this menu component, if there is one; null otherwise.
Description
Gets the font used for this menu component.

See Also
setFont


 MenuComponent.getName

MenuComponent.getName

Class Overview | Class Members | This Package | All Packages

Syntax
public String getName()
Returns
the name of the menu component.
Description
Gets the name of the menu component.

See Also
setName


 MenuComponent.getParent

MenuComponent.getParent

Class Overview | Class Members | This Package | All Packages

Syntax
public MenuContainer getParent()
Returns
the menu component containing this menu component, or null if this menu component is the outermost component, the menu bar itself.
Description
Returns the parent container for this menu component.


 MenuComponent.getPeer

MenuComponent.getPeer

Class Overview | Class Members | This Package | All Packages

Syntax
public MenuComponentPeer getPeer()
Description
Note: getPeer() is deprecated. As of JDK version 1.1, programs should not directly manipulate peers.


 MenuComponent.paramString

MenuComponent.paramString

Class Overview | Class Members | This Package | All Packages

Syntax
protected String paramString()
Returns
the parameter string of this menu component.
Description
Returns the parameter string representing the state of this menu component. This string is useful for debugging.


 MenuComponent.postEvent

MenuComponent.postEvent

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean postEvent( Event evt )
Parameters
evt
the event which is to take place
Description
Note: postEvent() is deprecated. As of JDK version 1.1, replaced by dispatchEvent(AWTEvent).

Posts the specified event to the menu. This method is part of the Java 1.0 event system and it is maintained only for backwards compatibility. Its use is discouraged, and it may not be supported in the future.


 MenuComponent.processEvent

MenuComponent.processEvent

Class Overview | Class Members | This Package | All Packages

Syntax
protected void processEvent( AWTEvent e )
Parameters
e
the event
Description
Processes events occurring on this menu component.


 MenuComponent.removeNotify

MenuComponent.removeNotify

Class Overview | Class Members | This Package | All Packages

Syntax
public void removeNotify()
Description
Removes the menu component's peer. The peer allows us to modify the appearance of the menu component without changing the functionality of the menu component.


 MenuComponent.setFont

MenuComponent.setFont

Class Overview | Class Members | This Package | All Packages

Syntax
public void setFont( Font f )
Parameters
f
the font to be set.
Description
Sets the font to be used for this menu component to the specified font. This font is also used by all subcomponents of this menu component, unless those subcomponents specify a different font.

See Also
getFont


 MenuComponent.setName

MenuComponent.setName

Class Overview | Class Members | This Package | All Packages

Syntax
public void setName( String name )
Parameters
name
the name of the menu component.
Description
Sets the name of the component to the specified string.

See Also
getName


 MenuComponent.toString

MenuComponent.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string representation of this menu component.
Description
Returns a representation of this menu component as a string.

Overrides
toString in class Object


 Interface MenuContainer

Interface java.awt.MenuContainer

Interface Members | This Package | All Packages

public interface MenuContainer

The super class of all menu related containers.


 MenuContainer Members

MenuContainer Members

Interface Overview | This Package | All Packages

Methods
Name | Description
getFont() |
postEvent(Event) | Deprecated.
remove(MenuComponent) |


 MenuContainer.getFont

MenuContainer.getFont

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Font getFont()


 MenuContainer.postEvent

MenuContainer.postEvent

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean postEvent( Event evt )
Description
Note: postEvent() is deprecated. As of JDK version 1.1 replaced by dispatchEvent(AWTEvent).


 MenuContainer.remove

MenuContainer.remove

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void remove( MenuComponent comp )


 Class MenuItem

Class java.awt.MenuItem

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.MenuComponent
           |
           +----java.awt.MenuItem

public class MenuItem
extends MenuComponent

All items in a menu must belong to the class MenuItem, or one of its subclasses.

The default MenuItem object embodies a simple labeled menu item.

This picture of a menu bar shows five menu items:
The first two items are simple menu items, labeled "Basic" and "Simple". Following these two items is a separator, which is itself a menu item, created with the label "-". Next is an instance of CheckboxMenuItem labeled "Check". The final menu item is a submenu labeled "More Examples", and this submenu is an instance of Menu.

When a menu item is selected, AWT sends an action event to the menu item. Since the event is an instance of ActionEvent, the processEvent method examines the event and passes it along to processActionEvent. The latter method redirects the event to any ActionListener objects that have registered an interest in action events generated by this menu item.

Note that the subclass Menu overrides this behavior and does not send any event to the frame until one of its subitems is selected.


 MenuItem Members

MenuItem Members

Class Overview | This Package | All Packages

Constructors
Name | Description
MenuItem() | Constructs a new MenuItem with an empty label and no keyboard shortcut.
MenuItem(String) | Constructs a new MenuItem with the specified label and no keyboard shortcut.
MenuItem(String, MenuShortcut) | Create a menu item with an associated keyboard shortcut.

Methods
Name | Description
addActionListener(ActionListener) | Adds the specified action listener to receive action events from this menu item.
addNotify() | Creates the menu item's peer.
deleteShortcut() | Delete any MenuShortcut object associated with this menu item.
disable() | Deprecated.
disableEvents(long) | Disables event delivery to this menu item for events defined by the specified event mask parameter.
enable() | Deprecated.
enable(boolean) | Deprecated.
enableEvents(long) | Enables event delivery to this menu item for events to be defined by the specified event mask parameter Since event types are automatically enabled when a listener for that type is added to the menu item, this method only needs to be invoked by subclasses of MenuItem which desire to have the specified event types delivered to processEvent regardless of whether a listener is registered.
getActionCommand() | Gets the command name of the action event that is fired by this menu item.
getLabel() | Gets the label for this menu item.
getShortcut() | Get the MenuShortcut object associated with this menu item,
isEnabled() | Checks whether this menu item is enabled.
paramString() | Returns the parameter string representing the state of this menu item.
processActionEvent(ActionEvent) | Processes action events occurring on this menu item, by dispatching them to any registered ActionListener objects.
processEvent(AWTEvent) | Processes events on this menu item.
removeActionListener(ActionListener) | Removes the specified action listener so it no longer receives action events from this menu item.
setActionCommand(String) | Sets the command name of the action event that is fired by this menu item.
setEnabled(boolean) | Sets whether or not this menu item can be chosen.
setLabel(String) | Sets the label for this menu item to the specified label.
setShortcut(MenuShortcut) | Set the MenuShortcut object associated with this menu item.


 MenuItem.MenuItem

MenuItem.MenuItem

Class Overview | Class Members | This Package | All Packages

Syntax 1
public MenuItem()
Description
Constructs a new MenuItem with an empty label and no keyboard shortcut.

Syntax 2
public MenuItem( String label )
Parameters
label
the label for this menu item.
Description
Constructs a new MenuItem with the specified label and no keyboard shortcut. Note that use of "-" in a label is reserved to indicate a separator between menu items. By default, all menu items except for separators are enabled.

Syntax 3
public MenuItem( String label, MenuShortcut s )
Parameters
label
the label for this menu item.
s
the instance of MenuShortcut associated with this menu item.
Description
Create a menu item with an associated keyboard shortcut. Note that use of "-" in a label is reserved to indicate a separator between menu items. By default, all menu items except for separators are enabled.


 MenuItem.addActionListener

MenuItem.addActionListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void addActionListener( ActionListener l )
Parameters
l
the action listener.
Description
Adds the specified action listener to receive action events from this menu item.

See Also
ActionEvent, ActionListener, removeActionListener


 MenuItem.addNotify

MenuItem.addNotify

Class Overview | Class Members | This Package | All Packages

Syntax
public void addNotify()
Description
Creates the menu item's peer. The peer allows us to modify the appearance of the menu item without changing its functionality.


 MenuItem.deleteShortcut

MenuItem.deleteShortcut

Class Overview | Class Members | This Package | All Packages

Syntax
public void deleteShortcut()
Description
Delete any MenuShortcut object associated with this menu item.


 MenuItem.disable

MenuItem.disable

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void disable()
Description
Note: disable() is deprecated. As of JDK version 1.1, replaced by setEnabled(boolean).


 MenuItem.disableEvents

MenuItem.disableEvents

Class Overview | Class Members | This Package | All Packages

Syntax
protected final void disableEvents( long eventsToDisable )
Parameters
eventsToDisable
the event mask defining the event types.
Description
Disables event delivery to this menu item for events defined by the specified event mask parameter.

See Also
processEvent, enableEvents, disableEvents


 MenuItem.enable

MenuItem.enable

Class Overview | Class Members | This Package | All Packages

Syntax 1
public synchronized void enable()
Description
Note: enable() is deprecated. As of JDK version 1.1, replaced by setEnabled(boolean).

Syntax 2
public void enable( boolean b )
Description
Note: enable() is deprecated. As of JDK version 1.1, replaced by setEnabled(boolean).


 MenuItem.enableEvents

MenuItem.enableEvents

Class Overview | Class Members | This Package | All Packages

Syntax
protected final void enableEvents( long eventsToEnable )
Parameters
eventsToEnable
the event mask defining the event types.
Description
Enables event delivery to this menu item for events to be defined by the specified event mask parameter

Since event types are automatically enabled when a listener for that type is added to the menu item, this method only needs to be invoked by subclasses of MenuItem which desire to have the specified event types delivered to processEvent regardless of whether a listener is registered.

See Also
processEvent, disableEvents, enableEvents


 MenuItem.getActionCommand

MenuItem.getActionCommand

Class Overview | Class Members | This Package | All Packages

Syntax
public String getActionCommand()
Description
Gets the command name of the action event that is fired by this menu item.

See Also
setActionCommand


 MenuItem.getLabel

MenuItem.getLabel

Class Overview | Class Members | This Package | All Packages

Syntax
public String getLabel()
Returns
the label of this menu item, or null if this menu item has no label.
Description
Gets the label for this menu item.

See Also
setLabel


 MenuItem.getShortcut

MenuItem.getShortcut

Class Overview | Class Members | This Package | All Packages

Syntax
public MenuShortcut getShortcut()
Returns
the menu shortcut associated with this menu item, or null if none has been specified.
Description
Get the MenuShortcut object associated with this menu item,

See Also
setShortcut


 MenuItem.isEnabled

MenuItem.isEnabled

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isEnabled()
Description
Checks whether this menu item is enabled.

See Also
setEnabled


 MenuItem.paramString

MenuItem.paramString

Class Overview | Class Members | This Package | All Packages

Syntax
public String paramString()
Returns
the parameter string of this menu item.
Description
Returns the parameter string representing the state of this menu item. This string is useful for debugging.

Overrides
paramString in class MenuComponent


 MenuItem.processActionEvent

MenuItem.processActionEvent

Class Overview | Class Members | This Package | All Packages

Syntax
protected void processActionEvent( ActionEvent e )
Parameters
e
the action event.
Description
Processes action events occurring on this menu item, by dispatching them to any registered ActionListener objects. This method is not called unless action events are enabled for this component. Action events are enabled when one of the following occurs:

  • An ActionListener object is registered via addActionListener.
  • Action events are enabled via enableEvents.

See Also
ActionEvent, ActionListener, enableEvents


 MenuItem.processEvent

MenuItem.processEvent

Class Overview | Class Members | This Package | All Packages

Syntax
protected void processEvent( AWTEvent e )
Parameters
e
the event.
Description
Processes events on this menu item. If the event is an instance of ActionEvent, it invokes processActionEvent, another method defined by MenuItem.

Currently, menu items only support action events.

Overrides
processEvent in class MenuComponent
See Also
processActionEvent


 MenuItem.removeActionListener

MenuItem.removeActionListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void removeActionListener( ActionListener l )
Parameters
l
the action listener.
Description
Removes the specified action listener so it no longer receives action events from this menu item.

See Also
ActionEvent, ActionListener, addActionListener


 MenuItem.setActionCommand

MenuItem.setActionCommand

Class Overview | Class Members | This Package | All Packages

Syntax
public void setActionCommand( String command )
Parameters
command
the action command to be set for this menu item.
Description
Sets the command name of the action event that is fired by this menu item.

By default, the action command is set to the label of the menu item.

See Also
getActionCommand


 MenuItem.setEnabled

MenuItem.setEnabled

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setEnabled( boolean b )
Parameters
b
if true, enables this menu item; if false, disables it.
Description
Sets whether or not this menu item can be chosen.

See Also
isEnabled


 MenuItem.setLabel

MenuItem.setLabel

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setLabel( String label )
Parameters
label
the new label, or null for no label.
Description
Sets the label for this menu item to the specified label.

See Also
getLabel


 MenuItem.setShortcut

MenuItem.setShortcut

Class Overview | Class Members | This Package | All Packages

Syntax
public void setShortcut( MenuShortcut s )
Parameters
s
the menu shortcut to associate with this menu item.
Description
Set the MenuShortcut object associated with this menu item. If a menu shortcut is already associated with this menu item, it is replaced.

See Also
getShortcut


 Class MenuShortcut

Class java.awt.MenuShortcut

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.MenuShortcut

public class MenuShortcut
extends Object
implements Serializable

A class which represents a keyboard accelerator for a MenuItem.


 MenuShortcut Members

MenuShortcut Members

Class Overview | This Package | All Packages

Constructors
Name | Description
MenuShortcut(int) | Constructs a new MenuShortcut for the specified key.
MenuShortcut(int, boolean) | Constructs a new MenuShortcut for the specified key.

Methods
Name | Description
equals(MenuShortcut) | Returns whether this MenuShortcut is the same as another: equality is defined to mean that both MenuShortcuts use the same key and both either use or don't use the SHIFT key.
getKey() | Return the raw keycode of this MenuShortcut.
paramString() |
toString() | Returns an internationalized description of the MenuShortcut.
usesShiftModifier() | Return whether this MenuShortcut must be invoked using the SHIFT key.


 MenuShortcut.MenuShortcut

MenuShortcut.MenuShortcut

Class Overview | Class Members | This Package | All Packages

Syntax 1
public MenuShortcut( int key )
Parameters
key
the raw keycode for this MenuShortcut, as would be returned in the keyCode field of a KeyEvent if this key were pressed.
Description
Constructs a new MenuShortcut for the specified key.

Syntax 2
public MenuShortcut( int key, boolean useShiftModifier )
Parameters
key
the raw keycode for this MenuShortcut, as would be returned in the keyCode field of a KeyEvent if this key were pressed.
useShiftModifier
indicates whether this MenuShortcut is invoked with the SHIFT key down.
Description
Constructs a new MenuShortcut for the specified key.


 MenuShortcut.equals

MenuShortcut.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( MenuShortcut s )
Parameters
s
the MenuShortcut to compare with this.
Description
Returns whether this MenuShortcut is the same as another: equality is defined to mean that both MenuShortcuts use the same key and both either use or don't use the SHIFT key.


 MenuShortcut.getKey

MenuShortcut.getKey

Class Overview | Class Members | This Package | All Packages

Syntax
public int getKey()
Description
Return the raw keycode of this MenuShortcut.


 MenuShortcut.paramString

MenuShortcut.paramString

Class Overview | Class Members | This Package | All Packages

Syntax
protected String paramString()


 MenuShortcut.toString

MenuShortcut.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Description
Returns an internationalized description of the MenuShortcut.

Overrides
toString in class Object


 MenuShortcut.usesShiftModifier

MenuShortcut.usesShiftModifier

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean usesShiftModifier()
Description
Return whether this MenuShortcut must be invoked using the SHIFT key.


 Class Panel

Class java.awt.Panel

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.Component
           |
           +----java.awt.Container
                   |
                   +----java.awt.Panel

public class Panel
extends Container

Panel is the simplest container class. A panel provides space in which an application can attach any other component, including other panels.

The default layout manager for a panel is the FlowLayout layout manager.

See Also:
FlowLayout


 Panel Members

Panel Members

Class Overview | This Package | All Packages

Constructors
Name | Description
Panel() | Creates a new panel using the default layout manager.
Panel(LayoutManager) | Creates a new panel with the specified layout manager.

Methods
Name | Description
addNotify() | Creates the Panel's peer.


 Panel.Panel

Panel.Panel

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Panel()
Description
Creates a new panel using the default layout manager. The default layout manager for all panels is the FlowLayout class.

Syntax 2
public Panel( LayoutManager layout )
Parameters
layout
the layout manager for this panel.
Description
Creates a new panel with the specified layout manager.


 Panel.addNotify

Panel.addNotify

Class Overview | Class Members | This Package | All Packages

Syntax
public void addNotify()
Description
Creates the Panel's peer. The peer allows you to modify the appearance of the panel without changing its functionality.

Overrides
addNotify in class Container


 Class Point

Class java.awt.Point

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.Point

public class Point
extends Object
implements Serializable

The Point class represents a location in a two-dimensional (x, y) coordinate space.


 Point Members

Point Members

Class Overview | This Package | All Packages

Fields
Name | Description
x | The x coordinate.
y | The y coordinate.

Constructors
Name | Description
Point() | Constructs and initializes a point at the origin (0, 0) of the coordinate space.
Point(int, int) | Constructs and initializes a point at the specified (x, y) location in the coordinate space.
Point(Point) | Constructs and initializes a point with the same location as the specified Point object.

Methods
Name | Description
equals(Object) | Determines whether two points are equal.
getLocation() | Returns the location of this point.
hashCode() | Returns the hashcode for this point.
move(int, int) | Moves this point to the specificed location in the (x, y) coordinate plane.
setLocation(int, int) | Changes the point to have the specificed location.
setLocation(Point) | Sets the location of the point to the specificed location.
toString() | Returns a representation of this point and its location in the (x, y) coordinate space as a string.
translate(int, int) | Translates this point, at location (x, y), by dx along the x axis and dy along the y axis so that it now represents the point (x + dx, y + dy).


 Point.x

Point.x

Class Overview | Class Members | This Package | All Packages

Syntax
public int x
Description
The x coordinate.


 Point.y

Point.y

Class Overview | Class Members | This Package | All Packages

Syntax
public int y
Description
The y coordinate.


 Point.Point

Point.Point

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Point()
Parameters
x
the x coordinate.
y
the y coordinate.
Description
Constructs and initializes a point at the origin (0, 0) of the coordinate space.

Syntax 2
public Point( Point p )
Parameters
p
a point.
Description
Constructs and initializes a point with the same location as the specified Point object.

Syntax 3
public Point( int x, int y )
Parameters
x
the x coordinate.
y
the y coordinate.
Description
Constructs and initializes a point at the specified (x, y) location in the coordinate space.


 Point.equals

Point.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Parameters
obj
an object to be compared with this point.
Returns
true if the object to be compared is an instance of Point and has the same values; false otherwise.
Description
Determines whether two points are equal. Two instances of Point are equal if the values of their x and y member fields, representing their position in the coordinate space, are the same.

Overrides
equals in class Object


 Point.getLocation

Point.getLocation

Class Overview | Class Members | This Package | All Packages

Syntax
public Point getLocation()
Returns
a copy of this point, at the same location.
Description
Returns the location of this point. This method is included for completeness, to parallel the getLocation method of Component.

See Also
getLocation, setLocation, setLocation


 Point.hashCode

Point.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int hashCode()
Returns
a hash code for this point.
Description
Returns the hashcode for this point.

Overrides
hashCode in class Object


 Point.move

Point.move

Class Overview | Class Members | This Package | All Packages

Syntax
public void move( int x, int y )
Parameters
x
the x coordinate of the new location.
y
the y coordinate of the new location.
Description
Moves this point to the specificed location in the (x, y) coordinate plane. This method is identical with setLocation(int, int).

See Also
setLocation


 Point.setLocation

Point.setLocation

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void setLocation( Point p )
Parameters
p
a point, the new location for this point.
Description
Sets the location of the point to the specificed location. This method is included for completeness, to parallel the setLocation method of Component.

See Also
setLocation, getLocation

Syntax 2
public void setLocation( int x, int y )
Parameters
x
the x coordinate of the new location.
y
the y coordinate of the new location.
Description
Changes the point to have the specificed location.

This method is included for completeness, to parallel the setLocation method of Component. Its behavior is identical with move(int, int).

See Also
setLocation, getLocation, move


 Point.toString

Point.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string representation of this point, including the values of its member fields.
Description
Returns a representation of this point and its location in the (x, y) coordinate space as a string.

Overrides
toString in class Object


 Point.translate

Point.translate

Class Overview | Class Members | This Package | All Packages

Syntax
public void translate( int x, int y )
Parameters
dx
the distance to move this point along the x axis.
dy
the distance to move this point along the y axis.
Description
Translates this point, at location (x, y), by dx along the x axis and dy along the y axis so that it now represents the point (x + dx, y + dy).


 Class Polygon

Class java.awt.Polygon

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.Polygon

public class Polygon
extends Object
implements Shape, Serializable

The Polygon class encapsulates a description of a closed, two-dimensional region within a coordinate space. This region is bounded by an arbitrary number of line segments, each of which is one side of the polygon. Internally, a polygon comprises of a list of (x, y) coordinate pairs, where each pair defines a vertex of the polygon, and two successive pairs are the endpoints of a line that is a side of the polygon. The first and final pairs of (x, y) points are joined by a line segment that closes the polygon.


 Polygon Members

Polygon Members

Class Overview | This Package | All Packages

Fields
Name | Description
bounds |
npoints | The total number of points.
xpoints | The array of x coordinates.
ypoints | The array of y coordinates.

Constructors
Name | Description
Polygon() | Creates an empty polygon.
Polygon(int[], int[], int) | Constructs and initializes a polygon from the specified parameters.

Methods
Name | Description
addPoint(int, int) | Appends a point to this polygon.
contains(int, int) | Determines whether the specified point is contained by this polygon.
contains(Point) | Determines whether the specified point is inside the Polygon.
getBoundingBox() | Deprecated.
getBounds() | Gets the bounding box of this polygon.
inside(int, int) | Deprecated.
translate(int, int) | Translates the vertices by deltaX along the x axis and by deltaY along the y axis.


 Polygon.bounds

Polygon.bounds

Class Overview | Class Members | This Package | All Packages

Syntax
protected Rectangle bounds


 Polygon.npoints

Polygon.npoints

Class Overview | Class Members | This Package | All Packages

Syntax
public int npoints
Description
The total number of points.


 Polygon.xpoints

Polygon.xpoints

Class Overview | Class Members | This Package | All Packages

Syntax
public int xpoints[]
Description
The array of x coordinates.


 Polygon.ypoints

Polygon.ypoints

Class Overview | Class Members | This Package | All Packages

Syntax
public int ypoints[]
Description
The array of y coordinates.


 Polygon.Polygon

Polygon.Polygon

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Polygon()
Description
Creates an empty polygon.

Syntax 2
public Polygon( int xpoints[], int ypoints[], int npoints )
Parameters
xpoints
an array of x coordinates.
ypoints
an array of y coordinates.
npoints
the total number of points in the polygon.
Description
Constructs and initializes a polygon from the specified parameters.

Exceptions
NegativeArraySizeException if the value of npoints is negative.


 Polygon.addPoint

Polygon.addPoint

Class Overview | Class Members | This Package | All Packages

Syntax
public void addPoint( int x, int y )
Parameters
x
the x coordinate of the point.
y
the y coordinate of the point.
Description
Appends a point to this polygon.

If an operation that calculates the bounding box of this polygon has already been performed, such as getBounds or contains, then this method updates the bounding box.

See Also
getBounds, contains


 Polygon.contains

Polygon.contains

Class Overview | Class Members | This Package | All Packages

Syntax 1
public boolean contains( Point p )
Parameters
p
the point to be tested
Description
Determines whether the specified point is inside the Polygon. Uses an even-odd insideness rule (also known as an alternating rule).

Syntax 2
public boolean contains( int x, int y )
Parameters
x
the x coordinate of the point to be tested.
y
the y coordinate of the point to be tested.
Returns
true if the point (x, y) is contained by this polygon; false otherwise.
Description
Determines whether the specified point is contained by this polygon.

(The contains method is based on code by Hanpeter van Vliet [hvvliet@inter.nl.net].)


 Polygon.getBoundingBox

Polygon.getBoundingBox

Class Overview | Class Members | This Package | All Packages

Syntax
public Rectangle getBoundingBox()
Description
Note: getBoundingBox() is deprecated. As of JDK version 1.1, replaced by getBounds().


 Polygon.getBounds

Polygon.getBounds

Class Overview | Class Members | This Package | All Packages

Syntax
public Rectangle getBounds()
Returns
a rectangle that defines the bounds of this polygon.
Description
Gets the bounding box of this polygon. The bounding box is the smallest rectangle whose sides are parallel to the x and y axes of the coordinate space, and that can completely contain the polygon.


 Polygon.inside

Polygon.inside

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean inside( int x, int y )
Description
Note: inside() is deprecated. As of JDK version 1.1, replaced by contains(int, int).


 Polygon.translate

Polygon.translate

Class Overview | Class Members | This Package | All Packages

Syntax
public void translate( int deltaX, int deltaY )
Parameters
deltaX
the amount to translate along the x axis
deltaY
the amount to translate along the y axis
Description
Translates the vertices by deltaX along the x axis and by deltaY along the y axis.


 Class PopupMenu

Class java.awt.PopupMenu

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.MenuComponent
           |
           +----java.awt.MenuItem
                   |
                   +----java.awt.Menu
                           |
                           +----java.awt.PopupMenu

public class PopupMenu
extends Menu

A class that implements a menu which can be dynamically popped up at a specified position within a component.


 PopupMenu Members

PopupMenu Members

Class Overview | This Package | All Packages

Constructors
Name | Description
PopupMenu() | Creates a new popup menu.
PopupMenu(String) | Creates a new popup menu with the specified name.

Methods
Name | Description
addNotify() | Creates the popup menu's peer.
show(Component, int, int) | Shows the popup menu at the x, y position relative to an origin component.


 PopupMenu.PopupMenu

PopupMenu.PopupMenu

Class Overview | Class Members | This Package | All Packages

Syntax 1
public PopupMenu()
Description
Creates a new popup menu.

Syntax 2
public PopupMenu( String label )
Parameters
title
the title string for the popup menu
Description
Creates a new popup menu with the specified name.


 PopupMenu.addNotify

PopupMenu.addNotify

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void addNotify()
Description
Creates the popup menu's peer. The peer allows us to change the appearance of the popup menu without changing any of the popup menu's functionality.

Overrides
addNotify in class Menu


 PopupMenu.show

PopupMenu.show

Class Overview | Class Members | This Package | All Packages

Syntax
public void show( Component origin, int x, int y )
Parameters
origin
the component which defines the coordinate space
x
the x coordinate position to popup the menu
y
the y coordinate position to popup the menu
Description
Shows the popup menu at the x, y position relative to an origin component. The origin component must be contained within the component hierarchy of the popup menu's parent. Both the origin and the parent must be showing on the screen for this method to be valid.


 Interface PrintGraphics

Interface java.awt.PrintGraphics

Interface Members | This Package | All Packages

public interface PrintGraphics

An abstract class which provides a print graphics context for a page.


 PrintGraphics Members

PrintGraphics Members

Interface Overview | This Package | All Packages

Methods
Name | Description
getPrintJob() | Returns the PrintJob object from which this PrintGraphics object originated.


 PrintGraphics.getPrintJob

PrintGraphics.getPrintJob

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract PrintJob getPrintJob()
Description
Returns the PrintJob object from which this PrintGraphics object originated.


 Class PrintJob

Class java.awt.PrintJob

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.PrintJob

public abstract class PrintJob
extends Object

An abstract class which initiates and executes a print job. It provides access to a print graphics object which renders to an appropriate print device.

See Also:
getPrintJob


 PrintJob Members

PrintJob Members

Class Overview | This Package | All Packages

Constructors
Name | Description
PrintJob() |

Methods
Name | Description
end() | Ends the print job and does any necessary cleanup.
finalize() | Ends this print job once it is no longer referenced.
getGraphics() | Gets a Graphics object that will draw to the next page.
getPageDimension() | Returns the dimensions of the page in pixels.
getPageResolution() | Returns the resolution of the page in pixels per inch.
lastPageFirst() | Returns true if the last page will be printed first.


 PrintJob.PrintJob

PrintJob.PrintJob

Class Overview | Class Members | This Package | All Packages

Syntax
public PrintJob()


 PrintJob.end

PrintJob.end

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void end()
Description
Ends the print job and does any necessary cleanup.


 PrintJob.finalize

PrintJob.finalize

Class Overview | Class Members | This Package | All Packages

Syntax
public void finalize()
Description
Ends this print job once it is no longer referenced.

Overrides
finalize in class Object
See Also
end


 PrintJob.getGraphics

PrintJob.getGraphics

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract Graphics getGraphics()
Description
Gets a Graphics object that will draw to the next page. The page is sent to the printer when the graphics object is disposed. This graphics object will also implement the PrintGraphics interface.

See Also
PrintGraphics


 PrintJob.getPageDimension

PrintJob.getPageDimension

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract Dimension getPageDimension()
Description
Returns the dimensions of the page in pixels. The resolution of the page is chosen so that it is similar to the screen resolution.


 PrintJob.getPageResolution

PrintJob.getPageResolution

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract int getPageResolution()
Description
Returns the resolution of the page in pixels per inch. Note that this doesn't have to correspond to the physical resolution of the printer.


 PrintJob.lastPageFirst

PrintJob.lastPageFirst

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract boolean lastPageFirst()
Description
Returns true if the last page will be printed first.


 Class Rectangle

Class java.awt.Rectangle

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.Rectangle

public class Rectangle
extends Object
implements Shape, Serializable

A rectangle specifies an area in a coordinate space that is defined by the rectangle's top-left point (x, y) in the coordinate space, its width, and its height.

A rectangle's width and height are public fields. The constructors that allow you to create a rectangle, and the methods that allow you to modify one, do not prevent you from setting a negative value for width or height.

A rectangle whose width or height is negative is considered empty, and all methods defined by the Rectangle class behave accordingly. If the rectangle is empty, then the method isEmpty returns true. No point can be contained by or inside an empty rectangle, however the values of width and height are still valid. An empty rectangle still has a location in the coordinate space, and methods that change its size or location remain valid. The behavior of methods that operate on more than one rectangle is undefined if any of the participating rectangles has a negative width or height. These methods include intersects, intersection, and union.


 Rectangle Members

Rectangle Members

Class Overview | This Package | All Packages

Fields
Name | Description
height | The height of the rectangle.
width | The width of the rectangle.
x | The x coordinate of the rectangle.
y | The y coordinate of the rectangle.

Constructors
Name | Description
Rectangle() | Constructs a new rectangle whose top-left corner is at (0, 0) in the coordinate space, and whose width and height are zero.
Rectangle(Dimension) | Constructs a new rectangle whose top left corner is (0, 0) and whose width and height are specified by the dimension argument.
Rectangle(int, int) | Constructs a new rectangle whose top-left corner is at (0, 0) in the coordinate space, and whose width and height are specified by the arguments of the same name.
Rectangle(int, int, int, int) | Constructs a new rectangle whose top-left corner is specified as (x, y) and whose width and height are specified by the arguments of the same name.
Rectangle(Point) | Constructs a new rectangle whose top-left corner is the specified point, and whose width and height are zero.
Rectangle(Point, Dimension) | Constructs a new rectangle whose top-left corner is specified by the point argument, and whose width and height are specified by the dimension argument.
Rectangle(Rectangle) | Constructs a new rectangle, initialized to match the values of the specificed rectangle.

Methods
Name | Description
add(int, int) | Adds a point, specified by the integer arguments newx and newy, to a rectangle.
add(Point) | Adds a point to this rectangle.
add(Rectangle) | Adds a rectangle to this rectangle.
contains(int, int) | Checks whether this rectangle contains the point at the specified location (x, y).
contains(Point) | Checks whether this rectangle contains the specified point.
equals(Object) | Checks whether two rectangles are equal.
getBounds() | Gets the bounding rectangle of this rectangle.
getLocation() | Returns the location of this rectangle.
getSize() | Gets the size (width and height) of this rectangle.
grow(int, int) | Grows the rectangle both horizontally and vertically.
hashCode() | Returns the hashcode for this rectangle.
inside(int, int) | Deprecated.
intersection(Rectangle) | Computes the intersection of this rectangle with the specified rectangle.
intersects(Rectangle) | Determines whether this rectangle and the specified rectangle intersect.
isEmpty() | Determines whether this rectangle is empty.
move(int, int) | Deprecated.
reshape(int, int, int, int) | Deprecated.
resize(int, int) | Deprecated.
setBounds(int, int, int, int) | Sets the bounding rectangle of this rectangle to the specified values for x, y, width, and height.
setBounds(Rectangle) | Sets the bounding rectangle of this rectangle to match the specified rectangle.
setLocation(int, int) | Moves the rectangle to the specified location.
setLocation(Point) | Moves the rectangle to the specified location.
setSize(Dimension) | Sets the size of this rectangle to match the specified dimension.
setSize(int, int) | Sets the size of this rectangle to the specified width and height.
toString() | Returns a string representation of this rectangle and its values.
translate(int, int) | Translates the rectangle the indicated distance, to the right along the x coordinate axis, and downward along the y coordinate axis.
union(Rectangle) | Computes the union of this rectangle with the specified rectangle.


 Rectangle.height

Rectangle.height

Class Overview | Class Members | This Package | All Packages

Syntax
public int height
Description
The height of the rectangle.


 Rectangle.width

Rectangle.width

Class Overview | Class Members | This Package | All Packages

Syntax
public int width
Description
The width of the rectangle.


 Rectangle.x

Rectangle.x

Class Overview | Class Members | This Package | All Packages

Syntax
public int x
Description
The x coordinate of the rectangle.


 Rectangle.y

Rectangle.y

Class Overview | Class Members | This Package | All Packages

Syntax
public int y
Description
The y coordinate of the rectangle.


 Rectangle.Rectangle

Rectangle.Rectangle

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Rectangle()
Description
Constructs a new rectangle whose top-left corner is at (0, 0) in the coordinate space, and whose width and height are zero.

Syntax 2
public Rectangle( Rectangle r )
Parameters
r
a rectangle from which to copy initial values.
Description
Constructs a new rectangle, initialized to match the values of the specificed rectangle.

Syntax 3
public Rectangle( int x, int y, int width, int height )
Parameters
x
the x coordinate.
y
the y coordinate.
width
the width of the rectangle.
height
the height of the rectangle.
Description
Constructs a new rectangle whose top-left corner is specified as (x, y) and whose width and height are specified by the arguments of the same name.

Syntax 4
public Rectangle( int width, int height )
Parameters
width
the width of the rectangle.
height
the height of the rectangle.
Description
Constructs a new rectangle whose top-left corner is at (0, 0) in the coordinate space, and whose width and height are specified by the arguments of the same name.

Syntax 5
public Rectangle( Point p, Dimension d )
Parameters
p
a point, the top-left corner of the rectangle.
d
a dimension, representing the width and height.
Description
Constructs a new rectangle whose top-left corner is specified by the point argument, and whose width and height are specified by the dimension argument.

Syntax 6
public Rectangle( Point p )
Parameters
p
the top left corner of the rectangle.
Description
Constructs a new rectangle whose top-left corner is the specified point, and whose width and height are zero.

Syntax 7
public Rectangle( Dimension d )
Parameters
d
a dimension, specifying width and height.
Description
Constructs a new rectangle whose top left corner is (0, 0) and whose width and height are specified by the dimension argument.


 Rectangle.add

Rectangle.add

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void add( int newx, int newy )
Parameters
newx
the x coordinate of the new point.
newy
the y coordinate of the new point.
Description
Adds a point, specified by the integer arguments newx and newy, to a rectangle. The resulting rectangle is the smallest rectangle that contains both the rectangle and the specified point.

Syntax 2
public void add( Point pt )
Parameters
a
point.
Description
Adds a point to this rectangle. The resulting rectangle is the smallest rectangle that contains both the rectangle and the specified point.

Syntax 3
public void add( Rectangle r )
Parameters
a
rectangle.
Description
Adds a rectangle to this rectangle. The resulting rectangle is the union of the two rectangles.


 Rectangle.contains

Rectangle.contains

Class Overview | Class Members | This Package | All Packages

Syntax 1
public boolean contains( Point p )
Parameters
p
the point (location) to test.
Returns
true if the point (x, y) is inside this rectangle; false otherwise.
Description
Checks whether this rectangle contains the specified point.

Syntax 2
public boolean contains( int x, int y )
Parameters
x
the x coordinate.
y
the y coordinate.
Returns
true if the point (x, y) is inside this rectangle; false otherwise.
Description
Checks whether this rectangle contains the point at the specified location (x, y).


 Rectangle.equals

Rectangle.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Parameters
obj
the object to compare with.
Returns
true if the objects are equal; false otherwise.
Description
Checks whether two rectangles are equal.

The result is true if and only if the argument is not null and is a Rectangle object that has the same top-left corner, width, and height as this rectangle.

Overrides
equals in class Object


 Rectangle.getBounds

Rectangle.getBounds

Class Overview | Class Members | This Package | All Packages

Syntax
public Rectangle getBounds()
Returns
a new rectangle, equal to the bounding rectangle for this rectangle.
Description
Gets the bounding rectangle of this rectangle.

This method is included for completeness, to parallel the getBounds method of Component.

See Also
getBounds


 Rectangle.getLocation

Rectangle.getLocation

Class Overview | Class Members | This Package | All Packages

Syntax
public Point getLocation()
Description
Returns the location of this rectangle.

This method is included for completeness, to parallel the getLocation method of Component.

See Also
getLocation


 Rectangle.getSize

Rectangle.getSize

Class Overview | Class Members | This Package | All Packages

Syntax
public Dimension getSize()
Returns
a dimension, representing the size.
Description
Gets the size (width and height) of this rectangle.

This method is included for completeness, to parallel the getSize method of Component.

See Also
getSize


 Rectangle.grow

Rectangle.grow

Class Overview | Class Members | This Package | All Packages

Syntax
public void grow( int h, int v )
Parameters
h
the horizontal expansion.
v
the vertical expansion.
Description
Grows the rectangle both horizontally and vertically.

This method modifies the rectangle so that it is h units larger on both the left and right side, and v units larger at both the top and bottom.

The new rectangle has (x - h, y - v) as its top-left corner, a width of width + 2h, and a height of height + 2v.

If negative values are supplied for h and v, the size of the rectangle decreases accordingly. The grow method does not check whether the resulting values of width and height are non-negative.


 Rectangle.hashCode

Rectangle.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int hashCode()
Returns
the hashcode for this rectangle.
Description
Returns the hashcode for this rectangle.

Overrides
hashCode in class Object


 Rectangle.inside

Rectangle.inside

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean inside( int x, int y )
Description
Note: inside() is deprecated. As of JDK version 1.1, replaced by contains(int, int).


 Rectangle.intersection

Rectangle.intersection

Class Overview | Class Members | This Package | All Packages

Syntax
public Rectangle intersection( Rectangle r )
Parameters
r
a rectangle.
Returns
the largest rectangle contained in both the specified rectangle and in this rectangle.
Description
Computes the intersection of this rectangle with the specified rectangle. Returns a new rectangle that represents the intersection of the two rectangles.


 Rectangle.intersects

Rectangle.intersects

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean intersects( Rectangle r )
Parameters
r
a rectangle.
Returns
true if the specified rectangle and this rectangle insersect; false otherwise.
Description
Determines whether this rectangle and the specified rectangle intersect. Two rectangles intersect if their intersection is nonempty.


 Rectangle.isEmpty

Rectangle.isEmpty

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isEmpty()
Returns
true if this rectangle is empty; false otherwise.
Description
Determines whether this rectangle is empty. A rectangle is empty if its width or its height is less than or equal to zero.


 Rectangle.move

Rectangle.move

Class Overview | Class Members | This Package | All Packages

Syntax
public void move( int x, int y )
Description
Note: move() is deprecated. As of JDK version 1.1, replaced by setLocation(int, int).


 Rectangle.reshape

Rectangle.reshape

Class Overview | Class Members | This Package | All Packages

Syntax
public void reshape( int x, int y, int width, int height )
Description
Note: reshape() is deprecated. As of JDK version 1.1, replaced by setBounds(int, int, int, int).


 Rectangle.resize

Rectangle.resize

Class Overview | Class Members | This Package | All Packages

Syntax
public void resize( int width, int height )
Description
Note: resize() is deprecated. As of JDK version 1.1, replaced by setSize(int, int).


 Rectangle.setBounds

Rectangle.setBounds

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void setBounds( Rectangle r )
Parameters
r
a rectangle.
Description
Sets the bounding rectangle of this rectangle to match the specified rectangle.

This method is included for completeness, to parallel the setBounds method of Component.

See Also
setBounds

Syntax 2
public void setBounds( int x, int y, int width, int height )
Parameters
x
the new x coordinate for the top-left corner of this rectangle.
y
the new y coordinate for the top-left corner of this rectangle.
width
the new width for this rectangle.
height
the new height for this rectangle.
Description
Sets the bounding rectangle of this rectangle to the specified values for x, y, width, and height.

This method is included for completeness, to parallel the setBounds method of Component.

See Also
setBounds


 Rectangle.setLocation

Rectangle.setLocation

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void setLocation( Point p )
Parameters
p
the new location for the point.
Description
Moves the rectangle to the specified location.

This method is included for completeness, to parallel the setLocation method of Component.

See Also
setLocation

Syntax 2
public void setLocation( int x, int y )
Parameters
x
the x coordinate of the new location.
y
the y coordinate of the new location.
Description
Moves the rectangle to the specified location.

This method is included for completeness, to parallel the setLocation method of Component.

See Also
setLocation


 Rectangle.setSize

Rectangle.setSize

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void setSize( Dimension d )
Parameters
d
the new size for the Dimension object
Description
Sets the size of this rectangle to match the specified dimension.

This method is included for completeness, to parallel the setSize method of Component.

See Also
setSize

Syntax 2
public void setSize( int width, int height )
Parameters
width
the new width for this rectangle object.
height
the new height for this rectangle object.
Description
Sets the size of this rectangle to the specified width and height.

This method is included for completeness, to parallel the setSize method of Component.

See Also
setSize


 Rectangle.toString

Rectangle.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string representation of this rectangle.
Description
Returns a string representation of this rectangle and its values.

Overrides
toString in class Object


 Rectangle.translate

Rectangle.translate

Class Overview | Class Members | This Package | All Packages

Syntax
public void translate( int x, int y )
Parameters
dx
the distance to move the rectangle along the x axis.
dy
the distance to move the rectangle along the y axis.
Description
Translates the rectangle the indicated distance, to the right along the x coordinate axis, and downward along the y coordinate axis.

See Also
setLocation, setLocation


 Rectangle.union

Rectangle.union

Class Overview | Class Members | This Package | All Packages

Syntax
public Rectangle union( Rectangle r )
Parameters
r
a rectangle.
Returns
the smallest rectangle containing both the specified rectangle and this rectangle.
Description
Computes the union of this rectangle with the specified rectangle. Returns a new rectangle that represents the union of the two rectangles.


 Class ScrollPane

Class java.awt.ScrollPane

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.Component
           |
           +----java.awt.Container
                   |
                   +----java.awt.ScrollPane

public class ScrollPane
extends Container

A container class which implements automatic horizontal and/or vertical scrolling for a single child component. The display policy for the scrollbars can be set to:

  1. as needed: scrollbars created and shown only when needed by scrollpane
  2. always: scrollbars created and always shown by the scrollpane
  3. never: scrollbars never created or shown by the scrollpane

The state of the horizontal and vertical scrollbars is represented by two objects (one for each dimension) which implement the Adjustable interface. The API provides methods to access those objects such that the attributes on the Adjustable object (such as unitIncrement, value, etc.) can be manipulated.

Certain adjustable properties (minimum, maximum, blockIncrement, and visibleAmount) are set internally by the scrollpane in accordance with the geometry of the scrollpane and its child and these should not be set by programs using the scrollpane.

If the scrollbar display policy is defined as "never", then the scrollpane can still be programmatically scrolled using the setScrollPosition() method and the scrollpane will move and clip the child's contents appropriately. This policy is useful if the program needs to create and manage its own adjustable controls.

The placement of the scrollbars is controlled by platform-specific properties set by the user outside of the program.

The initial size of this container is set to 100x100, but can be reset using setSize().

Insets are used to define any space used by scrollbars and any borders created by the scroll pane. getInsets() can be used to get the current value for the insets. If the value of scrollbarsAlwaysVisible is false, then the value of the insets will change dynamically depending on whether the scrollbars are currently visible or not.


 ScrollPane Members

ScrollPane Members

Class Overview | This Package | All Packages

Fields
Name | Description
SCROLLBARS_ALWAYS | Specifies that horizontal/vertical scrollbars should always be shown regardless of the respective sizes of the scrollpane and child.
SCROLLBARS_AS_NEEDED | Specifies that horizontal/vertical scrollbar should be shown only when the size of the child exceeds the size of the scrollpane in the horizontal/vertical dimension.
SCROLLBARS_NEVER | Specifies that horizontal/vertical scrollbars should never be shown regardless of the respective sizes of the scrollpane and child.

Constructors
Name | Description
ScrollPane() | Create a new scrollpane container with a scrollbar display policy of "as needed".
ScrollPane(int) | Create a new scrollpane container.

Methods
Name | Description
addImpl(Component, Object, int) | Adds the specified component to this scroll pane container.
addNotify() | Creates the scroll pane's peer.
doLayout() | Lays out this container by resizing its child to its preferred size.
getHAdjustable() | Returns the Adjustable object which represents the state of the horizontal scrollbar.
getHScrollbarHeight() | Returns the height that would be occupied by a horizontal scrollbar, which is independent of whether it is currently displayed by the scroll pane or not.
getScrollbarDisplayPolicy() | Returns the display policy for the scrollbars.
getScrollPosition() | Returns the current x,y position within the child which is displayed at the 0,0 location of the scrolled panel's view port.
getVAdjustable() | Returns the Adjustable object which represents the state of the vertical scrollbar.
getViewportSize() | Returns the current size of the scroll pane's view port.
getVScrollbarWidth() | Returns the width that would be occupied by a vertical scrollbar, which is independent of whether it is currently displayed by the scroll pane or not.
layout() | Deprecated.
paramString() | Returns the parameter string representing the state of this container.
printComponents(Graphics) | Prints the component in this scroll pane.
setLayout(LayoutManager) | Sets the layout manager for this container.
setScrollPosition(int, int) | Scrolls to the specified position within the child component.
setScrollPosition(Point) | Scrolls to the specified position within the child component.


 ScrollPane.SCROLLBARS_ALWAYS

ScrollPane.SCROLLBARS_ALWAYS

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SCROLLBARS_ALWAYS
Description
Specifies that horizontal/vertical scrollbars should always be shown regardless of the respective sizes of the scrollpane and child.


 ScrollPane.SCROLLBARS_AS_NEEDED

ScrollPane.SCROLLBARS_AS_NEEDED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SCROLLBARS_AS_NEEDED
Description
Specifies that horizontal/vertical scrollbar should be shown only when the size of the child exceeds the size of the scrollpane in the horizontal/vertical dimension.


 ScrollPane.SCROLLBARS_NEVER

ScrollPane.SCROLLBARS_NEVER

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SCROLLBARS_NEVER
Description
Specifies that horizontal/vertical scrollbars should never be shown regardless of the respective sizes of the scrollpane and child.


 ScrollPane.ScrollPane

ScrollPane.ScrollPane

Class Overview | Class Members | This Package | All Packages

Syntax 1
public ScrollPane()
Description
Create a new scrollpane container with a scrollbar display policy of "as needed".

Syntax 2
public ScrollPane( int scrollbarDisplayPolicy )
Parameters
scrollbarDisplayPolicy
policy for when scrollbars should be shown
Description
Create a new scrollpane container.


 ScrollPane.addImpl

ScrollPane.addImpl

Class Overview | Class Members | This Package | All Packages

Syntax
protected final void addImpl( Component comp, Object constraints, int index )
Parameters
comp
the component to be added
constraints
not applicable
index
position of child component (must be <= 0)
Description
Adds the specified component to this scroll pane container. If the scroll pane has an existing child component, that component is removed and the new one is added.

Overrides
addImpl in class Container


 ScrollPane.addNotify

ScrollPane.addNotify

Class Overview | Class Members | This Package | All Packages

Syntax
public void addNotify()
Description
Creates the scroll pane's peer.

Overrides
addNotify in class Container


 ScrollPane.doLayout

ScrollPane.doLayout

Class Overview | Class Members | This Package | All Packages

Syntax
public void doLayout()
Description
Lays out this container by resizing its child to its preferred size. If the new preferred size of the child causes the current scroll position to be invalid, the scroll position is set to the closest valid position.

Overrides
doLayout in class Container
See Also
validate


 ScrollPane.getHAdjustable

ScrollPane.getHAdjustable

Class Overview | Class Members | This Package | All Packages

Syntax
public Adjustable getHAdjustable()
Description
Returns the Adjustable object which represents the state of the horizontal scrollbar. If the scrollbar display policy is "never", this method returns null.


 ScrollPane.getHScrollbarHeight

ScrollPane.getHScrollbarHeight

Class Overview | Class Members | This Package | All Packages

Syntax
public int getHScrollbarHeight()
Returns
the height of a horizontal scrollbar in pixels
Description
Returns the height that would be occupied by a horizontal scrollbar, which is independent of whether it is currently displayed by the scroll pane or not.


 ScrollPane.getScrollbarDisplayPolicy

ScrollPane.getScrollbarDisplayPolicy

Class Overview | Class Members | This Package | All Packages

Syntax
public int getScrollbarDisplayPolicy()
Returns
the display policy for the scrollbars
Description
Returns the display policy for the scrollbars.


 ScrollPane.getScrollPosition

ScrollPane.getScrollPosition

Class Overview | Class Members | This Package | All Packages

Syntax
public Point getScrollPosition()
Returns
the coordinate position for the current scroll position
Description
Returns the current x,y position within the child which is displayed at the 0,0 location of the scrolled panel's view port. This is a convenience method which interfaces with the adjustable objects which respresent the state of the scrollbars.


 ScrollPane.getVAdjustable

ScrollPane.getVAdjustable

Class Overview | Class Members | This Package | All Packages

Syntax
public Adjustable getVAdjustable()
Description
Returns the Adjustable object which represents the state of the vertical scrollbar. If the scrollbar display policy is "never", this method returns null.


 ScrollPane.getViewportSize

ScrollPane.getViewportSize

Class Overview | Class Members | This Package | All Packages

Syntax
public Dimension getViewportSize()
Returns
the size of the view port in pixels
Description
Returns the current size of the scroll pane's view port.


 ScrollPane.getVScrollbarWidth

ScrollPane.getVScrollbarWidth

Class Overview | Class Members | This Package | All Packages

Syntax
public int getVScrollbarWidth()
Returns
the width of a vertical scrollbar in pixels
Description
Returns the width that would be occupied by a vertical scrollbar, which is independent of whether it is currently displayed by the scroll pane or not.


 ScrollPane.layout

ScrollPane.layout

Class Overview | Class Members | This Package | All Packages

Syntax
public void layout()
Description
Note: layout() is deprecated. As of JDK version 1.1, replaced by doLayout().

Overrides
layout in class Container


 ScrollPane.paramString

ScrollPane.paramString

Class Overview | Class Members | This Package | All Packages

Syntax
public String paramString()
Description
Returns the parameter string representing the state of this container.

Overrides
paramString in class Container


 ScrollPane.printComponents

ScrollPane.printComponents

Class Overview | Class Members | This Package | All Packages

Syntax
public void printComponents( Graphics g )
Parameters
g
the specified Graphics window
Description
Prints the component in this scroll pane.

Overrides
printComponents in class Container
See Also
print, printAll


 ScrollPane.setLayout

ScrollPane.setLayout

Class Overview | Class Members | This Package | All Packages

Syntax
public final void setLayout( LayoutManager mgr )
Parameters
mgr
the specified layout manager
Description
Sets the layout manager for this container. This method is overridden to prevent the layout mgr from being set.

Overrides
setLayout in class Container


 ScrollPane.setScrollPosition

ScrollPane.setScrollPosition

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void setScrollPosition( int x, int y )
Parameters
x
the x position to scroll to
y
the y position to scroll to
Description
Scrolls to the specified position within the child component. A call to this method is only valid if the scroll pane contains a child. Specifying a position outside of the legal scrolling bounds of the child will scroll to the closest legal position. Legal bounds are defined to be the rectangle: x = 0, y = 0, width = (child width - view port width), height = (child height - view port height). This is a convenience method which interfaces with the Adjustable objects which respresent the state of the scrollbars.

Exceptions
IllegalArgumentException if specified coordinates are not within the legal scrolling bounds of the child component.

Syntax 2
public void setScrollPosition( Point p )
Parameters
p
the Point representing the position to scroll to
Description
Scrolls to the specified position within the child component. A call to this method is only valid if the scroll pane contains a child and the specified position is within legal scrolling bounds of the child. Legal bounds are defined to be the rectangle: x = 0, y = 0, width = (child width - view port width), height = (child height - view port height). This is a convenience method which interfaces with the Adjustable objects which respresent the state of the scrollbars.

Exceptions
IllegalArgumentException if specified coordinates are not within the legal scrolling bounds of the child component.


 Class Scrollbar

Class java.awt.Scrollbar

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.Component
           |
           +----java.awt.Scrollbar

public class Scrollbar
extends Component
implements Adjustable

The Scrollbar class embodies a scroll bar, a familiar user-interface object. A scroll bar provides a convenient means for allowing a user to select from a range of values. The following three vertical scroll bars could be used as slider controls to pick the red, green, and blue components of a color:

Each scroll bar in this example could be created with code similar to the following:

 redSlider=new Scrollbar(Scrollbar.VERTICAL, 0, 1, 0, 255);
 add(redSlider);

Alternatively, a scroll bar can represent a range of values. For example, if a scroll bar is used for scrolling through text, the width of the "bubble" or "thumb" can represent the amount of text that is visible. Here is an example of a scroll bar that represents a range:

The value range represented by the bubble is the visible range of the scroll bar. The horizontal scroll bar in this example could be created with code like the following:

 ranger = new Scrollbar(Scrollbar.HORIZONTAL, 0, 64, 0, 255);
 add(ranger);

Note that the maximum value above, 255, is the maximum value for the scroll bar's bubble. The actual width of the scroll bar's track is 255 + 64. When the scroll bar is set to its maximum value, the left side of the bubble is at 255, and the right side is at 255 + 64.

Normally, the user changes the value of the scroll bar by making a gesture with the mouse. For example, the user can drag the scroll bar's bubble up and down, or click in the scroll bar's unit increment or block increment areas. Keyboard gestures can also be mapped to the scroll bar. By convention, the Page Up and Page Down keys are equivalent to clicking in the scroll bar's block increment and block decrement areas.

When the user changes the value of the scroll bar, the scroll bar receives an instance of AdjustmentEvent. The scroll bar processes this event, passing it along to any registered listeners.

Any object that wishes to be notified of changes to the scroll bar's value should implement AdjustmentListener, an interface defined in the package java.awt.event. Listeners can be added and removed dynamically by calling the methods addAdjustmentListener and removeAdjustmentListener.

The AdjustmentEvent class defines five types of adjustment event, listed here:

  • AdjustmentEvent.TRACK is sent out when the user drags the scroll bar's bubble.
  • AdjustmentEvent.UNIT_INCREMENT is sent out when the user clicks in the left arrow of a horizontal scroll bar, or the top arrow of a vertical scroll bar, or makes the equivalent gesture from the keyboard.
  • AdjustmentEvent.UNIT_DECREMENT is sent out when the user clicks in the right arrow of a horizontal scroll bar, or the bottom arrow of a vertical scroll bar, or makes the equivalent gesture from the keyboard.
  • AdjustmentEvent.BLOCK_INCREMENT is sent out when the user clicks in the track, to the left of the bubble on a horizontal scroll bar, or above the bubble on a vertical scroll bar. By convention, the Page Up key is equivalent, if the user is using a keyboard that defines a Page Up key.
  • AdjustmentEvent.BLOCK_DECREMENT is sent out when the user clicks in the track, to the right of the bubble on a horizontal scroll bar, or below the bubble on a vertical scroll bar. By convention, the Page Down key is equivalent, if the user is using a keyboard that defines a Page Down key.

The JDK 1.0 event system is supported for backwards compatibility, but its use with newer versions of JDK is discouraged. The fives types of adjustment event introduced with JDK 1.1 correspond to the five event types that are associated with scroll bars in previous JDK versions. The following list gives the adjustment event type, and the corresponding JDK 1.0 event type it replaces.

  • AdjustmentEvent.TRACK replaces Event.SCROLL_ABSOLUTE
  • AdjustmentEvent.UNIT_INCREMENT replaces Event.SCROLL_LINE_UP
  • AdjustmentEvent.UNIT_DECREMENT replaces Event.SCROLL_LINE_DOWN
  • AdjustmentEvent.BLOCK_INCREMENT replaces Event.SCROLL_PAGE_UP
  • AdjustmentEvent.BLOCK_DECREMENT replaces Event.SCROLL_PAGE_DOWN

See Also:
AdjustmentEvent, AdjustmentListener


 Scrollbar Members

Scrollbar Members

Class Overview | This Package | All Packages

Fields
Name | Description
HORIZONTAL | A constant that indicates a horizontal scroll bar.
VERTICAL | A constant that indicates a vertical scroll bar.

Constructors
Name | Description
Scrollbar() | Constructs a new vertical scroll bar.
Scrollbar(int) | Constructs a new scroll bar with the specified orientation.
Scrollbar(int, int, int, int, int) | Constructs a new scroll bar with the specified orientation, initial value, page size, and minimum and maximum values.

Methods
Name | Description
addAdjustmentListener(AdjustmentListener) | Adds the specified adjustment listener to receive instances of AdjustmentEvent from this scroll bar.
addNotify() | Creates the Scrollbar's peer.
getBlockIncrement() | Gets the block increment of this scroll bar.
getLineIncrement() | Deprecated.
getMaximum() | Gets the maximum value of this scroll bar.
getMinimum() | Gets the minimum value of this scroll bar.
getOrientation() | Determines the orientation of this scroll bar.
getPageIncrement() | Deprecated.
getUnitIncrement() | Gets the unit increment for this scrollbar.
getValue() | Gets the current value of this scroll bar.
getVisible() | Deprecated.
getVisibleAmount() | Gets the visible amount of this scroll bar.
paramString() | Returns the parameter string representing the state of this scroll bar.
processAdjustmentEvent(AdjustmentEvent) | Processes adjustment events occurring on this scrollbar by dispatching them to any registered AdjustmentListener objects.
processEvent(AWTEvent) | Processes events on this scroll bar.
removeAdjustmentListener(AdjustmentListener) | Removes the specified adjustment listener so that it no longer receives instances of AdjustmentEvent from this scroll bar.
setBlockIncrement(int) | Sets the block increment for this scroll bar.
setLineIncrement(int) | Deprecated.
setMaximum(int) | Sets the maximum value of this scroll bar.
setMinimum(int) | Sets the minimum value of this scroll bar.
setOrientation(int) | Sets the orientation for this scroll bar.
setPageIncrement(int) | Deprecated.
setUnitIncrement(int) | Sets the unit increment for this scroll bar.
setValue(int) | Sets the value of this scroll bar to the specified value.
setValues(int, int, int, int) | Sets the values of four properties for this scroll bar.
setVisibleAmount(int) | Sets the visible amount of this scroll bar.


 Scrollbar.HORIZONTAL

Scrollbar.HORIZONTAL

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HORIZONTAL
Description
A constant that indicates a horizontal scroll bar.


 Scrollbar.VERTICAL

Scrollbar.VERTICAL

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VERTICAL
Description
A constant that indicates a vertical scroll bar.


 Scrollbar.Scrollbar

Scrollbar.Scrollbar

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Scrollbar()
Description
Constructs a new vertical scroll bar.

Syntax 2
public Scrollbar( int orientation )
Parameters
orientation
indicates the orientation of the scroll bar.
Description
Constructs a new scroll bar with the specified orientation.

The orientation argument must take one of the two values Scrollbar.HORIZONTAL, or Scrollbar.VERTICAL, indicating a horizontal or vertical scroll bar, respectively.

Exceptions
IllegalArgumentException when an illegal value for the orientation argument is supplied.

Syntax 3
public Scrollbar( int orientation, int value, int visible, int minimum, int maximum )
Parameters
orientation
indicates the orientation of the scroll bar.
value
the initial value of the scroll bar.
visible
the size of the scroll bar's bubble, representing the visible portion; the scroll bar uses this value when paging up or down by a page.
minimum
the minimum value of the scroll bar.
maximum
the maximum value of the scroll bar.
Description
Constructs a new scroll bar with the specified orientation, initial value, page size, and minimum and maximum values.

The orientation argument must take one of the two values Scrollbar.HORIZONTAL, or Scrollbar.VERTICAL, indicating a horizontal or vertical scroll bar, respectively.

If the specified maximum value is less than the minimum value, it is changed to be the same as the minimum value. If the initial value is lower than the minimum value, it is changed to be the minimum value; if it is greater than the maximum value, it is changed to be the maximum value.


 Scrollbar.addAdjustmentListener

Scrollbar.addAdjustmentListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void addAdjustmentListener( AdjustmentListener l )
Parameters
l
the adjustment listener.
Description
Adds the specified adjustment listener to receive instances of AdjustmentEvent from this scroll bar.

See Also
AdjustmentEvent, AdjustmentListener, removeAdjustmentListener


 Scrollbar.addNotify

Scrollbar.addNotify

Class Overview | Class Members | This Package | All Packages

Syntax
public void addNotify()
Description
Creates the Scrollbar's peer. The peer allows you to modify the appearance of the Scrollbar without changing any of its functionality.

Overrides
addNotify in class Component


 Scrollbar.getBlockIncrement

Scrollbar.getBlockIncrement

Class Overview | Class Members | This Package | All Packages

Syntax
public int getBlockIncrement()
Returns
the block increment of this scroll bar.
Description
Gets the block increment of this scroll bar.

The block increment is the value that is added (subtracted) when the user activates the block increment area of the scroll bar, generally through a mouse or keyboard gesture that the scroll bar receives as an adjustment event.

See Also
setBlockIncrement


 Scrollbar.getLineIncrement

Scrollbar.getLineIncrement

Class Overview | Class Members | This Package | All Packages

Syntax
public int getLineIncrement()
Description
Note: getLineIncrement() is deprecated. As of JDK version 1.1, replaced by getUnitIncrement().


 Scrollbar.getMaximum

Scrollbar.getMaximum

Class Overview | Class Members | This Package | All Packages

Syntax
public int getMaximum()
Returns
the maximum value of this scroll bar.
Description
Gets the maximum value of this scroll bar.

See Also
getValue, getMinimum


 Scrollbar.getMinimum

Scrollbar.getMinimum

Class Overview | Class Members | This Package | All Packages

Syntax
public int getMinimum()
Returns
the minimum value of this scroll bar.
Description
Gets the minimum value of this scroll bar.

See Also
getValue, getMaximum


 Scrollbar.getOrientation

Scrollbar.getOrientation

Class Overview | Class Members | This Package | All Packages

Syntax
public int getOrientation()
Returns
the orientation of this scroll bar, either Scrollbar.HORIZONTAL or Scrollbar.VERTICAL.
Description
Determines the orientation of this scroll bar.

See Also
setOrientation


 Scrollbar.getPageIncrement

Scrollbar.getPageIncrement

Class Overview | Class Members | This Package | All Packages

Syntax
public int getPageIncrement()
Description
Note: getPageIncrement() is deprecated. As of JDK version 1.1, replaced by getBlockIncrement().


 Scrollbar.getUnitIncrement

Scrollbar.getUnitIncrement

Class Overview | Class Members | This Package | All Packages

Syntax
public int getUnitIncrement()
Returns
the unit increment of this scroll bar.
Description
Gets the unit increment for this scrollbar.

The unit increment is the value that is added (subtracted) when the user activates the unit increment area of the scroll bar, generally through a mouse or keyboard gesture that the scroll bar receives as an adjustment event.

See Also
setUnitIncrement


 Scrollbar.getValue

Scrollbar.getValue

Class Overview | Class Members | This Package | All Packages

Syntax
public int getValue()
Returns
the current value of this scroll bar.
Description
Gets the current value of this scroll bar.

See Also
getMinimum, getMaximum


 Scrollbar.getVisible

Scrollbar.getVisible

Class Overview | Class Members | This Package | All Packages

Syntax
public int getVisible()
Description
Note: getVisible() is deprecated. As of JDK version 1.1, replaced by getVisibleAmount().


 Scrollbar.getVisibleAmount

Scrollbar.getVisibleAmount

Class Overview | Class Members | This Package | All Packages

Syntax
public int getVisibleAmount()
Returns
the visible amount of this scroll bar.
Description
Gets the visible amount of this scroll bar.

The visible amount of a scroll bar is the range of values represented by the width of the scroll bar's bubble. It is used to determine the scroll bar's block increment.

See Also
setVisibleAmount


 Scrollbar.paramString

Scrollbar.paramString

Class Overview | Class Members | This Package | All Packages

Syntax
protected String paramString()
Returns
the parameter string of this scroll bar.
Description
Returns the parameter string representing the state of this scroll bar. This string is useful for debugging.

Overrides
paramString in class Component


 Scrollbar.processAdjustmentEvent

Scrollbar.processAdjustmentEvent

Class Overview | Class Members | This Package | All Packages

Syntax
protected void processAdjustmentEvent( AdjustmentEvent e )
Parameters
e
the adjustment event.
Description
Processes adjustment events occurring on this scrollbar by dispatching them to any registered AdjustmentListener objects.

This method is not called unless adjustment events are enabled for this component. Adjustment events are enabled when one of the following occurs:

  • An AdjustmentListener object is registered via addAdjustmentListener.
  • Adjustment events are enabled via enableEvents.

See Also
AdjustmentEvent, AdjustmentListener, addAdjustmentListener, enableEvents


 Scrollbar.processEvent

Scrollbar.processEvent

Class Overview | Class Members | This Package | All Packages

Syntax
protected void processEvent( AWTEvent e )
Parameters
e
the event.
Description
Processes events on this scroll bar. If the event is an instance of AdjustmentEvent, it invokes the processAdjustmentEvent method. Otherwise, it invokes its superclass's processEvent method.

Overrides
processEvent in class Component
See Also
AdjustmentEvent, processAdjustmentEvent


 Scrollbar.removeAdjustmentListener

Scrollbar.removeAdjustmentListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void removeAdjustmentListener( AdjustmentListener l )
Parameters
l
the adjustment listener.
Description
Removes the specified adjustment listener so that it no longer receives instances of AdjustmentEvent from this scroll bar.

See Also
AdjustmentEvent, AdjustmentListener, addAdjustmentListener


 Scrollbar.setBlockIncrement

Scrollbar.setBlockIncrement

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setBlockIncrement( int v )
Parameters
v
the amount by which to increment or decrement the scroll bar's value.
Description
Sets the block increment for this scroll bar.

The block increment is the value that is added (subtracted) when the user activates the block increment area of the scroll bar, generally through a mouse or keyboard gesture that the scroll bar receives as an adjustment event.

See Also
getBlockIncrement


 Scrollbar.setLineIncrement

Scrollbar.setLineIncrement

Class Overview | Class Members | This Package | All Packages

Syntax
public void setLineIncrement( int v )
Description
Note: setLineIncrement() is deprecated. As of JDK version 1.1, replaced by setUnitIncrement(int).


 Scrollbar.setMaximum

Scrollbar.setMaximum

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setMaximum( int newMaximum )
Parameters
newMaximum
the new maximum value for this scroll bar.
Description
Sets the maximum value of this scroll bar.

Normally, a program should change a scroll bar's maximum value only by calling setValues. The setValues method simultaneously and synchronously sets the minimum, maximum, visible amount, and value properties of a scroll bar, so that they are mutually consistent.

See Also
setValues, setMinimum


 Scrollbar.setMinimum

Scrollbar.setMinimum

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setMinimum( int newMinimum )
Parameters
newMinimum
the new minimum value for this scroll bar.
Description
Sets the minimum value of this scroll bar.

Normally, a program should change a scroll bar's minimum value only by calling setValues. The setValues method simultaneously and synchronously sets the minimum, maximum, visible amount, and value properties of a scroll bar, so that they are mutually consistent.

See Also
setValues, setMaximum


 Scrollbar.setOrientation

Scrollbar.setOrientation

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setOrientation( int orientation )
Parameters
the
orientation of this scroll bar, either Scrollbar.HORIZONTAL or Scrollbar.VERTICAL.
Description
Sets the orientation for this scroll bar.

Exceptions
IllegalArgumentException if the value supplied for orientation is not a legal value.
See Also
getOrientation


 Scrollbar.setPageIncrement

Scrollbar.setPageIncrement

Class Overview | Class Members | This Package | All Packages

Syntax
public void setPageIncrement( int v )
Description
Note: setPageIncrement() is deprecated. As of JDK version 1.1, replaced by setBlockIncrement().


 Scrollbar.setUnitIncrement

Scrollbar.setUnitIncrement

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setUnitIncrement( int v )
Parameters
v
the amount by which to increment or decrement the scroll bar's value.
Description
Sets the unit increment for this scroll bar.

The unit increment is the value that is added (subtracted) when the user activates the unit increment area of the scroll bar, generally through a mouse or keyboard gesture that the scroll bar receives as an adjustment event.

See Also
getUnitIncrement


 Scrollbar.setValue

Scrollbar.setValue

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setValue( int newValue )
Parameters
newValue
the new value of the scroll bar.
Description
Sets the value of this scroll bar to the specified value.

If the value supplied is less than the current minimum or greater than the current maximum, then one of those values is substituted, as appropriate.

Normally, a program should change a scroll bar's value only by calling setValues. The setValues method simultaneously and synchronously sets the minimum, maximum, visible amount, and value properties of a scroll bar, so that they are mutually consistent.

See Also
setValues, getValue, getMinimum, getMaximum


 Scrollbar.setValues

Scrollbar.setValues

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setValues( int value, int visible, int minimum, int maximum )
Parameters
value
is the position in the current window.
visible
is the amount visible per page.
minimum
is the minimum value of the scroll bar.
maximum
is the maximum value of the scroll bar.
Description
Sets the values of four properties for this scroll bar.

This method simultaneously and synchronously sets the values of four scroll bar properties, assuring that the values of these properties are mutually consistent. It enforces the constraints that maximum cannot be less than minimum, and that value cannot be less than the minimum or greater than the maximum.


 Scrollbar.setVisibleAmount

Scrollbar.setVisibleAmount

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setVisibleAmount( int newAmount )
Parameters
newAmount
the amount visible per page.
Description
Sets the visible amount of this scroll bar.

The visible amount of a scroll bar is the range of values represented by the width of the scroll bar's bubble. It is used to determine the scroll bar's block increment.

Normally, a program should change a scroll bar's value only by calling setValues. The setValues method simultaneously and synchronously sets the minimum, maximum, visible amount, and value properties of a scroll bar, so that they are mutually consistent.

See Also
getVisibleAmount, setValues


 Interface Shape

Interface java.awt.Shape

Interface Members | This Package | All Packages

public interface Shape

The interface for objects which represent some form of geometric shape.

This interface will be revised in the upcoming Java2D project. It is meant to provide a common interface for various existing geometric AWT classes and methods which operate on them. Since it may be superseded or expanded in the future, developers should avoid implementing this interface in their own classes until it is completed in a later release.


 Shape Members

Shape Members

Interface Overview | This Package | All Packages

Methods
Name | Description
getBounds() | Return the bounding box of the shape.


 Shape.getBounds

Shape.getBounds

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Rectangle getBounds()
Description
Return the bounding box of the shape.


 Class SystemColor

Class java.awt.SystemColor

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.Color
           |
           +----java.awt.SystemColor

public final class SystemColor
extends Color
implements Serializable

A class to encapsulate symbolic colors representing the color of GUI objects on a system. For systems which support the dynamic update of the system colors (when the user changes the colors) the actual RGB values of these symbolic colors will also change dynamically. In order to compare the "current" RGB value of a SystemColor object with a non-symbolic Color object, getRGB() should be used rather than equals().


 SystemColor Members

SystemColor Members

Class Overview | This Package | All Packages

Fields
Name | Description
ACTIVE_CAPTION | The array index for the active caption background color.
ACTIVE_CAPTION_BORDER | The array index for the active caption border color.
ACTIVE_CAPTION_TEXT | The array index for the action caption text color.
activeCaption | The background color for captions in window borders.
activeCaptionBorder | The border color for captions in window borders.
activeCaptionText | The text color for captions in window borders.
CONTROL | The array index for the control background color.
control | The background color for control objects.
CONTROL_DK_SHADOW | The array index for the control dark shadow color.
CONTROL_HIGHLIGHT | The array index for the control highlight color.
CONTROL_LT_HIGHLIGHT | The array index for the control light highlight color.
CONTROL_SHADOW | The array index for the control shadow color.
CONTROL_TEXT | The array index for the control text color.
controlDkShadow | The dark shadow color for control objects.
controlHighlight | The regular highlight color for control objects.
controlLtHighlight | The light highlight color for control objects.
controlShadow | The regular shadow color for control objects.
controlText | The text color for control objects.
desktop | The color of the desktop background.
DESKTOP | The array index for the desktop background color.
INACTIVE_CAPTION | The array index for the inactive caption background color.
INACTIVE_CAPTION_BORDER | The array index for the inactive caption border color.
INACTIVE_CAPTION_TEXT | The array index for the inactive caption text color.
inactiveCaption | The background color for inactive captions in window borders.
inactiveCaptionBorder | The border color for inactive captios in window borders.
inactiveCaptionText | The text color for inactive captions in window borders.
INFO | The array index for the info background color.
info | The background color for info(help) text.
INFO_TEXT | The array index for the info text color.
infoText | The text color for info(help) text.
menu | The background color for menus.
MENU | The array index for the menu background color.
MENU_TEXT | The array index for the menu text color.
menuText | The text color for menus.
NUM_COLORS | The number of system colors in the array.
scrollbar | The background color for scrollbars.
SCROLLBAR | The array index for the scrollbar background color.
TEXT | The array index for the text background color.
text | The background color for text components.
TEXT_HIGHLIGHT | The array index for the text highlight color.
TEXT_HIGHLIGHT_TEXT | The array index for the text highlight text color.
TEXT_INACTIVE_TEXT | The array index for the text inactive text color.
TEXT_TEXT | The array index for the text text color.
textHighlight | The background color for highlighted text.
textHighlightText | The text color for highlighted text.
textInactiveText | The text color for inactive text.
textText | The text color for text components.
WINDOW | The array index for the window background color.
window | The background color for windows.
WINDOW_BORDER | The array index for the window border color.
WINDOW_TEXT | The array index for the window text color.
windowBorder | The border color for windows.
windowText | The text color for windows.

Methods
Name | Description
getRGB() | Gets the "current" RGB value representing the symbolic color.
toString() | Returns the String representation of this Color's values.


 SystemColor.ACTIVE_CAPTION

SystemColor.ACTIVE_CAPTION

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int ACTIVE_CAPTION
Description
The array index for the active caption background color.


 SystemColor.ACTIVE_CAPTION_BORDER

SystemColor.ACTIVE_CAPTION_BORDER

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int ACTIVE_CAPTION_BORDER
Description
The array index for the active caption border color.


 SystemColor.ACTIVE_CAPTION_TEXT

SystemColor.ACTIVE_CAPTION_TEXT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int ACTIVE_CAPTION_TEXT
Description
The array index for the action caption text color.


 SystemColor.activeCaption

SystemColor.activeCaption

Class Overview | Class Members | This Package | All Packages

Syntax
public static final SystemColor activeCaption
Description
The background color for captions in window borders.


 SystemColor.activeCaptionBorder

SystemColor.activeCaptionBorder

Class Overview | Class Members | This Package | All Packages

Syntax
public static final SystemColor activeCaptionBorder
Description
The border color for captions in window borders.


 SystemColor.activeCaptionText

SystemColor.activeCaptionText

Class Overview | Class Members | This Package | All Packages

Syntax
public static final SystemColor activeCaptionText
Description
The text color for captions in window borders.


 SystemColor.CONTROL

SystemColor.CONTROL

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int CONTROL
Description
The array index for the control background color.


 SystemColor.control

SystemColor.control

Class Overview | Class Members | This Package | All Packages

Syntax
public static final SystemColor control
Description
The background color for control objects.


 SystemColor.CONTROL_DK_SHADOW

SystemColor.CONTROL_DK_SHADOW

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int CONTROL_DK_SHADOW
Description
The array index for the control dark shadow color.


 SystemColor.CONTROL_HIGHLIGHT

SystemColor.CONTROL_HIGHLIGHT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int CONTROL_HIGHLIGHT
Description
The array index for the control highlight color.


 SystemColor.CONTROL_LT_HIGHLIGHT

SystemColor.CONTROL_LT_HIGHLIGHT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int CONTROL_LT_HIGHLIGHT
Description
The array index for the control light highlight color.


 SystemColor.CONTROL_SHADOW

SystemColor.CONTROL_SHADOW

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int CONTROL_SHADOW
Description
The array index for the control shadow color.


 SystemColor.CONTROL_TEXT

SystemColor.CONTROL_TEXT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int CONTROL_TEXT
Description
The array index for the control text color.


 SystemColor.controlDkShadow

SystemColor.controlDkShadow

Class Overview | Class Members | This Package | All Packages

Syntax
public static final SystemColor controlDkShadow
Description
The dark shadow color for control objects.


 SystemColor.controlHighlight

SystemColor.controlHighlight

Class Overview | Class Members | This Package | All Packages

Syntax
public static final SystemColor controlHighlight
Description
The regular highlight color for control objects.


 SystemColor.controlLtHighlight

SystemColor.controlLtHighlight

Class Overview | Class Members | This Package | All Packages

Syntax
public static final SystemColor controlLtHighlight
Description
The light highlight color for control objects.


 SystemColor.controlShadow

SystemColor.controlShadow

Class Overview | Class Members | This Package | All Packages

Syntax
public static final SystemColor controlShadow
Description
The regular shadow color for control objects.


 SystemColor.controlText

SystemColor.controlText

Class Overview | Class Members | This Package | All Packages

Syntax
public static final SystemColor controlText
Description
The text color for control objects.


 SystemColor.DESKTOP

SystemColor.DESKTOP

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int DESKTOP
Description
The array index for the desktop background color.


 SystemColor.desktop

SystemColor.desktop

Class Overview | Class Members | This Package | All Packages

Syntax
public static final SystemColor desktop
Description
The color of the desktop background.


 SystemColor.INACTIVE_CAPTION

SystemColor.INACTIVE_CAPTION

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int INACTIVE_CAPTION
Description
The array index for the inactive caption background color.


 SystemColor.INACTIVE_CAPTION_BORDER

SystemColor.INACTIVE_CAPTION_BORDER

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int INACTIVE_CAPTION_BORDER
Description
The array index for the inactive caption border color.


 SystemColor.INACTIVE_CAPTION_TEXT

SystemColor.INACTIVE_CAPTION_TEXT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int INACTIVE_CAPTION_TEXT
Description
The array index for the inactive caption text color.


 SystemColor.inactiveCaption

SystemColor.inactiveCaption

Class Overview | Class Members | This Package | All Packages

Syntax
public static final SystemColor inactiveCaption
Description
The background color for inactive captions in window borders.


 SystemColor.inactiveCaptionBorder

SystemColor.inactiveCaptionBorder

Class Overview | Class Members | This Package | All Packages

Syntax
public static final SystemColor inactiveCaptionBorder
Description
The border color for inactive captios in window borders.


 SystemColor.inactiveCaptionText

SystemColor.inactiveCaptionText

Class Overview | Class Members | This Package | All Packages

Syntax
public static final SystemColor inactiveCaptionText
Description
The text color for inactive captions in window borders.


 SystemColor.INFO

SystemColor.INFO

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int INFO
Description
The array index for the info background color.


 SystemColor.info

SystemColor.info

Class Overview | Class Members | This Package | All Packages

Syntax
public static final SystemColor info
Description
The background color for info(help) text.


 SystemColor.INFO_TEXT

SystemColor.INFO_TEXT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int INFO_TEXT
Description
The array index for the info text color.


 SystemColor.infoText

SystemColor.infoText

Class Overview | Class Members | This Package | All Packages

Syntax
public static final SystemColor infoText
Description
The text color for info(help) text.


 SystemColor.MENU

SystemColor.MENU

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int MENU
Description
The array index for the menu background color.


 SystemColor.menu

SystemColor.menu

Class Overview | Class Members | This Package | All Packages

Syntax
public static final SystemColor menu
Description
The background color for menus.


 SystemColor.MENU_TEXT

SystemColor.MENU_TEXT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int MENU_TEXT
Description
The array index for the menu text color.


 SystemColor.menuText

SystemColor.menuText

Class Overview | Class Members | This Package | All Packages

Syntax
public static final SystemColor menuText
Description
The text color for menus.


 SystemColor.NUM_COLORS

SystemColor.NUM_COLORS

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int NUM_COLORS
Description
The number of system colors in the array.


 SystemColor.SCROLLBAR

SystemColor.SCROLLBAR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SCROLLBAR
Description
The array index for the scrollbar background color.


 SystemColor.scrollbar

SystemColor.scrollbar

Class Overview | Class Members | This Package | All Packages

Syntax
public static final SystemColor scrollbar
Description
The background color for scrollbars.


 SystemColor.TEXT

SystemColor.TEXT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int TEXT
Description
The array index for the text background color.


 SystemColor.text

SystemColor.text

Class Overview | Class Members | This Package | All Packages

Syntax
public static final SystemColor text
Description
The background color for text components.


 SystemColor.TEXT_HIGHLIGHT

SystemColor.TEXT_HIGHLIGHT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int TEXT_HIGHLIGHT
Description
The array index for the text highlight color.


 SystemColor.TEXT_HIGHLIGHT_TEXT

SystemColor.TEXT_HIGHLIGHT_TEXT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int TEXT_HIGHLIGHT_TEXT
Description
The array index for the text highlight text color.


 SystemColor.TEXT_INACTIVE_TEXT

SystemColor.TEXT_INACTIVE_TEXT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int TEXT_INACTIVE_TEXT
Description
The array index for the text inactive text color.


 SystemColor.TEXT_TEXT

SystemColor.TEXT_TEXT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int TEXT_TEXT
Description
The array index for the text text color.


 SystemColor.textHighlight

SystemColor.textHighlight

Class Overview | Class Members | This Package | All Packages

Syntax
public static final SystemColor textHighlight
Description
The background color for highlighted text.


 SystemColor.textHighlightText

SystemColor.textHighlightText

Class Overview | Class Members | This Package | All Packages

Syntax
public static final SystemColor textHighlightText
Description
The text color for highlighted text.


 SystemColor.textInactiveText

SystemColor.textInactiveText

Class Overview | Class Members | This Package | All Packages

Syntax
public static final SystemColor textInactiveText
Description
The text color for inactive text.


 SystemColor.textText

SystemColor.textText

Class Overview | Class Members | This Package | All Packages

Syntax
public static final SystemColor textText
Description
The text color for text components.


 SystemColor.WINDOW

SystemColor.WINDOW

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int WINDOW
Description
The array index for the window background color.


 SystemColor.window

SystemColor.window

Class Overview | Class Members | This Package | All Packages

Syntax
public static final SystemColor window
Description
The background color for windows.


 SystemColor.WINDOW_BORDER

SystemColor.WINDOW_BORDER

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int WINDOW_BORDER
Description
The array index for the window border color.


 SystemColor.WINDOW_TEXT

SystemColor.WINDOW_TEXT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int WINDOW_TEXT
Description
The array index for the window text color.


 SystemColor.windowBorder

SystemColor.windowBorder

Class Overview | Class Members | This Package | All Packages

Syntax
public static final SystemColor windowBorder
Description
The border color for windows.


 SystemColor.windowText

SystemColor.windowText

Class Overview | Class Members | This Package | All Packages

Syntax
public static final SystemColor windowText
Description
The text color for windows.


 SystemColor.getRGB

SystemColor.getRGB

Class Overview | Class Members | This Package | All Packages

Syntax
public int getRGB()
Description
Gets the "current" RGB value representing the symbolic color. (Bits 24-31 are 0xff, 16-23 are red, 8-15 are green, 0-7 are blue).

Overrides
getRGB in class Color
See Also
getRGBdefault, getBlue, getGreen, getRed


 SystemColor.toString

SystemColor.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Description
Returns the String representation of this Color's values.

Overrides
toString in class Color


 Class TextArea

Class java.awt.TextArea

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.Component
           |
           +----java.awt.TextComponent
                   |
                   +----java.awt.TextArea

public class TextArea
extends TextComponent

A TextArea object is a multi-line region that displays text. It can be set to allow editing or to be read-only.

The following image shows the appearance of a text area:

This text area could be created by the following line of code:

 new TextArea("Hello", 5, 40);


 TextArea Members

TextArea Members

Class Overview | This Package | All Packages

Fields
Name | Description
SCROLLBARS_BOTH | Create and display both vertical and horizontal scrollbars.
SCROLLBARS_HORIZONTAL_ONLY | Create and display horizontal scrollbar only.
SCROLLBARS_NONE | Do not create or display any scrollbars for the text area.
SCROLLBARS_VERTICAL_ONLY | Create and display vertical scrollbar only.

Constructors
Name | Description
TextArea() | Constructs a new text area.
TextArea(int, int) | Constructs a new empty TextArea with the specified number of rows and columns.
TextArea(String) | Constructs a new text area with the specified text.
TextArea(String, int, int) | Constructs a new text area with the specified text, and with the specified number of rows and columns.
TextArea(String, int, int, int) | Constructs a new text area with the specified text, and with the rows, columns, and scroll bar visibility as specified.

Methods
Name | Description
addNotify() | Creates the TextArea's peer.
append(String) | Appends the given text to the text area's current text.
appendText(String) | Deprecated.
getColumns() | Gets the number of columns in this text area.
getMinimumSize() | Determines the minimum size of this text area.
getMinimumSize(int, int) | Determines the minimum size of a text area with the specified number of rows and columns.
getPreferredSize() | Determines the preferred size of this text area.
getPreferredSize(int, int) | Determines the preferred size of a text area with the specified number of rows and columns.
getRows() | Gets the number of rows in the text area.
getScrollbarVisibility() | Gets an enumerated value that indicates which scroll bars the text area uses.
insert(String, int) | Inserts the specified text at the specified position in this text area.
insertText(String, int) | Deprecated.
minimumSize() | Deprecated.
minimumSize(int, int) | Deprecated.
paramString() | Returns the parameter string representing the state of this text area.
preferredSize() | Deprecated.
preferredSize(int, int) | Deprecated.
replaceRange(String, int, int) | Replaces text between the indicated start and end positions with the specified replacement text.
replaceText(String, int, int) | Deprecated.
setColumns(int) | Sets the number of columns for this text area.
setRows(int) | Sets the number of rows for this text area.


 TextArea.SCROLLBARS_BOTH

TextArea.SCROLLBARS_BOTH

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SCROLLBARS_BOTH
Description
Create and display both vertical and horizontal scrollbars.


 TextArea.SCROLLBARS_HORIZONTAL_ONLY

TextArea.SCROLLBARS_HORIZONTAL_ONLY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SCROLLBARS_HORIZONTAL_ONLY
Description
Create and display horizontal scrollbar only.


 TextArea.SCROLLBARS_NONE

TextArea.SCROLLBARS_NONE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SCROLLBARS_NONE
Description
Do not create or display any scrollbars for the text area.


 TextArea.SCROLLBARS_VERTICAL_ONLY

TextArea.SCROLLBARS_VERTICAL_ONLY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SCROLLBARS_VERTICAL_ONLY
Description
Create and display vertical scrollbar only.


 TextArea.TextArea

TextArea.TextArea

Class Overview | Class Members | This Package | All Packages

Syntax 1
public TextArea()
Description
Constructs a new text area. This text area is created with both vertical and horizontal scroll bars.

Syntax 2
public TextArea( String text )
Parameters
text
the text to be displayed.
Description
Constructs a new text area with the specified text. This text area is created with both vertical and horizontal scroll bars.

Syntax 3
public TextArea( int rows, int columns )
Parameters
rows
the number of rows
columns
the number of columns
Description
Constructs a new empty TextArea with the specified number of rows and columns.

Syntax 4
public TextArea( String text, int rows, int columns )
Parameters
text
the text to be displayed.
rows
the number of rows.
columns
the number of columns.
Description
Constructs a new text area with the specified text, and with the specified number of rows and columns. This text area is created with both vertical and horizontal scroll bars.

Syntax 5
public TextArea( String text, int rows, int columns, int scrollbars )
Parameters
text
the text to be displayed.
rows
the number of rows.
columns
the number of columns.
scrollbars
a constant that determines what scrollbars are created to view the text area.
Description
Constructs a new text area with the specified text, and with the rows, columns, and scroll bar visibility as specified.

The TextArea class defines several constants that can be supplied as values for the scrollbars argument: SCROLLBARS_BOTH, SCROLLBARS_VERTICAL_ONLY, SCROLLBARS_HORIZONTAL_ONLY, and SCROLLBARS_NONE.


 TextArea.addNotify

TextArea.addNotify

Class Overview | Class Members | This Package | All Packages

Syntax
public void addNotify()
Description
Creates the TextArea's peer. The peer allows us to modify the appearance of the TextArea without changing any of its functionality.

Overrides
addNotify in class Component


 TextArea.append

TextArea.append

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void append( String str )
Parameters
str
the text to append.
Description
Appends the given text to the text area's current text.

See Also
insert


 TextArea.appendText

TextArea.appendText

Class Overview | Class Members | This Package | All Packages

Syntax
public void appendText( String str )
Description
Note: appendText() is deprecated. As of JDK version 1.1, replaced by append(String).


 TextArea.getColumns

TextArea.getColumns

Class Overview | Class Members | This Package | All Packages

Syntax
public int getColumns()
Returns
the number of columns in the text area.
Description
Gets the number of columns in this text area.

See Also
setColumns, getRows


 TextArea.getMinimumSize

TextArea.getMinimumSize

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Dimension getMinimumSize( int rows, int columns )
Parameters
rows
the number of rows.
cols
the number of columns.
Returns
the minimum dimensions required to display the text area with the specified number of rows and columns.
Description
Determines the minimum size of a text area with the specified number of rows and columns.

See Also
getMinimumSize

Syntax 2
public Dimension getMinimumSize()
Returns
the preferred dimensions needed for this text area.
Description
Determines the minimum size of this text area.

Overrides
getMinimumSize in class Component
See Also
getPreferredSize


 TextArea.getPreferredSize

TextArea.getPreferredSize

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Dimension getPreferredSize( int rows, int columns )
Parameters
rows
the number of rows.
cols
the number of columns.
Returns
the preferred dimensions required to display the text area with the specified number of rows and columns.
Description
Determines the preferred size of a text area with the specified number of rows and columns.

See Also
getPreferredSize

Syntax 2
public Dimension getPreferredSize()
Returns
the preferred dimensions needed for this text area.
Description
Determines the preferred size of this text area.

Overrides
getPreferredSize in class Component
See Also
getPreferredSize


 TextArea.getRows

TextArea.getRows

Class Overview | Class Members | This Package | All Packages

Syntax
public int getRows()
Returns
the number of rows in the text area.
Description
Gets the number of rows in the text area.

See Also
setRows, getColumns


 TextArea.getScrollbarVisibility

TextArea.getScrollbarVisibility

Class Overview | Class Members | This Package | All Packages

Syntax
public int getScrollbarVisibility()
Returns
an integer that indicates which scroll bars are used.
Description
Gets an enumerated value that indicates which scroll bars the text area uses.

The TextArea class defines four integer constants that are used to specify which scroll bars are available. TextArea has one constructor that gives the application discretion over scroll bars.

See Also
SCROLLBARS_BOTH, SCROLLBARS_VERTICAL_ONLY, SCROLLBARS_HORIZONTAL_ONLY, SCROLLBARS_NONE, TextArea


 TextArea.insert

TextArea.insert

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void insert( String str, int pos )
Parameters
str
the text to insert.
pos
the position at which to insert.
Description
Inserts the specified text at the specified position in this text area.

See Also
setText, replaceRange, append


 TextArea.insertText

TextArea.insertText

Class Overview | Class Members | This Package | All Packages

Syntax
public void insertText( String str, int pos )
Description
Note: insertText() is deprecated. As of JDK version 1.1, replaced by insert(String, int).


 TextArea.minimumSize

TextArea.minimumSize

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Dimension minimumSize( int rows, int columns )
Description
Note: minimumSize() is deprecated. As of JDK version 1.1, replaced by getMinimumSize(int, int).

Syntax 2
public Dimension minimumSize()
Description
Note: minimumSize() is deprecated. As of JDK version 1.1, replaced by getMinimumSize().

Overrides
minimumSize in class Component


 TextArea.paramString

TextArea.paramString

Class Overview | Class Members | This Package | All Packages

Syntax
protected String paramString()
Returns
the parameter string of this text area.
Description
Returns the parameter string representing the state of this text area. This string is useful for debugging.

Overrides
paramString in class TextComponent


 TextArea.preferredSize

TextArea.preferredSize

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Dimension preferredSize( int rows, int columns )
Description
Note: preferredSize() is deprecated. As of JDK version 1.1, replaced by getPreferredSize(int, int).

Syntax 2
public Dimension preferredSize()
Description
Note: preferredSize() is deprecated. As of JDK version 1.1, replaced by getPreferredSize().

Overrides
preferredSize in class Component


 TextArea.replaceRange

TextArea.replaceRange

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void replaceRange( String str, int start, int end )
Parameters
str
the text to use as the replacement.
start
the start position.
end
the end position.
Description
Replaces text between the indicated start and end positions with the specified replacement text.

See Also
insert


 TextArea.replaceText

TextArea.replaceText

Class Overview | Class Members | This Package | All Packages

Syntax
public void replaceText( String str, int start, int end )
Description
Note: replaceText() is deprecated. As of JDK version 1.1, replaced by replaceRange(String, int, int).


 TextArea.setColumns

TextArea.setColumns

Class Overview | Class Members | This Package | All Packages

Syntax
public void setColumns( int columns )
Parameters
columns
the number of columns.
Description
Sets the number of columns for this text area.

Exceptions
IllegalArgumentException if the value supplied for columns is less than zero.
See Also
getColumns, setRows


 TextArea.setRows

TextArea.setRows

Class Overview | Class Members | This Package | All Packages

Syntax
public void setRows( int rows )
Parameters
rows
the number of rows.
Description
Sets the number of rows for this text area.

Exceptions
IllegalArgumentException if the value supplied for rows is less than zero.
See Also
getRows, setColumns


 Class TextComponent

Class java.awt.TextComponent

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.Component
           |
           +----java.awt.TextComponent

public class TextComponent
extends Component

The TextComponent class is the superclass of any component that allows the editing of some text.

A text component embodies a string of text. The TextComponent class defines a set of methods that determine whether or not this text is editable. If the component is editable, it defines another set of methods that supports a text insertion caret.

In addition, the class defines methods that are used to maintain a current selection from the text. The text selection, a substring of the component's text, is the target of editing operations. It is also referred to as the selected text.


 TextComponent Members

TextComponent Members

Class Overview | This Package | All Packages

Fields
Name | Description
textListener |

Methods
Name | Description
addTextListener(TextListener) | Adds the specified text event listener to recieve text events from this textcomponent.
getCaretPosition() | Gets the position of the text insertion caret for this text component.
getSelectedText() | Gets the selected text from the text that is presented by this text component.
getSelectionEnd() | Gets the end position of the selected text in this text component.
getSelectionStart() | Gets the start position of the selected text in this text component.
getText() | Gets the text that is presented by this text component.
isEditable() | Indicates whether or not this text component is editable.
paramString() | Returns the parameter string representing the state of this text component.
processEvent(AWTEvent) | Processes events on this textcomponent.
processTextEvent(TextEvent) | Processes text events occurring on this text component by dispatching them to any registered TextListener objects.
removeNotify() | Removes the TextComponent's peer.
removeTextListener(TextListener) | Removes the specified text event listener so that it no longer receives text events from this textcomponent
select(int, int) | Selects the text between the specified start and end positions.
selectAll() | Selects all the text in this text component.
setCaretPosition(int) | Sets the position of the text insertion caret for this text component.
setEditable(boolean) | Sets the flag that determines whether or not this text component is editable.
setSelectionEnd(int) | Sets the selection end for this text component to the specified position.
setSelectionStart(int) | Sets the selection start for this text component to the specified position.
setText(String) | Sets the text that is presented by this text component to be the specified text.


 TextComponent.textListener

TextComponent.textListener

Class Overview | Class Members | This Package | All Packages

Syntax
protected transient TextListener textListener


 TextComponent.addTextListener

TextComponent.addTextListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void addTextListener( TextListener l )
Parameters
l
the text event listener
Description
Adds the specified text event listener to recieve text events from this textcomponent.


 TextComponent.getCaretPosition

TextComponent.getCaretPosition

Class Overview | Class Members | This Package | All Packages

Syntax
public int getCaretPosition()
Returns
the position of the text insertion caret.
Description
Gets the position of the text insertion caret for this text component.


 TextComponent.getSelectedText

TextComponent.getSelectedText

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized String getSelectedText()
Returns
the selected text of this text component.
Description
Gets the selected text from the text that is presented by this text component.

See Also
select


 TextComponent.getSelectionEnd

TextComponent.getSelectionEnd

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized int getSelectionEnd()
Returns
the end position of the selected text.
Description
Gets the end position of the selected text in this text component.

See Also
setSelectionEnd, getSelectionStart


 TextComponent.getSelectionStart

TextComponent.getSelectionStart

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized int getSelectionStart()
Returns
the start position of the selected text.
Description
Gets the start position of the selected text in this text component.

See Also
setSelectionStart, getSelectionEnd


 TextComponent.getText

TextComponent.getText

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized String getText()
Description
Gets the text that is presented by this text component.

See Also
setText


 TextComponent.isEditable

TextComponent.isEditable

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isEditable()
Returns
true if this text component is editable; false otherwise.
Description
Indicates whether or not this text component is editable.

See Also
setEditable


 TextComponent.paramString

TextComponent.paramString

Class Overview | Class Members | This Package | All Packages

Syntax
protected String paramString()
Returns
the parameter string of this text component.
Description
Returns the parameter string representing the state of this text component. This string is useful for debugging.

Overrides
paramString in class Component


 TextComponent.processEvent

TextComponent.processEvent

Class Overview | Class Members | This Package | All Packages

Syntax
protected void processEvent( AWTEvent e )
Parameters
e
the event
Description
Processes events on this textcomponent. If the event is a TextEvent, it invokes the processTextEvent method, else it invokes its superclass's processEvent.

Overrides
processEvent in class Component


 TextComponent.processTextEvent

TextComponent.processTextEvent

Class Overview | Class Members | This Package | All Packages

Syntax
protected void processTextEvent( TextEvent e )
Parameters
e
the text event
Description
Processes text events occurring on this text component by dispatching them to any registered TextListener objects. NOTE: This method will not be called unless text events are enabled for this component; this happens when one of the following occurs: a) A TextListener object is registered via addTextListener() b) Text events are enabled via enableEvents()

See Also
enableEvents


 TextComponent.removeNotify

TextComponent.removeNotify

Class Overview | Class Members | This Package | All Packages

Syntax
public void removeNotify()
Description
Removes the TextComponent's peer. The peer allows us to modify the appearance of the TextComponent without changing its functionality.

Overrides
removeNotify in class Component


 TextComponent.removeTextListener

TextComponent.removeTextListener

Class Overview | Class Members | This Package | All Packages

Syntax
public void removeTextListener( TextListener l )
Description
Removes the specified text event listener so that it no longer receives text events from this textcomponent


 TextComponent.select

TextComponent.select

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void select( int selectionStart, int selectionEnd )
Parameters
selectionStart
the start position of the text to select.
selectionEnd
the end position of the text to select.
Description
Selects the text between the specified start and end positions.

This method sets the start and end positions of the selected text, enforcing the restriction that the end position must be greater than or equal to the start position. The start position must be greater than zero, and the end position must be less that or equal to the length of the text component's text. If the caller supplies values that are inconsistent or out of bounds, the method enforces these constraints silently, and without failure.

See Also
setSelectionStart, setSelectionEnd, selectAll


 TextComponent.selectAll

TextComponent.selectAll

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void selectAll()
Description
Selects all the text in this text component.

See Also
TextComponent@select


 TextComponent.setCaretPosition

TextComponent.setCaretPosition

Class Overview | Class Members | This Package | All Packages

Syntax
public void setCaretPosition( int position )
Parameters
position
the position of the text insertion caret.
Description
Sets the position of the text insertion caret for this text component.

Exceptions
IllegalArgumentException if the value supplied for position is less than zero.


 TextComponent.setEditable

TextComponent.setEditable

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setEditable( boolean b )
Parameters
t
a flag indicating whether this text component should be user editable.
Description
Sets the flag that determines whether or not this text component is editable.

If the flag is set to true, this text component becomes user editable. If the flag is set to false, the user cannot change the text of this text component.

See Also
isEditable


 TextComponent.setSelectionEnd

TextComponent.setSelectionEnd

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setSelectionEnd( int selectionEnd )
Parameters
selectionEnd
the end position of the selected text.
Description
Sets the selection end for this text component to the specified position. The new end point is constrained to be at or after the current selection start. It also cannot be set beyond the end of the component's text. If the caller supplies a value for selectionEnd that is out of bounds, the method enforces these constraints silently, and without failure.

See Also
getSelectionEnd, setSelectionStart


 TextComponent.setSelectionStart

TextComponent.setSelectionStart

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setSelectionStart( int selectionStart )
Parameters
selectionStart
the start position of the selected text.
Description
Sets the selection start for this text component to the specified position. The new start point is constrained to be at or before the current selection end. It also cannot be set to less than zero, the beginning of the component's text. If the caller supplies a value for selectionStart that is out of bounds, the method enforces these constraints silently, and without failure.

See Also
getSelectionStart, setSelectionEnd


 TextComponent.setText

TextComponent.setText

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setText( String t )
Parameters
t
the new text.
Description
Sets the text that is presented by this text component to be the specified text.

See Also
getText


 Class TextField

Class java.awt.TextField

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.Component
           |
           +----java.awt.TextComponent
                   |
                   +----java.awt.TextField

public class TextField
extends TextComponent

A TextField object is a text component that allows for the editing of a single line of text.

For example, the following image depicts a frame with four text fields of varying widths. Two of these text fields display the predefined text "Hello".

Here is the code that produces these four text fields:

 TextField tf1, tf2, tf3, tf4;
 // a blank text field
 tf1 = new TextField();
 // blank field of 20 columns
 tf2 = new TextField("", 20);
 // predefined text displayed
 tf3 = new TextField("Hello!");
 // predefined text in 30 columns
 tf4 = new TextField("Hello", 30);

Every time the user types a key in the text field, AWT sends two action events to the text field. The first one represents the key press and the second one, the key release. Each action event embodies the state of the system at the time that some action occurred. The properties of an action event indicate which key was pressed, what modifier keys were also pressed, and the time at which the event occurred.

Since the event is an instance of ActionEvent, the TextField class's processEvent method examines the event and passes it along to processActionEvent. The latter method redirects the event to any ActionListener objects that have registered an interest in action events generated by this text field.

See Also:
ActionEvent, processEvent, processActionEvent


 TextField Members

TextField Members

Class Overview | This Package | All Packages

Constructors
Name | Description
TextField() | Constructs a new text field.
TextField(int) | Constructs a new empty TextField with the specified number of columns.
TextField(String) | Constructs a new text field initialized with the specified text.
TextField(String, int) | Constructs a new text field initialized with the specified text to be displayed, and wide enough to hold the specified number of characters.

Methods
Name | Description
addActionListener(ActionListener) | Adds the specified action listener to recieve action events from this text field.
addNotify() | Creates the TextField's peer.
echoCharIsSet() | Indicates whether or not this text field has a character set for echoing.
getColumns() | Gets the number of columns in this text field.
getEchoChar() | Gets the character that is to be used for echoing.
getMinimumSize() | Gets the minumum dimensions for this text field.
getMinimumSize(int) | Gets the minumum dimensions for a text field with the specified number of columns.
getPreferredSize() | Gets the preferred size of this text field.
getPreferredSize(int) | Gets the preferred size of this text field with the specified number of columns.
minimumSize() | Deprecated.
minimumSize(int) | Deprecated.
paramString() | Returns the parameter string representing the state of this text field.
preferredSize() | Deprecated.
preferredSize(int) | Deprecated.
processActionEvent(ActionEvent) | Processes action events occurring on this text field by dispatching them to any registered ActionListener objects.
processEvent(AWTEvent) | Processes events on this text field.
removeActionListener(ActionListener) | Removes the specified action listener so that it no longer receives action events from this text field.
setColumns(int) | Sets the number of columns in this text field.
setEchoChar(char) | Sets the echo character for this text field.
setEchoCharacter(char) | Deprecated.


 TextField.TextField

TextField.TextField

Class Overview | Class Members | This Package | All Packages

Syntax 1
public TextField()
Description
Constructs a new text field.

Syntax 2
public TextField( String text )
Parameters
text
the text to be displayed.
Description
Constructs a new text field initialized with the specified text.

Syntax 3
public TextField( int columns )
Parameters
columns
the number of columns
Description
Constructs a new empty TextField with the specified number of columns.

Syntax 4
public TextField( String text, int columns )
Parameters
text
the text to be displayed.
columns
the number of characters.
Description
Constructs a new text field initialized with the specified text to be displayed, and wide enough to hold the specified number of characters.


 TextField.addActionListener

TextField.addActionListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void addActionListener( ActionListener l )
Parameters
l
the action listener.
Description
Adds the specified action listener to recieve action events from this text field.

See Also
ActionListener, removeActionListener


 TextField.addNotify

TextField.addNotify

Class Overview | Class Members | This Package | All Packages

Syntax
public void addNotify()
Description
Creates the TextField's peer. The peer allows us to modify the appearance of the TextField without changing its functionality.

Overrides
addNotify in class Component


 TextField.echoCharIsSet

TextField.echoCharIsSet

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean echoCharIsSet()
Returns
true if this text field has a character set for echoing; false otherwise.
Description
Indicates whether or not this text field has a character set for echoing.

An echo character is useful for text fields where user input should not be echoed to the screen, as in the case of a text field for entering a password.

See Also
setEchoChar, getEchoChar


 TextField.getColumns

TextField.getColumns

Class Overview | Class Members | This Package | All Packages

Syntax
public int getColumns()
Returns
the number of columns.
Description
Gets the number of columns in this text field.

See Also
setColumns


 TextField.getEchoChar

TextField.getEchoChar

Class Overview | Class Members | This Package | All Packages

Syntax
public char getEchoChar()
Returns
the echo character for this text field.
Description
Gets the character that is to be used for echoing.

An echo character is useful for text fields where user input should not be echoed to the screen, as in the case of a text field for entering a password.

See Also
echoCharIsSet, setEchoChar


 TextField.getMinimumSize

TextField.getMinimumSize

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Dimension getMinimumSize( int columns )
Parameters
columns
the number of columns in this text field.
Description
Gets the minumum dimensions for a text field with the specified number of columns.

Syntax 2
public Dimension getMinimumSize()
Returns
the minimum dimensions for displaying this text field.
Description
Gets the minumum dimensions for this text field.

Overrides
getMinimumSize in class Component


 TextField.getPreferredSize

TextField.getPreferredSize

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Dimension getPreferredSize( int columns )
Parameters
columns
the number of columns in this text field.
Returns
the preferred dimensions for displaying this text field.
Description
Gets the preferred size of this text field with the specified number of columns.

Syntax 2
public Dimension getPreferredSize()
Returns
the preferred dimensions for displaying this text field.
Description
Gets the preferred size of this text field.

Overrides
getPreferredSize in class Component


 TextField.minimumSize

TextField.minimumSize

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Dimension minimumSize( int columns )
Description
Note: minimumSize() is deprecated. As of JDK version 1.1, replaced by getMinimumSize(int).

Syntax 2
public Dimension minimumSize()
Description
Note: minimumSize() is deprecated. As of JDK version 1.1, replaced by getMinimumSize().

Overrides
minimumSize in class Component


 TextField.paramString

TextField.paramString

Class Overview | Class Members | This Package | All Packages

Syntax
protected String paramString()
Returns
the parameter string of this text field.
Description
Returns the parameter string representing the state of this text field. This string is useful for debugging.

Overrides
paramString in class TextComponent


 TextField.preferredSize

TextField.preferredSize

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Dimension preferredSize( int columns )
Description
Note: preferredSize() is deprecated. As of JDK version 1.1, replaced by getPreferredSize(int).

Syntax 2
public Dimension preferredSize()
Description
Note: preferredSize() is deprecated. As of JDK version 1.1, replaced by getPreferredSize().

Overrides
preferredSize in class Component


 TextField.processActionEvent

TextField.processActionEvent

Class Overview | Class Members | This Package | All Packages

Syntax
protected void processActionEvent( ActionEvent e )
Parameters
e
the action event.
Description
Processes action events occurring on this text field by dispatching them to any registered ActionListener objects.

This method is not called unless action events are enabled for this component. Action events are enabled when one of the following occurs:

  • An ActionListener object is registered via addActionListener.
  • Action events are enabled via enableEvents.

See Also
ActionListener, addActionListener, enableEvents


 TextField.processEvent

TextField.processEvent

Class Overview | Class Members | This Package | All Packages

Syntax
protected void processEvent( AWTEvent e )
Parameters
e
the event.
Description
Processes events on this text field. If the event is an instance of ActionEvent, it invokes the processActionEvent method. Otherwise, it invokes processEvent on the superclass.

Overrides
processEvent in class TextComponent
See Also
ActionEvent, processActionEvent


 TextField.removeActionListener

TextField.removeActionListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void removeActionListener( ActionListener l )
Parameters
l
the action listener.
Description
Removes the specified action listener so that it no longer receives action events from this text field.

See Also
ActionListener, addActionListener


 TextField.setColumns

TextField.setColumns

Class Overview | Class Members | This Package | All Packages

Syntax
public void setColumns( int columns )
Parameters
columns
the number of columns.
Description
Sets the number of columns in this text field.

Exceptions
IllegalArgumentException if the value supplied for columns is less than zero.
See Also
getColumns


 TextField.setEchoChar

TextField.setEchoChar

Class Overview | Class Members | This Package | All Packages

Syntax
public void setEchoChar( char c )
Parameters
c
the echo character for this text field.
Description
Sets the echo character for this text field.

An echo character is useful for text fields where user input should not be echoed to the screen, as in the case of a text field for entering a password.

See Also
echoCharIsSet, getEchoChar


 TextField.setEchoCharacter

TextField.setEchoCharacter

Class Overview | Class Members | This Package | All Packages

Syntax
public void setEchoCharacter( char c )
Description
Note: setEchoCharacter() is deprecated. As of JDK version 1.1, replaced by setEchoChar(char).


 Class Toolkit

Class java.awt.Toolkit

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.Toolkit

public abstract class Toolkit
extends Object

This class is the abstract superclass of all actual implementations of the Abstract Window Toolkit. Subclasses of Toolkit are used to bind the various components to particular native toolkit implementations.

Most applications should not call any of the methods in this class directly. The methods defined by Toolkit are the "glue" that joins the platform-independent classes in the java.awt package with their counterparts in java.awt.peer. Some methods defined by Toolkit query the native operating system directly.


 Toolkit Members

Toolkit Members

Class Overview | This Package | All Packages

Constructors
Name | Description
Toolkit() |

Methods
Name | Description
beep() | Emits an audio beep.
checkImage(Image, int, int, ImageObserver) | Indicates the construction status of a specified image that is being prepared for display.
createButton(Button) | Creates this toolkit's implementation of Button using the specified peer interface.
createCanvas(Canvas) | Creates this toolkit's implementation of Canvas using the specified peer interface.
createCheckbox(Checkbox) | Creates this toolkit's implementation of Checkbox using the specified peer interface.
createCheckboxMenuItem(CheckboxMenuItem) | Creates this toolkit's implementation of CheckboxMenuItem using the specified peer interface.
createChoice(Choice) | Creates this toolkit's implementation of Choice using the specified peer interface.
createComponent(Component) | Creates a peer for a component or container.
createDialog(Dialog) | Creates this toolkit's implementation of Dialog using the specified peer interface.
createFileDialog(FileDialog) | Creates this toolkit's implementation of FileDialog using the specified peer interface.
createFrame(Frame) | Creates this toolkit's implementation of Frame using the specified peer interface.
createImage(byte[]) | Creates an image which decodes the image stored in the specified byte array.
createImage(byte[], int, int) | Creates an image which decodes the image stored in the specified byte array, and at the specified offset and length.
createImage(ImageProducer) | Creates an image with the specified image producer.
createLabel(Label) | Creates this toolkit's implementation of Label using the specified peer interface.
createList(List) | Creates this toolkit's implementation of List using the specified peer interface.
createMenu(Menu) | Creates this toolkit's implementation of Menu using the specified peer interface.
createMenuBar(MenuBar) | Creates this toolkit's implementation of MenuBar using the specified peer interface.
createMenuItem(MenuItem) | Creates this toolkit's implementation of MenuItem using the specified peer interface.
createPanel(Panel) | Creates this toolkit's implementation of Panel using the specified peer interface.
createPopupMenu(PopupMenu) | Creates this toolkit's implementation of PopupMenu using the specified peer interface.
createScrollbar(Scrollbar) | Creates this toolkit's implementation of Scrollbar using the specified peer interface.
createScrollPane(ScrollPane) | Creates this toolkit's implementation of ScrollPane using the specified peer interface.
createTextArea(TextArea) | Creates this toolkit's implementation of TextArea using the specified peer interface.
createTextField(TextField) | Creates this toolkit's implementation of TextField using the specified peer interface.
createWindow(Window) | Creates this toolkit's implementation of Window using the specified peer interface.
getColorModel() | Determines the color model of this toolkit's screen.
getDefaultToolkit() | Gets the default toolkit.
getFontList() Returns the names of the available fonts in this toolkit.

For 1.1, the following font names are deprecated (the replacement name follows):

  • TimesRoman (use Serif)
  • Helvetica (use SansSerif)
  • Courier (use Monospaced)

The ZapfDingbats font is also deprecated in 1.1, but only as a separate fontname.

getFontMetrics(Font) | Gets the screen metrics of the font.
getFontPeer(String, int) | Creates this toolkit's implementation of Font using the specified peer interface.
getImage(String) | Returns an image which gets pixel data from the specified file.
getImage(URL) | Returns an image which gets pixel data from the specified URL.
getMenuShortcutKeyMask() | Determines which modifier key is the appropriate accelerator key for menu shortcuts.
getNativeContainer(Component) | Give native peers the ability to query the native container given a native component (eg the direct parent may be lightweight).
getPrintJob(Frame, String, Properties) | Gets a PrintJob object which is the result of initiating a print operation on the toolkit's platform.
getProperty(String, String) | Gets a property with the specified key and default.
getScreenResolution() | Returns the screen resolution in dots-per-inch.
getScreenSize() | Gets the size of the screen.
getSystemClipboard() | Gets an instance of the system clipboard which interfaces with clipboard facilities provided by the native platform.
getSystemEventQueue() | Get the application's or applet's EventQueue instance.
getSystemEventQueueImpl()
loadSystemColors(int[]) | Fills in the integer array that is supplied as an argument with the current system color values.
prepareImage(Image, int, int, ImageObserver) | Prepares an image for rendering.
sync() | Synchronizes this toolkit's graphics state.


 Toolkit.Toolkit

Toolkit.Toolkit

Class Overview | Class Members | This Package | All Packages

Syntax
public Toolkit()


 Toolkit.beep

Toolkit.beep

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void beep()
Description
Emits an audio beep.


 Toolkit.checkImage

Toolkit.checkImage

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract int checkImage( Image image, int width, int height, ImageObserver observer )
Parameters
image
the image whose status is being checked.
width
the width of the scaled version whose status is being checked, or -1.
height
the height of the scaled version whose status is being checked, or -1.
observer
the ImageObserver object to be notified as the image is being prepared.
Returns
the bitwise inclusive OR of the ImageObserver flags for the image data that is currently available.
Description
Indicates the construction status of a specified image that is being prepared for display.

If the values of the width and height arguments are both -1, this method returns the construction status of a screen representation of the specified image in this toolkit. Otherwise, this method returns the construction status of a scaled representation of the image at the specified width and height.

This method does not cause the image to begin loading. An application must call prepareImage to force the loading of an image.

This method is called by the component's checkImage methods.

Information on the flags returned by this method can be found with the definition of the ImageObserver interface.

See Also
prepareImage, checkImage, checkImage, ImageObserver


 Toolkit.createButton

Toolkit.createButton

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract ButtonPeer createButton( Button target )
Parameters
target
the button to be implemented.
Returns
this toolkit's implementation of Button.
Description
Creates this toolkit's implementation of Button using the specified peer interface.

See Also
Button, ButtonPeer


 Toolkit.createCanvas

Toolkit.createCanvas

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract CanvasPeer createCanvas( Canvas target )
Parameters
target
the canvas to be implemented.
Returns
this toolkit's implementation of Canvas.
Description
Creates this toolkit's implementation of Canvas using the specified peer interface.

See Also
Canvas, CanvasPeer


 Toolkit.createCheckbox

Toolkit.createCheckbox

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract CheckboxPeer createCheckbox( Checkbox target )
Parameters
target
the check box to be implemented.
Returns
this toolkit's implementation of Checkbox.
Description
Creates this toolkit's implementation of Checkbox using the specified peer interface.

See Also
Checkbox, CheckboxPeer


 Toolkit.createCheckboxMenuItem

Toolkit.createCheckboxMenuItem

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract CheckboxMenuItemPeer createCheckboxMenuItem( CheckboxMenuItem target )
Parameters
target
the checkbox menu item to be implemented.
Returns
this toolkit's implementation of CheckboxMenuItem.
Description
Creates this toolkit's implementation of CheckboxMenuItem using the specified peer interface.

See Also
CheckboxMenuItem, CheckboxMenuItemPeer


 Toolkit.createChoice

Toolkit.createChoice

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract ChoicePeer createChoice( Choice target )
Parameters
target
the choice to be implemented.
Returns
this toolkit's implementation of Choice.
Description
Creates this toolkit's implementation of Choice using the specified peer interface.

See Also
Choice, ChoicePeer


 Toolkit.createComponent

Toolkit.createComponent

Class Overview | Class Members | This Package | All Packages

Syntax
protected LightweightPeer createComponent( Component target )
Parameters
target
The Component to be created.
Description
Creates a peer for a component or container. This peer is windowless and allows the Component and Container classes to be extended directly to create windowless components that are defined entirely in java.


 Toolkit.createDialog

Toolkit.createDialog

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract DialogPeer createDialog( Dialog target )
Parameters
target
the dialog to be implemented.
Returns
this toolkit's implementation of Dialog.
Description
Creates this toolkit's implementation of Dialog using the specified peer interface.

See Also
Dialog, DialogPeer


 Toolkit.createFileDialog

Toolkit.createFileDialog

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract FileDialogPeer createFileDialog( FileDialog target )
Parameters
target
the file dialog to be implemented.
Returns
this toolkit's implementation of FileDialog.
Description
Creates this toolkit's implementation of FileDialog using the specified peer interface.

See Also
FileDialog, FileDialogPeer


 Toolkit.createFrame

Toolkit.createFrame

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract FramePeer createFrame( Frame target )
Parameters
target
the frame to be implemented.
Returns
this toolkit's implementation of Frame.
Description
Creates this toolkit's implementation of Frame using the specified peer interface.

See Also
Frame, FramePeer


 Toolkit.createImage

Toolkit.createImage

Class Overview | Class Members | This Package | All Packages

Syntax 1
public abstract Image createImage( ImageProducer producer )
Parameters
producer
the image producer to be used.
Returns
an image with the specified image producer.
Description
Creates an image with the specified image producer.

See Also
Image, ImageProducer, createImage

Syntax 2
public Image createImage( byte imagedata[] )
Parameters
imagedata
an array of bytes, representing image data in a supported image format.
Returns
an image.
Description
Creates an image which decodes the image stored in the specified byte array.

The data must be in some image format, such as GIF or JPEG, that is supported by this toolkit.

Syntax 3
public abstract Image createImage( byte imagedata[], int imageoffset, int imagelength )
Parameters
imagedata
an array of bytes, representing image data in a supported image format.
imageoffset
the offset of the beginning of the data in the array.
imagelength
the length of the data in the array.
Returns
an image.
Description
Creates an image which decodes the image stored in the specified byte array, and at the specified offset and length. The data must be in some image format, such as GIF or JPEG, that is supported by this toolkit.


 Toolkit.createLabel

Toolkit.createLabel

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract LabelPeer createLabel( Label target )
Parameters
target
the label to be implemented.
Returns
this toolkit's implementation of Label.
Description
Creates this toolkit's implementation of Label using the specified peer interface.

See Also
Label, LabelPeer


 Toolkit.createList

Toolkit.createList

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract ListPeer createList( List target )
Parameters
target
the list to be implemented.
Returns
this toolkit's implementation of List.
Description
Creates this toolkit's implementation of List using the specified peer interface.

See Also
List, ListPeer


 Toolkit.createMenu

Toolkit.createMenu

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract MenuPeer createMenu( Menu target )
Parameters
target
the menu to be implemented.
Returns
this toolkit's implementation of Menu.
Description
Creates this toolkit's implementation of Menu using the specified peer interface.

See Also
Menu, MenuPeer


 Toolkit.createMenuBar

Toolkit.createMenuBar

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract MenuBarPeer createMenuBar( MenuBar target )
Parameters
target
the menu bar to be implemented.
Returns
this toolkit's implementation of MenuBar.
Description
Creates this toolkit's implementation of MenuBar using the specified peer interface.

See Also
MenuBar, MenuBarPeer


 Toolkit.createMenuItem

Toolkit.createMenuItem

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract MenuItemPeer createMenuItem( MenuItem target )
Parameters
target
the menu item to be implemented.
Returns
this toolkit's implementation of MenuItem.
Description
Creates this toolkit's implementation of MenuItem using the specified peer interface.

See Also
MenuItem, MenuItemPeer


 Toolkit.createPanel

Toolkit.createPanel

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract PanelPeer createPanel( Panel target )
Parameters
target
the panel to be implemented.
Returns
this toolkit's implementation of Panel.
Description
Creates this toolkit's implementation of Panel using the specified peer interface.

See Also
Panel, PanelPeer


 Toolkit.createPopupMenu

Toolkit.createPopupMenu

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract PopupMenuPeer createPopupMenu( PopupMenu target )
Parameters
target
the popup menu to be implemented.
Returns
this toolkit's implementation of PopupMenu.
Description
Creates this toolkit's implementation of PopupMenu using the specified peer interface.

See Also
PopupMenu, PopupMenuPeer


 Toolkit.createScrollbar

Toolkit.createScrollbar

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract ScrollbarPeer createScrollbar( Scrollbar target )
Parameters
target
the scroll bar to be implemented.
Returns
this toolkit's implementation of Scrollbar.
Description
Creates this toolkit's implementation of Scrollbar using the specified peer interface.

See Also
Scrollbar, ScrollbarPeer


 Toolkit.createScrollPane

Toolkit.createScrollPane

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract ScrollPanePeer createScrollPane( ScrollPane target )
Parameters
target
the scroll pane to be implemented.
Returns
this toolkit's implementation of ScrollPane.
Description
Creates this toolkit's implementation of ScrollPane using the specified peer interface.

See Also
ScrollPane, ScrollPanePeer


 Toolkit.createTextArea

Toolkit.createTextArea

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract TextAreaPeer createTextArea( TextArea target )
Parameters
target
the text area to be implemented.
Returns
this toolkit's implementation of TextArea.
Description
Creates this toolkit's implementation of TextArea using the specified peer interface.

See Also
TextArea, TextAreaPeer


 Toolkit.createTextField

Toolkit.createTextField

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract TextFieldPeer createTextField( TextField target )
Parameters
target
the text field to be implemented.
Returns
this toolkit's implementation of TextField.
Description
Creates this toolkit's implementation of TextField using the specified peer interface.

See Also
TextField, TextFieldPeer


 Toolkit.createWindow

Toolkit.createWindow

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract WindowPeer createWindow( Window target )
Parameters
target
the window to be implemented.
Returns
this toolkit's implementation of Window.
Description
Creates this toolkit's implementation of Window using the specified peer interface.

See Also
Window, WindowPeer


 Toolkit.getColorModel

Toolkit.getColorModel

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract ColorModel getColorModel()
Returns
the color model of this toolkit's screen.
Description
Determines the color model of this toolkit's screen.

ColorModel is an abstract class that encapsulates the ability to translate between the pixel values of an image and its red, green, blue, and alpha components.

This toolkit method is called by the getColorModel method of the Component class.

See Also
ColorModel, getColorModel


 Toolkit.getDefaultToolkit

Toolkit.getDefaultToolkit

Class Overview | Class Members | This Package | All Packages

Syntax
public static synchronized Toolkit getDefaultToolkit()
Returns
the default toolkit.
Description
Gets the default toolkit.

If there is a system property named "awt.toolkit", that property is treated as the name of a class that is a subclass of Toolkit.

If the system property does not exist, then the default toolkit used is the class named "sun.awt.motif.MToolkit", which is a motif implementation of the Abstract Window Toolkit.

Exceptions
AWTError if a toolkit could not be found, or if one could not be accessed or instantiated.


 Toolkit.getFontList

Toolkit.getFontList

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract String[] getFontList()
Returns
the names of the available fonts in this toolkit.
Description
Returns the names of the available fonts in this toolkit.

For 1.1, the following font names are deprecated (the replacement name follows):

  • TimesRoman (use Serif)
  • Helvetica (use SansSerif)
  • Courier (use Monospaced)

The ZapfDingbats font is also deprecated in 1.1, but only as a separate fontname. Unicode defines the ZapfDingbat characters starting at ?, and as of 1.1 Java supports those characters.


 Toolkit.getFontMetrics

Toolkit.getFontMetrics

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract FontMetrics getFontMetrics( Font font )
Parameters
font
a font.
Returns
the screen metrics of the specified font in this toolkit.
Description
Gets the screen metrics of the font.


 Toolkit.getFontPeer

Toolkit.getFontPeer

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract FontPeer getFontPeer( String name, int style )
Parameters
target
the font to be implemented.
Returns
this toolkit's implementation of Font.
Description
Creates this toolkit's implementation of Font using the specified peer interface.

See Also
Font, FontPeer


 Toolkit.getImage

Toolkit.getImage

Class Overview | Class Members | This Package | All Packages

Syntax 1
public abstract Image getImage( String filename )
Parameters
filename
the name of a file containing pixel data in a recognized file format.
Returns
an image which gets its pixel data from the specified file.
Description
Returns an image which gets pixel data from the specified file.

Syntax 2
public abstract Image getImage( URL url )
Parameters
url
the URL to use in fetching the pixel data.
Returns
an image which gets its pixel data from the specified URL.
Description
Returns an image which gets pixel data from the specified URL.


 Toolkit.getMenuShortcutKeyMask

Toolkit.getMenuShortcutKeyMask

Class Overview | Class Members | This Package | All Packages

Syntax
public int getMenuShortcutKeyMask()
Returns
the modifier mask on the Event class that is used for menu shortcuts on this toolkit.
Description
Determines which modifier key is the appropriate accelerator key for menu shortcuts.

Menu shortcuts, which are embodied in the MenuShortcut class, are handled by the MenuBar class.

By default, this method returns Event.CTRL_MASK. Toolkit implementations should override this method if the Control key isn't the correct key for accelerators.

See Also
MenuBar, MenuShortcut


 Toolkit.getNativeContainer

Toolkit.getNativeContainer

Class Overview | Class Members | This Package | All Packages

Syntax
protected static Container getNativeContainer( Component c )
Description
Give native peers the ability to query the native container given a native component (eg the direct parent may be lightweight).


 Toolkit.getPrintJob

Toolkit.getPrintJob

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract PrintJob getPrintJob( Frame frame, String jobtitle, Properties props )
Returns
a PrintJob object, or null if the user cancelled the print job.
Description
Gets a PrintJob object which is the result of initiating a print operation on the toolkit's platform.

See Also
PrintJob


 Toolkit.getProperty

Toolkit.getProperty

Class Overview | Class Members | This Package | All Packages

Syntax
public static String getProperty( String key, String defaultValue )
Description
Gets a property with the specified key and default. This method returns defaultValue if the property is not found.


 Toolkit.getScreenResolution

Toolkit.getScreenResolution

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract int getScreenResolution()
Returns
this toolkit's screen resolution, in dots-per-inch.
Description
Returns the screen resolution in dots-per-inch.


 Toolkit.getScreenSize

Toolkit.getScreenSize

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract Dimension getScreenSize()
Returns
the size of this toolkit's screen, in pixels.
Description
Gets the size of the screen.


 Toolkit.getSystemClipboard

Toolkit.getSystemClipboard

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract Clipboard getSystemClipboard()
Returns
an instance of the system clipboard.
Description
Gets an instance of the system clipboard which interfaces with clipboard facilities provided by the native platform.

This clipboard enables data transfer between Java programs and native applications which use native clipboard facilities.

See Also
Clipboard


 Toolkit.getSystemEventQueue

Toolkit.getSystemEventQueue

Class Overview | Class Members | This Package | All Packages

Syntax
public final EventQueue getSystemEventQueue()
Description
Get the application's or applet's EventQueue instance. Depending on the Toolkit implementation, different EventQueues may be returned for different applets. Applets should therefore not assume that the EventQueue instance returned by this method will be shared by other applets or the system.


 Toolkit.getSystemEventQueueImpl

Toolkit.getSystemEventQueueImpl

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract EventQueue getSystemEventQueueImpl()


 Toolkit.loadSystemColors

Toolkit.loadSystemColors

Class Overview | Class Members | This Package | All Packages

Syntax
protected void loadSystemColors( int systemColors[] )
Parameters
an
integer array.
Description
Fills in the integer array that is supplied as an argument with the current system color values.


 Toolkit.prepareImage

Toolkit.prepareImage

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract boolean prepareImage( Image image, int width, int height, ImageObserver observer )
Parameters
image
the image for which to prepare a screen representation.
width
the width of the desired screen representation, or -1.
height
the height of the desired screen representation, or -1.
observer
the ImageObserver object to be notified as the image is being prepared.
Returns
true if the image has already been fully prepared; false otherwise.
Description
Prepares an image for rendering.

If the values of the width and height arguments are both -1, this method prepares the image for rendering on the default screen; otherwise, this method prepares an image for rendering on the default screen at the specified width and height.

The image data is downloaded asynchronously in another thread, and an appropriately scaled screen representation of the image is generated.

This method is called by components prepareImage methods.

Information on the flags returned by this method can be found with the definition of the ImageObserver interface.

See Also
prepareImage, prepareImage, ImageObserver


 Toolkit.sync

Toolkit.sync

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void sync()
Description
Synchronizes this toolkit's graphics state. Some window systems may do buffering of graphics events.

This method ensures that the display is up-to-date. It is useful for animation.


 Class Window

Class java.awt.Window

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.Component
           |
           +----java.awt.Container
                   |
                   +----java.awt.Window

public class Window
extends Container

A Window object is a top-level window with no borders and no menubar. It could be used to implement a pop-up menu. The default layout for a window is BorderLayout. A Window object blocks input to other application windows when it is shown.

Windows are capable of generating the following window events: WindowOpened, WindowClosed.

See Also:
WindowEvent, addWindowListener, BorderLayout


 Window Members

Window Members

Class Overview | This Package | All Packages

Constructors
Name | Description
Window(Frame) | Constructs a new invisible window.

Methods
Name | Description
addNotify() | Creates the Window's peer.
addWindowListener(WindowListener) | Adds the specified window listener to receive window events from this window.
dispose() | Disposes of this window.
getFocusOwner() | Returns the child component of this Window which has focus if and only if this Window is active.
getLocale() | Gets the Locale object that is associated with this window, if the locale has been set.
getToolkit() | Returns the toolkit of this frame.
getWarningString() | Gets the warning string that is displayed with this window.
isShowing() | Checks if this Window is showing on screen.
pack() | Causes subcomponents of this window to be laid out at their preferred size.
postEvent(Event) | Deprecated.
processEvent(AWTEvent) | Processes events on this window.
processWindowEvent(WindowEvent) | Processes window events occurring on this window by dispatching them to any registered WindowListener objects.
removeWindowListener(WindowListener) | Removes the specified window listener so that it no longer receives window events from this window.
show() | Shows this window, and brings it to the front.
toBack() | Sends this window to the back.
toFront() | Brings this window to the front.


 Window.Window

Window.Window

Class Overview | Class Members | This Package | All Packages

Syntax
public Window( Frame parent )
Parameters
parent
the main application frame.
Description
Constructs a new invisible window.

The window is not initially visible. Call the show method to cause the window to become visible.

See Also
show, setSize


 Window.addNotify

Window.addNotify

Class Overview | Class Members | This Package | All Packages

Syntax
public void addNotify()
Description
Creates the Window's peer. The peer allows us to modify the appearance of the Window without changing its functionality.

Overrides
addNotify in class Container


 Window.addWindowListener

Window.addWindowListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void addWindowListener( WindowListener l )
Parameters
l
the window listener
Description
Adds the specified window listener to receive window events from this window.


 Window.dispose

Window.dispose

Class Overview | Class Members | This Package | All Packages

Syntax
public void dispose()
Description
Disposes of this window. This method must be called to release the resources that are used for the window.


 Window.getFocusOwner

Window.getFocusOwner

Class Overview | Class Members | This Package | All Packages

Syntax
public Component getFocusOwner()
Returns
the component with focus, or null if no children have focus assigned to them.
Description
Returns the child component of this Window which has focus if and only if this Window is active.


 Window.getLocale

Window.getLocale

Class Overview | Class Members | This Package | All Packages

Syntax
public Locale getLocale()
Returns
the locale that is set for this window.
Description
Gets the Locale object that is associated with this window, if the locale has been set. If no locale has been set, then the default locale is returned.

Overrides
getLocale in class Component
See Also
Locale


 Window.getToolkit

Window.getToolkit

Class Overview | Class Members | This Package | All Packages

Syntax
public Toolkit getToolkit()
Returns
the toolkit of this window.
Description
Returns the toolkit of this frame.

Overrides
getToolkit in class Component
See Also
Toolkit, getDefaultToolkit, getToolkit


 Window.getWarningString

Window.getWarningString

Class Overview | Class Members | This Package | All Packages

Syntax
public final String getWarningString()
Returns
the warning string for this window.
Description
Gets the warning string that is displayed with this window. If this window is insecure, the warning string is displayed somewhere in the visible area of the window. A window is insecure if there is a security manager, and the security manager's checkTopLevelWindow method returns false when this window is passed to it as an argument.

If the window is secure, then getWarningString returns null. If the window is insecure, this methods checks for the system property awt.appletWarning and returns the string value of that property.

See Also
checkTopLevelWindow


 Window.isShowing

Window.isShowing

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isShowing()
Description
Checks if this Window is showing on screen.

Overrides
isShowing in class Component
See Also
setVisible


 Window.pack

Window.pack

Class Overview | Class Members | This Package | All Packages

Syntax
public void pack()
Description
Causes subcomponents of this window to be laid out at their preferred size.


 Window.postEvent

Window.postEvent

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean postEvent( Event e )
Description
Note: postEvent() is deprecated. As of JDK version 1.1 replaced by dispatchEvent(AWTEvent).

Overrides
postEvent in class Component


 Window.processEvent

Window.processEvent

Class Overview | Class Members | This Package | All Packages

Syntax
protected void processEvent( AWTEvent e )
Parameters
e
the event
Description
Processes events on this window. If the event is an WindowEvent, it invokes the processWindowEvent method, else it invokes its superclass's processEvent.

Overrides
processEvent in class Container


 Window.processWindowEvent

Window.processWindowEvent

Class Overview | Class Members | This Package | All Packages

Syntax
protected void processWindowEvent( WindowEvent e )
Parameters
e
the window event
Description
Processes window events occurring on this window by dispatching them to any registered WindowListener objects. NOTE: This method will not be called unless window events are enabled for this component; this happens when one of the following occurs: a) A WindowListener object is registered via addWindowListener() b) Window events are enabled via enableEvents()

See Also
enableEvents


 Window.removeWindowListener

Window.removeWindowListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void removeWindowListener( WindowListener l )
Parameters
l
the window listener
Description
Removes the specified window listener so that it no longer receives window events from this window.


 Window.show

Window.show

Class Overview | Class Members | This Package | All Packages

Syntax
public void show()
Description
Shows this window, and brings it to the front.

If this window is not yet visible, show makes it visible. If this window is already visible, then this method brings it to the front.

Overrides
show in class Component
See Also
toFront, setVisible


 Window.toBack

Window.toBack

Class Overview | Class Members | This Package | All Packages

Syntax
public void toBack()
Description
Sends this window to the back. Places this window at the bottom of the stacking order and makes the corresponding adjustment to other visible windows.

See Also
toFront


 Window.toFront

Window.toFront

Class Overview | Class Members | This Package | All Packages

Syntax
public void toFront()
Description
Brings this window to the front. Places this window at the top of the stacking order and shows it in front of any other windows.

See Also
toBack


 Package java.awt.datatransfer

Package java.awt.datatransfer

All Packages

Interfaces

  • ClipboardOwner
  • Transferable

    • Classes

  • Clipboard
  • DataFlavor
  • StringSelection

    • Exceptions

  • UnsupportedFlavorException


 Class Clipboard

Class java.awt.datatransfer.Clipboard

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.datatransfer.Clipboard

public class Clipboard
extends Object

A class which implements a mechanism to transfer data using cut/copy/paste operations.


 Clipboard Members

Clipboard Members

Class Overview | This Package | All Packages

Fields
Name | Description
contents |
owner |

Constructors
Name | Description
Clipboard(String) | Creates a clipboard object.

Methods
Name | Description
getContents(Object) | Returns a transferable object representing the current contents of the clipboard.
getName() | Returns the name of this clipboard object.
setContents(Transferable, ClipboardOwner) | Sets the current contents of the clipboard to the specified transferable object and registers the specified clipboard owner as the owner of the new contents.


 Clipboard.contents

Clipboard.contents

Class Overview | Class Members | This Package | All Packages

Syntax
protected Transferable contents


 Clipboard.owner

Clipboard.owner

Class Overview | Class Members | This Package | All Packages

Syntax
protected ClipboardOwner owner


 Clipboard.Clipboard

Clipboard.Clipboard

Class Overview | Class Members | This Package | All Packages

Syntax
public Clipboard( String name )
Description
Creates a clipboard object.


 Clipboard.getContents

Clipboard.getContents

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized Transferable getContents( Object requestor )
Parameters
requestor
the object requesting the clip data
Returns
the current transferable object on the clipboard
Description
Returns a transferable object representing the current contents of the clipboard. If the clipboard currently has no contents, it returns null.


 Clipboard.getName

Clipboard.getName

Class Overview | Class Members | This Package | All Packages

Syntax
public String getName()
Description
Returns the name of this clipboard object.


 Clipboard.setContents

Clipboard.setContents

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setContents( Transferable contents, ClipboardOwner owner )
Parameters
content
the transferable object representing the clipboard content
owner
the object which owns the clipboard content
Description
Sets the current contents of the clipboard to the specified transferable object and registers the specified clipboard owner as the owner of the new contents. If there is an existing owner registered, that owner is notified that it no longer holds ownership of the clipboard contents.


 Interface ClipboardOwner

Interface java.awt.datatransfer.ClipboardOwner

Interface Members | This Package | All Packages

public interface ClipboardOwner

Defines the interface for classes that will provide data to a clipboard.


 ClipboardOwner Members

ClipboardOwner Members

Interface Overview | This Package | All Packages

Methods
Name | Description
lostOwnership(Clipboard, Transferable) | Notifies this object that it is no longer the owner of the contents of the clipboard.


 ClipboardOwner.lostOwnership

ClipboardOwner.lostOwnership

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void lostOwnership( Clipboard clipboard, Transferable contents )
Parameters
clipboard
the clipboard that is no longer owned
contents
the contents which this owner had placed on the clipboard
Description
Notifies this object that it is no longer the owner of the contents of the clipboard.


 Class DataFlavor

Class java.awt.datatransfer.DataFlavor

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.datatransfer.DataFlavor

public class DataFlavor
extends Object

Each instance represents the opaque concept of a data format as would appear on a clipboard, during drag and drop, or in a file system.


 DataFlavor Members

DataFlavor Members

Class Overview | This Package | All Packages

Fields
Name | Description
plainTextFlavor | The DataFlavor representing plain text with unicode encoding, where: representationClass = InputStream mimeType = "text/plain; charset=unicode"
stringFlavor | The DataFlavor representing a Java Unicode String class, where: representationClass = java.lang.String mimeType = "application/x-java-serialized-object"

Constructors
Name | Description
DataFlavor(Class, String) | Construct a DataFlavor that represents a Java class The returned DataFlavor will have the following characteristics representationClass = representationClass mimeType = application/x-java-serialized-object
DataFlavor(String, String) | Construct a DataFlavor that represents a MimeType The returned DataFlavor will have the following characteristics: If the mimeType is "application/x-java-serialized-object; class=", the result is the same as calling new DataFlavor(Class:forName() as above otherwise: representationClass = InputStream mimeType = mimeType

Methods
Name | Description
equals(DataFlavor) |
getHumanPresentableName() | Returns the human presentable name for the data foramt that this DataFlavor represents.
getMimeType() | Returns the MIME type string for this DataFlavor
getRepresentationClass() | Returns the Class which objects supporting this DataFlavor will return when this DataFlavor is requested.
isMimeTypeEqual(DataFlavor) | Convenience function equivalent to calling: isMimeTypeEqual(dataFlavor.getMimeType());
isMimeTypeEqual(String) | Is the string representation of the MIME type passed in equivalent to the MIME type of this DataFlavor.
normalizeMimeType(String) | Called for each MIME type string to give DataFlavor subtypes the opportunity to change how the normalization of MIME types is accomplished.
normalizeMimeTypeParameter(String, String) | Called on DataFlavor for every MIME Type parameter to allow DataFlavor subclasses to handle special parameters like the text/plain charset parameters, whose values are case insensitive.
setHumanPresentableName(String) | Sets the human presentable name for the data format that this DataFlavor represents.


 DataFlavor.plainTextFlavor

DataFlavor.plainTextFlavor

Class Overview | Class Members | This Package | All Packages

Syntax
public static DataFlavor plainTextFlavor
Description
The DataFlavor representing plain text with unicode encoding, where:

representationClass = InputStream
mimeType = "text/plain; charset=unicode"


 DataFlavor.stringFlavor

DataFlavor.stringFlavor

Class Overview | Class Members | This Package | All Packages

Syntax
public static DataFlavor stringFlavor
Description
The DataFlavor representing a Java Unicode String class, where:

representationClass = java.lang.String
mimeType = "application/x-java-serialized-object"


 DataFlavor.DataFlavor

DataFlavor.DataFlavor

Class Overview | Class Members | This Package | All Packages

Syntax 1
public DataFlavor( Class representationClass, String humanPresentableName )
Parameters
representationClass
the class used to transfer data in this flavor
humanPresentableName
the human-readible string used to identify this flavor
Description
Construct a DataFlavor that represents a Java class

The returned DataFlavor will have the following characteristics

representationClass = representationClass
mimeType = application/x-java-serialized-object

Syntax 2
public DataFlavor( String mimeType, String humanPresentableName )
Parameters
mimeType
the string used to identify the MIME type for this flavor
humanPresentableName
the human-readible string used to identify this flavor
Description
Construct a DataFlavor that represents a MimeType

The returned DataFlavor will have the following characteristics:

If the mimeType is "application/x-java-serialized-object; class=", the result is the same as calling new DataFlavor(Class:forName() as above

otherwise:

representationClass = InputStream
mimeType = mimeType


 DataFlavor.equals

DataFlavor.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( DataFlavor dataFlavor )


 DataFlavor.getHumanPresentableName

DataFlavor.getHumanPresentableName

Class Overview | Class Members | This Package | All Packages

Syntax
public String getHumanPresentableName()
Description
Returns the human presentable name for the data foramt that this DataFlavor represents. This name would be localized for different countries


 DataFlavor.getMimeType

DataFlavor.getMimeType

Class Overview | Class Members | This Package | All Packages

Syntax
public String getMimeType()
Description
Returns the MIME type string for this DataFlavor


 DataFlavor.getRepresentationClass

DataFlavor.getRepresentationClass

Class Overview | Class Members | This Package | All Packages

Syntax
public Class getRepresentationClass()
Description
Returns the Class which objects supporting this DataFlavor will return when this DataFlavor is requested.


 DataFlavor.isMimeTypeEqual

DataFlavor.isMimeTypeEqual

Class Overview | Class Members | This Package | All Packages

Syntax 1
public boolean isMimeTypeEqual( String mimeType )
Description
Is the string representation of the MIME type passed in equivalent to the MIME type of this DataFlavor. This may involve adding default attributes for some MIME types (like adding charset=US-ASCII to text/plain MIME types that have no charset parameter specified)

Syntax 2
public final boolean isMimeTypeEqual( DataFlavor dataFlavor )
Description
Convenience function equivalent to calling: isMimeTypeEqual(dataFlavor.getMimeType());


 DataFlavor.normalizeMimeType

DataFlavor.normalizeMimeType

Class Overview | Class Members | This Package | All Packages

Syntax
protected String normalizeMimeType( String mimeType )
Description
Called for each MIME type string to give DataFlavor subtypes the opportunity to change how the normalization of MIME types is accomplished. One possible use would be to add default parameter/value pairs in cases where none are present in the MIME type string passed in


 DataFlavor.normalizeMimeTypeParameter

DataFlavor.normalizeMimeTypeParameter

Class Overview | Class Members | This Package | All Packages

Syntax
protected String normalizeMimeTypeParameter( String parameterName, String parameterValue )
Description
Called on DataFlavor for every MIME Type parameter to allow DataFlavor subclasses to handle special parameters like the text/plain charset parameters, whose values are case insensitive. (MIME type parameter values are supposed to be case sensitive.

This method is called for each parameter name/value pair and should return the normalized representation of the parameterValue


 DataFlavor.setHumanPresentableName

DataFlavor.setHumanPresentableName

Class Overview | Class Members | This Package | All Packages

Syntax
public void setHumanPresentableName( String humanPresentableName )
Description
Sets the human presentable name for the data format that this DataFlavor represents. This name would be localized for different countries


 Class StringSelection

Class java.awt.datatransfer.StringSelection

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.datatransfer.StringSelection

public class StringSelection
extends Object
implements Transferable, ClipboardOwner

A class which implements the capability required to transfer a simple java String in plain text format.


 StringSelection Members

StringSelection Members

Class Overview | This Package | All Packages

Constructors
Name | Description
StringSelection(String) | Creates a transferable object capable of transferring the specified string in plain text format.

Methods
Name | Description
getTransferData(DataFlavor) | If the data was requested in the "java.lang.String" flavor, return the String representing the selection.
getTransferDataFlavors() | Returns the array of flavors in which it can provide the data.
isDataFlavorSupported(DataFlavor) | Returns whether the requested flavor is supported by this object.
lostOwnership(Clipboard, Transferable) |


 StringSelection.StringSelection

StringSelection.StringSelection

Class Overview | Class Members | This Package | All Packages

Syntax
public StringSelection( String data )
Description
Creates a transferable object capable of transferring the specified string in plain text format.


 StringSelection.getTransferData

StringSelection.getTransferData

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized Object getTransferData( DataFlavor flavor ) throws UnsupportedFlavorException, IOException
Parameters
flavor
the requested flavor for the data
Description
If the data was requested in the "java.lang.String" flavor, return the String representing the selection.

Exceptions
UnsupportedFlavorException if the requested data flavor is not supported in the "java.lang.String" flavor.


 StringSelection.getTransferDataFlavors

StringSelection.getTransferDataFlavors

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized DataFlavor[] getTransferDataFlavors()
Description
Returns the array of flavors in which it can provide the data.


 StringSelection.isDataFlavorSupported

StringSelection.isDataFlavorSupported

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isDataFlavorSupported( DataFlavor flavor )
Parameters
flavor
the requested flavor for the data
Description
Returns whether the requested flavor is supported by this object.


 StringSelection.lostOwnership

StringSelection.lostOwnership

Class Overview | Class Members | This Package | All Packages

Syntax
public void lostOwnership( Clipboard clipboard, Transferable contents )


 Interface Transferable

Interface java.awt.datatransfer.Transferable

Interface Members | This Package | All Packages

public interface Transferable

Defines the interface for classes that can be used to provide data for a transfer operation.


 Transferable Members

Transferable Members

Interface Overview | This Package | All Packages

Methods
Name | Description
getTransferData(DataFlavor) | Returns an object which represents the data to be transferred.
getTransferDataFlavors() | Returns an array of DataFlavor objects indicating the flavors the data can be provided in.
isDataFlavorSupported(DataFlavor) | Returns whether or not the specified data flavor is supported for this object.


 Transferable.getTransferData

Transferable.getTransferData

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Object getTransferData( DataFlavor flavor ) throws UnsupportedFlavorException, IOException
Parameters
flavor
the requested flavor for the data
Description
Returns an object which represents the data to be transferred. The class of the object returned is defined by the representation class of the flavor.

Exceptions
IOException if the data is no longer available in the requested flavor.
Exceptions
UnsupportedFlavorException if the requested data flavor is not supported.
See Also
getRepresentationClass


 Transferable.getTransferDataFlavors

Transferable.getTransferDataFlavors

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract DataFlavor[] getTransferDataFlavors()
Returns
an array of data flavors in which this data can be transferred
Description
Returns an array of DataFlavor objects indicating the flavors the data can be provided in. The array should be ordered according to preference for providing the data (from most richly descriptive to least descriptive).


 Transferable.isDataFlavorSupported

Transferable.isDataFlavorSupported

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean isDataFlavorSupported( DataFlavor flavor )
Parameters
flavor
the requested flavor for the data
Returns
boolean indicating wjether or not the data flavor is supported
Description
Returns whether or not the specified data flavor is supported for this object.


 Class UnsupportedFlavorException

Class java.awt.datatransfer.UnsupportedFlavorException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.awt.datatransfer.UnsupportedFlavorException

public class UnsupportedFlavorException
extends Exception

Signals that the requested data is not supported in this flavor.

See Also:
getTransferData


 UnsupportedFlavorException Members

UnsupportedFlavorException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
UnsupportedFlavorException(DataFlavor) | Constructs an UnsupportedFlavorException.


 UnsupportedFlavorException.UnsupportedFlavorException

UnsupportedFlavorException.UnsupportedFlavorException

Class Overview | Class Members | This Package | All Packages

Syntax
public UnsupportedFlavorException( DataFlavor flavor )
Parameters
flavor
the flavor object which caused the exception
Description
Constructs an UnsupportedFlavorException.


 Package java.awt.event

Package java.awt.event

All Packages

Interfaces

  • ActionListener
  • AdjustmentListener
  • ComponentListener
  • ContainerListener
  • FocusListener
  • ItemListener
  • KeyListener
  • MouseListener
  • MouseMotionListener
  • TextListener
  • WindowListener

    • Classes

  • ActionEvent
  • AdjustmentEvent
  • ComponentAdapter
  • ComponentEvent
  • ContainerAdapter
  • ContainerEvent
  • FocusAdapter
  • FocusEvent
  • InputEvent
  • ItemEvent
  • KeyAdapter
  • KeyEvent
  • MouseAdapter
  • MouseEvent
  • MouseMotionAdapter
  • PaintEvent
  • TextEvent
  • WindowAdapter
  • WindowEvent


 Class ActionEvent

Class java.awt.event.ActionEvent

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.EventObject
           |
           +----java.awt.AWTEvent
                   |
                   +----java.awt.event.ActionEvent

public class ActionEvent
extends AWTEvent

The action semantic event.

See Also:
ActionListener


 ActionEvent Members

ActionEvent Members

Class Overview | This Package | All Packages

Fields
Name | Description
ACTION_FIRST | Marks the first integer id for the range of action event ids.
ACTION_LAST | Marks the last integer id for the range of action event ids.
ACTION_PERFORMED | An action performed event type.
ALT_MASK | The alt modifier constant.
CTRL_MASK | The control modifier constant.
META_MASK | The meta modifier constant.
SHIFT_MASK | The shift modifier constant.

Constructors
Name | Description
ActionEvent(Object, int, String) | Constructs an ActionEvent object with the specified source object.
ActionEvent(Object, int, String, int) | Constructs an ActionEvent object with the specified source object.

Methods
Name | Description
getActionCommand() | Returns the command name associated with this action.
getModifiers() | Returns the modifiers held down during this action event.
paramString() |


 ActionEvent.ACTION_FIRST

ActionEvent.ACTION_FIRST

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int ACTION_FIRST
Description
Marks the first integer id for the range of action event ids.


 ActionEvent.ACTION_LAST

ActionEvent.ACTION_LAST

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int ACTION_LAST
Description
Marks the last integer id for the range of action event ids.


 ActionEvent.ACTION_PERFORMED

ActionEvent.ACTION_PERFORMED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int ACTION_PERFORMED
Description
An action performed event type.


 ActionEvent.ALT_MASK

ActionEvent.ALT_MASK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int ALT_MASK
Description
The alt modifier constant.


 ActionEvent.CTRL_MASK

ActionEvent.CTRL_MASK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int CTRL_MASK
Description
The control modifier constant.


 ActionEvent.META_MASK

ActionEvent.META_MASK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int META_MASK
Description
The meta modifier constant.


 ActionEvent.SHIFT_MASK

ActionEvent.SHIFT_MASK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SHIFT_MASK
Description
The shift modifier constant.


 ActionEvent.ActionEvent

ActionEvent.ActionEvent

Class Overview | Class Members | This Package | All Packages

Syntax 1
public ActionEvent( Object source, int id, String command )
Parameters
source
the object where the event originated
id
the type of event
command
the command string for this action event
Description
Constructs an ActionEvent object with the specified source object.

Syntax 2
public ActionEvent( Object source, int id, String command, int modifiers )
Parameters
source
the object where the event originated
id
the type of event
command
the command string for this action event
modifiers
the modifiers held down during this action
Description
Constructs an ActionEvent object with the specified source object.


 ActionEvent.getActionCommand

ActionEvent.getActionCommand

Class Overview | Class Members | This Package | All Packages

Syntax
public String getActionCommand()
Description
Returns the command name associated with this action.


 ActionEvent.getModifiers

ActionEvent.getModifiers

Class Overview | Class Members | This Package | All Packages

Syntax
public int getModifiers()
Description
Returns the modifiers held down during this action event.


 ActionEvent.paramString

ActionEvent.paramString

Class Overview | Class Members | This Package | All Packages

Syntax
public String paramString()
Overrides
paramString in class AWTEvent


 Interface ActionListener

Interface java.awt.event.ActionListener

Interface Members | This Package | All Packages

public interface ActionListener
extends EventListener

The listener interface for receiving action events.


 ActionListener Members

ActionListener Members

Interface Overview | This Package | All Packages

Methods
Name | Description
actionPerformed(ActionEvent) | Invoked when an action occurs.


 ActionListener.actionPerformed

ActionListener.actionPerformed

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void actionPerformed( ActionEvent e )
Description
Invoked when an action occurs.


 Class AdjustmentEvent

Class java.awt.event.AdjustmentEvent

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.EventObject
           |
           +----java.awt.AWTEvent
                   |
                   +----java.awt.event.AdjustmentEvent

public class AdjustmentEvent
extends AWTEvent

The adjustment event emitted by Adjustable objects.

See Also:
Adjustable, AdjustmentListener


 AdjustmentEvent Members

AdjustmentEvent Members

Class Overview | This Package | All Packages

Fields
Name | Description
ADJUSTMENT_FIRST | Marks the first integer id for the range of adjustment event ids.
ADJUSTMENT_LAST | Marks the last integer id for the range of adjustment event ids.
ADJUSTMENT_VALUE_CHANGED | The adjustment value changed event.
BLOCK_DECREMENT | The block decrement adjustment type.
BLOCK_INCREMENT | The block increment adjustment type.
TRACK | The absolute tracking adjustment type.
UNIT_DECREMENT | The unit decrement adjustment type.
UNIT_INCREMENT | The unit increment adjustment type.

Constructors
Name | Description
AdjustmentEvent(Adjustable, int, int, int) | Constructs a AdjustmentEvent object with the specified Adjustable source, type, and value.

Methods
Name | Description
getAdjustable() | Returns the Adjustable object where this event originated.
getAdjustmentType() | Returns the type of adjustment which caused the value changed event.
getValue() | Returns the current value in the adjustment event.
paramString() |


 AdjustmentEvent.ADJUSTMENT_FIRST

AdjustmentEvent.ADJUSTMENT_FIRST

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int ADJUSTMENT_FIRST
Description
Marks the first integer id for the range of adjustment event ids.


 AdjustmentEvent.ADJUSTMENT_LAST

AdjustmentEvent.ADJUSTMENT_LAST

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int ADJUSTMENT_LAST
Description
Marks the last integer id for the range of adjustment event ids.


 AdjustmentEvent.ADJUSTMENT_VALUE_CHANGED

AdjustmentEvent.ADJUSTMENT_VALUE_CHANGED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int ADJUSTMENT_VALUE_CHANGED
Description
The adjustment value changed event.


 AdjustmentEvent.BLOCK_DECREMENT

AdjustmentEvent.BLOCK_DECREMENT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int BLOCK_DECREMENT
Description
The block decrement adjustment type.


 AdjustmentEvent.BLOCK_INCREMENT

AdjustmentEvent.BLOCK_INCREMENT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int BLOCK_INCREMENT
Description
The block increment adjustment type.


 AdjustmentEvent.TRACK

AdjustmentEvent.TRACK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int TRACK
Description
The absolute tracking adjustment type.


 AdjustmentEvent.UNIT_DECREMENT

AdjustmentEvent.UNIT_DECREMENT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int UNIT_DECREMENT
Description
The unit decrement adjustment type.


 AdjustmentEvent.UNIT_INCREMENT

AdjustmentEvent.UNIT_INCREMENT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int UNIT_INCREMENT
Description
The unit increment adjustment type.


 AdjustmentEvent.AdjustmentEvent

AdjustmentEvent.AdjustmentEvent

Class Overview | Class Members | This Package | All Packages

Syntax
public AdjustmentEvent( Adjustable source, int id, int type, int value )
Parameters
source
the Adjustable object where the event originated
Description
Constructs a AdjustmentEvent object with the specified Adjustable source, type, and value.


 AdjustmentEvent.getAdjustable

AdjustmentEvent.getAdjustable

Class Overview | Class Members | This Package | All Packages

Syntax
public Adjustable getAdjustable()
Description
Returns the Adjustable object where this event originated.


 AdjustmentEvent.getAdjustmentType

AdjustmentEvent.getAdjustmentType

Class Overview | Class Members | This Package | All Packages

Syntax
public int getAdjustmentType()
Description
Returns the type of adjustment which caused the value changed event.

See Also
UNIT_INCREMENT, UNIT_DECREMENT, BLOCK_INCREMENT, BLOCK_DECREMENT, TRACK


 AdjustmentEvent.getValue

AdjustmentEvent.getValue

Class Overview | Class Members | This Package | All Packages

Syntax
public int getValue()
Description
Returns the current value in the adjustment event.


 AdjustmentEvent.paramString

AdjustmentEvent.paramString

Class Overview | Class Members | This Package | All Packages

Syntax
public String paramString()
Overrides
paramString in class AWTEvent


 Interface AdjustmentListener

Interface java.awt.event.AdjustmentListener

Interface Members | This Package | All Packages

public interface AdjustmentListener
extends EventListener

The listener interface for receiving adjustment events.


 AdjustmentListener Members

AdjustmentListener Members

Interface Overview | This Package | All Packages

Methods
Name | Description
adjustmentValueChanged(AdjustmentEvent) | Invoked when the value of the adjustable has changed.


 AdjustmentListener.adjustmentValueChanged

AdjustmentListener.adjustmentValueChanged

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void adjustmentValueChanged( AdjustmentEvent e )
Description
Invoked when the value of the adjustable has changed.


 Class ComponentAdapter

Class java.awt.event.ComponentAdapter

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.event.ComponentAdapter

public abstract class ComponentAdapter
extends Object
implements ComponentListener

The adapter which receives component events. The methods in this class are empty; this class is provided as a convenience for easily creating listeners by extending this class and overriding only the methods of interest.


 ComponentAdapter Members

ComponentAdapter Members

Class Overview | This Package | All Packages

Constructors
Name | Description
ComponentAdapter() |

Methods
Name | Description
componentHidden(ComponentEvent) |
componentMoved(ComponentEvent) |
componentResized(ComponentEvent) |
componentShown(ComponentEvent) |


 ComponentAdapter.ComponentAdapter

ComponentAdapter.ComponentAdapter

Class Overview | Class Members | This Package | All Packages

Syntax
public ComponentAdapter()


 ComponentAdapter.componentHidden

ComponentAdapter.componentHidden

Class Overview | Class Members | This Package | All Packages

Syntax
public void componentHidden( ComponentEvent e )


 ComponentAdapter.componentMoved

ComponentAdapter.componentMoved

Class Overview | Class Members | This Package | All Packages

Syntax
public void componentMoved( ComponentEvent e )


 ComponentAdapter.componentResized

ComponentAdapter.componentResized

Class Overview | Class Members | This Package | All Packages

Syntax
public void componentResized( ComponentEvent e )


 ComponentAdapter.componentShown

ComponentAdapter.componentShown

Class Overview | Class Members | This Package | All Packages

Syntax
public void componentShown( ComponentEvent e )


 Class ComponentEvent

Class java.awt.event.ComponentEvent

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.EventObject
           |
           +----java.awt.AWTEvent
                   |
                   +----java.awt.event.ComponentEvent

public class ComponentEvent
extends AWTEvent

The root event class for all component-level events. These events are provided for notification purposes ONLY; The AWT will automatically handle component moves and resizes internally so that GUI layout works properly regardless of whether a program is receiving these events or not.

See Also:
ComponentListener


 ComponentEvent Members

ComponentEvent Members

Class Overview | This Package | All Packages

Fields
Name | Description
COMPONENT_FIRST | Marks the first integer id for the range of component event ids.
COMPONENT_HIDDEN | The component hidden event type.
COMPONENT_LAST | Marks the last integer id for the range of component event ids.
COMPONENT_MOVED | The component moved event type.
COMPONENT_RESIZED | The component resized event type.
COMPONENT_SHOWN | The component shown event type.

Constructors
Name | Description
ComponentEvent(Component, int) | Constructs a ComponentEvent object with the specified source component and type.

Methods
Name | Description
getComponent() | Returns the component where this event originated.
paramString() |


 ComponentEvent.COMPONENT_FIRST

ComponentEvent.COMPONENT_FIRST

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int COMPONENT_FIRST
Description
Marks the first integer id for the range of component event ids.


 ComponentEvent.COMPONENT_HIDDEN

ComponentEvent.COMPONENT_HIDDEN

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int COMPONENT_HIDDEN
Description
The component hidden event type.


 ComponentEvent.COMPONENT_LAST

ComponentEvent.COMPONENT_LAST

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int COMPONENT_LAST
Description
Marks the last integer id for the range of component event ids.


 ComponentEvent.COMPONENT_MOVED

ComponentEvent.COMPONENT_MOVED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int COMPONENT_MOVED
Description
The component moved event type.


 ComponentEvent.COMPONENT_RESIZED

ComponentEvent.COMPONENT_RESIZED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int COMPONENT_RESIZED
Description
The component resized event type.


 ComponentEvent.COMPONENT_SHOWN

ComponentEvent.COMPONENT_SHOWN

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int COMPONENT_SHOWN
Description
The component shown event type.


 ComponentEvent.ComponentEvent

ComponentEvent.ComponentEvent

Class Overview | Class Members | This Package | All Packages

Syntax
public ComponentEvent( Component source, int id )
Parameters
source
the component where the event originated
Description
Constructs a ComponentEvent object with the specified source component and type.


 ComponentEvent.getComponent

ComponentEvent.getComponent

Class Overview | Class Members | This Package | All Packages

Syntax
public Component getComponent()
Description
Returns the component where this event originated.


 ComponentEvent.paramString

ComponentEvent.paramString

Class Overview | Class Members | This Package | All Packages

Syntax
public String paramString()
Overrides
paramString in class AWTEvent


 Interface ComponentListener

Interface java.awt.event.ComponentListener

Interface Members | This Package | All Packages

public interface ComponentListener
extends EventListener

The listener interface for receiving component events. Component events are provided for notification purposes ONLY; The AWT will automatically handle component moves and resizes internally so that GUI layout works properly regardless of whether a program registers a ComponentListener or not.


 ComponentListener Members

ComponentListener Members

Interface Overview | This Package | All Packages

Methods
Name | Description
componentHidden(ComponentEvent) | Invoked when component has been hidden.
componentMoved(ComponentEvent) | Invoked when component has been moved.
componentResized(ComponentEvent) | Invoked when component has been resized.
componentShown(ComponentEvent) | Invoked when component has been shown.


 ComponentListener.componentHidden

ComponentListener.componentHidden

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void componentHidden( ComponentEvent e )
Description
Invoked when component has been hidden.


 ComponentListener.componentMoved

ComponentListener.componentMoved

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void componentMoved( ComponentEvent e )
Description
Invoked when component has been moved.


 ComponentListener.componentResized

ComponentListener.componentResized

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void componentResized( ComponentEvent e )
Description
Invoked when component has been resized.


 ComponentListener.componentShown

ComponentListener.componentShown

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void componentShown( ComponentEvent e )
Description
Invoked when component has been shown.


 Class ContainerAdapter

Class java.awt.event.ContainerAdapter

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.event.ContainerAdapter

public abstract class ContainerAdapter
extends Object
implements ContainerListener

The adapter which receives container events. The methods in this class are empty; this class is provided as a convenience for easily creating listeners by extending this class and overriding only the methods of interest.


 ContainerAdapter Members

ContainerAdapter Members

Class Overview | This Package | All Packages

Constructors
Name | Description
ContainerAdapter() |

Methods
Name | Description
componentAdded(ContainerEvent) |
componentRemoved(ContainerEvent) |


 ContainerAdapter.ContainerAdapter

ContainerAdapter.ContainerAdapter

Class Overview | Class Members | This Package | All Packages

Syntax
public ContainerAdapter()


 ContainerAdapter.componentAdded

ContainerAdapter.componentAdded

Class Overview | Class Members | This Package | All Packages

Syntax
public void componentAdded( ContainerEvent e )


 ContainerAdapter.componentRemoved

ContainerAdapter.componentRemoved

Class Overview | Class Members | This Package | All Packages

Syntax
public void componentRemoved( ContainerEvent e )


 Class ContainerEvent

Class java.awt.event.ContainerEvent

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.EventObject
           |
           +----java.awt.AWTEvent
                   |
                   +----java.awt.event.ComponentEvent
                           |
                           +----java.awt.event.ContainerEvent

public class ContainerEvent
extends ComponentEvent

The class for container-level events. These events are provided for notification purposes ONLY; The AWT will automatically handle container add and remove operations internally.

See Also:
ContainerListener


 ContainerEvent Members

ContainerEvent Members

Class Overview | This Package | All Packages

Fields
Name | Description
COMPONENT_ADDED | The component moved event type.
COMPONENT_REMOVED | The component resized event type.
CONTAINER_FIRST | Marks the first integer id for the range of container event ids.
CONTAINER_LAST | Marks the last integer id for the range of container event ids.

Constructors
Name | Description
ContainerEvent(Component, int, Component) | Constructs a ContainerEvent object with the specified source container, type, and child which is being added or removed.

Methods
Name | Description
getChild() | Returns the child component that was added or removed in this event.
getContainer() | Returns the container where this event originated.
paramString() |


 ContainerEvent.COMPONENT_ADDED

ContainerEvent.COMPONENT_ADDED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int COMPONENT_ADDED
Description
The component moved event type.


 ContainerEvent.COMPONENT_REMOVED

ContainerEvent.COMPONENT_REMOVED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int COMPONENT_REMOVED
Description
The component resized event type.


 ContainerEvent.CONTAINER_FIRST

ContainerEvent.CONTAINER_FIRST

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int CONTAINER_FIRST
Description
Marks the first integer id for the range of container event ids.


 ContainerEvent.CONTAINER_LAST

ContainerEvent.CONTAINER_LAST

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int CONTAINER_LAST
Description
Marks the last integer id for the range of container event ids.


 ContainerEvent.ContainerEvent

ContainerEvent.ContainerEvent

Class Overview | Class Members | This Package | All Packages

Syntax
public ContainerEvent( Component source, int id, Component child )
Parameters
source
the container where the event originated
Description
Constructs a ContainerEvent object with the specified source container, type, and child which is being added or removed.


 ContainerEvent.getChild

ContainerEvent.getChild

Class Overview | Class Members | This Package | All Packages

Syntax
public Component getChild()
Description
Returns the child component that was added or removed in this event.


 ContainerEvent.getContainer

ContainerEvent.getContainer

Class Overview | Class Members | This Package | All Packages

Syntax
public Container getContainer()
Description
Returns the container where this event originated.


 ContainerEvent.paramString

ContainerEvent.paramString

Class Overview | Class Members | This Package | All Packages

Syntax
public String paramString()
Overrides
paramString in class ComponentEvent


 Interface ContainerListener

Interface java.awt.event.ContainerListener

Interface Members | This Package | All Packages

public interface ContainerListener
extends EventListener

The listener interface for receiving container events. Container events are provided for notification purposes ONLY; The AWT will automatically handle add and remove operations internally.


 ContainerListener Members

ContainerListener Members

Interface Overview | This Package | All Packages

Methods
Name | Description
componentAdded(ContainerEvent) | Invoked when a component has been added to the container.
componentRemoved(ContainerEvent) | Invoked when a component has been removed from the container.


 ContainerListener.componentAdded

ContainerListener.componentAdded

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void componentAdded( ContainerEvent e )
Description
Invoked when a component has been added to the container.


 ContainerListener.componentRemoved

ContainerListener.componentRemoved

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void componentRemoved( ContainerEvent e )
Description
Invoked when a component has been removed from the container.


 Class FocusAdapter

Class java.awt.event.FocusAdapter

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.event.FocusAdapter

public abstract class FocusAdapter
extends Object
implements FocusListener

The adapter which receives focus events. The methods in this class are empty; this class is provided as a convenience for easily creating listeners by extending this class and overriding only the methods of interest.


 FocusAdapter Members

FocusAdapter Members

Class Overview | This Package | All Packages

Constructors
Name | Description
FocusAdapter() |

Methods
Name | Description
focusGained(FocusEvent) |
focusLost(FocusEvent) |


 FocusAdapter.FocusAdapter

FocusAdapter.FocusAdapter

Class Overview | Class Members | This Package | All Packages

Syntax
public FocusAdapter()


 FocusAdapter.focusGained

FocusAdapter.focusGained

Class Overview | Class Members | This Package | All Packages

Syntax
public void focusGained( FocusEvent e )


 FocusAdapter.focusLost

FocusAdapter.focusLost

Class Overview | Class Members | This Package | All Packages

Syntax
public void focusLost( FocusEvent e )


 Class FocusEvent

Class java.awt.event.FocusEvent

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.EventObject
           |
           +----java.awt.AWTEvent
                   |
                   +----java.awt.event.ComponentEvent
                           |
                           +----java.awt.event.FocusEvent

public class FocusEvent
extends ComponentEvent

The component-level focus event. There are two levels of focus change events: permanent and temporary. Permanent focus change events occur when focus is directly moved from one component to another, such as through calls to requestFocus() or as the user uses the Tab key to traverse components. Temporary focus change events occur when focus is temporarily gained or lost for a component as the indirect result of another operation, such as window deactivation or a scrollbar drag. In this case, the original focus state will automatically be restored once that operation is finished, or, for the case of window deactivation, when the window is reactivated. Both permanent and temporary focus events are delivered using the FOCUS_GAINED and FOCUS_LOST event ids; the levels may be distinguished in the event using the isTemporary() method.


 FocusEvent Members

FocusEvent Members

Class Overview | This Package | All Packages

Fields
Name | Description
FOCUS_FIRST | Marks the first integer id for the range of focus event ids.
FOCUS_GAINED | The focus gained event type.
FOCUS_LAST | Marks the last integer id for the range of focus event ids.
FOCUS_LOST | The focus lost event type.

Constructors
Name | Description
FocusEvent(Component, int) | Constructs a permanent-level FocusEvent object with the specified source component and type.
FocusEvent(Component, int, boolean) | Constructs a FocusEvent object with the specified source component, type, and whether or not the focus event is a temporary level event.

Methods
Name | Description
isTemporary() | Returns whether or not this focus change event is a temporary change.
paramString() |


 FocusEvent.FOCUS_FIRST

FocusEvent.FOCUS_FIRST

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int FOCUS_FIRST
Description
Marks the first integer id for the range of focus event ids.


 FocusEvent.FOCUS_GAINED

FocusEvent.FOCUS_GAINED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int FOCUS_GAINED
Description
The focus gained event type.


 FocusEvent.FOCUS_LAST

FocusEvent.FOCUS_LAST

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int FOCUS_LAST
Description
Marks the last integer id for the range of focus event ids.


 FocusEvent.FOCUS_LOST

FocusEvent.FOCUS_LOST

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int FOCUS_LOST
Description
The focus lost event type.


 FocusEvent.FocusEvent

FocusEvent.FocusEvent

Class Overview | Class Members | This Package | All Packages

Syntax 1
public FocusEvent( Component source, int id, boolean temporary )
Parameters
source
the object where the event originated
Description
Constructs a FocusEvent object with the specified source component, type, and whether or not the focus event is a temporary level event.

Syntax 2
public FocusEvent( Component source, int id )
Parameters
source
the object where the event originated
Description
Constructs a permanent-level FocusEvent object with the specified source component and type.


 FocusEvent.isTemporary

FocusEvent.isTemporary

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isTemporary()
Description
Returns whether or not this focus change event is a temporary change.


 FocusEvent.paramString

FocusEvent.paramString

Class Overview | Class Members | This Package | All Packages

Syntax
public String paramString()
Overrides
paramString in class ComponentEvent


 Interface FocusListener

Interface java.awt.event.FocusListener

Interface Members | This Package | All Packages

public interface FocusListener
extends EventListener

The listener interface for receiving keyboard focus events on a component.


 FocusListener Members

FocusListener Members

Interface Overview | This Package | All Packages

Methods
Name | Description
focusGained(FocusEvent) | Invoked when a component gains the keyboard focus.
focusLost(FocusEvent) | Invoked when a component loses the keyboard focus.


 FocusListener.focusGained

FocusListener.focusGained

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void focusGained( FocusEvent e )
Description
Invoked when a component gains the keyboard focus.


 FocusListener.focusLost

FocusListener.focusLost

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void focusLost( FocusEvent e )
Description
Invoked when a component loses the keyboard focus.


 Class InputEvent

Class java.awt.event.InputEvent

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.EventObject
           |
           +----java.awt.AWTEvent
                   |
                   +----java.awt.event.ComponentEvent
                           |
                           +----java.awt.event.InputEvent

public abstract class InputEvent
extends ComponentEvent

The root event class for all component-level input events. Input events are delivered to listeners before they are processed normally by the source where they originated. This allows listeners and component subclasses to "consume" the event so that the source will not process them in their default manner. For example, consuming mousePressed events on a Button component will prevent the Button from being activated.


 InputEvent Members

InputEvent Members

Class Overview | This Package | All Packages

Fields
Name | Description
ALT_MASK | The alt key modifier constant.
BUTTON1_MASK | The mouse button1 modifier constant.
BUTTON2_MASK | The mouse button2 modifier constant.
BUTTON3_MASK | The mouse button3 modifier constant.
CTRL_MASK | The control key modifier constant.
META_MASK | The meta key modifier constant.
SHIFT_MASK | The shift key modifier constant.

Methods
Name | Description
consume() | Consumes this event so that it will not be processed in the default manner by the source which originated it.
getModifiers() | Returns the modifiers flag for this event.
getWhen() | Returns the timestamp of when this event occurred.
isAltDown() | Returns whether or not the Alt modifier is down on this event.
isConsumed() | Returns whether or not this event has been consumed.
isControlDown() | Returns whether or not the Control modifier is down on this event.
isMetaDown() | Returns whether or not the Meta modifier is down on this event.
isShiftDown() | Returns whether or not the Shift modifier is down on this event.


 InputEvent.ALT_MASK

InputEvent.ALT_MASK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int ALT_MASK
Description
The alt key modifier constant.


 InputEvent.BUTTON1_MASK

InputEvent.BUTTON1_MASK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int BUTTON1_MASK
Description
The mouse button1 modifier constant.


 InputEvent.BUTTON2_MASK

InputEvent.BUTTON2_MASK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int BUTTON2_MASK
Description
The mouse button2 modifier constant.


 InputEvent.BUTTON3_MASK

InputEvent.BUTTON3_MASK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int BUTTON3_MASK
Description
The mouse button3 modifier constant.


 InputEvent.CTRL_MASK

InputEvent.CTRL_MASK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int CTRL_MASK
Description
The control key modifier constant.


 InputEvent.META_MASK

InputEvent.META_MASK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int META_MASK
Description
The meta key modifier constant.


 InputEvent.SHIFT_MASK

InputEvent.SHIFT_MASK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SHIFT_MASK
Description
The shift key modifier constant.


 InputEvent.consume

InputEvent.consume

Class Overview | Class Members | This Package | All Packages

Syntax
public void consume()
Description
Consumes this event so that it will not be processed in the default manner by the source which originated it.

Overrides
consume in class AWTEvent


 InputEvent.getModifiers

InputEvent.getModifiers

Class Overview | Class Members | This Package | All Packages

Syntax
public int getModifiers()
Description
Returns the modifiers flag for this event.


 InputEvent.getWhen

InputEvent.getWhen

Class Overview | Class Members | This Package | All Packages

Syntax
public long getWhen()
Description
Returns the timestamp of when this event occurred.


 InputEvent.isAltDown

InputEvent.isAltDown

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isAltDown()
Description
Returns whether or not the Alt modifier is down on this event.


 InputEvent.isConsumed

InputEvent.isConsumed

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isConsumed()
Description
Returns whether or not this event has been consumed.

Overrides
isConsumed in class AWTEvent
See Also
consume


 InputEvent.isControlDown

InputEvent.isControlDown

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isControlDown()
Description
Returns whether or not the Control modifier is down on this event.


 InputEvent.isMetaDown

InputEvent.isMetaDown

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isMetaDown()
Description
Returns whether or not the Meta modifier is down on this event.


 InputEvent.isShiftDown

InputEvent.isShiftDown

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isShiftDown()
Description
Returns whether or not the Shift modifier is down on this event.


 Class ItemEvent

Class java.awt.event.ItemEvent

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.EventObject
           |
           +----java.awt.AWTEvent
                   |
                   +----java.awt.event.ItemEvent

public class ItemEvent
extends AWTEvent

The item event emitted by ItemSelectable objects. This event is generated when an item is selected or de-selected.

See Also:
ItemSelectable, ItemListener


 ItemEvent Members

ItemEvent Members

Class Overview | This Package | All Packages

Fields
Name | Description
DESELECTED | The item de-selected state change type.
ITEM_FIRST | Marks the first integer id for the range of item event ids.
ITEM_LAST | Marks the last integer id for the range of item event ids.
ITEM_STATE_CHANGED | The item state changed event type.
SELECTED | The item selected state change type.

Constructors
Name | Description
ItemEvent(ItemSelectable, int, Object, int) | Constructs a ItemSelectEvent object with the specified ItemSelectable source, type, item, and item select state.

Methods
Name | Description
getItem() | Returns the item where the event occurred.
getItemSelectable() | Returns the ItemSelectable object where this event originated.
getStateChange() | Returns the state change type which generated the event.
paramString() |


 ItemEvent.DESELECTED

ItemEvent.DESELECTED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int DESELECTED
Description
The item de-selected state change type.


 ItemEvent.ITEM_FIRST

ItemEvent.ITEM_FIRST

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int ITEM_FIRST
Description
Marks the first integer id for the range of item event ids.


 ItemEvent.ITEM_LAST

ItemEvent.ITEM_LAST

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int ITEM_LAST
Description
Marks the last integer id for the range of item event ids.


 ItemEvent.ITEM_STATE_CHANGED

ItemEvent.ITEM_STATE_CHANGED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int ITEM_STATE_CHANGED
Description
The item state changed event type.


 ItemEvent.SELECTED

ItemEvent.SELECTED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SELECTED
Description
The item selected state change type.


 ItemEvent.ItemEvent

ItemEvent.ItemEvent

Class Overview | Class Members | This Package | All Packages

Syntax
public ItemEvent( ItemSelectable source, int id, Object item, int stateChange )
Parameters
source
the ItemSelectable object where the event originated
Description
Constructs a ItemSelectEvent object with the specified ItemSelectable source, type, item, and item select state.


 ItemEvent.getItem

ItemEvent.getItem

Class Overview | Class Members | This Package | All Packages

Syntax
public Object getItem()
Description
Returns the item where the event occurred.


 ItemEvent.getItemSelectable

ItemEvent.getItemSelectable

Class Overview | Class Members | This Package | All Packages

Syntax
public ItemSelectable getItemSelectable()
Description
Returns the ItemSelectable object where this event originated.


 ItemEvent.getStateChange

ItemEvent.getStateChange

Class Overview | Class Members | This Package | All Packages

Syntax
public int getStateChange()
Description
Returns the state change type which generated the event.

See Also
SELECTED, DESELECTED


 ItemEvent.paramString

ItemEvent.paramString

Class Overview | Class Members | This Package | All Packages

Syntax
public String paramString()
Overrides
paramString in class AWTEvent


 Interface ItemListener

Interface java.awt.event.ItemListener

Interface Members | This Package | All Packages

public interface ItemListener
extends EventListener

The listener interface for receiving item events.

See Also:
ItemSelectable


 ItemListener Members

ItemListener Members

Interface Overview | This Package | All Packages

Methods
Name | Description
itemStateChanged(ItemEvent) | Invoked when an item's state has been changed.


 ItemListener.itemStateChanged

ItemListener.itemStateChanged

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void itemStateChanged( ItemEvent e )
Description
Invoked when an item's state has been changed.


 Class KeyAdapter

Class java.awt.event.KeyAdapter

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.event.KeyAdapter

public abstract class KeyAdapter
extends Object
implements KeyListener

The adapter which receives keyboard events. The methods in this class are empty; this class is provided as a convenience for easily creating listeners by extending this class and overriding only the methods of interest.


 KeyAdapter Members

KeyAdapter Members

Class Overview | This Package | All Packages

Constructors
Name | Description
KeyAdapter() |

Methods
Name | Description
keyPressed(KeyEvent) |
keyReleased(KeyEvent) |
keyTyped(KeyEvent) |


 KeyAdapter.KeyAdapter

KeyAdapter.KeyAdapter

Class Overview | Class Members | This Package | All Packages

Syntax
public KeyAdapter()


 KeyAdapter.keyPressed

KeyAdapter.keyPressed

Class Overview | Class Members | This Package | All Packages

Syntax
public void keyPressed( KeyEvent e )


 KeyAdapter.keyReleased

KeyAdapter.keyReleased

Class Overview | Class Members | This Package | All Packages

Syntax
public void keyReleased( KeyEvent e )


 KeyAdapter.keyTyped

KeyAdapter.keyTyped

Class Overview | Class Members | This Package | All Packages

Syntax
public void keyTyped( KeyEvent e )


 Class KeyEvent

Class java.awt.event.KeyEvent

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.EventObject
           |
           +----java.awt.AWTEvent
                   |
                   +----java.awt.event.ComponentEvent
                           |
                           +----java.awt.event.InputEvent
                                   |
                                   +----java.awt.event.KeyEvent

public class KeyEvent
extends InputEvent

The component-level keyboard event.


 KeyEvent Members

KeyEvent Members

Class Overview | This Package | All Packages

Fields
Name | Description
CHAR_UNDEFINED | KEY_PRESSED and KEY_RELEASED events which do not map to a valid Unicode character do not have a defined keyChar.
KEY_FIRST | Marks the first integer id for the range of key event ids.
KEY_LAST | Marks the last integer id for the range of key event ids.
KEY_PRESSED | The key pressed event type.
KEY_RELEASED | The key released event type.
KEY_TYPED | The key typed event type.
VK_0 | VK_0 thru VK_9 are the same as ASCII '0' thru '9' (0x30 - 0x39)
VK_1 |
VK_2 |
VK_3 |
VK_4 |
VK_5 |
VK_6 |
VK_7 |
VK_8 |
VK_9 |
VK_A | VK_A thru VK_Z are the same as ASCII 'A' thru 'Z' (0x41 - 0x5A)
VK_ACCEPT |
VK_ADD |
VK_ALT |
VK_B |
VK_BACK_QUOTE |
VK_BACK_SLASH |
VK_BACK_SPACE |
VK_C |
VK_CANCEL |
VK_CAPS_LOCK |
VK_CLEAR |
VK_CLOSE_BRACKET |
VK_COMMA |
VK_CONTROL |
VK_CONVERT |
VK_D |
VK_DECIMAL |
VK_DELETE |
VK_DIVIDE |
VK_DOWN |
VK_E |
VK_END |
VK_ENTER | Virtual key codes.
VK_EQUALS |
VK_ESCAPE |
VK_F |
VK_F1 |
VK_F10 |
VK_F11 |
VK_F12 |
VK_F2 |
VK_F3 |
VK_F4 |
VK_F5 |
VK_F6 |
VK_F7 |
VK_F8 |
VK_F9 |
VK_FINAL | for Asian Keyboard
VK_G |
VK_H |
VK_HELP |
VK_HOME |
VK_I |
VK_INSERT |
VK_J |
VK_K |
VK_KANA |
VK_KANJI |
VK_L |
VK_LEFT |
VK_M |
VK_META |
VK_MODECHANGE |
VK_MULTIPLY |
VK_N |
VK_NONCONVERT |
VK_NUM_LOCK |
VK_NUMPAD0 |
VK_NUMPAD1 |
VK_NUMPAD2 |
VK_NUMPAD3 |
VK_NUMPAD4 |
VK_NUMPAD5 |
VK_NUMPAD6 |
VK_NUMPAD7 |
VK_NUMPAD8 |
VK_NUMPAD9 |
VK_O |
VK_OPEN_BRACKET |
VK_P |
VK_PAGE_DOWN |
VK_PAGE_UP |
VK_PAUSE |
VK_PERIOD |
VK_PRINTSCREEN |
VK_Q |
VK_QUOTE |
VK_R |
VK_RIGHT |
VK_S |
VK_SCROLL_LOCK |
VK_SEMICOLON |
VK_SEPARATER |
VK_SHIFT |
VK_SLASH |
VK_SPACE |
VK_SUBTRACT |
VK_T |
VK_TAB |
VK_U |
VK_UNDEFINED | KEY_TYPED events do not have a defined keyCode.
VK_UP |
VK_V |
VK_W |
VK_X |
VK_Y |
VK_Z |

Constructors
Name | Description
KeyEvent(Component, int, long, int, int) |
KeyEvent(Component, int, long, int, int, char) | Constructs a KeyEvent object with the specified source component, type, modifiers, and key.

Methods
Name | Description
getKeyChar() | Returns the character associated with the key in this event.
getKeyCode() | Returns the integer key-code associated with the key in this event.
getKeyModifiersText(int) | Returns a String describing the modifier key(s), such as "Shift", or "Ctrl+Shift".
getKeyText(int) | Returns a String describing the keyCode, such as "HOME", "F1" or "A".
isActionKey() | Returns whether or not the key in this event is an "action" key, as defined in Event.java.
paramString() |
setKeyChar(char) |
setKeyCode(int) |
setModifiers(int) |


 KeyEvent.CHAR_UNDEFINED

KeyEvent.CHAR_UNDEFINED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final char CHAR_UNDEFINED
Description
KEY_PRESSED and KEY_RELEASED events which do not map to a valid Unicode character do not have a defined keyChar.


 KeyEvent.KEY_FIRST

KeyEvent.KEY_FIRST

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int KEY_FIRST
Description
Marks the first integer id for the range of key event ids.


 KeyEvent.KEY_LAST

KeyEvent.KEY_LAST

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int KEY_LAST
Description
Marks the last integer id for the range of key event ids.


 KeyEvent.KEY_PRESSED

KeyEvent.KEY_PRESSED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int KEY_PRESSED
Description
The key pressed event type.


 KeyEvent.KEY_RELEASED

KeyEvent.KEY_RELEASED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int KEY_RELEASED
Description
The key released event type.


 KeyEvent.KEY_TYPED

KeyEvent.KEY_TYPED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int KEY_TYPED
Description
The key typed event type. This type is generated by a combination of a key press followed by a key release.


 KeyEvent.VK_0

KeyEvent.VK_0

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_0
Description
VK_0 thru VK_9 are the same as ASCII '0' thru '9' (0x30 - 0x39)


 KeyEvent.VK_1

KeyEvent.VK_1

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_1


 KeyEvent.VK_2

KeyEvent.VK_2

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_2


 KeyEvent.VK_3

KeyEvent.VK_3

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_3


 KeyEvent.VK_4

KeyEvent.VK_4

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_4


 KeyEvent.VK_5

KeyEvent.VK_5

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_5


 KeyEvent.VK_6

KeyEvent.VK_6

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_6


 KeyEvent.VK_7

KeyEvent.VK_7

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_7


 KeyEvent.VK_8

KeyEvent.VK_8

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_8


 KeyEvent.VK_9

KeyEvent.VK_9

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_9


 KeyEvent.VK_A

KeyEvent.VK_A

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_A
Description
VK_A thru VK_Z are the same as ASCII 'A' thru 'Z' (0x41 - 0x5A)


 KeyEvent.VK_ACCEPT

KeyEvent.VK_ACCEPT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_ACCEPT


 KeyEvent.VK_ADD

KeyEvent.VK_ADD

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_ADD


 KeyEvent.VK_ALT

KeyEvent.VK_ALT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_ALT


 KeyEvent.VK_B

KeyEvent.VK_B

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_B


 KeyEvent.VK_BACK_QUOTE

KeyEvent.VK_BACK_QUOTE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_BACK_QUOTE


 KeyEvent.VK_BACK_SLASH

KeyEvent.VK_BACK_SLASH

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_BACK_SLASH


 KeyEvent.VK_BACK_SPACE

KeyEvent.VK_BACK_SPACE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_BACK_SPACE


 KeyEvent.VK_C

KeyEvent.VK_C

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_C


 KeyEvent.VK_CANCEL

KeyEvent.VK_CANCEL

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_CANCEL


 KeyEvent.VK_CAPS_LOCK

KeyEvent.VK_CAPS_LOCK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_CAPS_LOCK


 KeyEvent.VK_CLEAR

KeyEvent.VK_CLEAR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_CLEAR


 KeyEvent.VK_CLOSE_BRACKET

KeyEvent.VK_CLOSE_BRACKET

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_CLOSE_BRACKET


 KeyEvent.VK_COMMA

KeyEvent.VK_COMMA

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_COMMA


 KeyEvent.VK_CONTROL

KeyEvent.VK_CONTROL

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_CONTROL


 KeyEvent.VK_CONVERT

KeyEvent.VK_CONVERT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_CONVERT


 KeyEvent.VK_D

KeyEvent.VK_D

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_D


 KeyEvent.VK_DECIMAL

KeyEvent.VK_DECIMAL

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_DECIMAL


 KeyEvent.VK_DELETE

KeyEvent.VK_DELETE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_DELETE


 KeyEvent.VK_DIVIDE

KeyEvent.VK_DIVIDE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_DIVIDE


 KeyEvent.VK_DOWN

KeyEvent.VK_DOWN

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_DOWN


 KeyEvent.VK_E

KeyEvent.VK_E

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_E


 KeyEvent.VK_END

KeyEvent.VK_END

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_END


 KeyEvent.VK_ENTER

KeyEvent.VK_ENTER

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_ENTER
Description
Virtual key codes. These codes report which keyboard key has been pressed, rather than any character generated by one or more keys being pressed. For example, pressing the Shift key will cause a KEY_PRESSED event with a VK_SHIFT keyCode, while pressing the 'a' key will result in a VK_A keyCode. After the 'a' key is released, a KEY_RELEASED event will be fired with VK_A, followed by a KEY_TYPED event with a keyChar value of 'A'. Key combinations which do not result in characters, such as action keys like F1, will not generate KEY_TYPED events. Note: not all keyboards or systems are capable of generating all virtual key codes. No attempt is made in Java to artificially generate these keys. WARNING: aside from those keys where are defined by the Java language (VK_ENTER, VK_BACK_SPACE, and VK_TAB), do not rely on the values of these constants. Sun reserves the right to change these values as needed to accomodate a wider range of keyboards in the future.


 KeyEvent.VK_EQUALS

KeyEvent.VK_EQUALS

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_EQUALS


 KeyEvent.VK_ESCAPE

KeyEvent.VK_ESCAPE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_ESCAPE


 KeyEvent.VK_F

KeyEvent.VK_F

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_F


 KeyEvent.VK_F1

KeyEvent.VK_F1

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_F1


 KeyEvent.VK_F10

KeyEvent.VK_F10

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_F10


 KeyEvent.VK_F11

KeyEvent.VK_F11

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_F11


 KeyEvent.VK_F12

KeyEvent.VK_F12

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_F12


 KeyEvent.VK_F2

KeyEvent.VK_F2

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_F2


 KeyEvent.VK_F3

KeyEvent.VK_F3

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_F3


 KeyEvent.VK_F4

KeyEvent.VK_F4

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_F4


 KeyEvent.VK_F5

KeyEvent.VK_F5

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_F5


 KeyEvent.VK_F6

KeyEvent.VK_F6

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_F6


 KeyEvent.VK_F7

KeyEvent.VK_F7

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_F7


 KeyEvent.VK_F8

KeyEvent.VK_F8

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_F8


 KeyEvent.VK_F9

KeyEvent.VK_F9

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_F9


 KeyEvent.VK_FINAL

KeyEvent.VK_FINAL

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_FINAL
Description
for Asian Keyboard


 KeyEvent.VK_G

KeyEvent.VK_G

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_G


 KeyEvent.VK_H

KeyEvent.VK_H

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_H


 KeyEvent.VK_HELP

KeyEvent.VK_HELP

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_HELP


 KeyEvent.VK_HOME

KeyEvent.VK_HOME

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_HOME


 KeyEvent.VK_I

KeyEvent.VK_I

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_I


 KeyEvent.VK_INSERT

KeyEvent.VK_INSERT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_INSERT


 KeyEvent.VK_J

KeyEvent.VK_J

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_J


 KeyEvent.VK_K

KeyEvent.VK_K

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_K


 KeyEvent.VK_KANA

KeyEvent.VK_KANA

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_KANA


 KeyEvent.VK_KANJI

KeyEvent.VK_KANJI

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_KANJI


 KeyEvent.VK_L

KeyEvent.VK_L

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_L


 KeyEvent.VK_LEFT

KeyEvent.VK_LEFT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_LEFT


 KeyEvent.VK_M

KeyEvent.VK_M

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_M


 KeyEvent.VK_META

KeyEvent.VK_META

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_META


 KeyEvent.VK_MODECHANGE

KeyEvent.VK_MODECHANGE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_MODECHANGE


 KeyEvent.VK_MULTIPLY

KeyEvent.VK_MULTIPLY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_MULTIPLY


 KeyEvent.VK_N

KeyEvent.VK_N

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_N


 KeyEvent.VK_NONCONVERT

KeyEvent.VK_NONCONVERT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_NONCONVERT


 KeyEvent.VK_NUM_LOCK

KeyEvent.VK_NUM_LOCK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_NUM_LOCK


 KeyEvent.VK_NUMPAD0

KeyEvent.VK_NUMPAD0

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_NUMPAD0


 KeyEvent.VK_NUMPAD1

KeyEvent.VK_NUMPAD1

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_NUMPAD1


 KeyEvent.VK_NUMPAD2

KeyEvent.VK_NUMPAD2

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_NUMPAD2


 KeyEvent.VK_NUMPAD3

KeyEvent.VK_NUMPAD3

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_NUMPAD3


 KeyEvent.VK_NUMPAD4

KeyEvent.VK_NUMPAD4

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_NUMPAD4


 KeyEvent.VK_NUMPAD5

KeyEvent.VK_NUMPAD5

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_NUMPAD5


 KeyEvent.VK_NUMPAD6

KeyEvent.VK_NUMPAD6

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_NUMPAD6


 KeyEvent.VK_NUMPAD7

KeyEvent.VK_NUMPAD7

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_NUMPAD7


 KeyEvent.VK_NUMPAD8

KeyEvent.VK_NUMPAD8

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_NUMPAD8


 KeyEvent.VK_NUMPAD9

KeyEvent.VK_NUMPAD9

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_NUMPAD9


 KeyEvent.VK_O

KeyEvent.VK_O

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_O


 KeyEvent.VK_OPEN_BRACKET

KeyEvent.VK_OPEN_BRACKET

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_OPEN_BRACKET


 KeyEvent.VK_P

KeyEvent.VK_P

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_P


 KeyEvent.VK_PAGE_DOWN

KeyEvent.VK_PAGE_DOWN

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_PAGE_DOWN


 KeyEvent.VK_PAGE_UP

KeyEvent.VK_PAGE_UP

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_PAGE_UP


 KeyEvent.VK_PAUSE

KeyEvent.VK_PAUSE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_PAUSE


 KeyEvent.VK_PERIOD

KeyEvent.VK_PERIOD

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_PERIOD


 KeyEvent.VK_PRINTSCREEN

KeyEvent.VK_PRINTSCREEN

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_PRINTSCREEN


 KeyEvent.VK_Q

KeyEvent.VK_Q

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_Q


 KeyEvent.VK_QUOTE

KeyEvent.VK_QUOTE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_QUOTE


 KeyEvent.VK_R

KeyEvent.VK_R

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_R


 KeyEvent.VK_RIGHT

KeyEvent.VK_RIGHT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_RIGHT


 KeyEvent.VK_S

KeyEvent.VK_S

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_S


 KeyEvent.VK_SCROLL_LOCK

KeyEvent.VK_SCROLL_LOCK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_SCROLL_LOCK


 KeyEvent.VK_SEMICOLON

KeyEvent.VK_SEMICOLON

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_SEMICOLON


 KeyEvent.VK_SEPARATER

KeyEvent.VK_SEPARATER

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_SEPARATER


 KeyEvent.VK_SHIFT

KeyEvent.VK_SHIFT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_SHIFT


 KeyEvent.VK_SLASH

KeyEvent.VK_SLASH

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_SLASH


 KeyEvent.VK_SPACE

KeyEvent.VK_SPACE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_SPACE


 KeyEvent.VK_SUBTRACT

KeyEvent.VK_SUBTRACT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_SUBTRACT


 KeyEvent.VK_T

KeyEvent.VK_T

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_T


 KeyEvent.VK_TAB

KeyEvent.VK_TAB

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_TAB


 KeyEvent.VK_U

KeyEvent.VK_U

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_U


 KeyEvent.VK_UNDEFINED

KeyEvent.VK_UNDEFINED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_UNDEFINED
Description
KEY_TYPED events do not have a defined keyCode.


 KeyEvent.VK_UP

KeyEvent.VK_UP

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_UP


 KeyEvent.VK_V

KeyEvent.VK_V

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_V


 KeyEvent.VK_W

KeyEvent.VK_W

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_W


 KeyEvent.VK_X

KeyEvent.VK_X

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_X


 KeyEvent.VK_Y

KeyEvent.VK_Y

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_Y


 KeyEvent.VK_Z

KeyEvent.VK_Z

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VK_Z


 KeyEvent.KeyEvent

KeyEvent.KeyEvent

Class Overview | Class Members | This Package | All Packages

Syntax 1
public KeyEvent( Component source, int id, long when, int modifiers, int keyCode, char keyChar )
Parameters
source
the object where the event originated
Description
Constructs a KeyEvent object with the specified source component, type, modifiers, and key.

Syntax 2
public KeyEvent( Component source, int id, long when, int modifiers, int keyCode )


 KeyEvent.getKeyChar

KeyEvent.getKeyChar

Class Overview | Class Members | This Package | All Packages

Syntax
public char getKeyChar()
Description
Returns the character associated with the key in this event. If no valid Unicode character exists for this key event, keyChar is CHAR_UNDEFINED.


 KeyEvent.getKeyCode

KeyEvent.getKeyCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int getKeyCode()
Description
Returns the integer key-code associated with the key in this event. For KEY_TYPED events, keyCode is VK_UNDEFINED.


 KeyEvent.getKeyModifiersText

KeyEvent.getKeyModifiersText

Class Overview | Class Members | This Package | All Packages

Syntax
public static String getKeyModifiersText( int modifiers )
Description
Returns a String describing the modifier key(s), such as "Shift", or "Ctrl+Shift". These strings can be localized by changing the awt.properties file.


 KeyEvent.getKeyText

KeyEvent.getKeyText

Class Overview | Class Members | This Package | All Packages

Syntax
public static String getKeyText( int keyCode )
Description
Returns a String describing the keyCode, such as "HOME", "F1" or "A". These strings can be localized by changing the awt.properties file.


 KeyEvent.isActionKey

KeyEvent.isActionKey

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isActionKey()
Description
Returns whether or not the key in this event is an "action" key, as defined in Event.java.


 KeyEvent.paramString

KeyEvent.paramString

Class Overview | Class Members | This Package | All Packages

Syntax
public String paramString()
Overrides
paramString in class ComponentEvent


 KeyEvent.setKeyChar

KeyEvent.setKeyChar

Class Overview | Class Members | This Package | All Packages

Syntax
public void setKeyChar( char keyChar )


 KeyEvent.setKeyCode

KeyEvent.setKeyCode

Class Overview | Class Members | This Package | All Packages

Syntax
public void setKeyCode( int keyCode )


 KeyEvent.setModifiers

KeyEvent.setModifiers

Class Overview | Class Members | This Package | All Packages

Syntax
public void setModifiers( int modifiers )


 Interface KeyListener

Interface java.awt.event.KeyListener

Interface Members | This Package | All Packages

public interface KeyListener
extends EventListener

The listener interface for receiving keyboard events.


 KeyListener Members

KeyListener Members

Interface Overview | This Package | All Packages

Methods
Name | Description
keyPressed(KeyEvent) | Invoked when a key has been pressed.
keyReleased(KeyEvent) | Invoked when a key has been released.
keyTyped(KeyEvent) | Invoked when a key has been typed.


 KeyListener.keyPressed

KeyListener.keyPressed

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void keyPressed( KeyEvent e )
Description
Invoked when a key has been pressed.


 KeyListener.keyReleased

KeyListener.keyReleased

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void keyReleased( KeyEvent e )
Description
Invoked when a key has been released.


 KeyListener.keyTyped

KeyListener.keyTyped

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void keyTyped( KeyEvent e )
Description
Invoked when a key has been typed. This event occurs when a key press is followed by a key release.


 Class MouseAdapter

Class java.awt.event.MouseAdapter

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.event.MouseAdapter

public abstract class MouseAdapter
extends Object
implements MouseListener

The adapter which receives mouse events. The methods in this class are empty; this class is provided as a convenience for easily creating listeners by extending this class and overriding only the methods of interest.


 MouseAdapter Members

MouseAdapter Members

Class Overview | This Package | All Packages

Constructors
Name | Description
MouseAdapter() |

Methods
Name | Description
mouseClicked(MouseEvent) |
mouseEntered(MouseEvent) |
mouseExited(MouseEvent) |
mousePressed(MouseEvent) |
mouseReleased(MouseEvent) |


 MouseAdapter.MouseAdapter

MouseAdapter.MouseAdapter

Class Overview | Class Members | This Package | All Packages

Syntax
public MouseAdapter()


 MouseAdapter.mouseClicked

MouseAdapter.mouseClicked

Class Overview | Class Members | This Package | All Packages

Syntax
public void mouseClicked( MouseEvent e )


 MouseAdapter.mouseEntered

MouseAdapter.mouseEntered

Class Overview | Class Members | This Package | All Packages

Syntax
public void mouseEntered( MouseEvent e )


 MouseAdapter.mouseExited

MouseAdapter.mouseExited

Class Overview | Class Members | This Package | All Packages

Syntax
public void mouseExited( MouseEvent e )


 MouseAdapter.mousePressed

MouseAdapter.mousePressed

Class Overview | Class Members | This Package | All Packages

Syntax
public void mousePressed( MouseEvent e )


 MouseAdapter.mouseReleased

MouseAdapter.mouseReleased

Class Overview | Class Members | This Package | All Packages

Syntax
public void mouseReleased( MouseEvent e )


 Class MouseEvent

Class java.awt.event.MouseEvent

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.EventObject
           |
           +----java.awt.AWTEvent
                   |
                   +----java.awt.event.ComponentEvent
                           |
                           +----java.awt.event.InputEvent
                                   |
                                   +----java.awt.event.MouseEvent

public class MouseEvent
extends InputEvent

The mouse event.


 MouseEvent Members

MouseEvent Members

Class Overview | This Package | All Packages

Fields
Name | Description
MOUSE_CLICKED | The mouse clicked event type.
MOUSE_DRAGGED | The mouse dragged event type.
MOUSE_ENTERED | The mouse entered event type.
MOUSE_EXITED | The mouse exited event type.
MOUSE_FIRST | Marks the first integer id for the range of mouse event ids.
MOUSE_LAST | Marks the last integer id for the range of mouse event ids.
MOUSE_MOVED | The mouse moved event type.
MOUSE_PRESSED | The mouse pressed event type.
MOUSE_RELEASED | The mouse released event type.

Constructors
Name | Description
MouseEvent(Component, int, long, int, int, int, int, boolean) | Constructs a MouseEvent object with the specified source component, type, modifiers, coordinates, and click count.

Methods
Name | Description
getClickCount() | Return the number of mouse clicks associated with this event.
getPoint() | Returns the x,y position of the event relative to the source component.
getX() | Returns the x position of the event relative to the source component.
getY() | Returns the y position of the event relative to the source component.
isPopupTrigger() | Returns whether or not this mouse event is the popup-menu trigger event for the platform.
paramString() |
translatePoint(int, int) | Translates the coordinate position of the event by x, y.


 MouseEvent.MOUSE_CLICKED

MouseEvent.MOUSE_CLICKED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int MOUSE_CLICKED
Description
The mouse clicked event type.


 MouseEvent.MOUSE_DRAGGED

MouseEvent.MOUSE_DRAGGED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int MOUSE_DRAGGED
Description
The mouse dragged event type.


 MouseEvent.MOUSE_ENTERED

MouseEvent.MOUSE_ENTERED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int MOUSE_ENTERED
Description
The mouse entered event type.


 MouseEvent.MOUSE_EXITED

MouseEvent.MOUSE_EXITED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int MOUSE_EXITED
Description
The mouse exited event type.


 MouseEvent.MOUSE_FIRST

MouseEvent.MOUSE_FIRST

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int MOUSE_FIRST
Description
Marks the first integer id for the range of mouse event ids.


 MouseEvent.MOUSE_LAST

MouseEvent.MOUSE_LAST

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int MOUSE_LAST
Description
Marks the last integer id for the range of mouse event ids.


 MouseEvent.MOUSE_MOVED

MouseEvent.MOUSE_MOVED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int MOUSE_MOVED
Description
The mouse moved event type.


 MouseEvent.MOUSE_PRESSED

MouseEvent.MOUSE_PRESSED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int MOUSE_PRESSED
Description
The mouse pressed event type.


 MouseEvent.MOUSE_RELEASED

MouseEvent.MOUSE_RELEASED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int MOUSE_RELEASED
Description
The mouse released event type.


 MouseEvent.MouseEvent

MouseEvent.MouseEvent

Class Overview | Class Members | This Package | All Packages

Syntax
public MouseEvent( Component source, int id, long when, int modifiers, int x, int y, int clickCount, boolean popupTrigger )
Parameters
source
the object where the event originated
Description
Constructs a MouseEvent object with the specified source component, type, modifiers, coordinates, and click count.


 MouseEvent.getClickCount

MouseEvent.getClickCount

Class Overview | Class Members | This Package | All Packages

Syntax
public int getClickCount()
Description
Return the number of mouse clicks associated with this event.


 MouseEvent.getPoint

MouseEvent.getPoint

Class Overview | Class Members | This Package | All Packages

Syntax
public Point getPoint()
Description
Returns the x,y position of the event relative to the source component.


 MouseEvent.getX

MouseEvent.getX

Class Overview | Class Members | This Package | All Packages

Syntax
public int getX()
Description
Returns the x position of the event relative to the source component.


 MouseEvent.getY

MouseEvent.getY

Class Overview | Class Members | This Package | All Packages

Syntax
public int getY()
Description
Returns the y position of the event relative to the source component.


 MouseEvent.isPopupTrigger

MouseEvent.isPopupTrigger

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isPopupTrigger()
Description
Returns whether or not this mouse event is the popup-menu trigger event for the platform.


 MouseEvent.paramString

MouseEvent.paramString

Class Overview | Class Members | This Package | All Packages

Syntax
public String paramString()
Overrides
paramString in class ComponentEvent


 MouseEvent.translatePoint

MouseEvent.translatePoint

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void translatePoint( int x, int y )
Parameters
x
the x value added to the current x coordinate position
y
the y value added to the current y coordinate position
Description
Translates the coordinate position of the event by x, y.


 Interface MouseListener

Interface java.awt.event.MouseListener

Interface Members | This Package | All Packages

public interface MouseListener
extends EventListener

The listener interface for receiving mouse events on a component.


 MouseListener Members

MouseListener Members

Interface Overview | This Package | All Packages

Methods
Name | Description
mouseClicked(MouseEvent) | Invoked when the mouse has been clicked on a component.
mouseEntered(MouseEvent) | Invoked when the mouse enters a component.
mouseExited(MouseEvent) | Invoked when the mouse exits a component.
mousePressed(MouseEvent) | Invoked when a mouse button has been pressed on a component.
mouseReleased(MouseEvent) | Invoked when a mouse button has been released on a component.


 MouseListener.mouseClicked

MouseListener.mouseClicked

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void mouseClicked( MouseEvent e )
Description
Invoked when the mouse has been clicked on a component.


 MouseListener.mouseEntered

MouseListener.mouseEntered

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void mouseEntered( MouseEvent e )
Description
Invoked when the mouse enters a component.


 MouseListener.mouseExited

MouseListener.mouseExited

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void mouseExited( MouseEvent e )
Description
Invoked when the mouse exits a component.


 MouseListener.mousePressed

MouseListener.mousePressed

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void mousePressed( MouseEvent e )
Description
Invoked when a mouse button has been pressed on a component.


 MouseListener.mouseReleased

MouseListener.mouseReleased

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void mouseReleased( MouseEvent e )
Description
Invoked when a mouse button has been released on a component.


 Class MouseMotionAdapter

Class java.awt.event.MouseMotionAdapter

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.event.MouseMotionAdapter

public abstract class MouseMotionAdapter
extends Object
implements MouseMotionListener

The adapter which receives mouse motion events. The methods in this class are empty; this class is provided as a convenience for easily creating listeners by extending this class and overriding only the methods of interest.


 MouseMotionAdapter Members

MouseMotionAdapter Members

Class Overview | This Package | All Packages

Constructors
Name | Description
MouseMotionAdapter() |

Methods
Name | Description
mouseDragged(MouseEvent) |
mouseMoved(MouseEvent) |


 MouseMotionAdapter.MouseMotionAdapter

MouseMotionAdapter.MouseMotionAdapter

Class Overview | Class Members | This Package | All Packages

Syntax
public MouseMotionAdapter()


 MouseMotionAdapter.mouseDragged

MouseMotionAdapter.mouseDragged

Class Overview | Class Members | This Package | All Packages

Syntax
public void mouseDragged( MouseEvent e )


 MouseMotionAdapter.mouseMoved

MouseMotionAdapter.mouseMoved

Class Overview | Class Members | This Package | All Packages

Syntax
public void mouseMoved( MouseEvent e )


 Interface MouseMotionListener

Interface java.awt.event.MouseMotionListener

Interface Members | This Package | All Packages

public interface MouseMotionListener
extends EventListener

The listener interface for receiving mouse motion events on a component.


 MouseMotionListener Members

MouseMotionListener Members

Interface Overview | This Package | All Packages

Methods
Name | Description
mouseDragged(MouseEvent) | Invoked when a mouse button is pressed on a component and then dragged.
mouseMoved(MouseEvent) | Invoked when the mouse button has been moved on a component (with no buttons no down).


 MouseMotionListener.mouseDragged

MouseMotionListener.mouseDragged

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void mouseDragged( MouseEvent e )
Description
Invoked when a mouse button is pressed on a component and then dragged. Mouse drag events will continue to be delivered to the component where the first originated until the mouse button is released (regardless of whether the mouse position is within the bounds of the component).


 MouseMotionListener.mouseMoved

MouseMotionListener.mouseMoved

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void mouseMoved( MouseEvent e )
Description
Invoked when the mouse button has been moved on a component (with no buttons no down).


 Class PaintEvent

Class java.awt.event.PaintEvent

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.EventObject
           |
           +----java.awt.AWTEvent
                   |
                   +----java.awt.event.ComponentEvent
                           |
                           +----java.awt.event.PaintEvent

public class PaintEvent
extends ComponentEvent

The component-level paint event. This event is a special type which is used to ensure that paint/update method calls are serialized along with the other events delivered from the event queue. This event is not designed to be used with the Event Listener model; programs should continue to override paint/update methods in order render themselves properly.


 PaintEvent Members

PaintEvent Members

Class Overview | This Package | All Packages

Fields
Name | Description
PAINT | The paint event type.
PAINT_FIRST | Marks the first integer id for the range of paint event ids.
PAINT_LAST | Marks the last integer id for the range of paint event ids.
UPDATE | The update event type.

Constructors
Name | Description
PaintEvent(Component, int, Rectangle) | Constructs a PaintEvent object with the specified source component and type.

Methods
Name | Description
getUpdateRect() | Returns the rectangle representing the area which needs to be repainted in response to this event.
paramString() |
setUpdateRect(Rectangle) | Sets the rectangle representing the area which needs to be repainted in response to this event.


 PaintEvent.PAINT

PaintEvent.PAINT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int PAINT
Description
The paint event type.


 PaintEvent.PAINT_FIRST

PaintEvent.PAINT_FIRST

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int PAINT_FIRST
Description
Marks the first integer id for the range of paint event ids.


 PaintEvent.PAINT_LAST

PaintEvent.PAINT_LAST

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int PAINT_LAST
Description
Marks the last integer id for the range of paint event ids.


 PaintEvent.UPDATE

PaintEvent.UPDATE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int UPDATE
Description
The update event type.


 PaintEvent.PaintEvent

PaintEvent.PaintEvent

Class Overview | Class Members | This Package | All Packages

Syntax
public PaintEvent( Component source, int id, Rectangle updateRect )
Parameters
source
the object where the event originated
Description
Constructs a PaintEvent object with the specified source component and type.


 PaintEvent.getUpdateRect

PaintEvent.getUpdateRect

Class Overview | Class Members | This Package | All Packages

Syntax
public Rectangle getUpdateRect()
Description
Returns the rectangle representing the area which needs to be repainted in response to this event.


 PaintEvent.paramString

PaintEvent.paramString

Class Overview | Class Members | This Package | All Packages

Syntax
public String paramString()
Overrides
paramString in class ComponentEvent


 PaintEvent.setUpdateRect

PaintEvent.setUpdateRect

Class Overview | Class Members | This Package | All Packages

Syntax
public void setUpdateRect( Rectangle updateRect )
Parameters
updateRect
the rectangle area which needs to be repainted
Description
Sets the rectangle representing the area which needs to be repainted in response to this event.


 Class TextEvent

Class java.awt.event.TextEvent

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.EventObject
           |
           +----java.awt.AWTEvent
                   |
                   +----java.awt.event.TextEvent

public class TextEvent
extends AWTEvent

The text event emitted by TextComponents.

See Also:
TextComponent, TextEventListener


 TextEvent Members

TextEvent Members

Class Overview | This Package | All Packages

Fields
Name | Description
TEXT_FIRST | Marks the first integer id for the range of adjustment event ids.
TEXT_LAST | Marks the last integer id for the range of adjustment event ids.
TEXT_VALUE_CHANGED | The adjustment value changed event.

Constructors
Name | Description
TextEvent(Object, int) | Constructs a TextEvent object with the specified TextComponent source, and type.

Methods
Name | Description
paramString() |


 TextEvent.TEXT_FIRST

TextEvent.TEXT_FIRST

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int TEXT_FIRST
Description
Marks the first integer id for the range of adjustment event ids.


 TextEvent.TEXT_LAST

TextEvent.TEXT_LAST

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int TEXT_LAST
Description
Marks the last integer id for the range of adjustment event ids.


 TextEvent.TEXT_VALUE_CHANGED

TextEvent.TEXT_VALUE_CHANGED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int TEXT_VALUE_CHANGED
Description
The adjustment value changed event.


 TextEvent.TextEvent

TextEvent.TextEvent

Class Overview | Class Members | This Package | All Packages

Syntax
public TextEvent( Object source, int id )
Parameters
source
the TextComponent where the event originated
Description
Constructs a TextEvent object with the specified TextComponent source, and type.


 TextEvent.paramString

TextEvent.paramString

Class Overview | Class Members | This Package | All Packages

Syntax
public String paramString()
Overrides
paramString in class AWTEvent


 Interface TextListener

Interface java.awt.event.TextListener

Interface Members | This Package | All Packages

public interface TextListener
extends EventListener

The listener interface for receiving adjustment events.


 TextListener Members

TextListener Members

Interface Overview | This Package | All Packages

Methods
Name | Description
textValueChanged(TextEvent) | Invoked when the value of the text has changed.


 TextListener.textValueChanged

TextListener.textValueChanged

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void textValueChanged( TextEvent e )
Description
Invoked when the value of the text has changed.


 Class WindowAdapter

Class java.awt.event.WindowAdapter

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.event.WindowAdapter

public abstract class WindowAdapter
extends Object
implements WindowListener

The adapter which receives window events. The methods in this class are empty; this class is provided as a convenience for easily creating listeners by extending this class and overriding only the methods of interest.


 WindowAdapter Members

WindowAdapter Members

Class Overview | This Package | All Packages

Constructors
Name | Description
WindowAdapter() |

Methods
Name | Description
windowActivated(WindowEvent) |
windowClosed(WindowEvent) |
windowClosing(WindowEvent) |
windowDeactivated(WindowEvent) |
windowDeiconified(WindowEvent) |
windowIconified(WindowEvent) |
windowOpened(WindowEvent) |


 WindowAdapter.WindowAdapter

WindowAdapter.WindowAdapter

Class Overview | Class Members | This Package | All Packages

Syntax
public WindowAdapter()


 WindowAdapter.windowActivated

WindowAdapter.windowActivated

Class Overview | Class Members | This Package | All Packages

Syntax
public void windowActivated( WindowEvent e )


 WindowAdapter.windowClosed

WindowAdapter.windowClosed

Class Overview | Class Members | This Package | All Packages

Syntax
public void windowClosed( WindowEvent e )


 WindowAdapter.windowClosing

WindowAdapter.windowClosing

Class Overview | Class Members | This Package | All Packages

Syntax
public void windowClosing( WindowEvent e )


 WindowAdapter.windowDeactivated

WindowAdapter.windowDeactivated

Class Overview | Class Members | This Package | All Packages

Syntax
public void windowDeactivated( WindowEvent e )


 WindowAdapter.windowDeiconified

WindowAdapter.windowDeiconified

Class Overview | Class Members | This Package | All Packages

Syntax
public void windowDeiconified( WindowEvent e )


 WindowAdapter.windowIconified

WindowAdapter.windowIconified

Class Overview | Class Members | This Package | All Packages

Syntax
public void windowIconified( WindowEvent e )


 WindowAdapter.windowOpened

WindowAdapter.windowOpened

Class Overview | Class Members | This Package | All Packages

Syntax
public void windowOpened( WindowEvent e )


 Class WindowEvent

Class java.awt.event.WindowEvent

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.EventObject
           |
           +----java.awt.AWTEvent
                   |
                   +----java.awt.event.ComponentEvent
                           |
                           +----java.awt.event.WindowEvent

public class WindowEvent
extends ComponentEvent

The window-level event.


 WindowEvent Members

WindowEvent Members

Class Overview | This Package | All Packages

Fields
Name | Description
WINDOW_ACTIVATED | The window activated event type.
WINDOW_CLOSED | The window closed event type.
WINDOW_CLOSING | The window closing event type.
WINDOW_DEACTIVATED | The window deactivated event type.
WINDOW_DEICONIFIED | The window deiconified event type.
WINDOW_FIRST | Marks the first integer id for the range of window event ids.
WINDOW_ICONIFIED | The window iconified event type.
WINDOW_LAST | Marks the last integer id for the range of window event ids.
WINDOW_OPENED | The window opened event type.

Constructors
Name | Description
WindowEvent(Window, int) | Constructs a WindowEvent object with the specified source window and type.

Methods
Name | Description
getWindow() | Returns the window where this event originated.
paramString() |


 WindowEvent.WINDOW_ACTIVATED

WindowEvent.WINDOW_ACTIVATED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int WINDOW_ACTIVATED
Description
The window activated event type.


 WindowEvent.WINDOW_CLOSED

WindowEvent.WINDOW_CLOSED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int WINDOW_CLOSED
Description
The window closed event type. This event is delivered after the window has been closed as the result of a call to hide or destroy.


 WindowEvent.WINDOW_CLOSING

WindowEvent.WINDOW_CLOSING

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int WINDOW_CLOSING
Description
The window closing event type. This event is delivered when the user selects "Quit" from the window's system menu. If the program does not explicitly hide or destroy the window as a result of this event, the window close operation will be cancelled.


 WindowEvent.WINDOW_DEACTIVATED

WindowEvent.WINDOW_DEACTIVATED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int WINDOW_DEACTIVATED
Description
The window deactivated event type.


 WindowEvent.WINDOW_DEICONIFIED

WindowEvent.WINDOW_DEICONIFIED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int WINDOW_DEICONIFIED
Description
The window deiconified event type.


 WindowEvent.WINDOW_FIRST

WindowEvent.WINDOW_FIRST

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int WINDOW_FIRST
Description
Marks the first integer id for the range of window event ids.


 WindowEvent.WINDOW_ICONIFIED

WindowEvent.WINDOW_ICONIFIED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int WINDOW_ICONIFIED
Description
The window iconified event type.


 WindowEvent.WINDOW_LAST

WindowEvent.WINDOW_LAST

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int WINDOW_LAST
Description
Marks the last integer id for the range of window event ids.


 WindowEvent.WINDOW_OPENED

WindowEvent.WINDOW_OPENED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int WINDOW_OPENED
Description
The window opened event type. This event is delivered only the first time a window is made visible.


 WindowEvent.WindowEvent

WindowEvent.WindowEvent

Class Overview | Class Members | This Package | All Packages

Syntax
public WindowEvent( Window source, int id )
Parameters
source
the component where the event originated
Description
Constructs a WindowEvent object with the specified source window and type.


 WindowEvent.getWindow

WindowEvent.getWindow

Class Overview | Class Members | This Package | All Packages

Syntax
public Window getWindow()
Description
Returns the window where this event originated.


 WindowEvent.paramString

WindowEvent.paramString

Class Overview | Class Members | This Package | All Packages

Syntax
public String paramString()
Overrides
paramString in class ComponentEvent


 Interface WindowListener

Interface java.awt.event.WindowListener

Interface Members | This Package | All Packages

public interface WindowListener
extends EventListener

The listener interface for receiving window events.


 WindowListener Members

WindowListener Members

Interface Overview | This Package | All Packages

Methods
Name | Description
windowActivated(WindowEvent) | Invoked when a window is activated.
windowClosed(WindowEvent) | Invoked when a window has been closed.
windowClosing(WindowEvent) | Invoked when a window is in the process of being closed.
windowDeactivated(WindowEvent) | Invoked when a window is de-activated.
windowDeiconified(WindowEvent) | Invoked when a window is de-iconified.
windowIconified(WindowEvent) | Invoked when a window is iconified.
windowOpened(WindowEvent) | Invoked when a window has been opened.


 WindowListener.windowActivated

WindowListener.windowActivated

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void windowActivated( WindowEvent e )
Description
Invoked when a window is activated.


 WindowListener.windowClosed

WindowListener.windowClosed

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void windowClosed( WindowEvent e )
Description
Invoked when a window has been closed.


 WindowListener.windowClosing

WindowListener.windowClosing

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void windowClosing( WindowEvent e )
Description
Invoked when a window is in the process of being closed. The close operation can be overridden at this point.


 WindowListener.windowDeactivated

WindowListener.windowDeactivated

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void windowDeactivated( WindowEvent e )
Description
Invoked when a window is de-activated.


 WindowListener.windowDeiconified

WindowListener.windowDeiconified

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void windowDeiconified( WindowEvent e )
Description
Invoked when a window is de-iconified.


 WindowListener.windowIconified

WindowListener.windowIconified

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void windowIconified( WindowEvent e )
Description
Invoked when a window is iconified.


 WindowListener.windowOpened

WindowListener.windowOpened

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void windowOpened( WindowEvent e )
Description
Invoked when a window has been opened.


 Package java.awt.image

Package java.awt.image

All Packages

Interfaces

  • ImageConsumer
  • ImageObserver
  • ImageProducer

    • Classes

  • AreaAveragingScaleFilter
  • ColorModel
  • CropImageFilter
  • DirectColorModel
  • FilteredImageSource
  • ImageFilter
  • IndexColorModel
  • MemoryImageSource
  • PixelGrabber
  • RGBImageFilter
  • ReplicateScaleFilter


 Class AreaAveragingScaleFilter

Class java.awt.image.AreaAveragingScaleFilter

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.image.ImageFilter
           |
           +----java.awt.image.ReplicateScaleFilter
                   |
                   +----java.awt.image.AreaAveragingScaleFilter

public class AreaAveragingScaleFilter
extends ReplicateScaleFilter

An ImageFilter class for scaling images using a simple area averaging algorithm that produces smoother results than the nearest neighbor algorithm. This class extends the basic ImageFilter Class to scale an existing image and provide a source for a new image containing the resampled image. The pixels in the source image are blended to produce pixels for an image of the specified size. The blending process is analogous to scaling up the source image to a multiple of the destination size using pixel replication and then scaling it back down to the destination size by simply averaging all the pixels in the supersized image that fall within a given pixel of the destination image. If the data from the source is not delivered in TopDownLeftRight order then the filter will back off to a simple pixel replication behavior and utilize the requestTopDownLeftRightResend() method to refilter the pixels in a better way at the end. It is meant to be used in conjunction with a FilteredImageSource object to produce scaled versions of existing images.

See Also:
FilteredImageSource, ReplicateImageFilter, ImageFilter


 AreaAveragingScaleFilter Members

AreaAveragingScaleFilter Members

Class Overview | This Package | All Packages

Constructors
Name | Description
AreaAveragingScaleFilter(int, int) | Constructs an AreaAveragingScaleFilter that scales the pixels from its source Image as specified by the width and height parameters.

Methods
Name | Description
setHints(int) | Detect if the data is being delivered with the necessary hints to allow the averaging algorithm to do its work.
setPixels(int, int, int, int, ColorModel, byte[], int, int) | Combine the components for the delivered byte pixels into the accumulation arrays and send on any averaged data for rows of pixels that are complete.
setPixels(int, int, int, int, ColorModel, int[], int, int) | Combine the components for the delivered int pixels into the accumulation arrays and send on any averaged data for rows of pixels that are complete.


 AreaAveragingScaleFilter.AreaAveragingScaleFilter

AreaAveragingScaleFilter.AreaAveragingScaleFilter

Class Overview | Class Members | This Package | All Packages

Syntax
public AreaAveragingScaleFilter( int width, int height )
Parameters
width
the target width to scale the image
height
the target height to scale the image
Description
Constructs an AreaAveragingScaleFilter that scales the pixels from its source Image as specified by the width and height parameters.


 AreaAveragingScaleFilter.setHints

AreaAveragingScaleFilter.setHints

Class Overview | Class Members | This Package | All Packages

Syntax
public void setHints( int hints )
Description
Detect if the data is being delivered with the necessary hints to allow the averaging algorithm to do its work.

Overrides
setHints in class ImageFilter
See Also
setHints


 AreaAveragingScaleFilter.setPixels

AreaAveragingScaleFilter.setPixels

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void setPixels( int x, int y, int w, int h, ColorModel model, byte pixels[], int off, int scansize )
Description
Combine the components for the delivered byte pixels into the accumulation arrays and send on any averaged data for rows of pixels that are complete. If the correct hints were not specified in the setHints call then relay the work to our superclass which is capable of scaling pixels regardless of the delivery hints.

Overrides
setPixels in class ReplicateScaleFilter
See Also
ReplicateScaleFilter

Syntax 2
public void setPixels( int x, int y, int w, int h, ColorModel model, int pixels[], int off, int scansize )
Description
Combine the components for the delivered int pixels into the accumulation arrays and send on any averaged data for rows of pixels that are complete. If the correct hints were not specified in the setHints call then relay the work to our superclass which is capable of scaling pixels regardless of the delivery hints.

Overrides
setPixels in class ReplicateScaleFilter
See Also
ReplicateScaleFilter


 Class ColorModel

Class java.awt.image.ColorModel

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.image.ColorModel

public abstract class ColorModel
extends Object

A class that encapsulates the methods for translating from pixel values to alpha, red, green, and blue color components for an image. This class is abstract.

See Also:
IndexColorModel, DirectColorModel


 ColorModel Members

ColorModel Members

Class Overview | This Package | All Packages

Fields
Name | Description
pixel_bits |

Constructors
Name | Description
ColorModel(int) | Constructs a ColorModel which describes a pixel of the specified number of bits.

Methods
Name | Description
finalize() | Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
getAlpha(int) | The subclass must provide a function which provides the alpha color compoment for the specified pixel.
getBlue(int) | The subclass must provide a function which provides the blue color compoment for the specified pixel.
getGreen(int) | The subclass must provide a function which provides the green color compoment for the specified pixel.
getPixelSize() | Returns the number of bits per pixel described by this ColorModel.
getRed(int) | The subclass must provide a function which provides the red color compoment for the specified pixel.
getRGB(int) | Returns the color of the pixel in the default RGB color model.
getRGBdefault() | Return a ColorModel which describes the default format for integer RGB values used throughout the AWT image interfaces.


 ColorModel.pixel_bits

ColorModel.pixel_bits

Class Overview | Class Members | This Package | All Packages

Syntax
protected int pixel_bits


 ColorModel.ColorModel

ColorModel.ColorModel

Class Overview | Class Members | This Package | All Packages

Syntax
public ColorModel( int bits )
Description
Constructs a ColorModel which describes a pixel of the specified number of bits.


 ColorModel.finalize

ColorModel.finalize

Class Overview | Class Members | This Package | All Packages

Syntax
public void finalize()
Description
Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.

Overrides
finalize in class Object


 ColorModel.getAlpha

ColorModel.getAlpha

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract int getAlpha( int pixel )
Returns
The alpha transparency value ranging from 0 to 255
Description
The subclass must provide a function which provides the alpha color compoment for the specified pixel.


 ColorModel.getBlue

ColorModel.getBlue

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract int getBlue( int pixel )
Returns
The blue color component ranging from 0 to 255
Description
The subclass must provide a function which provides the blue color compoment for the specified pixel.


 ColorModel.getGreen

ColorModel.getGreen

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract int getGreen( int pixel )
Returns
The green color component ranging from 0 to 255
Description
The subclass must provide a function which provides the green color compoment for the specified pixel.


 ColorModel.getPixelSize

ColorModel.getPixelSize

Class Overview | Class Members | This Package | All Packages

Syntax
public int getPixelSize()
Description
Returns the number of bits per pixel described by this ColorModel.


 ColorModel.getRed

ColorModel.getRed

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract int getRed( int pixel )
Returns
The red color component ranging from 0 to 255
Description
The subclass must provide a function which provides the red color compoment for the specified pixel.


 ColorModel.getRGB

ColorModel.getRGB

Class Overview | Class Members | This Package | All Packages

Syntax
public int getRGB( int pixel )
Description
Returns the color of the pixel in the default RGB color model.

See Also
getRGBdefault


 ColorModel.getRGBdefault

ColorModel.getRGBdefault

Class Overview | Class Members | This Package | All Packages

Syntax
public static ColorModel getRGBdefault()
Description
Return a ColorModel which describes the default format for integer RGB values used throughout the AWT image interfaces. The format for the RGB values is an integer with 8 bits each of alpha, red, green, and blue color components ordered correspondingly from the most significant byte to the least significant byte, as in: 0xAARRGGBB


 Class CropImageFilter

Class java.awt.image.CropImageFilter

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.image.ImageFilter
           |
           +----java.awt.image.CropImageFilter

public class CropImageFilter
extends ImageFilter

An ImageFilter class for cropping images. This class extends the basic ImageFilter Class to extract a given rectangular region of an existing Image and provide a source for a new image containing just the extracted region. It is meant to be used in conjunction with a FilteredImageSource object to produce cropped versions of existing images.

See Also:
FilteredImageSource, ImageFilter


 CropImageFilter Members

CropImageFilter Members

Class Overview | This Package | All Packages

Constructors
Name | Description
CropImageFilter(int, int, int, int) | Constructs a CropImageFilter that extracts the absolute rectangular region of pixels from its source Image as specified by the x, y, w, and h parameters.

Methods
Name | Description
setDimensions(int, int) | Override the source image's dimensions and pass the dimensions of the rectangular cropped region to the ImageConsumer.
setPixels(int, int, int, int, ColorModel, byte[], int, int) | Determine whether the delivered byte pixels intersect the region to be extracted and passes through only that subset of pixels that appear in the output region.
setPixels(int, int, int, int, ColorModel, int[], int, int) | Determine if the delivered int pixels intersect the region to be extracted and pass through only that subset of pixels that appear in the output region.
setProperties(Hashtable) | Passes along the properties from the source object after adding a property indicating the cropped region.


 CropImageFilter.CropImageFilter

CropImageFilter.CropImageFilter

Class Overview | Class Members | This Package | All Packages

Syntax
public CropImageFilter( int x, int y, int w, int h )
Parameters
x
the x location of the top of the rectangle to be extracted
y
the y location of the top of the rectangle to be extracted
w
the width of the rectangle to be extracted
h
the height of the rectangle to be extracted
Description
Constructs a CropImageFilter that extracts the absolute rectangular region of pixels from its source Image as specified by the x, y, w, and h parameters.


 CropImageFilter.setDimensions

CropImageFilter.setDimensions

Class Overview | Class Members | This Package | All Packages

Syntax
public void setDimensions( int w, int h )
Description
Override the source image's dimensions and pass the dimensions of the rectangular cropped region to the ImageConsumer.

Overrides
setDimensions in class ImageFilter
See Also
ImageConsumer


 CropImageFilter.setPixels

CropImageFilter.setPixels

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void setPixels( int x, int y, int w, int h, ColorModel model, byte pixels[], int off, int scansize )
Description
Determine whether the delivered byte pixels intersect the region to be extracted and passes through only that subset of pixels that appear in the output region.

Overrides
setPixels in class ImageFilter

Syntax 2
public void setPixels( int x, int y, int w, int h, ColorModel model, int pixels[], int off, int scansize )
Description
Determine if the delivered int pixels intersect the region to be extracted and pass through only that subset of pixels that appear in the output region.

Overrides
setPixels in class ImageFilter


 CropImageFilter.setProperties

CropImageFilter.setProperties

Class Overview | Class Members | This Package | All Packages

Syntax
public void setProperties( Hashtable props )
Description
Passes along the properties from the source object after adding a property indicating the cropped region.

Overrides
setProperties in class ImageFilter


 Class DirectColorModel

Class java.awt.image.DirectColorModel

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.image.ColorModel
           |
           +----java.awt.image.DirectColorModel

public class DirectColorModel
extends ColorModel

A ColorModel class that specifies a translation from pixel values to alpha, red, green, and blue color components for pixels which have the color components embedded directly in the bits of the pixel itself. This color model is similar to an X11 TrueColor visual.

Many of the methods in this class are final. This is because the underlying native graphics code makes assumptions about the layout and operation of this class and those assumptions are reflected in the implementations of the methods here that are marked final. You can subclass this class for other reaons, but you cannot override or modify the behaviour of those methods.

See Also:
ColorModel


 DirectColorModel Members

DirectColorModel Members

Class Overview | This Package | All Packages

Constructors
Name | Description
DirectColorModel(int, int, int, int) | Constructs a DirectColorModel from the given masks specifying which bits in the pixel contain the red, green and blue color components.
DirectColorModel(int, int, int, int, int) | Constructs a DirectColorModel from the given masks specifying which bits in the pixel contain the alhpa, red, green and blue color components.

Methods
Name | Description
getAlpha(int) | Return the alpha transparency value for the specified pixel in the range 0-255.
getAlphaMask() | Returns the mask indicating which bits in a pixel contain the alpha transparency component.
getBlue(int) | Returns the blue color compoment for the specified pixel in the range 0-255.
getBlueMask() | Returns the mask indicating which bits in a pixel contain the blue color component.
getGreen(int) | Returns the green color compoment for the specified pixel in the range 0-255.
getGreenMask() | Returns the mask indicating which bits in a pixel contain the green color component.
getRed(int) | Returns the red color compoment for the specified pixel in the range 0-255.
getRedMask() | Returns the mask indicating which bits in a pixel contain the red color component.
getRGB(int) | Returns the color of the pixel in the default RGB color model.


 DirectColorModel.DirectColorModel

DirectColorModel.DirectColorModel

Class Overview | Class Members | This Package | All Packages

Syntax 1
public DirectColorModel( int bits, int rmask, int gmask, int bmask )
Description
Constructs a DirectColorModel from the given masks specifying which bits in the pixel contain the red, green and blue color components. Pixels described by this color model will all have alpha components of 255 (fully opaque). All of the bits in each mask must be contiguous and fit in the specified number of least significant bits of the integer.

Syntax 2
public DirectColorModel( int bits, int rmask, int gmask, int bmask, int amask )
Description
Constructs a DirectColorModel from the given masks specifying which bits in the pixel contain the alhpa, red, green and blue color components. All of the bits in each mask must be contiguous and fit in the specified number of least significant bits of the integer.


 DirectColorModel.getAlpha

DirectColorModel.getAlpha

Class Overview | Class Members | This Package | All Packages

Syntax
public final int getAlpha( int pixel )
Description
Return the alpha transparency value for the specified pixel in the range 0-255.

Overrides
getAlpha in class ColorModel


 DirectColorModel.getAlphaMask

DirectColorModel.getAlphaMask

Class Overview | Class Members | This Package | All Packages

Syntax
public final int getAlphaMask()
Description
Returns the mask indicating which bits in a pixel contain the alpha transparency component.


 DirectColorModel.getBlue

DirectColorModel.getBlue

Class Overview | Class Members | This Package | All Packages

Syntax
public final int getBlue( int pixel )
Description
Returns the blue color compoment for the specified pixel in the range 0-255.

Overrides
getBlue in class ColorModel


 DirectColorModel.getBlueMask

DirectColorModel.getBlueMask

Class Overview | Class Members | This Package | All Packages

Syntax
public final int getBlueMask()
Description
Returns the mask indicating which bits in a pixel contain the blue color component.


 DirectColorModel.getGreen

DirectColorModel.getGreen

Class Overview | Class Members | This Package | All Packages

Syntax
public final int getGreen( int pixel )
Description
Returns the green color compoment for the specified pixel in the range 0-255.

Overrides
getGreen in class ColorModel


 DirectColorModel.getGreenMask

DirectColorModel.getGreenMask

Class Overview | Class Members | This Package | All Packages

Syntax
public final int getGreenMask()
Description
Returns the mask indicating which bits in a pixel contain the green color component.


 DirectColorModel.getRed

DirectColorModel.getRed

Class Overview | Class Members | This Package | All Packages

Syntax
public final int getRed( int pixel )
Description
Returns the red color compoment for the specified pixel in the range 0-255.

Overrides
getRed in class ColorModel


 DirectColorModel.getRedMask

DirectColorModel.getRedMask

Class Overview | Class Members | This Package | All Packages

Syntax
public final int getRedMask()
Description
Returns the mask indicating which bits in a pixel contain the red color component.


 DirectColorModel.getRGB

DirectColorModel.getRGB

Class Overview | Class Members | This Package | All Packages

Syntax
public final int getRGB( int pixel )
Description
Returns the color of the pixel in the default RGB color model.

Overrides
getRGB in class ColorModel
See Also
getRGBdefault


 Class FilteredImageSource

Class java.awt.image.FilteredImageSource

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.image.FilteredImageSource

public class FilteredImageSource
extends Object
implements ImageProducer

This class is an implementation of the ImageProducer interface which takes an existing image and a filter object and uses them to produce image data for a new filtered version of the original image. Here is an example which filters an image by swapping the red and blue compents:

    Image src = getImage("doc:///demo/images/duke/T1.gif");
    ImageFilter colorfilter = new RedBlueSwapFilter();
    Image img = createImage(new FilteredImageSource(src.getSource(),
                            colorfilter));

See Also:
ImageProducer


 FilteredImageSource Members

FilteredImageSource Members

Class Overview | This Package | All Packages

Constructors
Name | Description
FilteredImageSource(ImageProducer, ImageFilter) | Constructs an ImageProducer object from an existing ImageProducer and a filter object.

Methods
Name | Description
addConsumer(ImageConsumer) | Adds an ImageConsumer to the list of consumers interested in data for this image.
isConsumer(ImageConsumer) | Determines whether an ImageConsumer is on the list of consumers currently interested in data for this image.
removeConsumer(ImageConsumer) | Removes an ImageConsumer from the list of consumers interested in data for this image.
requestTopDownLeftRightResend(ImageConsumer) | Requests that a given ImageConsumer have the image data delivered one more time in top-down, left-right order.
startProduction(ImageConsumer) | Adds an ImageConsumer to the list of consumers interested in data for this image, and immediately starts delivery of the image data through the ImageConsumer interface.


 FilteredImageSource.FilteredImageSource

FilteredImageSource.FilteredImageSource

Class Overview | Class Members | This Package | All Packages

Syntax
public FilteredImageSource( ImageProducer orig, ImageFilter imgf )
Description
Constructs an ImageProducer object from an existing ImageProducer and a filter object.

See Also
ImageFilter, createImage


 FilteredImageSource.addConsumer

FilteredImageSource.addConsumer

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void addConsumer( ImageConsumer ic )
Description
Adds an ImageConsumer to the list of consumers interested in data for this image.

See Also
ImageConsumer


 FilteredImageSource.isConsumer

FilteredImageSource.isConsumer

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized boolean isConsumer( ImageConsumer ic )
Returns
true if the ImageConsumer is on the list; false otherwise
Description
Determines whether an ImageConsumer is on the list of consumers currently interested in data for this image.

See Also
ImageConsumer


 FilteredImageSource.removeConsumer

FilteredImageSource.removeConsumer

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void removeConsumer( ImageConsumer ic )
Description
Removes an ImageConsumer from the list of consumers interested in data for this image.

See Also
ImageConsumer


 FilteredImageSource.requestTopDownLeftRightResend

FilteredImageSource.requestTopDownLeftRightResend

Class Overview | Class Members | This Package | All Packages

Syntax
public void requestTopDownLeftRightResend( ImageConsumer ic )
Description
Requests that a given ImageConsumer have the image data delivered one more time in top-down, left-right order. The request is handed to the ImageFilter for further processing, since the ability to preserve the pixel ordering depends on the filter.

See Also
ImageConsumer


 FilteredImageSource.startProduction

FilteredImageSource.startProduction

Class Overview | Class Members | This Package | All Packages

Syntax
public void startProduction( ImageConsumer ic )
Description
Adds an ImageConsumer to the list of consumers interested in data for this image, and immediately starts delivery of the image data through the ImageConsumer interface.

See Also
ImageConsumer


 Interface ImageConsumer

Interface java.awt.image.ImageConsumer

Interface Members | This Package | All Packages

public interface ImageConsumer

The interface for objects expressing interest in image data through the ImageProducer interfaces. When a consumer is added to an image producer, the producer delivers all of the data about the image using the method calls defined in this interface.

See Also:
ImageProducer


 ImageConsumer Members

ImageConsumer Members

Interface Overview | This Package | All Packages

Fields
Name | Description
COMPLETESCANLINES | The pixels will be delivered in (multiples of) complete scanlines at a time.
IMAGEABORTED | The image creation process was deliberately aborted.
IMAGEERROR | An error was encountered while producing the image.
RANDOMPIXELORDER | The pixels will be delivered in a random order.
SINGLEFRAME | The image contain a single static image.
SINGLEFRAMEDONE | One frame of the image is complete but there are more frames to be delivered.
SINGLEPASS | The pixels will be delivered in a single pass.
STATICIMAGEDONE | The image is complete and there are no more pixels or frames to be delivered.
TOPDOWNLEFTRIGHT | The pixels will be delivered in top-down, left-to-right order.

Methods
Name | Description
imageComplete(int) | The imageComplete method is called when the ImageProducer is finished delivering all of the pixels that the source image contains, or when a single frame of a multi-frame animation has been completed, or when an error in loading or producing the image has occured.
setColorModel(ColorModel) | The ColorModel object used for the majority of the pixels reported using the setPixels method calls.
setDimensions(int, int) | The dimensions of the source image are reported using the setDimensions method call.
setHints(int) | The ImageProducer can deliver the pixels in any order, but the ImageConsumer may be able to scale or convert the pixels to the destination ColorModel more efficiently or with higher quality if it knows some information about how the pixels will be delivered up front.
setPixels(int, int, int, int, ColorModel, byte[], int, int) | The pixels of the image are delivered using one or more calls to the setPixels method.
setPixels(int, int, int, int, ColorModel, int[], int, int) | The pixels of the image are delivered using one or more calls to the setPixels method.
setProperties(Hashtable) | Sets the extensible list of properties associated with this image.


 ImageConsumer.COMPLETESCANLINES

ImageConsumer.COMPLETESCANLINES

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int COMPLETESCANLINES
Description
The pixels will be delivered in (multiples of) complete scanlines at a time.

See Also
setHints


 ImageConsumer.IMAGEABORTED

ImageConsumer.IMAGEABORTED

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int IMAGEABORTED
Description
The image creation process was deliberately aborted.

See Also
imageComplete


 ImageConsumer.IMAGEERROR

ImageConsumer.IMAGEERROR

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int IMAGEERROR
Description
An error was encountered while producing the image.

See Also
imageComplete


 ImageConsumer.RANDOMPIXELORDER

ImageConsumer.RANDOMPIXELORDER

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int RANDOMPIXELORDER
Description
The pixels will be delivered in a random order. This tells the ImageConsumer not to use any optimizations that depend on the order of pixel delivery, which should be the default assumption in the absence of any call to the setHints method.

See Also
setHints


 ImageConsumer.SINGLEFRAME

ImageConsumer.SINGLEFRAME

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int SINGLEFRAME
Description
The image contain a single static image. The pixels will be defined in calls to the setPixels methods and then the imageComplete method will be called with the STATICIMAGEDONE flag after which no more image data will be delivered. An example of an image type which would not meet these criteria would be the output of a video feed, or the representation of a 3D rendering being manipulated by the user. The end of each frame in those types of images will be indicated by calling imageComplete with the SINGLEFRAMEDONE flag.

See Also
setHints, imageComplete


 ImageConsumer.SINGLEFRAMEDONE

ImageConsumer.SINGLEFRAMEDONE

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int SINGLEFRAMEDONE
Description
One frame of the image is complete but there are more frames to be delivered.

See Also
imageComplete


 ImageConsumer.SINGLEPASS

ImageConsumer.SINGLEPASS

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int SINGLEPASS
Description
The pixels will be delivered in a single pass. Each pixel will appear in only one call to any of the setPixels methods. An example of an image format which does not meet this criterion is a progressive JPEG image which defines pixels in multiple passes, each more refined than the previous.

See Also
setHints


 ImageConsumer.STATICIMAGEDONE

ImageConsumer.STATICIMAGEDONE

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int STATICIMAGEDONE
Description
The image is complete and there are no more pixels or frames to be delivered.

See Also
imageComplete


 ImageConsumer.TOPDOWNLEFTRIGHT

ImageConsumer.TOPDOWNLEFTRIGHT

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int TOPDOWNLEFTRIGHT
Description
The pixels will be delivered in top-down, left-to-right order.

See Also
setHints


 ImageConsumer.imageComplete

ImageConsumer.imageComplete

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void imageComplete( int status )
Description
The imageComplete method is called when the ImageProducer is finished delivering all of the pixels that the source image contains, or when a single frame of a multi-frame animation has been completed, or when an error in loading or producing the image has occured. The ImageConsumer should remove itself from the list of consumers registered with the ImageProducer at this time, unless it is interested in successive frames.

See Also
removeConsumer


 ImageConsumer.setColorModel

ImageConsumer.setColorModel

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setColorModel( ColorModel model )
Description
The ColorModel object used for the majority of the pixels reported using the setPixels method calls. Note that each set of pixels delivered using setPixels contains its own ColorModel object, so no assumption should be made that this model will be the only one used in delivering pixel values. A notable case where multiple ColorModel objects may be seen is a filtered image when for each set of pixels that it filters, the filter determines whether the pixels can be sent on untouched, using the original ColorModel, or whether the pixels should be modified (filtered) and passed on using a ColorModel more convenient for the filtering process.

See Also
ColorModel


 ImageConsumer.setDimensions

ImageConsumer.setDimensions

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setDimensions( int width, int height )
Description
The dimensions of the source image are reported using the setDimensions method call.


 ImageConsumer.setHints

ImageConsumer.setHints

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setHints( int hintflags )
Description
The ImageProducer can deliver the pixels in any order, but the ImageConsumer may be able to scale or convert the pixels to the destination ColorModel more efficiently or with higher quality if it knows some information about how the pixels will be delivered up front. The setHints method should be called before any calls to any of the setPixels methods with a bit mask of hints about the manner in which the pixels will be delivered. If the ImageProducer does not follow the guidelines for the indicated hint, the results are undefined.


 ImageConsumer.setPixels

ImageConsumer.setPixels

Interface Overview | Interface Members | This Package | All Packages

Syntax 1
public abstract void setPixels( int x, int y, int w, int h, ColorModel model, byte pixels[], int off, int scansize )
Description
The pixels of the image are delivered using one or more calls to the setPixels method. Each call specifies the location and size of the rectangle of source pixels that are contained in the array of pixels. The specified ColorModel object should be used to convert the pixels into their corresponding color and alpha components. Pixel (m,n) is stored in the pixels array at index (n * scansize + m + off). The pixels delivered using this method are all stored as bytes.

See Also
ColorModel

Syntax 2
public abstract void setPixels( int x, int y, int w, int h, ColorModel model, int pixels[], int off, int scansize )
Description
The pixels of the image are delivered using one or more calls to the setPixels method. Each call specifies the location and size of the rectangle of source pixels that are contained in the array of pixels. The specified ColorModel object should be used to convert the pixels into their corresponding color and alpha components. Pixel (m,n) is stored in the pixels array at index (n * scansize + m + off). The pixels delivered using this method are all stored as ints.

See Also
ColorModel


 ImageConsumer.setProperties

ImageConsumer.setProperties

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setProperties( Hashtable props )
Description
Sets the extensible list of properties associated with this image.


 Class ImageFilter

Class java.awt.image.ImageFilter

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.image.ImageFilter

public class ImageFilter
extends Object
implements ImageConsumer, Cloneable

This class implements a filter for the set of interface methods that are used to deliver data from an ImageProducer to an ImageConsumer. It is meant to be used in conjunction with a FilteredImageSource object to produce filtered versions of existing images. It is a base class that provides the calls needed to implement a "Null filter" which has no effect on the data being passed through. Filters should subclass this class and override the methods which deal with the data that needs to be filtered and modify it as necessary.

See Also:
FilteredImageSource, ImageConsumer


 ImageFilter Members

ImageFilter Members

Class Overview | This Package | All Packages

Fields
Name | Description
consumer | The consumer of the particular image data stream for which this instance of the ImageFilter is filtering data.

Constructors
Name | Description
ImageFilter() |

Methods
Name | Description
clone() | Clones this object.
getFilterInstance(ImageConsumer) | Returns a unique instance of an ImageFilter object which will actually perform the filtering for the specified ImageConsumer.
imageComplete(int) | Filters the information provided in the imageComplete method of the ImageConsumer interface.
resendTopDownLeftRight(ImageProducer) | Responds to a request for a TopDownLeftRight (TDLR) ordered resend of the pixel data from an ImageConsumer.
setColorModel(ColorModel) | Filter the information provided in the setColorModel method of the ImageConsumer interface.
setDimensions(int, int) | Filters the information provided in the setDimensions method of the ImageConsumer interface.
setHints(int) | Filters the information provided in the setHints method of the ImageConsumer interface.
setPixels(int, int, int, int, ColorModel, byte[], int, int) | Filters the information provided in the setPixels method of the ImageConsumer interface which takes an array of bytes.
setPixels(int, int, int, int, ColorModel, int[], int, int) | Filters the information provided in the setPixels method of the ImageConsumer interface which takes an array of integers.
setProperties(Hashtable) | Passes the properties from the source object along after adding a property indicating the stream of filters it has been run through.


 ImageFilter.consumer

ImageFilter.consumer

Class Overview | Class Members | This Package | All Packages

Syntax
protected ImageConsumer consumer
Description
The consumer of the particular image data stream for which this instance of the ImageFilter is filtering data. It is not initialized during the constructor, but rather during the getFilterInstance() method call when the FilteredImageSource is creating a unique instance of this object for a particular image data stream.

See Also
getFilterInstance, ImageConsumer


 ImageFilter.ImageFilter

ImageFilter.ImageFilter

Class Overview | Class Members | This Package | All Packages

Syntax
public ImageFilter()


 ImageFilter.clone

ImageFilter.clone

Class Overview | Class Members | This Package | All Packages

Syntax
public Object clone()
Description
Clones this object.

Overrides
clone in class Object


 ImageFilter.getFilterInstance

ImageFilter.getFilterInstance

Class Overview | Class Members | This Package | All Packages

Syntax
public ImageFilter getFilterInstance( ImageConsumer ic )
Description
Returns a unique instance of an ImageFilter object which will actually perform the filtering for the specified ImageConsumer. The default implementation just clones this object.


 ImageFilter.imageComplete

ImageFilter.imageComplete

Class Overview | Class Members | This Package | All Packages

Syntax
public void imageComplete( int status )
Description
Filters the information provided in the imageComplete method of the ImageConsumer interface.

See Also
imageComplete


 ImageFilter.resendTopDownLeftRight

ImageFilter.resendTopDownLeftRight

Class Overview | Class Members | This Package | All Packages

Syntax
public void resendTopDownLeftRight( ImageProducer ip )
Parameters
ip
The ImageProducer that is feeding this instance of the filter - also the ImageProducer that the request should be forwarded to if necessary.
Description
Responds to a request for a TopDownLeftRight (TDLR) ordered resend of the pixel data from an ImageConsumer. The ImageFilter can respond to this request in one of three ways.
  1. If the filter can determine that it will forward the pixels in TDLR order if its upstream producer object sends them in TDLR order, then the request is automatically forwarded by default to the indicated ImageProducer using this filter as the requesting ImageConsumer, so no override is necessary.
  2. If the filter can resend the pixels in the right order on its own (presumably because the generated pixels have been saved in some sort of buffer), then it can override this method and simply resend the pixels in TDLR order as specified in the ImageProducer API.
  3. If the filter simply returns from this method then the request will be ignored and no resend will occur.

See Also
requestTopDownLeftRightResend


 ImageFilter.setColorModel

ImageFilter.setColorModel

Class Overview | Class Members | This Package | All Packages

Syntax
public void setColorModel( ColorModel model )
Description
Filter the information provided in the setColorModel method of the ImageConsumer interface.

See Also
setColorModel


 ImageFilter.setDimensions

ImageFilter.setDimensions

Class Overview | Class Members | This Package | All Packages

Syntax
public void setDimensions( int width, int height )
Description
Filters the information provided in the setDimensions method of the ImageConsumer interface.

See Also
setDimensions


 ImageFilter.setHints

ImageFilter.setHints

Class Overview | Class Members | This Package | All Packages

Syntax
public void setHints( int hints )
Description
Filters the information provided in the setHints method of the ImageConsumer interface.

See Also
setHints


 ImageFilter.setPixels

ImageFilter.setPixels

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void setPixels( int x, int y, int w, int h, ColorModel model, byte pixels[], int off, int scansize )
Description
Filters the information provided in the setPixels method of the ImageConsumer interface which takes an array of bytes.

See Also
setPixels

Syntax 2
public void setPixels( int x, int y, int w, int h, ColorModel model, int pixels[], int off, int scansize )
Description
Filters the information provided in the setPixels method of the ImageConsumer interface which takes an array of integers.

See Also
setPixels


 ImageFilter.setProperties

ImageFilter.setProperties

Class Overview | Class Members | This Package | All Packages

Syntax
public void setProperties( Hashtable props )
Description
Passes the properties from the source object along after adding a property indicating the stream of filters it has been run through.


 Interface ImageObserver

Interface java.awt.image.ImageObserver

Interface Members | This Package | All Packages

public interface ImageObserver

An asynchronous update interface for receiving notifications about Image information as the Image is constructed.


 ImageObserver Members

ImageObserver Members

Interface Overview | This Package | All Packages

Fields
Name | Description
ABORT | An image which was being tracked asynchronously was aborted before production was complete.
ALLBITS | A static image which was previously drawn is now complete and can be drawn again in its final form.
ERROR | An image which was being tracked asynchronously has encountered an error.
FRAMEBITS | Another complete frame of a multi-frame image which was previously drawn is now available to be drawn again.
HEIGHT | The height of the base image is now available and can be taken from the height argument to the imageUpdate callback method.
PROPERTIES | The properties of the image are now available.
SOMEBITS | More pixels needed for drawing a scaled variation of the image are available.
WIDTH | The width of the base image is now available and can be taken from the width argument to the imageUpdate callback method.

Methods
Name | Description
imageUpdate(Image, int, int, int, int, int) | This method is called when information about an image which was previously requested using an asynchronous interface becomes available.


 ImageObserver.ABORT

ImageObserver.ABORT

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int ABORT
Description
An image which was being tracked asynchronously was aborted before production was complete. No more information will become available without further action to trigger another image production sequence. If the ERROR flag was not also set in this image update, then accessing any of the data in the image will restart the production again, probably from the beginning.

See Also
imageUpdate


 ImageObserver.ALLBITS

ImageObserver.ALLBITS

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int ALLBITS
Description
A static image which was previously drawn is now complete and can be drawn again in its final form. The x, y, width, and height arguments to the imageUpdate callback method should be ignored.

See Also
drawImage, imageUpdate


 ImageObserver.ERROR

ImageObserver.ERROR

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int ERROR
Description
An image which was being tracked asynchronously has encountered an error. No further information will become available and drawing the image will fail. As a convenience, the ABORT flag will be indicated at the same time to indicate that the image production was aborted.

See Also
imageUpdate


 ImageObserver.FRAMEBITS

ImageObserver.FRAMEBITS

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int FRAMEBITS
Description
Another complete frame of a multi-frame image which was previously drawn is now available to be drawn again. The x, y, width, and height arguments to the imageUpdate callback method should be ignored.

See Also
drawImage, imageUpdate


 ImageObserver.HEIGHT

ImageObserver.HEIGHT

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int HEIGHT
Description
The height of the base image is now available and can be taken from the height argument to the imageUpdate callback method.

See Also
getHeight, imageUpdate


 ImageObserver.PROPERTIES

ImageObserver.PROPERTIES

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int PROPERTIES
Description
The properties of the image are now available.

See Also
getProperty, imageUpdate


 ImageObserver.SOMEBITS

ImageObserver.SOMEBITS

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int SOMEBITS
Description
More pixels needed for drawing a scaled variation of the image are available. The bounding box of the new pixels can be taken from the x, y, width, and height arguments to the imageUpdate callback method.

See Also
drawImage, imageUpdate


 ImageObserver.WIDTH

ImageObserver.WIDTH

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int WIDTH
Description
The width of the base image is now available and can be taken from the width argument to the imageUpdate callback method.

See Also
getWidth, imageUpdate


 ImageObserver.imageUpdate

ImageObserver.imageUpdate

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean imageUpdate( Image img, int infoflags, int x, int y, int width, int height )
Description
This method is called when information about an image which was previously requested using an asynchronous interface becomes available. Asynchronous interfaces are method calls such as getWidth(ImageObserver) and drawImage(img, x, y, ImageObserver) which take an ImageObserver object as an argument. Those methods register the caller as interested either in information about the overall image itself (in the case of getWidth(ImageObserver)) or about an output version of an image (in the case of the drawImage(img, x, y, [w, h,] ImageObserver) call).

This method should return true if further updates are needed or false if the required information has been acquired. The image which was being tracked is passed in using the img argument. Various constants are combined to form the infoflags argument which indicates what information about the image is now available. The interpretation of the x, y, width, and height arguments depends on the contents of the infoflags argument.

See Also
getWidth, getHeight, drawImage


 Interface ImageProducer

Interface java.awt.image.ImageProducer

Interface Members | This Package | All Packages

public interface ImageProducer

The interface for objects which can produce the image data for Images. Each image contains an ImageProducer which is used to reconstruct the image whenever it is needed, for example, when a new size of the Image is scaled, or when the width or height of the Image is being requested.

See Also:
ImageConsumer


 ImageProducer Members

ImageProducer Members

Interface Overview | This Package | All Packages

Methods
Name | Description
addConsumer(ImageConsumer) | This method is used to register an ImageConsumer with the ImageProducer for access to the image data during a later reconstruction of the Image.
isConsumer(ImageConsumer) | This method determines if a given ImageConsumer object is currently registered with this ImageProducer as one of its consumers.
removeConsumer(ImageConsumer) | This method removes the given ImageConsumer object from the list of consumers currently registered to receive image data.
requestTopDownLeftRightResend(ImageConsumer) | This method is used by an ImageConsumer to request that the ImageProducer attempt to resend the image data one more time in TOPDOWNLEFTRIGHT order so that higher quality conversion algorithms which depend on receiving pixels in order can be used to produce a better output version of the image.
startProduction(ImageConsumer) | This method both registers the given ImageConsumer object as a consumer and starts an immediate reconstruction of the image data which will then be delivered to this consumer and any other consumer which may have already been registered with the producer.


 ImageProducer.addConsumer

ImageProducer.addConsumer

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void addConsumer( ImageConsumer ic )
Description
This method is used to register an ImageConsumer with the ImageProducer for access to the image data during a later reconstruction of the Image. The ImageProducer may, at its discretion, start delivering the image data to the consumer using the ImageConsumer interface immediately, or when the next available image reconstruction is triggered by a call to the startProduction method.

See Also
startProduction


 ImageProducer.isConsumer

ImageProducer.isConsumer

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean isConsumer( ImageConsumer ic )
Description
This method determines if a given ImageConsumer object is currently registered with this ImageProducer as one of its consumers.


 ImageProducer.removeConsumer

ImageProducer.removeConsumer

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void removeConsumer( ImageConsumer ic )
Description
This method removes the given ImageConsumer object from the list of consumers currently registered to receive image data. It is not considered an error to remove a consumer that is not currently registered. The ImageProducer should stop sending data to this consumer as soon as is feasible.


 ImageProducer.requestTopDownLeftRightResend

ImageProducer.requestTopDownLeftRightResend

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void requestTopDownLeftRightResend( ImageConsumer ic )
Description
This method is used by an ImageConsumer to request that the ImageProducer attempt to resend the image data one more time in TOPDOWNLEFTRIGHT order so that higher quality conversion algorithms which depend on receiving pixels in order can be used to produce a better output version of the image. The ImageProducer is free to ignore this call if it cannot resend the data in that order. If the data can be resent, then the ImageProducer should respond by executing the following minimum set of ImageConsumer method calls:
    ic.setHints(TOPDOWNLEFTRIGHT | < otherhints >);
    ic.setPixels(...);	// As many times as needed
    ic.imageComplete();

See Also
setHints


 ImageProducer.startProduction

ImageProducer.startProduction

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void startProduction( ImageConsumer ic )
Description
This method both registers the given ImageConsumer object as a consumer and starts an immediate reconstruction of the image data which will then be delivered to this consumer and any other consumer which may have already been registered with the producer. This method differs from the addConsumer method in that a reproduction of the image data should be triggered as soon as possible.

See Also
addConsumer


 Class IndexColorModel

Class java.awt.image.IndexColorModel

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.image.ColorModel
           |
           +----java.awt.image.IndexColorModel

public class IndexColorModel
extends ColorModel

A ColorModel class that specifies a translation from pixel values to alpha, red, green, and blue color components for pixels which represent indices into a fixed colormap. An optional transparent pixel value can be supplied which indicates a completely transparent pixel, regardless of any alpha value recorded for that pixel value. This color model is similar to an X11 PseudoColor visual.

Many of the methods in this class are final. The reason for this is that the underlying native graphics code makes assumptions about the layout and operation of this class and those assumptions are reflected in the implementations of the methods here that are marked final. You can subclass this class for other reaons, but you cannot override or modify the behaviour of those methods.

See Also:
ColorModel


 IndexColorModel Members

IndexColorModel Members

Class Overview | This Package | All Packages

Constructors
Name | Description
IndexColorModel(int, int, byte[], byte[], byte[]) | Constructs an IndexColorModel from the given arrays of red, green, and blue components.
IndexColorModel(int, int, byte[], byte[], byte[], byte[]) | Constructs an IndexColorModel from the given arrays of red, green, blue and alpha components.
IndexColorModel(int, int, byte[], byte[], byte[], int) | Constructs an IndexColorModel from the given arrays of red, green, and blue components.
IndexColorModel(int, int, byte[], int, boolean) | Constructs an IndexColorModel from a single arrays of packed red, green, blue and optional alpha components.
IndexColorModel(int, int, byte[], int, boolean, int) | Constructs an IndexColorModel from a single arrays of packed red, green, blue and optional alpha components.

Methods
Name | Description
getAlpha(int) | Returns the alpha transparency value for the specified pixel in the range 0-255.
getAlphas(byte[]) | Copies the array of alpha transparency values into the given array.
getBlue(int) | Returns the blue color compoment for the specified pixel in the range 0-255.
getBlues(byte[]) | Copies the array of blue color components into the given array.
getGreen(int) | Returns the green color compoment for the specified pixel in the range 0-255.
getGreens(byte[]) | Copies the array of green color components into the given array.
getMapSize() | Returns the size of the color component arrays in this IndexColorModel.
getRed(int) | Returns the red color compoment for the specified pixel in the range 0-255.
getReds(byte[]) | Copies the array of red color components into the given array.
getRGB(int) | Returns the color of the pixel in the default RGB color model.
getTransparentPixel() | Returns the index of the transparent pixel in this IndexColorModel or -1 if there is no transparent pixel.


 IndexColorModel.IndexColorModel

IndexColorModel.IndexColorModel

Class Overview | Class Members | This Package | All Packages

Syntax 1
public IndexColorModel( int bits, int size, byte r[], byte g[], byte b[] )
Parameters
bits
The number of bits each pixel occupies.
size
The size of the color component arrays.
r
The array of red color components.
g
The array of green color components.
b
The array of blue color components.
Description
Constructs an IndexColorModel from the given arrays of red, green, and blue components. Pixels described by this color model will all have alpha components of 255 (fully opaque). All of the arrays specifying the color components must have at least the specified number of entries.

Syntax 2
public IndexColorModel( int bits, int size, byte r[], byte g[], byte b[], int trans )
Parameters
bits
The number of bits each pixel occupies.
size
The size of the color component arrays.
r
The array of red color components.
g
The array of green color components.
b
The array of blue color components.
trans
The index of the transparent pixel.
Description
Constructs an IndexColorModel from the given arrays of red, green, and blue components. Pixels described by this color model will all have alpha components of 255 (fully opaque), except for the indicated transparent pixel. All of the arrays specifying the color components must have at least the specified number of entries.

Syntax 3
public IndexColorModel( int bits, int size, byte r[], byte g[], byte b[], byte a[] )
Parameters
bits
The number of bits each pixel occupies.
size
The size of the color component arrays.
r
The array of red color components.
g
The array of green color components.
b
The array of blue color components.
a
The array of alpha value components.
Description
Constructs an IndexColorModel from the given arrays of red, green, blue and alpha components. All of the arrays specifying the color components must have at least the specified number of entries.

Syntax 4
public IndexColorModel( int bits, int size, byte cmap[], int start, boolean hasalpha )
Parameters
bits
The number of bits each pixel occupies.
size
The size of the color component arrays.
cmap
The array of color components.
start
The starting offset of the first color component.
hasalpha
Indicates whether alpha values are contained in the cmap array.
Description
Constructs an IndexColorModel from a single arrays of packed red, green, blue and optional alpha components. The array must have enough values in it to fill all of the needed component arrays of the specified size.

Syntax 5
public IndexColorModel( int bits, int size, byte cmap[], int start, boolean hasalpha, int trans )
Parameters
bits
The number of bits each pixel occupies.
size
The size of the color component arrays.
cmap
The array of color components.
start
The starting offset of the first color component.
hasalpha
Indicates whether alpha values are contained in the cmap array.
trans
The index of the fully transparent pixel.
Description
Constructs an IndexColorModel from a single arrays of packed red, green, blue and optional alpha components. The specified transparent index represents a pixel which will be considered entirely transparent regardless of any alpha value specified for it. The array must have enough values in it to fill all of the needed component arrays of the specified size.


 IndexColorModel.getAlpha

IndexColorModel.getAlpha

Class Overview | Class Members | This Package | All Packages

Syntax
public final int getAlpha( int pixel )
Description
Returns the alpha transparency value for the specified pixel in the range 0-255.

Overrides
getAlpha in class ColorModel


 IndexColorModel.getAlphas

IndexColorModel.getAlphas

Class Overview | Class Members | This Package | All Packages

Syntax
public final void getAlphas( byte a[] )
Description
Copies the array of alpha transparency values into the given array. Only the initial entries of the array as specified by getMapSize() will be written.


 IndexColorModel.getBlue

IndexColorModel.getBlue

Class Overview | Class Members | This Package | All Packages

Syntax
public final int getBlue( int pixel )
Description
Returns the blue color compoment for the specified pixel in the range 0-255.

Overrides
getBlue in class ColorModel


 IndexColorModel.getBlues

IndexColorModel.getBlues

Class Overview | Class Members | This Package | All Packages

Syntax
public final void getBlues( byte b[] )
Description
Copies the array of blue color components into the given array. Only the initial entries of the array as specified by getMapSize() will be written.


 IndexColorModel.getGreen

IndexColorModel.getGreen

Class Overview | Class Members | This Package | All Packages

Syntax
public final int getGreen( int pixel )
Description
Returns the green color compoment for the specified pixel in the range 0-255.

Overrides
getGreen in class ColorModel


 IndexColorModel.getGreens

IndexColorModel.getGreens

Class Overview | Class Members | This Package | All Packages

Syntax
public final void getGreens( byte g[] )
Description
Copies the array of green color components into the given array. Only the initial entries of the array as specified by getMapSize() are written.


 IndexColorModel.getMapSize

IndexColorModel.getMapSize

Class Overview | Class Members | This Package | All Packages

Syntax
public final int getMapSize()
Description
Returns the size of the color component arrays in this IndexColorModel.


 IndexColorModel.getRed

IndexColorModel.getRed

Class Overview | Class Members | This Package | All Packages

Syntax
public final int getRed( int pixel )
Description
Returns the red color compoment for the specified pixel in the range 0-255.

Overrides
getRed in class ColorModel


 IndexColorModel.getReds

IndexColorModel.getReds

Class Overview | Class Members | This Package | All Packages

Syntax
public final void getReds( byte r[] )
Description
Copies the array of red color components into the given array. Only the initial entries of the array as specified by getMapSize() are written.


 IndexColorModel.getRGB

IndexColorModel.getRGB

Class Overview | Class Members | This Package | All Packages

Syntax
public final int getRGB( int pixel )
Description
Returns the color of the pixel in the default RGB color model.

Overrides
getRGB in class ColorModel
See Also
getRGBdefault


 IndexColorModel.getTransparentPixel

IndexColorModel.getTransparentPixel

Class Overview | Class Members | This Package | All Packages

Syntax
public final int getTransparentPixel()
Description
Returns the index of the transparent pixel in this IndexColorModel or -1 if there is no transparent pixel.


 Class MemoryImageSource

Class java.awt.image.MemoryImageSource

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.image.MemoryImageSource

public class MemoryImageSource
extends Object
implements ImageProducer

This class is an implementation of the ImageProducer interface which uses an array to produce pixel values for an Image. Here is an example which calculates a 100x100 image representing a fade from black to blue along the X axis and a fade from black to red along the Y axis:

    int w = 100;
    int h = 100;
    int pix[] = new int[w * h];
    int index = 0;
    for (int y = 0; y < h; y++) {
        int red = (y * 255) / (h - 1);
        for (int x = 0; x < w; x++) {
        int blue = (x * 255) / (w - 1);
        pix[index++] = (255 << 24) | (red << 16) | blue;
        }
    }
    Image img = createImage(new MemoryImageSource(w, h, pix, 0, w));
The MemoryImageSource is also capable of managing a memory image which varies over time to allow animation or custom rendering. Here is an example showing how to set up the animation source and signal changes in the data (adapted from the MemoryAnimationSourceDemo by Garth Dickie):
    int pixels[];
    MemoryImageSource source;
    public void init() {
        int width = 50;
        int height = 50;
        int size = width * height;
        pixels = new int[size];
        int value = getBackground().getRGB();
        for (int i = 0; i < size; i++) {
        pixels[i] = value;
        }
        source = new MemoryImageSource(width, height, pixels, 0, width);
        source.setAnimated(true);
        image = createImage(source);
    }
    public void run() {
        Thread me = Thread.currentThread( );
        me.setPriority(Thread.MIN_PRIORITY);
        while (true) {
        try {
            thread.sleep(10);
        } catch( InterruptedException e ) {
            return;
        }
        // Modify the values in the pixels array at (x, y, w, h)
        // Send the new data to the interested ImageConsumers
        source.newPixels(x, y, w, h);
        }
    }

See Also:
ImageProducer


 MemoryImageSource Members

MemoryImageSource Members

Class Overview | This Package | All Packages

Constructors
Name | Description
MemoryImageSource(int, int, ColorModel, byte[], int, int) | Constructs an ImageProducer object which uses an array of bytes to produce data for an Image object.
MemoryImageSource(int, int, ColorModel, byte[], int, int, Hashtable) | Constructs an ImageProducer object which uses an array of bytes to produce data for an Image object.
MemoryImageSource(int, int, ColorModel, int[], int, int) | Constructs an ImageProducer object which uses an array of integers to produce data for an Image object.
MemoryImageSource(int, int, ColorModel, int[], int, int, Hashtable) | Constructs an ImageProducer object which uses an array of integers to produce data for an Image object.
MemoryImageSource(int, int, int[], int, int) | Constructs an ImageProducer object which uses an array of integers in the default RGB ColorModel to produce data for an Image object.
MemoryImageSource(int, int, int[], int, int, Hashtable) | Constructs an ImageProducer object which uses an array of integers in the default RGB ColorModel to produce data for an Image object.

Methods
Name | Description
addConsumer(ImageConsumer) | Adds an ImageConsumer to the list of consumers interested in data for this image.
isConsumer(ImageConsumer) | Determine if an ImageConsumer is on the list of consumers currently interested in data for this image.
newPixels() | Send a whole new buffer of pixels to any ImageConsumers that are currently interested in the data for this image and notify them that an animation frame is complete.
newPixels(byte[], ColorModel, int, int) | Change to a new byte array to hold the pixels for this image.
newPixels(int, int, int, int) | Send a rectangular region of the buffer of pixels to any ImageConsumers that are currently interested in the data for this image and notify them that an animation frame is complete.
newPixels(int, int, int, int, boolean) | Send a rectangular region of the buffer of pixels to any ImageConsumers that are currently interested in the data for this image.
newPixels(int[], ColorModel, int, int) | Change to a new int array to hold the pixels for this image.
removeConsumer(ImageConsumer) | Remove an ImageConsumer from the list of consumers interested in data for this image.
requestTopDownLeftRightResend(ImageConsumer) | Requests that a given ImageConsumer have the image data delivered one more time in top-down, left-right order.
setAnimated(boolean) | Change this memory image into a multi-frame animation or a single-frame static image depending on the animated parameter.
setFullBufferUpdates(boolean) | Specify whether this animated memory image should always be updated by sending the complete buffer of pixels whenever there is a change.
startProduction(ImageConsumer) | Adds an ImageConsumer to the list of consumers interested in data for this image, and immediately start delivery of the image data through the ImageConsumer interface.


 MemoryImageSource.MemoryImageSource

MemoryImageSource.MemoryImageSource

Class Overview | Class Members | This Package | All Packages

Syntax 1
public MemoryImageSource( int w, int h, ColorModel cm, byte pix[], int off, int scan )
Description
Constructs an ImageProducer object which uses an array of bytes to produce data for an Image object.

See Also
createImage

Syntax 2
public MemoryImageSource( int w, int h, ColorModel cm, byte pix[], int off, int scan, Hashtable props )
Description
Constructs an ImageProducer object which uses an array of bytes to produce data for an Image object.

See Also
createImage

Syntax 3
public MemoryImageSource( int w, int h, ColorModel cm, int pix[], int off, int scan )
Description
Constructs an ImageProducer object which uses an array of integers to produce data for an Image object.

See Also
createImage

Syntax 4
public MemoryImageSource( int w, int h, ColorModel cm, int pix[], int off, int scan, Hashtable props )
Description
Constructs an ImageProducer object which uses an array of integers to produce data for an Image object.

See Also
createImage

Syntax 5
public MemoryImageSource( int w, int h, int pix[], int off, int scan )
Description
Constructs an ImageProducer object which uses an array of integers in the default RGB ColorModel to produce data for an Image object.

See Also
createImage, getRGBdefault

Syntax 6
public MemoryImageSource( int w, int h, int pix[], int off, int scan, Hashtable props )
Description
Constructs an ImageProducer object which uses an array of integers in the default RGB ColorModel to produce data for an Image object.

See Also
createImage, getRGBdefault


 MemoryImageSource.addConsumer

MemoryImageSource.addConsumer

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void addConsumer( ImageConsumer ic )
Description
Adds an ImageConsumer to the list of consumers interested in data for this image.

See Also
ImageConsumer


 MemoryImageSource.isConsumer

MemoryImageSource.isConsumer

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized boolean isConsumer( ImageConsumer ic )
Returns
true if the ImageConsumer is on the list; false otherwise
Description
Determine if an ImageConsumer is on the list of consumers currently interested in data for this image.

See Also
ImageConsumer


 MemoryImageSource.newPixels

MemoryImageSource.newPixels

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void newPixels()
Description
Send a whole new buffer of pixels to any ImageConsumers that are currently interested in the data for this image and notify them that an animation frame is complete. This method only has effect if the animation flag has been turned on through the setAnimated() method.

See Also
ImageConsumer, setAnimated

Syntax 2
public synchronized void newPixels( int x, int y, int w, int h )
Parameters
x
the x coordinate of the upper left corner of the rectangle of pixels to be sent
y
the y coordinate of the upper left corner of the rectangle of pixels to be sent
w
the width of the rectangle of pixels to be sent
h
the height of the rectangle of pixels to be sent
Description
Send a rectangular region of the buffer of pixels to any ImageConsumers that are currently interested in the data for this image and notify them that an animation frame is complete. This method only has effect if the animation flag has been turned on through the setAnimated() method. If the full buffer update flag was turned on with the setFullBufferUpdates() method then the rectangle parameters will be ignored and the entire buffer will always be sent.

See Also
ImageConsumer, setAnimated, setFullBufferUpdates

Syntax 3
public synchronized void newPixels( int x, int y, int w, int h, boolean framenotify )
Parameters
x
the x coordinate of the upper left corner of the rectangle of pixels to be sent
y
the y coordinate of the upper left corner of the rectangle of pixels to be sent
w
the width of the rectangle of pixels to be sent
h
the height of the rectangle of pixels to be sent
framenotify
true if the consumers should be sent a SINGLEFRAMEDONE notification
Description
Send a rectangular region of the buffer of pixels to any ImageConsumers that are currently interested in the data for this image. If the framenotify parameter is true then the consumers are also notified that an animation frame is complete. This method only has effect if the animation flag has been turned on through the setAnimated() method. If the full buffer update flag was turned on with the setFullBufferUpdates() method then the rectangle parameters will be ignored and the entire buffer will always be sent.

See Also
ImageConsumer, setAnimated, setFullBufferUpdates

Syntax 4
public synchronized void newPixels( byte newpix[], ColorModel newmodel, int offset, int scansize )
Description
Change to a new byte array to hold the pixels for this image. If the animation flag has been turned on through the setAnimated() method, then the new pixels will be immediately delivered to any ImageConsumers that are currently interested in the data for this image.

See Also
setAnimated

Syntax 5
public synchronized void newPixels( int newpix[], ColorModel newmodel, int offset, int scansize )
Description
Change to a new int array to hold the pixels for this image. If the animation flag has been turned on through the setAnimated() method, then the new pixels will be immediately delivered to any ImageConsumers that are currently interested in the data for this image.

See Also
setAnimated


 MemoryImageSource.removeConsumer

MemoryImageSource.removeConsumer

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void removeConsumer( ImageConsumer ic )
Description
Remove an ImageConsumer from the list of consumers interested in data for this image.

See Also
ImageConsumer


 MemoryImageSource.requestTopDownLeftRightResend

MemoryImageSource.requestTopDownLeftRightResend

Class Overview | Class Members | This Package | All Packages

Syntax
public void requestTopDownLeftRightResend( ImageConsumer ic )
Description
Requests that a given ImageConsumer have the image data delivered one more time in top-down, left-right order.

See Also
ImageConsumer


 MemoryImageSource.setAnimated

MemoryImageSource.setAnimated

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setAnimated( boolean animated )
Parameters
animated
true if the image is a multi-frame animation
Description
Change this memory image into a multi-frame animation or a single-frame static image depending on the animated parameter.

This method should be called immediately after the MemoryImageSource is constructed and before an image is created with it to ensure that all ImageConsumers will receive the correct multi-frame data. If an ImageConsumer is added to this ImageProducer before this flag is set then that ImageConsumer will see only a snapshot of the pixel data that was available when it connected.


 MemoryImageSource.setFullBufferUpdates

MemoryImageSource.setFullBufferUpdates

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setFullBufferUpdates( boolean fullbuffers )
Parameters
fullbuffers
true if the complete pixel buffer should always be sent
Description
Specify whether this animated memory image should always be updated by sending the complete buffer of pixels whenever there is a change. This flag is ignored if the animation flag is not turned on through the setAnimated() method.

This method should be called immediately after the MemoryImageSource is constructed and before an image is created with it to ensure that all ImageConsumers will receive the correct pixel delivery hints.

See Also
setAnimated


 MemoryImageSource.startProduction

MemoryImageSource.startProduction

Class Overview | Class Members | This Package | All Packages

Syntax
public void startProduction( ImageConsumer ic )
Description
Adds an ImageConsumer to the list of consumers interested in data for this image, and immediately start delivery of the image data through the ImageConsumer interface.

See Also
ImageConsumer


 Class PixelGrabber

Class java.awt.image.PixelGrabber

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.image.PixelGrabber

public class PixelGrabber
extends Object
implements ImageConsumer

The PixelGrabber class implements an ImageConsumer which can be attached to an Image or ImageProducer object to retrieve a subset of the pixels in that image. Here is an example:

 public void handlesinglepixel(int x, int y, int pixel) {
    int alpha = (pixel >> 24) & 0xff;
    int red   = (pixel >> 16) & 0xff;
    int green = (pixel >>  8) & 0xff;
    int blue  = (pixel      ) & 0xff;
    // Deal with the pixel as necessary...
 }
 public void handlepixels(Image img, int x, int y, int w, int h) {
    int[] pixels = new int[w * h];
    PixelGrabber pg = new PixelGrabber(img, x, y, w, h, pixels, 0, w);
    try {
        pg.grabPixels();
    } catch (InterruptedException e) {
        System.err.println("interrupted waiting for pixels!");
        return;
    }
    if ((pg.getStatus() & ImageObserver.ABORT) != 0) {
        System.err.println("image fetch aborted or errored");
        return;
    }
    for (int j = 0; j < h; j++) {
        for (int i = 0; i < w; i++) {
        handlesinglepixel(x+i, y+j, pixels[j * w + i]);
        }
    }
 }

See Also:
getRGBdefault


 PixelGrabber Members

PixelGrabber Members

Class Overview | This Package | All Packages

Constructors
Name | Description
PixelGrabber(Image, int, int, int, int, boolean) | Create a PixelGrabber object to grab the (x, y, w, h) rectangular section of pixels from the specified image.
PixelGrabber(Image, int, int, int, int, int[], int, int) | Create a PixelGrabber object to grab the (x, y, w, h) rectangular section of pixels from the specified image into the given array.
PixelGrabber(ImageProducer, int, int, int, int, int[], int, int) | Create a PixelGrabber object to grab the (x, y, w, h) rectangular section of pixels from the image produced by the specified ImageProducer into the given array.

Methods
Name | Description
abortGrabbing() | Request the PixelGrabber to abort the image fetch.
getColorModel() | Get the ColorModel for the pixels stored in the array.
getHeight() | Get the height of the pixel buffer (after adjusting for image height).
getPixels() | Get the pixel buffer.
getStatus() | Return the status of the pixels.
getWidth() | Get the width of the pixel buffer (after adjusting for image width).
grabPixels() | Request the Image or ImageProducer to start delivering pixels and wait for all of the pixels in the rectangle of interest to be delivered.
grabPixels(long) | Request the Image or ImageProducer to start delivering pixels and wait for all of the pixels in the rectangle of interest to be delivered or until the specified timeout has elapsed.
imageComplete(int) | The imageComplete method is part of the ImageConsumer API which this class must implement to retrieve the pixels.
setColorModel(ColorModel) | The setColorModel method is part of the ImageConsumer API which this class must implement to retrieve the pixels.
setDimensions(int, int) | The setDimensions method is part of the ImageConsumer API which this class must implement to retrieve the pixels.
setHints(int) | The setHints method is part of the ImageConsumer API which this class must implement to retrieve the pixels.
setPixels(int, int, int, int, ColorModel, byte[], int, int) | The setPixels method is part of the ImageConsumer API which this class must implement to retrieve the pixels.
setPixels(int, int, int, int, ColorModel, int[], int, int) | The setPixels method is part of the ImageConsumer API which this class must implement to retrieve the pixels.
setProperties(Hashtable) | The setProperties method is part of the ImageConsumer API which this class must implement to retrieve the pixels.
startGrabbing() | Request the PixelGrabber to start fetching the pixels.
status() | DEPRECATED: Replaced by getStatus().


 PixelGrabber.PixelGrabber

PixelGrabber.PixelGrabber

Class Overview | Class Members | This Package | All Packages

Syntax 1
public PixelGrabber( Image img, int x, int y, int w, int h, int pix[], int off, int scansize )
Parameters
img
the image to retrieve pixels from
x
the x coordinate of the upper left corner of the rectangle of pixels to retrieve from the image, relative to the default (unscaled) size of the image
y
the y coordinate of the upper left corner of the rectangle of pixels to retrieve from the image
w
the width of the rectangle of pixels to retrieve
h
the height of the rectangle of pixels to retrieve
pix
the array of integers which are to be used to hold the RGB pixels retrieved from the image
off
the offset into the array of where to store the first pixel
scansize
the distance from one row of pixels to the next in the array
Description
Create a PixelGrabber object to grab the (x, y, w, h) rectangular section of pixels from the specified image into the given array. The pixels are stored into the array in the default RGB ColorModel. The RGB data for pixel (i, j) where (i, j) is inside the rectangle (x, y, w, h) is stored in the array at pix[(j - y) * scansize + (i - x) + off].

See Also
getRGBdefault

Syntax 2
public PixelGrabber( ImageProducer ip, int x, int y, int w, int h, int pix[], int off, int scansize )
Parameters
img
the image to retrieve pixels from
x
the x coordinate of the upper left corner of the rectangle of pixels to retrieve from the image, relative to the default (unscaled) size of the image
y
the y coordinate of the upper left corner of the rectangle of pixels to retrieve from the image
w
the width of the rectangle of pixels to retrieve
h
the height of the rectangle of pixels to retrieve
pix
the array of integers which are to be used to hold the RGB pixels retrieved from the image
off
the offset into the array of where to store the first pixel
scansize
the distance from one row of pixels to the next in the array
Description
Create a PixelGrabber object to grab the (x, y, w, h) rectangular section of pixels from the image produced by the specified ImageProducer into the given array. The pixels are stored into the array in the default RGB ColorModel. The RGB data for pixel (i, j) where (i, j) is inside the rectangle (x, y, w, h) is stored in the array at pix[(j - y) * scansize + (i - x) + off].

See Also
getRGBdefault

Syntax 3
public PixelGrabber( Image img, int x, int y, int w, int h, boolean forceRGB )
Parameters
img
the image to retrieve the image data from
x
the x coordinate of the upper left corner of the rectangle of pixels to retrieve from the image, relative to the default (unscaled) size of the image
y
the y coordinate of the upper left corner of the rectangle of pixels to retrieve from the image
w
the width of the rectangle of pixels to retrieve
h
the height of the rectangle of pixels to retrieve
forceRGB
true if the pixels should always be converted to the default RGB ColorModel
Description
Create a PixelGrabber object to grab the (x, y, w, h) rectangular section of pixels from the specified image. The pixels are accumulated in the original ColorModel if the same ColorModel is used for every call to setPixels, otherwise the pixels are accumulated in the default RGB ColorModel. If the forceRGB parameter is true, then the pixels will be accumulated in the default RGB ColorModel anywya. A buffer is allocated by the PixelGrabber to hold the pixels in either case. If (w < 0) or (h < 0), then they will default to the remaining width and height of the source data when that information is delivered.


 PixelGrabber.abortGrabbing

PixelGrabber.abortGrabbing

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void abortGrabbing()
Description
Request the PixelGrabber to abort the image fetch.


 PixelGrabber.getColorModel

PixelGrabber.getColorModel

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized ColorModel getColorModel()
Returns
the ColorModel object used for storing the pixels
Description
Get the ColorModel for the pixels stored in the array. If the PixelGrabber was constructed with an explicit pixel buffer then this method will always return the default RGB ColorModel, otherwise it may return null until the ColorModel used by the ImageProducer is known. Since the PixelGrabber may fall back on accumulating the data in the default RGB ColorModel at any time if the source image uses more than one ColorModel to deliver the data, the ColorModel object returned by this method may change over time until the image grab is complete.

See Also
getStatus, getRGBdefault


 PixelGrabber.getHeight

PixelGrabber.getHeight

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized int getHeight()
Returns
the final height used for the pixel buffer or -1 if the height is not yet known
Description
Get the height of the pixel buffer (after adjusting for image height). If no width was specified for the rectangle of pixels to grab then then this information will only be available after the image has delivered the dimensions.

See Also
getStatus


 PixelGrabber.getPixels

PixelGrabber.getPixels

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized Object getPixels()
Returns
either a byte array or an int array
Description
Get the pixel buffer. If the PixelGrabber was not constructed with an explicit pixel buffer to hold the pixels then this method will return null until the size and format of the image data is known. Since the PixelGrabber may fall back on accumulating the data in the default RGB ColorModel at any time if the source image uses more than one ColorModel to deliver the data, the array object returned by this method may change over time until the image grab is complete.

See Also
getStatus


 PixelGrabber.getStatus

PixelGrabber.getStatus

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized int getStatus()
Returns
the bitwise OR of all relevant ImageObserver flags
Description
Return the status of the pixels. The ImageObserver flags representing the available pixel information are returned.

See Also
ImageObserver


 PixelGrabber.getWidth

PixelGrabber.getWidth

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized int getWidth()
Returns
the final width used for the pixel buffer or -1 if the width is not yet known
Description
Get the width of the pixel buffer (after adjusting for image width). If no width was specified for the rectangle of pixels to grab then then this information will only be available after the image has delivered the dimensions.

See Also
getStatus


 PixelGrabber.grabPixels

PixelGrabber.grabPixels

Class Overview | Class Members | This Package | All Packages

Syntax 1
public boolean grabPixels() throws InterruptedException
Returns
true if the pixels were successfully grabbed, false on abort, error or timeout
Description
Request the Image or ImageProducer to start delivering pixels and wait for all of the pixels in the rectangle of interest to be delivered.

Exceptions
InterruptedException Another thread has interrupted this thread.

Syntax 2
public synchronized boolean grabPixels( long ms ) throws InterruptedException
Parameters
ms
the number of milliseconds to wait for the image pixels to arrive before timing out
Returns
true if the pixels were successfully grabbed, false on abort, error or timeout
Description
Request the Image or ImageProducer to start delivering pixels and wait for all of the pixels in the rectangle of interest to be delivered or until the specified timeout has elapsed.

Exceptions
InterruptedException Another thread has interrupted this thread.


 PixelGrabber.imageComplete

PixelGrabber.imageComplete

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void imageComplete( int status )
Description
The imageComplete method is part of the ImageConsumer API which this class must implement to retrieve the pixels.


 PixelGrabber.setColorModel

PixelGrabber.setColorModel

Class Overview | Class Members | This Package | All Packages

Syntax
public void setColorModel( ColorModel model )
Description
The setColorModel method is part of the ImageConsumer API which this class must implement to retrieve the pixels.


 PixelGrabber.setDimensions

PixelGrabber.setDimensions

Class Overview | Class Members | This Package | All Packages

Syntax
public void setDimensions( int width, int height )
Description
The setDimensions method is part of the ImageConsumer API which this class must implement to retrieve the pixels.


 PixelGrabber.setHints

PixelGrabber.setHints

Class Overview | Class Members | This Package | All Packages

Syntax
public void setHints( int hints )
Description
The setHints method is part of the ImageConsumer API which this class must implement to retrieve the pixels.


 PixelGrabber.setPixels

PixelGrabber.setPixels

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void setPixels( int srcX, int srcY, int srcW, int srcH, ColorModel model, byte pixels[], int srcOff, int srcScan )
Description
The setPixels method is part of the ImageConsumer API which this class must implement to retrieve the pixels.

Syntax 2
public void setPixels( int srcX, int srcY, int srcW, int srcH, ColorModel model, int pixels[], int srcOff, int srcScan )
Description
The setPixels method is part of the ImageConsumer API which this class must implement to retrieve the pixels.


 PixelGrabber.setProperties

PixelGrabber.setProperties

Class Overview | Class Members | This Package | All Packages

Syntax
public void setProperties( Hashtable props )
Description
The setProperties method is part of the ImageConsumer API which this class must implement to retrieve the pixels.


 PixelGrabber.startGrabbing

PixelGrabber.startGrabbing

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void startGrabbing()
Description
Request the PixelGrabber to start fetching the pixels.


 PixelGrabber.status

PixelGrabber.status

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized int status()
Description
DEPRECATED: Replaced by getStatus().


 Class RGBImageFilter

Class java.awt.image.RGBImageFilter

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.image.ImageFilter
           |
           +----java.awt.image.RGBImageFilter

public abstract class RGBImageFilter
extends ImageFilter

This class provides an easy way to create an ImageFilter which modifies the pixels of an image in the default RGB ColorModel. It is meant to be used in conjunction with a FilteredImageSource object to produce filtered versions of existing images. It is an abstract class that provides the calls needed to channel all of the pixel data through a single method which converts pixels one at a time in the default RGB ColorModel regardless of the ColorModel being used by the ImageProducer. The only method which needs to be defined to create a useable image filter is the filterRGB method. Here is an example of a definition of a filter which swaps the red and blue components of an image:

    class RedBlueSwapFilter extends RGBImageFilter {
        public RedBlueSwapFilter() {
        // The filter's operation does not depend on the
        // pixel's location, so IndexColorModels can be
        // filtered directly.
        canFilterIndexColorModel = true;
        }
        public int filterRGB(int x, int y, int rgb) {
        return ((rgb & 0xff00ff00)
            | ((rgb & 0xff0000) >> 16)
            | ((rgb & 0xff) << 16));
        }
    }

See Also:
FilteredImageSource, ImageFilter, getRGBdefault


 RGBImageFilter Members

RGBImageFilter Members

Class Overview | This Package | All Packages

Fields
Name | Description
canFilterIndexColorModel | This boolean indicates whether or not it is acceptable to apply the color filtering of the filterRGB method to the color table entries of an IndexColorModel object in lieu of pixel by pixel filtering.
newmodel |
origmodel |

Constructors
Name | Description
RGBImageFilter() |

Methods
Name | Description
filterIndexColorModel(IndexColorModel) | Filters an IndexColorModel object by running each entry in its color tables through the filterRGB function that RGBImageFilter subclasses must provide.
filterRGB(int, int, int) | Subclasses must specify a method to convert a single input pixel in the default RGB ColorModel to a single output pixel.
filterRGBPixels(int, int, int, int, int[], int, int) | Filters a buffer of pixels in the default RGB ColorModel by passing them one by one through the filterRGB method.
setColorModel(ColorModel) | If the ColorModel is an IndexColorModel, and the subclass has set the canFilterIndexColorModel flag to true, we substitute a filtered version of the color model here and wherever that original ColorModel object appears in the setPixels methods.
setPixels(int, int, int, int, ColorModel, byte[], int, int) | If the ColorModel object is the same one that has already been converted, then simply passes the pixels through with the converted ColorModel.
setPixels(int, int, int, int, ColorModel, int[], int, int) | If the ColorModel object is the same one that has already been converted, then simply passes the pixels through with the converted ColorModel, otherwise converts the buffer of integer pixels to the default RGB ColorModel and passes the converted buffer to the filterRGBPixels method to be converted one by one.
substituteColorModel(ColorModel, ColorModel) | Registers two ColorModel objects for substitution.


 RGBImageFilter.canFilterIndexColorModel

RGBImageFilter.canFilterIndexColorModel

Class Overview | Class Members | This Package | All Packages

Syntax
protected boolean canFilterIndexColorModel
Description
This boolean indicates whether or not it is acceptable to apply the color filtering of the filterRGB method to the color table entries of an IndexColorModel object in lieu of pixel by pixel filtering. Subclasses should set this variable to true in their constructor if their filterRGB method does not depend on the coordinate of the pixel being filtered.

See Also
substituteColorModel, filterRGB, IndexColorModel


 RGBImageFilter.newmodel

RGBImageFilter.newmodel

Class Overview | Class Members | This Package | All Packages

Syntax
protected ColorModel newmodel


 RGBImageFilter.origmodel

RGBImageFilter.origmodel

Class Overview | Class Members | This Package | All Packages

Syntax
protected ColorModel origmodel


 RGBImageFilter.RGBImageFilter

RGBImageFilter.RGBImageFilter

Class Overview | Class Members | This Package | All Packages

Syntax
public RGBImageFilter()


 RGBImageFilter.filterIndexColorModel

RGBImageFilter.filterIndexColorModel

Class Overview | Class Members | This Package | All Packages

Syntax
public IndexColorModel filterIndexColorModel( IndexColorModel icm )
Parameters
icm
the IndexColorModel object to be filtered
Returns
a new IndexColorModel representing the filtered colors
Description
Filters an IndexColorModel object by running each entry in its color tables through the filterRGB function that RGBImageFilter subclasses must provide. Uses coordinates of -1 to indicate that a color table entry is being filtered rather than an actual pixel value.


 RGBImageFilter.filterRGB

RGBImageFilter.filterRGB

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract int filterRGB( int x, int y, int rgb )
Description
Subclasses must specify a method to convert a single input pixel in the default RGB ColorModel to a single output pixel.

See Also
getRGBdefault, filterRGBPixels


 RGBImageFilter.filterRGBPixels

RGBImageFilter.filterRGBPixels

Class Overview | Class Members | This Package | All Packages

Syntax
public void filterRGBPixels( int x, int y, int w, int h, int pixels[], int off, int scansize )
Description
Filters a buffer of pixels in the default RGB ColorModel by passing them one by one through the filterRGB method.

See Also
getRGBdefault, filterRGB


 RGBImageFilter.setColorModel

RGBImageFilter.setColorModel

Class Overview | Class Members | This Package | All Packages

Syntax
public void setColorModel( ColorModel model )
Description
If the ColorModel is an IndexColorModel, and the subclass has set the canFilterIndexColorModel flag to true, we substitute a filtered version of the color model here and wherever that original ColorModel object appears in the setPixels methods. Otherwise overrides the default ColorModel used by the ImageProducer and specifies the default RGB ColorModel instead.

Overrides
setColorModel in class ImageFilter
See Also
ImageConsumer, getRGBdefault


 RGBImageFilter.setPixels

RGBImageFilter.setPixels

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void setPixels( int x, int y, int w, int h, ColorModel model, byte pixels[], int off, int scansize )
Description
If the ColorModel object is the same one that has already been converted, then simply passes the pixels through with the converted ColorModel. Otherwise converts the buffer of byte pixels to the default RGB ColorModel and passes the converted buffer to the filterRGBPixels method to be converted one by one.

Overrides
setPixels in class ImageFilter
See Also
getRGBdefault, filterRGBPixels

Syntax 2
public void setPixels( int x, int y, int w, int h, ColorModel model, int pixels[], int off, int scansize )
Description
If the ColorModel object is the same one that has already been converted, then simply passes the pixels through with the converted ColorModel, otherwise converts the buffer of integer pixels to the default RGB ColorModel and passes the converted buffer to the filterRGBPixels method to be converted one by one. Converts a buffer of integer pixels to the default RGB ColorModel and passes the converted buffer to the filterRGBPixels method.

Overrides
setPixels in class ImageFilter
See Also
getRGBdefault, filterRGBPixels


 RGBImageFilter.substituteColorModel

RGBImageFilter.substituteColorModel

Class Overview | Class Members | This Package | All Packages

Syntax
public void substituteColorModel( ColorModel oldcm, ColorModel newcm )
Parameters
oldcm
the ColorModel object to be replaced on the fly
newcm
the ColorModel object to replace oldcm on the fly
Description
Registers two ColorModel objects for substitution. If the oldcm is encountered during any of the setPixels methods, the newcm is substituted and the pixels passed through untouched (but with the new ColorModel object).


 Class ReplicateScaleFilter

Class java.awt.image.ReplicateScaleFilter

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.awt.image.ImageFilter
           |
           +----java.awt.image.ReplicateScaleFilter

public class ReplicateScaleFilter
extends ImageFilter

An ImageFilter class for scaling images using the simplest algorithm. This class extends the basic ImageFilter Class to scale an existing image and provide a source for a new image containing the resampled image. The pixels in the source image are sampled to produce pixels for an image of the specified size by replicating rows and columns of pixels to scale up or omitting rows and columns of pixels to scale down. It is meant to be used in conjunction with a FilteredImageSource object to produce scaled versions of existing images.

See Also:
FilteredImageSource, ImageFilter


 ReplicateScaleFilter Members

ReplicateScaleFilter Members

Class Overview | This Package | All Packages

Fields
Name | Description
destHeight |
destWidth |
outpixbuf |
srccols |
srcHeight |
srcrows |
srcWidth |

Constructors
Name | Description
ReplicateScaleFilter(int, int) | Constructs a ReplicateScaleFilter that scales the pixels from its source Image as specified by the width and height parameters.

Methods
Name | Description
setDimensions(int, int) | Override the dimensions of the source image and pass the dimensions of the new scaled size to the ImageConsumer.
setPixels(int, int, int, int, ColorModel, byte[], int, int) | Choose which rows and columns of the delivered byte pixels are needed for the destination scaled image and pass through just those rows and columns that are needed, replicated as necessary.
setPixels(int, int, int, int, ColorModel, int[], int, int) | Choose which rows and columns of the delivered int pixels are needed for the destination scaled image and pass through just those rows and columns that are needed, replicated as necessary.
setProperties(Hashtable) | Passes along the properties from the source object after adding a property indicating the scale applied.


 ReplicateScaleFilter.destHeight

ReplicateScaleFilter.destHeight

Class Overview | Class Members | This Package | All Packages

Syntax
protected int destHeight


 ReplicateScaleFilter.destWidth

ReplicateScaleFilter.destWidth

Class Overview | Class Members | This Package | All Packages

Syntax
protected int destWidth


 ReplicateScaleFilter.outpixbuf

ReplicateScaleFilter.outpixbuf

Class Overview | Class Members | This Package | All Packages

Syntax
protected Object outpixbuf


 ReplicateScaleFilter.srccols

ReplicateScaleFilter.srccols

Class Overview | Class Members | This Package | All Packages

Syntax
protected int srccols[]


 ReplicateScaleFilter.srcHeight

ReplicateScaleFilter.srcHeight

Class Overview | Class Members | This Package | All Packages

Syntax
protected int srcHeight


 ReplicateScaleFilter.srcrows

ReplicateScaleFilter.srcrows

Class Overview | Class Members | This Package | All Packages

Syntax
protected int srcrows[]


 ReplicateScaleFilter.srcWidth

ReplicateScaleFilter.srcWidth

Class Overview | Class Members | This Package | All Packages

Syntax
protected int srcWidth


 ReplicateScaleFilter.ReplicateScaleFilter

ReplicateScaleFilter.ReplicateScaleFilter

Class Overview | Class Members | This Package | All Packages

Syntax
public ReplicateScaleFilter( int width, int height )
Parameters
width
the target width to scale the image
height
the target height to scale the image
Description
Constructs a ReplicateScaleFilter that scales the pixels from its source Image as specified by the width and height parameters.


 ReplicateScaleFilter.setDimensions

ReplicateScaleFilter.setDimensions

Class Overview | Class Members | This Package | All Packages

Syntax
public void setDimensions( int w, int h )
Description
Override the dimensions of the source image and pass the dimensions of the new scaled size to the ImageConsumer.

Overrides
setDimensions in class ImageFilter
See Also
ImageConsumer


 ReplicateScaleFilter.setPixels

ReplicateScaleFilter.setPixels

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void setPixels( int x, int y, int w, int h, ColorModel model, byte pixels[], int off, int scansize )
Description
Choose which rows and columns of the delivered byte pixels are needed for the destination scaled image and pass through just those rows and columns that are needed, replicated as necessary.

Overrides
setPixels in class ImageFilter

Syntax 2
public void setPixels( int x, int y, int w, int h, ColorModel model, int pixels[], int off, int scansize )
Description
Choose which rows and columns of the delivered int pixels are needed for the destination scaled image and pass through just those rows and columns that are needed, replicated as necessary.

Overrides
setPixels in class ImageFilter


 ReplicateScaleFilter.setProperties

ReplicateScaleFilter.setProperties

Class Overview | Class Members | This Package | All Packages

Syntax
public void setProperties( Hashtable props )
Description
Passes along the properties from the source object after adding a property indicating the scale applied.

Overrides
setProperties in class ImageFilter


 Package java.beans

Package java.beans

All Packages

Interfaces

  • BeanInfo
  • Customizer
  • PropertyChangeListener
  • PropertyEditor
  • VetoableChangeListener
  • Visibility

    • Classes

  • BeanDescriptor
  • Beans
  • EventSetDescriptor
  • FeatureDescriptor
  • IndexedPropertyDescriptor
  • Introspector
  • MethodDescriptor
  • ParameterDescriptor
  • PropertyChangeEvent
  • PropertyChangeSupport
  • PropertyDescriptor
  • PropertyEditorManager
  • PropertyEditorSupport
  • SimpleBeanInfo
  • VetoableChangeSupport

    • Exceptions

  • IntrospectionException
  • PropertyVetoException


 Class BeanDescriptor

Class java.beans.BeanDescriptor

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.beans.FeatureDescriptor
           |
           +----java.beans.BeanDescriptor

public class BeanDescriptor
extends FeatureDescriptor

A BeanDescriptor provides global information about a "bean", including its Java class, its displayName, etc.

This is one of the kinds of descriptor returned by a BeanInfo object, which also returns descriptors for properties, method, and events.


 BeanDescriptor Members

BeanDescriptor Members

Class Overview | This Package | All Packages

Constructors
Name | Description
BeanDescriptor(Class) | Create a BeanDescriptor for a bean that doesn't have a customizer.
BeanDescriptor(Class, Class) | Create a BeanDescriptor for a bean that has a customizer.

Methods
Name | Description
getBeanClass() |
getCustomizerClass() |


 BeanDescriptor.BeanDescriptor

BeanDescriptor.BeanDescriptor

Class Overview | Class Members | This Package | All Packages

Syntax 1
public BeanDescriptor( Class beanClass )
Parameters
beanClass
The Class object of the Java class that implements the bean. For example sun.beans.OurButton.class.
Description
Create a BeanDescriptor for a bean that doesn't have a customizer.

Syntax 2
public BeanDescriptor( Class beanClass, Class customizerClass )
Parameters
beanClass
The Class object of the Java class that implements the bean. For example sun.beans.OurButton.class.
customizerClass
The Class object of the Java class that implements the bean's Customizer. For example sun.beans.OurButtonCustomizer.class.
Description
Create a BeanDescriptor for a bean that has a customizer.


 BeanDescriptor.getBeanClass

BeanDescriptor.getBeanClass

Class Overview | Class Members | This Package | All Packages

Syntax
public Class getBeanClass()
Returns
The Class object for the bean.


 BeanDescriptor.getCustomizerClass

BeanDescriptor.getCustomizerClass

Class Overview | Class Members | This Package | All Packages

Syntax
public Class getCustomizerClass()
Returns
The Class object for the bean's customizer. This may be null if the bean doesn't have a customizer.


 Interface BeanInfo

Interface java.beans.BeanInfo

Interface Members | This Package | All Packages

public interface BeanInfo

A bean implementor who wishes to provide explicit information about their bean may provide a BeanInfo class that implements this BeanInfo interface and provides explicit information about the methods, properties, events, etc, of their bean.

A bean implementor doesn't need to provide a complete set of explicit information. You can pick and choose which information you want to provide and the rest will be obtained by automatic analysis using low-level reflection of the bean classes' methods and applying standard design patterns.

You get the opportunity to provide lots and lots of different information as part of the various XyZDescriptor classes. But don't panic, you only really need to provide the minimal core information required by the various constructors.

See also the SimpleBeanInfo class which provides a convenient "noop" base class for BeanInfo classes, which you can override for those specific places where you want to return explicit info.

To learn about all the behaviour of a bean see the Introspector class.


 BeanInfo Members

BeanInfo Members

Interface Overview | This Package | All Packages

Fields
Name | Description
ICON_COLOR_16x16 | Constant to indicate a 16 x 16 color icon.
ICON_COLOR_32x32 | Constant to indicate a 32 x 32 color icon.
ICON_MONO_16x16 | Constant to indicate a 16 x 16 monochrome icon.
ICON_MONO_32x32 | Constant to indicate a 32 x 32 monochrome icon.

Methods
Name | Description
getAdditionalBeanInfo() | This method allows a BeanInfo object to return an arbitrary collection of other BeanInfo objects that provide additional information on the current bean.
getBeanDescriptor() |
getDefaultEventIndex() | A bean may have a "default" event that is the event that will mostly commonly be used by human's when using the bean.
getDefaultPropertyIndex() | A bean may have a "default" property that is the property that will mostly commonly be initially chosen for update by human's who are customizing the bean.
getEventSetDescriptors() |
getIcon(int) | This method returns an image object that can be used to represent the bean in toolboxes, toolbars, etc.
getMethodDescriptors() |
getPropertyDescriptors() |


 BeanInfo.ICON_COLOR_16x16

BeanInfo.ICON_COLOR_16x16

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int ICON_COLOR_16x16
Description
Constant to indicate a 16 x 16 color icon.


 BeanInfo.ICON_COLOR_32x32

BeanInfo.ICON_COLOR_32x32

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int ICON_COLOR_32x32
Description
Constant to indicate a 32 x 32 color icon.


 BeanInfo.ICON_MONO_16x16

BeanInfo.ICON_MONO_16x16

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int ICON_MONO_16x16
Description
Constant to indicate a 16 x 16 monochrome icon.


 BeanInfo.ICON_MONO_32x32

BeanInfo.ICON_MONO_32x32

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int ICON_MONO_32x32
Description
Constant to indicate a 32 x 32 monochrome icon.


 BeanInfo.getAdditionalBeanInfo

BeanInfo.getAdditionalBeanInfo

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract BeanInfo[] getAdditionalBeanInfo()
Returns
an array of BeanInfo objects. May return null.
Description
This method allows a BeanInfo object to return an arbitrary collection of other BeanInfo objects that provide additional information on the current bean.

If there are conflicts or overlaps between the information provided by different BeanInfo objects, then the current BeanInfo takes precedence over the getAdditionalBeanInfo objects, and later elements in the array take precedence over earlier ones.


 BeanInfo.getBeanDescriptor

BeanInfo.getBeanDescriptor

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract BeanDescriptor getBeanDescriptor()
Returns
A BeanDescriptor providing overall information about the bean, such as its displayName, its customizer, etc. May return null if the information should be obtained by automatic analysis.


 BeanInfo.getDefaultEventIndex

BeanInfo.getDefaultEventIndex

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getDefaultEventIndex()
Returns
Index of default event in the EventSetDescriptor array returned by getEventSetDescriptors.

Returns -1 if there is no default event.

Description
A bean may have a "default" event that is the event that will mostly commonly be used by human's when using the bean.


 BeanInfo.getDefaultPropertyIndex

BeanInfo.getDefaultPropertyIndex

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getDefaultPropertyIndex()
Returns
Index of default property in the PropertyDescriptor array returned by getPropertyDescriptors.

Returns -1 if there is no default property.

Description
A bean may have a "default" property that is the property that will mostly commonly be initially chosen for update by human's who are customizing the bean.


 BeanInfo.getEventSetDescriptors

BeanInfo.getEventSetDescriptors

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract EventSetDescriptor[] getEventSetDescriptors()
Returns
An array of EventSetDescriptors describing the kinds of events fired by this bean. May return null if the information should be obtained by automatic analysis.


 BeanInfo.getIcon

BeanInfo.getIcon

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Image getIcon( int iconKind )
Parameters
iconKind
The kind of icon requested. This should be one of the constant values ICON_COLOR_16x16, ICON_COLOR_32x32, ICON_MONO_16x16, or ICON_MONO_32x32.
Returns
An image object representing the requested icon. May return null if no suitable icon is available.
Description
This method returns an image object that can be used to represent the bean in toolboxes, toolbars, etc. Icon images will typically be GIFs, but may in future include other formats.

Beans aren't required to provide icons and may return null from this method.

There are four possible flavors of icons (16x16 color, 32x32 color, 16x16 mono, 32x32 mono). If a bean choses to only support a single icon we recommend supporting 16x16 color.

We recommend that icons have a "transparent" background so they can be rendered onto an existing background.


 BeanInfo.getMethodDescriptors

BeanInfo.getMethodDescriptors

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract MethodDescriptor[] getMethodDescriptors()
Returns
An array of MethodDescriptors describing the externally visible methods supported by this bean. May return null if the information should be obtained by automatic analysis.


 BeanInfo.getPropertyDescriptors

BeanInfo.getPropertyDescriptors

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract PropertyDescriptor[] getPropertyDescriptors()
Returns
An array of PropertyDescriptors describing the editable properties supported by this bean. May return null if the information should be obtained by automatic analysis.

If a property is indexed, then its entry in the result array will belong to the IndexedPropertyDescriptor subclass of PropertyDescriptor. A client of getPropertyDescriptors can use "instanceof" to check if a given PropertyDescriptor is an IndexedPropertyDescriptor.


 Class Beans

Class java.beans.Beans

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.beans.Beans

public class Beans
extends Object

This class provides some general purpose beans control methods.


 Beans Members

Beans Members

Class Overview | This Package | All Packages

Constructors
Name | Description
Beans() |

Methods
Name | Description
getInstanceOf(Object, Class) | From a given bean, obtain an object representing a specified type view of that source object.
instantiate(ClassLoader, String) | Instantiate a bean.
isDesignTime() | Test if we are in design-mode.
isGuiAvailable() |
isInstanceOf(Object, Class) | Check if a bean can be viewed as a given target type.
setDesignTime(boolean) | Used to indicate whether of not we are running in an application builder environment.
setGuiAvailable(boolean) | Used to indicate whether of not we are running in an environment where GUI interaction is available.


 Beans.Beans

Beans.Beans

Class Overview | Class Members | This Package | All Packages

Syntax
public Beans()


 Beans.getInstanceOf

Beans.getInstanceOf

Class Overview | Class Members | This Package | All Packages

Syntax
public static Object getInstanceOf( Object bean, Class targetType )
Parameters
obj
Object from which we want to obtain a view.
targetType
The type of view we'd like to get.
Description
From a given bean, obtain an object representing a specified type view of that source object.

The result may be the same object or a different object. If the requested target view isn't available then the given bean is returned.

This method is provided in Beans 1.0 as a hook to allow the addition of more flexible bean behaviour in the future.


 Beans.instantiate

Beans.instantiate

Class Overview | Class Members | This Package | All Packages

Syntax
public static Object instantiate( ClassLoader cls, String beanName ) throws IOException, ClassNotFoundException
Parameters
classLoader
the class-loader from which we should create the bean. If this is null, then the system class-loader is used.
beanName
the name of the bean within the class-loader. For example "sun.beanbox.foobah"
Description
Instantiate a bean.

The bean is created based on a name relative to a class-loader. This name should be a dot-separated name such as "a.b.c".

In Beans 1.0 the given name can indicate either a serialized object or a class. Other mechanisms may be added in the future. In beans 1.0 we first try to treat the beanName as a serialized object name then as a class name.

When using the beanName as a serialized object name we convert the given beanName to a resource pathname and add a trailing ".ser" suffix. We then try to load a serialized object from that resource.

For example, given a beanName of "x.y", Beans.instantiate would first try to read a serialized object from the resource "x/y.ser" and if that failed it would try to load the class "x.y" and create an instance of that class.

If the bean is a subtype of java.applet.Applet, then it is given some special initialization. First, it is supplied with a default AppletStub and AppletContext. Second, if it was instantiated from a classname the applet's "init" method is called. (If the bean was deserialized this step is skipped.)

Note that for beans which are applets, it is the caller's responsiblity to call "start" on the applet. For correct behaviour, this should be done after the applet has been added into a visible AWT container.

Note that applets created via beans.instantiate run in a slightly different environment than applets running inside browsers. In particular, bean applets have no access to "parameters", so they may wish to provide property get/set methods to set parameter values. We advise bean-applet developers to test their bean-applets against both the JDK appletviewer (for a reference browser environment) and the BDK BeanBox (for a reference bean container).

Exceptions
ClassNotFoundException if the class of a serialized object could not be found.
Exceptions
IOException if an I/O error occurs.


 Beans.isDesignTime

Beans.isDesignTime

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isDesignTime()
Returns
True if we are running in an application construction environment.
Description
Test if we are in design-mode.


 Beans.isGuiAvailable

Beans.isGuiAvailable

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isGuiAvailable()
Returns
True if we are running in an environment where beans can assume that an interactive GUI is available, so they can pop up dialog boxes, etc. This will normally return true in a windowing environment, and will normally return false in a server environment or if an application is running as part of a batch job.


 Beans.isInstanceOf

Beans.isInstanceOf

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isInstanceOf( Object bean, Class targetType )
Parameters
bean
Bean from which we want to obtain a view.
targetType
The type of view we'd like to get.
Returns
"true" if the given bean supports the given targetType.
Description
Check if a bean can be viewed as a given target type. The result will be true if the Beans.getInstanceof method can be used on the given bean to obtain an object that represents the specified targetType type view.


 Beans.setDesignTime

Beans.setDesignTime

Class Overview | Class Members | This Package | All Packages

Syntax
public static void setDesignTime( boolean isDesignTime ) throws SecurityException
Parameters
isDesignTime
True if we're in an application builder tool.
Description
Used to indicate whether of not we are running in an application builder environment. Note that this method is security checked and is not available to (for example) untrusted applets.


 Beans.setGuiAvailable

Beans.setGuiAvailable

Class Overview | Class Members | This Package | All Packages

Syntax
public static void setGuiAvailable( boolean isGuiAvailable ) throws SecurityException
Parameters
isGuiAvailable
True if GUI interaction is available.
Description
Used to indicate whether of not we are running in an environment where GUI interaction is available. Note that this method is security checked and is not available to (for example) untrusted applets.


 Interface Customizer

Interface java.beans.Customizer

Interface Members | This Package | All Packages

public interface Customizer

A customizer class provides a complete custom GUI for customizing a target Java Bean.

Each customizer should inherit from the java.awt.Component class so it can be instantiated inside an AWT dialog or panel.

Each customizer should have a null constructor.


 Customizer Members

Customizer Members

Interface Overview | This Package | All Packages

Methods
Name | Description
addPropertyChangeListener(PropertyChangeListener) | Register a listener for the PropertyChange event.
removePropertyChangeListener(PropertyChangeListener) | Remove a listener for the PropertyChange event.
setObject(Object) | Set the object to be customized.


 Customizer.addPropertyChangeListener

Customizer.addPropertyChangeListener

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void addPropertyChangeListener( PropertyChangeListener listener )
Parameters
listener
An object to be invoked when a PropertyChange event is fired.
Description
Register a listener for the PropertyChange event. The customizer should fire a PropertyChange event whenever it changes the target bean in a way that might require the displayed properties to be refreshed.


 Customizer.removePropertyChangeListener

Customizer.removePropertyChangeListener

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void removePropertyChangeListener( PropertyChangeListener listener )
Parameters
listener
The PropertyChange listener to be removed.
Description
Remove a listener for the PropertyChange event.


 Customizer.setObject

Customizer.setObject

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setObject( Object bean )
Parameters
bean
The object to be customized.
Description
Set the object to be customized. This method should be called only once, before the Customizer has been added to any parent AWT container.


 Class EventSetDescriptor

Class java.beans.EventSetDescriptor

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.beans.FeatureDescriptor
           |
           +----java.beans.EventSetDescriptor

public class EventSetDescriptor
extends FeatureDescriptor

An EventSetDescriptor describes a group of events that a given Java bean fires.

The given group of events are all delivered as method calls on a single event listener interface, and an event listener object can be registered via a call on a registration method supplied by the event source.


 EventSetDescriptor Members

EventSetDescriptor Members

Class Overview | This Package | All Packages

Constructors
Name | Description
EventSetDescriptor(Class, String, Class, String) | This constructor creates an EventSetDescriptor assuming that you are following the most simple standard design pattern where a named event "fred" is (1) delivered as a call on the single method of interface FredListener, (2) has a single argument of type FredEvent, and (3) where the FredListener may be registered with a call on an addFredListener method of the source component and removed with a call on a removeFredListener method.
EventSetDescriptor(Class, String, Class, String[], String, String) | This constructor creates an EventSetDescriptor from scratch using string names.
EventSetDescriptor(String, Class, Method[], Method, Method) | This constructor creates an EventSetDescriptor from scratch using java.lang.reflect.Method and java.lang.Class objects.
EventSetDescriptor(String, Class, MethodDescriptor[], Method, Method) | This constructor creates an EventSetDescriptor from scratch using java.lang.reflect.MethodDescriptor and java.lang.Class objects.

Methods
Name | Description
getAddListenerMethod() |
getListenerMethodDescriptors() |
getListenerMethods() |
getListenerType() |
getRemoveListenerMethod() |
isInDefaultEventSet() | Report if an event set is in the "default set".
isUnicast() | Normally event sources are multicast.
setInDefaultEventSet(boolean) | Mark an event set as being in the "default" set (or not).
setUnicast(boolean) | Mark an event set as unicast (or not).


 EventSetDescriptor.EventSetDescriptor

EventSetDescriptor.EventSetDescriptor

Class Overview | Class Members | This Package | All Packages

Syntax 1
public EventSetDescriptor( Class sourceClass, String eventSetName, Class listenerType, String listenerMethodName ) throws IntrospectionException
Parameters
sourceClass
The class firing the event.
eventSetName
The programmatic name of the event. E.g. "fred". Note that this should normally start with a lower-case character.
listenerType
The target interface that events will get delivered to.
listenerMethodName
The method that will get called when the event gets delivered to its target listener interface.
Description
This constructor creates an EventSetDescriptor assuming that you are following the most simple standard design pattern where a named event "fred" is (1) delivered as a call on the single method of interface FredListener, (2) has a single argument of type FredEvent, and (3) where the FredListener may be registered with a call on an addFredListener method of the source component and removed with a call on a removeFredListener method.

Exceptions
IntrospectionException if an exception occurs during introspection.

Syntax 2
public EventSetDescriptor( Class sourceClass, String eventSetName, Class listenerType, String listenerMethodNames[], String addListenerMethodName, String removeListenerMethodName ) throws IntrospectionException
Parameters
sourceClass
The class firing the event.
eventSetName
The programmatic name of the event set. Note that this should normally start with a lower-case character.
listenerType
The Class of the target interface that events will get delivered to.
listenerMethodNames
The names of the methods that will get called when the event gets delivered to its target listener interface.
addListenerMethodName
The name of the method on the event source that can be used to register an event listener object.
removeListenerMethodName
The name of the method on the event source that can be used to de-register an event listener object.
Description
This constructor creates an EventSetDescriptor from scratch using string names.

Exceptions
IntrospectionException if an exception occurs during introspection.

Syntax 3
public EventSetDescriptor( String eventSetName, Class listenerType, Method listenerMethods[], Method addListenerMethod, Method removeListenerMethod ) throws IntrospectionException
Parameters
eventSetName
The programmatic name of the event set.
listenerType
The Class for the listener interface.
listenerMethods
An array of Method objects describing each of the event handling methods in the target listener.
addListenerMethod
The method on the event source that can be used to register an event listener object.
removeListenerMethod
The method on the event source that can be used to de-register an event listener object.
Description
This constructor creates an EventSetDescriptor from scratch using java.lang.reflect.Method and java.lang.Class objects.

Exceptions
IntrospectionException if an exception occurs during introspection.

Syntax 4
public EventSetDescriptor( String eventSetName, Class listenerType, MethodDescriptor listenerMethodDescriptors[], Method addListenerMethod, Method removeListenerMethod ) throws IntrospectionException
Parameters
eventSetName
The programmatic name of the event set.
listenerType
The Class for the listener interface.
listenerMethodDescriptors
An array of MethodDescriptor objects describing each of the event handling methods in the target listener.
addListenerMethod
The method on the event source that can be used to register an event listener object.
removeListenerMethod
The method on the event source that can be used to de-register an event listener object.
Description
This constructor creates an EventSetDescriptor from scratch using java.lang.reflect.MethodDescriptor and java.lang.Class objects.

Exceptions
IntrospectionException if an exception occurs during introspection.


 EventSetDescriptor.getAddListenerMethod

EventSetDescriptor.getAddListenerMethod

Class Overview | Class Members | This Package | All Packages

Syntax
public Method getAddListenerMethod()
Returns
The method used to register a listener at the event source.


 EventSetDescriptor.getListenerMethodDescriptors

EventSetDescriptor.getListenerMethodDescriptors

Class Overview | Class Members | This Package | All Packages

Syntax
public MethodDescriptor[] getListenerMethodDescriptors()
Returns
An array of MethodDescriptor objects for the target methods within the target listener interface that will get called when events are fired.


 EventSetDescriptor.getListenerMethods

EventSetDescriptor.getListenerMethods

Class Overview | Class Members | This Package | All Packages

Syntax
public Method[] getListenerMethods()
Returns
An array of Method objects for the target methods within the target listener interface that will get called when events are fired.


 EventSetDescriptor.getListenerType

EventSetDescriptor.getListenerType

Class Overview | Class Members | This Package | All Packages

Syntax
public Class getListenerType()
Returns
The Class object for the target interface that will get invoked when the event is fired.


 EventSetDescriptor.getRemoveListenerMethod

EventSetDescriptor.getRemoveListenerMethod

Class Overview | Class Members | This Package | All Packages

Syntax
public Method getRemoveListenerMethod()
Returns
The method used to register a listener at the event source.


 EventSetDescriptor.isInDefaultEventSet

EventSetDescriptor.isInDefaultEventSet

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isInDefaultEventSet()
Returns
True if the event set is in the "default set". Defaults to "true".
Description
Report if an event set is in the "default set".


 EventSetDescriptor.isUnicast

EventSetDescriptor.isUnicast

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isUnicast()
Returns
True if the event set is unicast. Defaults to "false".
Description
Normally event sources are multicast. However there are some exceptions that are strictly unicast.


 EventSetDescriptor.setInDefaultEventSet

EventSetDescriptor.setInDefaultEventSet

Class Overview | Class Members | This Package | All Packages

Syntax
public void setInDefaultEventSet( boolean inDefaultEventSet )
Parameters
unicast
True if the event set is unicast.
Description
Mark an event set as being in the "default" set (or not). By default this is true.


 EventSetDescriptor.setUnicast

EventSetDescriptor.setUnicast

Class Overview | Class Members | This Package | All Packages

Syntax
public void setUnicast( boolean unicast )
Parameters
unicast
True if the event set is unicast.
Description
Mark an event set as unicast (or not).


 Class FeatureDescriptor

Class java.beans.FeatureDescriptor

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.beans.FeatureDescriptor

public class FeatureDescriptor
extends Object

The FeatureDescriptor class is the common baseclass for PropertyDescriptor, EventSetDescriptor, and MethodDescriptor, etc.

It supports some common information that can be set and retrieved for any of the introspection descriptors.

In addition it provides an extension mechanism so that arbitrary attribute/value pairs can be associated with a design feature.


 FeatureDescriptor Members

FeatureDescriptor Members

Class Overview | This Package | All Packages

Constructors
Name | Description
FeatureDescriptor() |

Methods
Name | Description
attributeNames() |
getDisplayName() |
getName() |
getShortDescription() |
getValue(String) | Retrieve a named attribute with this feature.
isExpert() | The "expert" flag is used to distinguish between those features that are intended for expert users from those that are intended for normal users.
isHidden() | The "hidden" flag is used to identify features that are intended only for tool use, and which should not be exposed to humans.
setDisplayName(String) |
setExpert(boolean) | The "expert" flag is used to distinguish between features that are intended for expert users from those that are intended for normal users.
setHidden(boolean) | The "hidden" flag is used to identify features that are intended only for tool use, and which should not be exposed to humans.
setName(String) |
setShortDescription(String) | You can associate a short descriptive string with a feature.
setValue(String, Object) | Associate a named attribute with this feature.


 FeatureDescriptor.FeatureDescriptor

FeatureDescriptor.FeatureDescriptor

Class Overview | Class Members | This Package | All Packages

Syntax
public FeatureDescriptor()


 FeatureDescriptor.attributeNames

FeatureDescriptor.attributeNames

Class Overview | Class Members | This Package | All Packages

Syntax
public Enumeration attributeNames()
Returns
An enumeration of the locale-independent names of any attributes that have been registered with setValue.


 FeatureDescriptor.getDisplayName

FeatureDescriptor.getDisplayName

Class Overview | Class Members | This Package | All Packages

Syntax
public String getDisplayName()
Returns
The localized display name for the property/method/event. This defaults to the same as its programmatic name from getName.


 FeatureDescriptor.getName

FeatureDescriptor.getName

Class Overview | Class Members | This Package | All Packages

Syntax
public String getName()
Returns
The programmatic name of the property/method/event


 FeatureDescriptor.getShortDescription

FeatureDescriptor.getShortDescription

Class Overview | Class Members | This Package | All Packages

Syntax
public String getShortDescription()
Returns
A localized short description associated with this property/method/event. This defaults to be the display name.


 FeatureDescriptor.getValue

FeatureDescriptor.getValue

Class Overview | Class Members | This Package | All Packages

Syntax
public Object getValue( String attributeName )
Parameters
attributeName
The locale-independent name of the attribute
Returns
The value of the attribute. May be null if the attribute is unknown.
Description
Retrieve a named attribute with this feature.


 FeatureDescriptor.isExpert

FeatureDescriptor.isExpert

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isExpert()
Returns
True if this feature is intended for use by experts only.
Description
The "expert" flag is used to distinguish between those features that are intended for expert users from those that are intended for normal users.


 FeatureDescriptor.isHidden

FeatureDescriptor.isHidden

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isHidden()
Returns
True if this feature should be hidden from human users.
Description
The "hidden" flag is used to identify features that are intended only for tool use, and which should not be exposed to humans.


 FeatureDescriptor.setDisplayName

FeatureDescriptor.setDisplayName

Class Overview | Class Members | This Package | All Packages

Syntax
public void setDisplayName( String displayName )
Parameters
displayName
The localized display name for the property/method/event.


 FeatureDescriptor.setExpert

FeatureDescriptor.setExpert

Class Overview | Class Members | This Package | All Packages

Syntax
public void setExpert( boolean expert )
Parameters
expert
True if this feature is intended for use by experts only.
Description
The "expert" flag is used to distinguish between features that are intended for expert users from those that are intended for normal users.


 FeatureDescriptor.setHidden

FeatureDescriptor.setHidden

Class Overview | Class Members | This Package | All Packages

Syntax
public void setHidden( boolean hidden )
Parameters
hidden
True if this feature should be hidden from human users.
Description
The "hidden" flag is used to identify features that are intended only for tool use, and which should not be exposed to humans.


 FeatureDescriptor.setName

FeatureDescriptor.setName

Class Overview | Class Members | This Package | All Packages

Syntax
public void setName( String name )
Parameters
name
The programmatic name of the property/method/event


 FeatureDescriptor.setShortDescription

FeatureDescriptor.setShortDescription

Class Overview | Class Members | This Package | All Packages

Syntax
public void setShortDescription( String text )
Parameters
text
A (localized) short description to be associated with this property/method/event.
Description
You can associate a short descriptive string with a feature. Normally these descriptive strings should be less than about 40 characters.


 FeatureDescriptor.setValue

FeatureDescriptor.setValue

Class Overview | Class Members | This Package | All Packages

Syntax
public void setValue( String attributeName, Object value )
Parameters
attributeName
The locale-independent name of the attribute
value
The value.
Description
Associate a named attribute with this feature.


 Class IndexedPropertyDescriptor

Class java.beans.IndexedPropertyDescriptor

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.beans.FeatureDescriptor
           |
           +----java.beans.PropertyDescriptor
                   |
                   +----java.beans.IndexedPropertyDescriptor

public class IndexedPropertyDescriptor
extends PropertyDescriptor

An IndexedPropertyDescriptor describes a property that acts like an array and has an indexed read and/or indexed write method to access specific elements of the array.

An indexed property may also provide simple non-indexed read and write methods. If these are present, they read and write arrays of the type returned by the indexed read method.


 IndexedPropertyDescriptor Members

IndexedPropertyDescriptor Members

Class Overview | This Package | All Packages

Constructors
Name | Description
IndexedPropertyDescriptor(String, Class) | This constructor constructs an IndexedPropertyDescriptor for a property that follows the standard Java conventions by having getFoo and setFoo accessor methods, for both indexed access and array access.
IndexedPropertyDescriptor(String, Class, String, String, String, String) | This constructor takes the name of a simple property, and method names for reading and writing the property, both indexed and non-indexed.
IndexedPropertyDescriptor(String, Method, Method, Method, Method) | This constructor takes the name of a simple property, and Method objects for reading and writing the property.

Methods
Name | Description
getIndexedPropertyType() |
getIndexedReadMethod() |
getIndexedWriteMethod() |


 IndexedPropertyDescriptor.IndexedPropertyDescriptor

IndexedPropertyDescriptor.IndexedPropertyDescriptor

Class Overview | Class Members | This Package | All Packages

Syntax 1
public IndexedPropertyDescriptor( String propertyName, Class beanClass ) throws IntrospectionException
Parameters
propertyName
The programmatic name of the property.
beanClass
The Class object for the target bean.
Description
This constructor constructs an IndexedPropertyDescriptor for a property that follows the standard Java conventions by having getFoo and setFoo accessor methods, for both indexed access and array access.

Thus if the argument name is "fred", it will assume that there is an indexed reader method "getFred", a non-indexed (array) reader method also called "getFred", an indexed writer method "setFred", and finally a non-indexed writer method "setFred".

Exceptions
IntrospectionException if an exception occurs during introspection.

Syntax 2
public IndexedPropertyDescriptor( String propertyName, Class beanClass, String getterName, String setterName, String indexedGetterName, String indexedSetterName ) throws IntrospectionException
Parameters
propertyName
The programmatic name of the property.
beanClass
The Class object for the target bean.
getterName
The name of the method used for reading the property values as an array. May be null if the property is write-only or must be indexed.
setterName
The name of the method used for writing the property values as an array. May be null if the property is read-only or must be indexed.
indexedGetterName
The name of the method used for reading an indexed property value. May be null if the property is write-only.
indexedSetterName
The name of the method used for writing an indexed property value. May be null if the property is read-only.
Description
This constructor takes the name of a simple property, and method names for reading and writing the property, both indexed and non-indexed.

Exceptions
IntrospectionException if an exception occurs during introspection.

Syntax 3
public IndexedPropertyDescriptor( String propertyName, Method getter, Method setter, Method indexedGetter, Method indexedSetter ) throws IntrospectionException
Parameters
propertyName
The programmatic name of the property.
getter
The method used for reading the property values as an array. May be null if the property is write-only or must be indexed.
setter
The method used for writing the property values as an array. May be null if the property is read-only or must be indexed.
indexedGetter
The method used for reading an indexed property value. May be null if the property is write-only.
indexedSetter
The method used for writing an indexed property value. May be null if the property is read-only.
Description
This constructor takes the name of a simple property, and Method objects for reading and writing the property.

Exceptions
IntrospectionException if an exception occurs during introspection.


 IndexedPropertyDescriptor.getIndexedPropertyType

IndexedPropertyDescriptor.getIndexedPropertyType

Class Overview | Class Members | This Package | All Packages

Syntax
public Class getIndexedPropertyType()
Returns
The Java Class for the indexed properties type. Note that the Class may describe a primitive Java type such as "int".

This is the type that will be returned by the indexedReadMethod.


 IndexedPropertyDescriptor.getIndexedReadMethod

IndexedPropertyDescriptor.getIndexedReadMethod

Class Overview | Class Members | This Package | All Packages

Syntax
public Method getIndexedReadMethod()
Returns
The method that should be used to read an indexed property value. May return null if the property isn't indexed or is write-only.


 IndexedPropertyDescriptor.getIndexedWriteMethod

IndexedPropertyDescriptor.getIndexedWriteMethod

Class Overview | Class Members | This Package | All Packages

Syntax
public Method getIndexedWriteMethod()
Returns
The method that should be used to write an indexed property value. May return null if the property isn't indexed or is read-only.


 Class IntrospectionException

Class java.beans.IntrospectionException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.beans.IntrospectionException

public class IntrospectionException
extends Exception

Thrown when an exception happens during Introspection.

Typical causes include not being able to map a string class name to a Class object, not being able to resolve a string method name, or specifying a method name that has the wrong type signature for its intended use.


 IntrospectionException Members

IntrospectionException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
IntrospectionException(String) |


 IntrospectionException.IntrospectionException

IntrospectionException.IntrospectionException

Class Overview | Class Members | This Package | All Packages

Syntax
public IntrospectionException( String mess )
Parameters
mess
Descriptive message


 Class Introspector

Class java.beans.Introspector

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.beans.Introspector

public class Introspector
extends Object

The Introspector class provides a standard way for tools to learn about the properties, events, and methods supported by a target Java Bean.

For each of those three kinds of information, the Introspector will separately analyze the bean's class and superclasses looking for either explicit or implicit information and use that information to build a BeanInfo object that comprehensively describes the target bean.

For each class "Foo", explicit information may be available if there exists a corresponding "FooBeanInfo" class that provides a non-null value when queried for the information. We first look for the BeanInfo class by taking the full package-qualified name of the target bean class and appending "BeanInfo" to form a new class name. If this fails, then we take the final classname component of this name, and look for that class in each of the packages specified in the BeanInfo package search path.

Thus for a class such as "sun.xyz.OurButton" we would first look for a BeanInfo class called "sun.xyz.OurButtonBeanInfo" and if that failed we'd look in each package in the BeanInfo search path for an OurButtonBeanInfo class. With the default search path, this would mean looking for "sun.beans.infos.OurButtonBeanInfo".

If a class provides explicit BeanInfo about itself then we add that to the BeanInfo information we obtained from analyzing any derived classes, but we regard the explicit information as being definitive for the current class and its base classes, and do not proceed any further up the superclass chain.

If we don't find explicit BeanInfo on a class, we use low-level reflection to study the methods of the class and apply standard design patterns to identify property accessors, event sources, or public methods. We then proceed to analyze the class's superclass and add in the information from it (and possibly on up the superclass chain).


 Introspector Members

Introspector Members

Class Overview | This Package | All Packages

Methods
Name | Description
decapitalize(String) | Utility method to take a string and convert it to normal Java variable name capitalization.
getBeanInfo(Class) | Introspect on a Java bean and learn about all its properties, exposed methods, and events.
getBeanInfo(Class, Class) | Introspect on a Java bean and learn all about its properties, exposed methods, below a given "stop" point.
getBeanInfoSearchPath() |
setBeanInfoSearchPath(String[]) | Change the list of package names that will be used for finding BeanInfo classes.


 Introspector.decapitalize

Introspector.decapitalize

Class Overview | Class Members | This Package | All Packages

Syntax
public static String decapitalize( String name )
Parameters
name
The string to be decapitalized.
Returns
The decapitalized version of the string.
Description
Utility method to take a string and convert it to normal Java variable name capitalization. This normally means converting the first character from upper case to lower case, but in the (unusual) special case when there is more than one character and both the first and second characters are upper case, we leave it alone.

Thus "FooBah" becomes "fooBah" and "X" becomes "x", but "URL" stays as "URL".


 Introspector.getBeanInfo

Introspector.getBeanInfo

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static BeanInfo getBeanInfo( Class beanClass ) throws IntrospectionException
Parameters
beanClass
The bean class to be analyzed.
Returns
A BeanInfo object describing the target bean.
Description
Introspect on a Java bean and learn about all its properties, exposed methods, and events.

Exceptions
IntrospectionException if an exception occurs during introspection.

Syntax 2
public static BeanInfo getBeanInfo( Class beanClass, Class stopClass ) throws IntrospectionException
Parameters
bean
The bean class to be analyzed.
stopClass
The baseclass at which to stop the analysis. Any methods/properties/events in the stopClass or in its baseclasses will be ignored in the analysis.
Description
Introspect on a Java bean and learn all about its properties, exposed methods, below a given "stop" point.

Exceptions
IntrospectionException if an exception occurs during introspection.


 Introspector.getBeanInfoSearchPath

Introspector.getBeanInfoSearchPath

Class Overview | Class Members | This Package | All Packages

Syntax
public static String[] getBeanInfoSearchPath()
Returns
The array of package names that will be searched in order to find BeanInfo classes.

This is initially set to {"sun.beans.infos"}.


 Introspector.setBeanInfoSearchPath

Introspector.setBeanInfoSearchPath

Class Overview | Class Members | This Package | All Packages

Syntax
public static void setBeanInfoSearchPath( String path[] )
Parameters
path
Array of package names.
Description
Change the list of package names that will be used for finding BeanInfo classes.


 Class MethodDescriptor

Class java.beans.MethodDescriptor

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.beans.FeatureDescriptor
           |
           +----java.beans.MethodDescriptor

public class MethodDescriptor
extends FeatureDescriptor

A MethodDescriptor describes a particular method that a Java Bean supports for external access from other components.


 MethodDescriptor Members

MethodDescriptor Members

Class Overview | This Package | All Packages

Constructors
Name | Description
MethodDescriptor(Method) |
MethodDescriptor(Method, ParameterDescriptor[]) |

Methods
Name | Description
getMethod() |
getParameterDescriptors() |


 MethodDescriptor.MethodDescriptor

MethodDescriptor.MethodDescriptor

Class Overview | Class Members | This Package | All Packages

Syntax 1
public MethodDescriptor( Method method )
Parameters
method
The low-level method information.

Syntax 2
public MethodDescriptor( Method method, ParameterDescriptor parameterDescriptors[] )
Parameters
method
The low-level method information.
parameterDescriptors
Descriptive information for each of the method's parameters.


 MethodDescriptor.getMethod

MethodDescriptor.getMethod

Class Overview | Class Members | This Package | All Packages

Syntax
public Method getMethod()
Returns
The low-level description of the method


 MethodDescriptor.getParameterDescriptors

MethodDescriptor.getParameterDescriptors

Class Overview | Class Members | This Package | All Packages

Syntax
public ParameterDescriptor[] getParameterDescriptors()
Returns
The locale-independent names of the parameters. May return a null array if the parameter names aren't known.


 Class ParameterDescriptor

Class java.beans.ParameterDescriptor

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.beans.FeatureDescriptor
           |
           +----java.beans.ParameterDescriptor

public class ParameterDescriptor
extends FeatureDescriptor

The ParameterDescriptor class allows bean implementors to provide additional information on each of their parameters, beyond the low level type information provided by the java.lang.reflect.Method class.

Currently all our state comes from the FeatureDescriptor base class.


 ParameterDescriptor Members

ParameterDescriptor Members

Class Overview | This Package | All Packages

Constructors
Name | Description
ParameterDescriptor() |


 ParameterDescriptor.ParameterDescriptor

ParameterDescriptor.ParameterDescriptor

Class Overview | Class Members | This Package | All Packages

Syntax
public ParameterDescriptor()


 Class PropertyChangeEvent

Class java.beans.PropertyChangeEvent

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.EventObject
           |
           +----java.beans.PropertyChangeEvent

public class PropertyChangeEvent
extends EventObject

A "PropertyChange" event gets delivered whenever a bean changes a "bound" or "constrained" property. A PropertyChangeEvent object is sent as an argument to the PropertyChangeListener and VetoableChangeListener methods.

Normally PropertyChangeEvents are accompanied by the name and the old and new value of the changed property. If the new value is a builtin type (such as int or boolean) it must be wrapped as the corresponding java.lang.* Object type (such as Integer or Boolean).

Null values may be provided for the old and the new values if their true values are not known.

An event source may send a null object as the name to indicate that an arbitrary set of if its properties have changed. In this case the old and new values should also be null.


 PropertyChangeEvent Members

PropertyChangeEvent Members

Class Overview | This Package | All Packages

Constructors
Name | Description
PropertyChangeEvent(Object, String, Object, Object) |

Methods
Name | Description
getNewValue() |
getOldValue() |
getPropagationId() | The "propagationId" field is reserved for future use.
getPropertyName() |
setPropagationId(Object) |


 PropertyChangeEvent.PropertyChangeEvent

PropertyChangeEvent.PropertyChangeEvent

Class Overview | Class Members | This Package | All Packages

Syntax
public PropertyChangeEvent( Object source, String propertyName, Object oldValue, Object newValue )
Parameters
source
The bean that fired the event.
propertyName
The programmatic name of the property that was changed.
oldValue
The old value of the property.
newValue
The new value of the property.


 PropertyChangeEvent.getNewValue

PropertyChangeEvent.getNewValue

Class Overview | Class Members | This Package | All Packages

Syntax
public Object getNewValue()
Returns
The new value for the property, expressed as an Object. May be null if multiple properties have changed.


 PropertyChangeEvent.getOldValue

PropertyChangeEvent.getOldValue

Class Overview | Class Members | This Package | All Packages

Syntax
public Object getOldValue()
Returns
The old value for the property, expressed as an Object. May be null if multiple properties have changed.


 PropertyChangeEvent.getPropagationId

PropertyChangeEvent.getPropagationId

Class Overview | Class Members | This Package | All Packages

Syntax
public Object getPropagationId()
Returns
the propagationId object associated with a bound/constrained property update.
Description
The "propagationId" field is reserved for future use. In Beans 1.0 the sole requirement is that if a listener catches a PropertyChangeEvent and then fires a PropertyChangeEvent of its own, then it should make sure that it propagates the propagationId field from its incoming event to its outgoing event.


 PropertyChangeEvent.getPropertyName

PropertyChangeEvent.getPropertyName

Class Overview | Class Members | This Package | All Packages

Syntax
public String getPropertyName()
Returns
The programmatic name of the property that was changed. May be null if multiple properties have changed.


 PropertyChangeEvent.setPropagationId

PropertyChangeEvent.setPropagationId

Class Overview | Class Members | This Package | All Packages

Syntax
public void setPropagationId( Object propagationId )
Parameters
propagationId
The propagationId object for the event.


 Interface PropertyChangeListener

Interface java.beans.PropertyChangeListener

Interface Members | This Package | All Packages

public interface PropertyChangeListener
extends EventListener

A "PropertyChange" event gets fired whenever a bean changes a "bound" property. You can register a PropertyChangeListener with a source bean so as to be notified of any bound property updates.


 PropertyChangeListener Members

PropertyChangeListener Members

Interface Overview | This Package | All Packages

Methods
Name | Description
propertyChange(PropertyChangeEvent) | This method gets called when a bound property is changed.


 PropertyChangeListener.propertyChange

PropertyChangeListener.propertyChange

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void propertyChange( PropertyChangeEvent evt )
Parameters
evt
A PropertyChangeEvent object describing the event source and the property that has changed.
Description
This method gets called when a bound property is changed.


 Class PropertyChangeSupport

Class java.beans.PropertyChangeSupport

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.beans.PropertyChangeSupport

public class PropertyChangeSupport
extends Object
implements Serializable

This is a utility class that can be used by beans that support bound properties. You can use an instance of this class as a member field of your bean and delegate various work to it.


 PropertyChangeSupport Members

PropertyChangeSupport Members

Class Overview | This Package | All Packages

Constructors
Name | Description
PropertyChangeSupport(Object) |

Methods
Name | Description
addPropertyChangeListener(PropertyChangeListener) | Add a PropertyChangeListener to the listener list.
firePropertyChange(String, Object, Object) | Report a bound property update to any registered listeners.
removePropertyChangeListener(PropertyChangeListener) | Remove a PropertyChangeListener from the listener list.


 PropertyChangeSupport.PropertyChangeSupport

PropertyChangeSupport.PropertyChangeSupport

Class Overview | Class Members | This Package | All Packages

Syntax
public PropertyChangeSupport( Object sourceBean )


 PropertyChangeSupport.addPropertyChangeListener

PropertyChangeSupport.addPropertyChangeListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void addPropertyChangeListener( PropertyChangeListener listener )
Parameters
listener
The PropertyChangeListener to be added
Description
Add a PropertyChangeListener to the listener list.


 PropertyChangeSupport.firePropertyChange

PropertyChangeSupport.firePropertyChange

Class Overview | Class Members | This Package | All Packages

Syntax
public void firePropertyChange( String propertyName, Object oldValue, Object newValue )
Parameters
propertyName
The programmatic name of the property that was changed.
oldValue
The old value of the property.
newValue
The new value of the property.
Description
Report a bound property update to any registered listeners. No event is fired if old and new are equal and non-null.


 PropertyChangeSupport.removePropertyChangeListener

PropertyChangeSupport.removePropertyChangeListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void removePropertyChangeListener( PropertyChangeListener listener )
Parameters
listener
The PropertyChangeListener to be removed
Description
Remove a PropertyChangeListener from the listener list.


 Class PropertyDescriptor

Class java.beans.PropertyDescriptor

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.beans.FeatureDescriptor
           |
           +----java.beans.PropertyDescriptor

public class PropertyDescriptor
extends FeatureDescriptor

A PropertyDescriptor describes one property that a Java Bean exports via a pair of accessor methods.


 PropertyDescriptor Members

PropertyDescriptor Members

Class Overview | This Package | All Packages

Constructors
Name | Description
PropertyDescriptor(String, Class) | Constructs a PropertyDescriptor for a property that follows the standard Java convention by having getFoo and setFoo accessor methods.
PropertyDescriptor(String, Class, String, String) | This constructor takes the name of a simple property, and method names for reading and writing the property.
PropertyDescriptor(String, Method, Method) | This constructor takes the name of a simple property, and Method objects for reading and writing the property.

Methods
Name | Description
getPropertyEditorClass() |
getPropertyType() |
getReadMethod() |
getWriteMethod() |
isBound() | Updates to "bound" properties will cause a "PropertyChange" event to get fired when the property is changed.
isConstrained() | Attempted updates to "Constrained" properties will cause a "VetoableChange" event to get fired when the property is changed.
setBound(boolean) | Updates to "bound" properties will cause a "PropertyChange" event to get fired when the property is changed.
setConstrained(boolean) | Attempted updates to "Constrained" properties will cause a "VetoableChange" event to get fired when the property is changed.
setPropertyEditorClass(Class) | Normally PropertyEditors will be found using the PropertyEditorManager.


 PropertyDescriptor.PropertyDescriptor

PropertyDescriptor.PropertyDescriptor

Class Overview | Class Members | This Package | All Packages

Syntax 1
public PropertyDescriptor( String propertyName, Class beanClass ) throws IntrospectionException
Parameters
propertyName
The programmatic name of the property.
beanClass
The Class object for the target bean. For example sun.beans.OurButton.class.
Description
Constructs a PropertyDescriptor for a property that follows the standard Java convention by having getFoo and setFoo accessor methods. Thus if the argument name is "fred", it will assume that the reader method is "getFred" and the writer method is "setFred". Note that the property name should start with a lower case character, which will be capitalized in the method names.

Exceptions
IntrospectionException if an exception occurs during introspection.

Syntax 2
public PropertyDescriptor( String propertyName, Class beanClass, String getterName, String setterName ) throws IntrospectionException
Parameters
propertyName
The programmatic name of the property.
beanClass
The Class object for the target bean. For example sun.beans.OurButton.class.
getterName
The name of the method used for reading the property value. May be null if the property is write-only.
setterName
The name of the method used for writing the property value. May be null if the property is read-only.
Description
This constructor takes the name of a simple property, and method names for reading and writing the property.

Exceptions
IntrospectionException if an exception occurs during introspection.

Syntax 3
public PropertyDescriptor( String propertyName, Method getter, Method setter ) throws IntrospectionException
Parameters
propertyName
The programmatic name of the property.
getter
The method used for reading the property value. May be null if the property is write-only.
setter
The method used for writing the property value. May be null if the property is read-only.
Description
This constructor takes the name of a simple property, and Method objects for reading and writing the property.

Exceptions
IntrospectionException if an exception occurs during introspection.


 PropertyDescriptor.getPropertyEditorClass

PropertyDescriptor.getPropertyEditorClass

Class Overview | Class Members | This Package | All Packages

Syntax
public Class getPropertyEditorClass()
Returns
Any explicit PropertyEditor Class that has been registered for this property. Normally this will return "null", indicating that no special editor has been registered, so the PropertyEditorManager should be used to locate a suitable PropertyEditor.


 PropertyDescriptor.getPropertyType

PropertyDescriptor.getPropertyType

Class Overview | Class Members | This Package | All Packages

Syntax
public Class getPropertyType()
Returns
The Java type info for the property. Note that the "Class" object may describe a built-in Java type such as "int". The result may be "null" if this is an indexed property that does not support non-indexed access.

This is the type that will be returned by the ReadMethod.


 PropertyDescriptor.getReadMethod

PropertyDescriptor.getReadMethod

Class Overview | Class Members | This Package | All Packages

Syntax
public Method getReadMethod()
Returns
The method that should be used to read the property value. May return null if the property can't be read.


 PropertyDescriptor.getWriteMethod

PropertyDescriptor.getWriteMethod

Class Overview | Class Members | This Package | All Packages

Syntax
public Method getWriteMethod()
Returns
The method that should be used to write the property value. May return null if the property can't be written.


 PropertyDescriptor.isBound

PropertyDescriptor.isBound

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isBound()
Returns
True if this is a bound property.
Description
Updates to "bound" properties will cause a "PropertyChange" event to get fired when the property is changed.


 PropertyDescriptor.isConstrained

PropertyDescriptor.isConstrained

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isConstrained()
Returns
True if this is a constrained property.
Description
Attempted updates to "Constrained" properties will cause a "VetoableChange" event to get fired when the property is changed.


 PropertyDescriptor.setBound

PropertyDescriptor.setBound

Class Overview | Class Members | This Package | All Packages

Syntax
public void setBound( boolean bound )
Parameters
bound
True if this is a bound property.
Description
Updates to "bound" properties will cause a "PropertyChange" event to get fired when the property is changed.


 PropertyDescriptor.setConstrained

PropertyDescriptor.setConstrained

Class Overview | Class Members | This Package | All Packages

Syntax
public void setConstrained( boolean constrained )
Parameters
constrained
True if this is a constrained property.
Description
Attempted updates to "Constrained" properties will cause a "VetoableChange" event to get fired when the property is changed.


 PropertyDescriptor.setPropertyEditorClass

PropertyDescriptor.setPropertyEditorClass

Class Overview | Class Members | This Package | All Packages

Syntax
public void setPropertyEditorClass( Class propertyEditorClass )
Parameters
propertyEditorClass
The Class for the desired PropertyEditor.
Description
Normally PropertyEditors will be found using the PropertyEditorManager. However if for some reason you want to associate a particular PropertyEditor with a given property, then you can do it with this method.


 Interface PropertyEditor

Interface java.beans.PropertyEditor

Interface Members | This Package | All Packages

public interface PropertyEditor

A PropertyEditor class provides support for GUIs that want to allow users to edit a property value of a given type.

PropertyEditor supports a variety of different kinds of ways of displaying and updating property values. Most PropertyEditors will only need to support a subset of the different options available in this API.

Simple PropertyEditors may only support the getAsText and setAsText methods and need not support (say) paintValue or getCustomEditor. More complex types may be unable to support getAsText and setAsText but will instead support paintValue and getCustomEditor.

Every propertyEditor must support one or more of the three simple display styles. Thus it can either (1) support isPaintable or (2) both return a non-null String[] from getTags() and return a non-null value from getAsText or (3) simply return a non-null String from getAsText().

Every property editor must support a call on setValue when the argument object is of the type for which this is the corresponding propertyEditor. In addition, each property editor must either support a custom editor, or support setAsText.

Each PropertyEditor should have a null constructor.


 PropertyEditor Members

PropertyEditor Members

Interface Overview | This Package | All Packages

Methods
Name | Description
addPropertyChangeListener(PropertyChangeListener) | Register a listener for the PropertyChange event.
getAsText() |
getCustomEditor() | A PropertyEditor may choose to make available a full custom Component that edits its property value.
getJavaInitializationString() | This method is intended for use when generating Java code to set the value of the property.
getTags() | If the property value must be one of a set of known tagged values, then this method should return an array of the tags.
getValue() |
isPaintable() |
paintValue(Graphics, Rectangle) | Paint a representation of the value into a given area of screen real estate.
removePropertyChangeListener(PropertyChangeListener) | Remove a listener for the PropertyChange event.
setAsText(String) | Set the property value by parsing a given String.
setValue(Object) | Set (or change) the object that is to be edited.
supportsCustomEditor() |


 PropertyEditor.addPropertyChangeListener

PropertyEditor.addPropertyChangeListener

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void addPropertyChangeListener( PropertyChangeListener listener )
Parameters
listener
An object to be invoked when a PropertyChange event is fired.
Description
Register a listener for the PropertyChange event. When a PropertyEditor changes its value it should fire a PropertyChange event on all registered PropertyChangeListeners, specifying the null value for the property name and itself as the source.


 PropertyEditor.getAsText

PropertyEditor.getAsText

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getAsText()
Returns
The property value as a human editable string.

Returns null if the value can't be expressed as an editable string.

If a non-null value is returned, then the PropertyEditor should be prepared to parse that string back in setAsText().


 PropertyEditor.getCustomEditor

PropertyEditor.getCustomEditor

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Component getCustomEditor()
Returns
A java.awt.Component that will allow a human to directly edit the current property value. May be null if this is not supported.
Description
A PropertyEditor may choose to make available a full custom Component that edits its property value. It is the responsibility of the PropertyEditor to hook itself up to its editor Component itself and to report property value changes by firing a PropertyChange event.

The higher-level code that calls getCustomEditor may either embed the Component in some larger property sheet, or it may put it in its own individual dialog, or ...


 PropertyEditor.getJavaInitializationString

PropertyEditor.getJavaInitializationString

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getJavaInitializationString()
Returns
A fragment of Java code representing an initializer for the current value.
Description
This method is intended for use when generating Java code to set the value of the property. It should return a fragment of Java code that can be used to initialize a variable with the current property value.

Example results are "2", "new Color(127,127,34)", "Color.orange", etc.


 PropertyEditor.getTags

PropertyEditor.getTags

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String[] getTags()
Returns
The tag values for this property. May be null if this property cannot be represented as a tagged value.
Description
If the property value must be one of a set of known tagged values, then this method should return an array of the tags. This can be used to represent (for example) enum values. If a PropertyEditor supports tags, then it should support the use of setAsText with a tag value as a way of setting the value and the use of getAsText to identify the current value.


 PropertyEditor.getValue

PropertyEditor.getValue

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Object getValue()
Returns
The value of the property. Builtin types such as "int" will be wrapped as the corresponding object type such as "java.lang.Integer".


 PropertyEditor.isPaintable

PropertyEditor.isPaintable

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean isPaintable()
Returns
True if the class will honor the paintValue method.


 PropertyEditor.paintValue

PropertyEditor.paintValue

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void paintValue( Graphics gfx, Rectangle box )
Parameters
gfx
Graphics object to paint into.
box
Rectangle within graphics object into which we should paint.
Description
Paint a representation of the value into a given area of screen real estate. Note that the propertyEditor is responsible for doing its own clipping so that it fits into the given rectangle.

If the PropertyEditor doesn't honor paint requests (see isPaintable) this method should be a silent noop.

The given Graphics object will have the default font, color, etc of the parent container. The PropertyEditor may change graphics attributes such as font and color and doesn't need to restore the old values.


 PropertyEditor.removePropertyChangeListener

PropertyEditor.removePropertyChangeListener

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void removePropertyChangeListener( PropertyChangeListener listener )
Parameters
listener
The PropertyChange listener to be removed.
Description
Remove a listener for the PropertyChange event.


 PropertyEditor.setAsText

PropertyEditor.setAsText

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setAsText( String text ) throws IllegalArgumentException
Parameters
text
The string to be parsed.
Description
Set the property value by parsing a given String. May raise java.lang.IllegalArgumentException if either the String is badly formatted or if this kind of property can't be expressed as text.


 PropertyEditor.setValue

PropertyEditor.setValue

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setValue( Object value )
Parameters
value
The new target object to be edited. Note that this object should not be modified by the PropertyEditor, rather the PropertyEditor should create a new object to hold any modified value.
Description
Set (or change) the object that is to be edited. Builtin types such as "int" must be wrapped as the corresponding object type such as "java.lang.Integer".


 PropertyEditor.supportsCustomEditor

PropertyEditor.supportsCustomEditor

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsCustomEditor()
Returns
True if the propertyEditor can provide a custom editor.


 Class PropertyEditorManager

Class java.beans.PropertyEditorManager

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.beans.PropertyEditorManager

public class PropertyEditorManager
extends Object

The PropertyEditorManager can be used to locate a property editor for any given type name. This property editor must support the java.beans.PropertyEditor interface for editing a given object.

The PropertyEditorManager uses three techniques for locating an editor for a given type. First, it provides a registerEditor method to allow an editor to be specifically registered for a given type. Second it tries to locate a suitable class by adding "Editor" to the full qualified classname of the given type (e.g. "foo.bah.FozEditor"). Finally it takes the simple classname (without the package name) adds "Editor" to it and looks in a search-path of packages for a matching class.

So for an input class foo.bah.Fred, the PropertyEditorManager would first look in its tables to see if an editor had been registered for foo.bah.Fred and if so use that. Then it will look for a foo.bah.FredEditor class. Then it will look for (say) standardEditorsPackage.FredEditor class.

Default PropertyEditors will be provided for the Java builtin types "boolean", "byte", "short", "int", "long", "float", and "double"; and for the classes java.lang.String. java.awt.Color, and java.awt.Font.


 PropertyEditorManager Members

PropertyEditorManager Members

Class Overview | This Package | All Packages

Constructors
Name | Description
PropertyEditorManager() |

Methods
Name | Description
findEditor(Class) | Locate a value editor for a given target type.
getEditorSearchPath() |
registerEditor(Class, Class) | Register an editor class to be used to editor values of a given target class.
setEditorSearchPath(String[]) | Change the list of package names that will be used for finding property editors.


 PropertyEditorManager.PropertyEditorManager

PropertyEditorManager.PropertyEditorManager

Class Overview | Class Members | This Package | All Packages

Syntax
public PropertyEditorManager()


 PropertyEditorManager.findEditor

PropertyEditorManager.findEditor

Class Overview | Class Members | This Package | All Packages

Syntax
public static PropertyEditor findEditor( Class targetType )
Parameters
targetType
The Class object for the type to be edited
Returns
An editor object for the given target class. The result is null if no suitable editor can be found.
Description
Locate a value editor for a given target type.


 PropertyEditorManager.getEditorSearchPath

PropertyEditorManager.getEditorSearchPath

Class Overview | Class Members | This Package | All Packages

Syntax
public static String[] getEditorSearchPath()
Returns
The array of package names that will be searched in order to find property editors.

This is initially set to {"sun.beans.editors"}.


 PropertyEditorManager.registerEditor

PropertyEditorManager.registerEditor

Class Overview | Class Members | This Package | All Packages

Syntax
public static void registerEditor( Class targetType, Class editorClass )
Parameters
targetType
the Class object of the type to be edited
editorClass
the Class object of the editor class. If this is null, then any existing definition will be removed.
Description
Register an editor class to be used to editor values of a given target class.


 PropertyEditorManager.setEditorSearchPath

PropertyEditorManager.setEditorSearchPath

Class Overview | Class Members | This Package | All Packages

Syntax
public static void setEditorSearchPath( String path[] )
Parameters
path
Array of package names.
Description
Change the list of package names that will be used for finding property editors.


 Class PropertyEditorSupport

Class java.beans.PropertyEditorSupport

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.beans.PropertyEditorSupport

public class PropertyEditorSupport
extends Object
implements PropertyEditor


 PropertyEditorSupport Members

PropertyEditorSupport Members

Class Overview | This Package | All Packages

Constructors
Name | Description
PropertyEditorSupport() | Constructor for use by derived PropertyEditor classes.
PropertyEditorSupport(Object) | Constructor for use when a PropertyEditor is delegating to us.

Methods
Name | Description
addPropertyChangeListener(PropertyChangeListener) | Register a listener for the PropertyChange event.
firePropertyChange() | Report that we have been modified to any interested listeners.
getAsText() |
getCustomEditor() | A PropertyEditor may chose to make available a full custom Component that edits its property value.
getJavaInitializationString() | This method is intended for use when generating Java code to set the value of the property.
getTags() | If the property value must be one of a set of known tagged values, then this method should return an array of the tag values.
getValue() |
isPaintable() |
paintValue(Graphics, Rectangle) | Paint a representation of the value into a given area of screen real estate.
removePropertyChangeListener(PropertyChangeListener) | Remove a listener for the PropertyChange event.
setAsText(String) | Set the property value by parsing a given String.
setValue(Object) | Set (or change) the object that is to be edited.
supportsCustomEditor() |


 PropertyEditorSupport.PropertyEditorSupport

PropertyEditorSupport.PropertyEditorSupport

Class Overview | Class Members | This Package | All Packages

Syntax 1
protected PropertyEditorSupport()
Description
Constructor for use by derived PropertyEditor classes.

Syntax 2
protected PropertyEditorSupport( Object source )
Parameters
source
The source to use for any events we fire.
Description
Constructor for use when a PropertyEditor is delegating to us.


 PropertyEditorSupport.addPropertyChangeListener

PropertyEditorSupport.addPropertyChangeListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void addPropertyChangeListener( PropertyChangeListener listener )
Parameters
listener
An object to be invoked when a PropertyChange event is fired.
Description
Register a listener for the PropertyChange event. The class will fire a PropertyChange value whenever the value is updated.


 PropertyEditorSupport.firePropertyChange

PropertyEditorSupport.firePropertyChange

Class Overview | Class Members | This Package | All Packages

Syntax
public void firePropertyChange()
Parameters
source
The PropertyEditor that caused the event.
Description
Report that we have been modified to any interested listeners.


 PropertyEditorSupport.getAsText

PropertyEditorSupport.getAsText

Class Overview | Class Members | This Package | All Packages

Syntax
public String getAsText()
Returns
The property value as a string suitable for presentation to a human to edit.

Returns "null" is the value can't be expressed as a string.

If a non-null value is returned, then the PropertyEditor should be prepared to parse that string back in setAsText().


 PropertyEditorSupport.getCustomEditor

PropertyEditorSupport.getCustomEditor

Class Overview | Class Members | This Package | All Packages

Syntax
public Component getCustomEditor()
Returns
A java.awt.Component that will allow a human to directly edit the current property value. May be null if this is not supported.
Description
A PropertyEditor may chose to make available a full custom Component that edits its property value. It is the responsibility of the PropertyEditor to hook itself up to its editor Component itself and to report property value changes by firing a PropertyChange event.

The higher-level code that calls getCustomEditor may either embed the Component in some larger property sheet, or it may put it in its own individual dialog, or ...


 PropertyEditorSupport.getJavaInitializationString

PropertyEditorSupport.getJavaInitializationString

Class Overview | Class Members | This Package | All Packages

Syntax
public String getJavaInitializationString()
Returns
A fragment of Java code representing an initializer for the current value.
Description
This method is intended for use when generating Java code to set the value of the property. It should return a fragment of Java code that can be used to initialize a variable with the current property value.

Example results are "2", "new Color(127,127,34)", "Color.orange", etc.


 PropertyEditorSupport.getTags

PropertyEditorSupport.getTags

Class Overview | Class Members | This Package | All Packages

Syntax
public String[] getTags()
Returns
The tag values for this property. May be null if this property cannot be represented as a tagged value.
Description
If the property value must be one of a set of known tagged values, then this method should return an array of the tag values. This can be used to represent (for example) enum values. If a PropertyEditor supports tags, then it should support the use of setAsText with a tag value as a way of setting the value.


 PropertyEditorSupport.getValue

PropertyEditorSupport.getValue

Class Overview | Class Members | This Package | All Packages

Syntax
public Object getValue()
Returns
The value of the property.


 PropertyEditorSupport.isPaintable

PropertyEditorSupport.isPaintable

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isPaintable()
Returns
True if the class will honor the paintValue method.


 PropertyEditorSupport.paintValue

PropertyEditorSupport.paintValue

Class Overview | Class Members | This Package | All Packages

Syntax
public void paintValue( Graphics gfx, Rectangle box )
Parameters
gfx
Graphics object to paint into.
box
Rectangle within graphics object into which we should paint.
Description
Paint a representation of the value into a given area of screen real estate. Note that the propertyEditor is responsible for doing its own clipping so that it fits into the given rectangle.

If the PropertyEditor doesn't honor paint requests (see isPaintable) this method should be a silent noop.


 PropertyEditorSupport.removePropertyChangeListener

PropertyEditorSupport.removePropertyChangeListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void removePropertyChangeListener( PropertyChangeListener listener )
Parameters
listener
The PropertyChange listener to be removed.
Description
Remove a listener for the PropertyChange event.


 PropertyEditorSupport.setAsText

PropertyEditorSupport.setAsText

Class Overview | Class Members | This Package | All Packages

Syntax
public void setAsText( String text ) throws IllegalArgumentException
Parameters
text
The string to be parsed.
Description
Set the property value by parsing a given String. May raise java.lang.IllegalArgumentException if either the String is badly formatted or if this kind of property can't be expressed as text.


 PropertyEditorSupport.setValue

PropertyEditorSupport.setValue

Class Overview | Class Members | This Package | All Packages

Syntax
public void setValue( Object value )
Parameters
value
The new target object to be edited. Note that this object should not be modified by the PropertyEditor, rather the PropertyEditor should create a new object to hold any modified value.
Description
Set (or change) the object that is to be edited.


 PropertyEditorSupport.supportsCustomEditor

PropertyEditorSupport.supportsCustomEditor

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean supportsCustomEditor()
Returns
True if the propertyEditor can provide a custom editor.


 Class PropertyVetoException

Class java.beans.PropertyVetoException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.beans.PropertyVetoException

public class PropertyVetoException
extends Exception

A PropertyVetoException is thrown when a proposed change to a property represents an unacceptable value.


 PropertyVetoException Members

PropertyVetoException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
PropertyVetoException(String, PropertyChangeEvent) |

Methods
Name | Description
getPropertyChangeEvent() |


 PropertyVetoException.PropertyVetoException

PropertyVetoException.PropertyVetoException

Class Overview | Class Members | This Package | All Packages

Syntax
public PropertyVetoException( String mess, PropertyChangeEvent evt )
Parameters
mess
Descriptive message
evt
A PropertyChangeEvent describing the vetoed change.


 PropertyVetoException.getPropertyChangeEvent

PropertyVetoException.getPropertyChangeEvent

Class Overview | Class Members | This Package | All Packages

Syntax
public PropertyChangeEvent getPropertyChangeEvent()


 Class SimpleBeanInfo

Class java.beans.SimpleBeanInfo

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.beans.SimpleBeanInfo

public class SimpleBeanInfo
extends Object
implements BeanInfo

This is a support class to make it easier for people to provide BeanInfo classes.

It defaults to providing "noop" information, and can be selectively overriden to provide more explicit information on chosen topics. When the introspector sees the "noop" values, it will apply low level introspection and design patterns to automatically analyze the target bean.


 SimpleBeanInfo Members

SimpleBeanInfo Members

Class Overview | This Package | All Packages

Constructors
Name | Description
SimpleBeanInfo() |

Methods
Name | Description
getAdditionalBeanInfo() | Claim there are no other relevant BeanInfo objects.
getBeanDescriptor() | Deny knowledge about the class and customizer of the bean.
getDefaultEventIndex() | Deny knowledge of a default event.
getDefaultPropertyIndex() | Deny knowledge of a default property.
getEventSetDescriptors() | Deny knowledge of event sets.
getIcon(int) | Claim there are no icons available.
getMethodDescriptors() | Deny knowledge of methods.
getPropertyDescriptors() | Deny knowledge of properties.
loadImage(String) | This is a utility method to help in loading icon images.


 SimpleBeanInfo.SimpleBeanInfo

SimpleBeanInfo.SimpleBeanInfo

Class Overview | Class Members | This Package | All Packages

Syntax
public SimpleBeanInfo()


 SimpleBeanInfo.getAdditionalBeanInfo

SimpleBeanInfo.getAdditionalBeanInfo

Class Overview | Class Members | This Package | All Packages

Syntax
public BeanInfo[] getAdditionalBeanInfo()
Description
Claim there are no other relevant BeanInfo objects. You may override this if you want to (for example) return a BeanInfo for a base class.


 SimpleBeanInfo.getBeanDescriptor

SimpleBeanInfo.getBeanDescriptor

Class Overview | Class Members | This Package | All Packages

Syntax
public BeanDescriptor getBeanDescriptor()
Description
Deny knowledge about the class and customizer of the bean. You can override this if you wish to provide explicit info.


 SimpleBeanInfo.getDefaultEventIndex

SimpleBeanInfo.getDefaultEventIndex

Class Overview | Class Members | This Package | All Packages

Syntax
public int getDefaultEventIndex()
Description
Deny knowledge of a default event. You can override this if you wish to define a default event for the bean.


 SimpleBeanInfo.getDefaultPropertyIndex

SimpleBeanInfo.getDefaultPropertyIndex

Class Overview | Class Members | This Package | All Packages

Syntax
public int getDefaultPropertyIndex()
Description
Deny knowledge of a default property. You can override this if you wish to define a default property for the bean.


 SimpleBeanInfo.getEventSetDescriptors

SimpleBeanInfo.getEventSetDescriptors

Class Overview | Class Members | This Package | All Packages

Syntax
public EventSetDescriptor[] getEventSetDescriptors()
Description
Deny knowledge of event sets. You can override this if you wish to provide explicit event set info.


 SimpleBeanInfo.getIcon

SimpleBeanInfo.getIcon

Class Overview | Class Members | This Package | All Packages

Syntax
public Image getIcon( int iconKind )
Description
Claim there are no icons available. You can override this if you want to provide icons for your bean.


 SimpleBeanInfo.getMethodDescriptors

SimpleBeanInfo.getMethodDescriptors

Class Overview | Class Members | This Package | All Packages

Syntax
public MethodDescriptor[] getMethodDescriptors()
Description
Deny knowledge of methods. You can override this if you wish to provide explicit method info.


 SimpleBeanInfo.getPropertyDescriptors

SimpleBeanInfo.getPropertyDescriptors

Class Overview | Class Members | This Package | All Packages

Syntax
public PropertyDescriptor[] getPropertyDescriptors()
Description
Deny knowledge of properties. You can override this if you wish to provide explicit property info.


 SimpleBeanInfo.loadImage

SimpleBeanInfo.loadImage

Class Overview | Class Members | This Package | All Packages

Syntax
public Image loadImage( String resourceName )
Parameters
resourceName
A pathname relative to the directory holding the class file of the current class. For example, "wombat.gif".
Returns
an image object. May be null if the load failed.
Description
This is a utility method to help in loading icon images. It takes the name of a resource file associated with the current object's class file and loads an image object from that file. Typically images will be GIFs.


 Interface VetoableChangeListener

Interface java.beans.VetoableChangeListener

Interface Members | This Package | All Packages

public interface VetoableChangeListener
extends EventListener

A VetoableChange event gets fired whenever a bean changes a "constrained" property. You can register a VetoableChangeListener with a source bean so as to be notified of any constrained property updates.


 VetoableChangeListener Members

VetoableChangeListener Members

Interface Overview | This Package | All Packages

Methods
Name | Description
vetoableChange(PropertyChangeEvent) | This method gets called when a constrained property is changed.


 VetoableChangeListener.vetoableChange

VetoableChangeListener.vetoableChange

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void vetoableChange( PropertyChangeEvent evt ) throws PropertyVetoException
Parameters
evt
a PropertyChangeEvent object describing the event source and the property that has changed.
Description
This method gets called when a constrained property is changed.

Exceptions
PropertyVetoException if the recipient wishes the property change to be rolled back.


 Class VetoableChangeSupport

Class java.beans.VetoableChangeSupport

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.beans.VetoableChangeSupport

public class VetoableChangeSupport
extends Object
implements Serializable

This is a utility class that can be used by beans that support constrained properties. You can use an instance of this class as a member field of your bean and delegate various work to it.


 VetoableChangeSupport Members

VetoableChangeSupport Members

Class Overview | This Package | All Packages

Constructors
Name | Description
VetoableChangeSupport(Object) |

Methods
Name | Description
addVetoableChangeListener(VetoableChangeListener) | Add a VetoableListener to the listener list.
fireVetoableChange(String, Object, Object) | Report a vetoable property update to any registered listeners.
removeVetoableChangeListener(VetoableChangeListener) | Remove a VetoableChangeListener from the listener list.


 VetoableChangeSupport.VetoableChangeSupport

VetoableChangeSupport.VetoableChangeSupport

Class Overview | Class Members | This Package | All Packages

Syntax
public VetoableChangeSupport( Object sourceBean )


 VetoableChangeSupport.addVetoableChangeListener

VetoableChangeSupport.addVetoableChangeListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void addVetoableChangeListener( VetoableChangeListener listener )
Parameters
listener
The VetoableChangeListener to be added
Description
Add a VetoableListener to the listener list.


 VetoableChangeSupport.fireVetoableChange

VetoableChangeSupport.fireVetoableChange

Class Overview | Class Members | This Package | All Packages

Syntax
public void fireVetoableChange( String propertyName, Object oldValue, Object newValue ) throws PropertyVetoException
Parameters
propertyName
The programmatic name of the property that was changed.
oldValue
The old value of the property.
newValue
The new value of the property.
Description
Report a vetoable property update to any registered listeners. If anyone vetos the change, then fire a new event reverting everyone to the old value and then rethrow the PropertyVetoException.

No event is fired if old and new are equal and non-null.

Exceptions
PropertyVetoException if the recipient wishes the property change to be rolled back.


 VetoableChangeSupport.removeVetoableChangeListener

VetoableChangeSupport.removeVetoableChangeListener

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void removeVetoableChangeListener( VetoableChangeListener listener )
Parameters
listener
The VetoableChangeListener to be removed
Description
Remove a VetoableChangeListener from the listener list.


 Interface Visibility

Interface java.beans.Visibility

Interface Members | This Package | All Packages

public interface Visibility

Under some circumstances a bean may be run on servers where a GUI is not available. This interface can be used to query a bean to determine whether it absolutely needs a gui, and to advise the bean whether a GUI is available.

This interface is for expert developers, and is not needed for normal simple beans. To avoid confusing end-users we avoid using getXXX setXXX design patterns for these methods.


 Visibility Members

Visibility Members

Interface Overview | This Package | All Packages

Methods
Name | Description
avoidingGui() |
dontUseGui() | This method instructs the bean that it should not use the Gui.
needsGui() |
okToUseGui() | This method instructs the bean that it is OK to use the Gui.


 Visibility.avoidingGui

Visibility.avoidingGui

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean avoidingGui()
Returns
true if the bean is currently avoiding use of the Gui. e.g. due to a call on dontUseGui().


 Visibility.dontUseGui

Visibility.dontUseGui

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void dontUseGui()
Description
This method instructs the bean that it should not use the Gui.


 Visibility.needsGui

Visibility.needsGui

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean needsGui()
Returns
True if the bean absolutely needs a GUI available in order to get its work done.


 Visibility.okToUseGui

Visibility.okToUseGui

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void okToUseGui()
Description
This method instructs the bean that it is OK to use the Gui.


 Package java.io

Package java.io

All Packages

Interfaces

  • DataInput
  • DataOutput
  • Externalizable
  • FilenameFilter
  • ObjectInput
  • ObjectInputValidation
  • ObjectOutput
  • Serializable

    • Classes

  • BufferedInputStream
  • BufferedOutputStream
  • BufferedReader
  • BufferedWriter
  • ByteArrayInputStream
  • ByteArrayOutputStream
  • CharArrayReader
  • CharArrayWriter
  • DataInputStream
  • DataOutputStream
  • File
  • FileDescriptor
  • FileInputStream
  • FileOutputStream
  • FileReader
  • FileWriter
  • FilterInputStream
  • FilterOutputStream
  • FilterReader
  • FilterWriter
  • InputStream
  • InputStreamReader
  • LineNumberInputStream
  • LineNumberReader
  • ObjectInputStream
  • ObjectOutputStream
  • ObjectStreamClass
  • OutputStream
  • OutputStreamWriter
  • PipedInputStream
  • PipedOutputStream
  • PipedReader
  • PipedWriter
  • PrintStream
  • PrintWriter
  • PushbackInputStream
  • PushbackReader
  • RandomAccessFile
  • Reader
  • SequenceInputStream
  • StreamTokenizer
  • StringBufferInputStream
  • StringReader
  • StringWriter
  • Writer

    • Exceptions

  • CharConversionException
  • EOFException
  • FileNotFoundException
  • IOException
  • InterruptedIOException
  • InvalidClassException
  • InvalidObjectException
  • NotActiveException
  • NotSerializableException
  • ObjectStreamException
  • OptionalDataException
  • StreamCorruptedException
  • SyncFailedException
  • UTFDataFormatException
  • UnsupportedEncodingException
  • WriteAbortedException


 Class BufferedInputStream

Class java.io.BufferedInputStream

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.InputStream
           |
           +----java.io.FilterInputStream
                   |
                   +----java.io.BufferedInputStream

public class BufferedInputStream
extends FilterInputStream

The class implements a buffered input stream. By setting up such an input stream, an application can read bytes from a stream without necessarily causing a call to the underlying system for each byte read. The data is read by blocks into a buffer; subsequent reads can access the data directly from the buffer.


 BufferedInputStream Members

BufferedInputStream Members

Class Overview | This Package | All Packages

Fields
Name | Description
buf | The buffer where data is stored.
count | The index one greater than the index of the last valid byte in the buffer.
marklimit | The maximum read ahead allowed after a call to the mark method before subsequent calls to the reset method fail.
markpos | The value of the pos field at the time the last mark method was called.
pos | The current position in the buffer.

Constructors
Name | Description
BufferedInputStream(InputStream) | Creates a new buffered input stream to read data from the specified input stream with a default 512-byte buffer size.
BufferedInputStream(InputStream, int) | Creates a new buffered input stream to read data from the specified input stream with the specified buffer size.

Methods
Name | Description
available() | Returns the number of bytes that can be read from this input stream without blocking.
mark(int) | Marks the current position in this input stream.
markSupported() | Tests if this input stream supports the mark and reset methods.
read() | Reads the next byte of data from this buffered input stream.
read(byte[], int, int) | Reads bytes into a portion of an array.
reset() | Repositions this stream to the position at the time the mark method was last called on this input stream.
skip(long) | Skips over and discards n bytes of data from the input stream.


 BufferedInputStream.buf

BufferedInputStream.buf

Class Overview | Class Members | This Package | All Packages

Syntax
protected byte buf[]
Description
The buffer where data is stored.


 BufferedInputStream.count

BufferedInputStream.count

Class Overview | Class Members | This Package | All Packages

Syntax
protected int count
Description
The index one greater than the index of the last valid byte in the buffer.


 BufferedInputStream.marklimit

BufferedInputStream.marklimit

Class Overview | Class Members | This Package | All Packages

Syntax
protected int marklimit
Description
The maximum read ahead allowed after a call to the mark method before subsequent calls to the reset method fail.

See Also
mark, reset


 BufferedInputStream.markpos

BufferedInputStream.markpos

Class Overview | Class Members | This Package | All Packages

Syntax
protected int markpos
Description
The value of the pos field at the time the last mark method was called. The value of this field is -1 if there is no current mark.

See Also
mark, pos


 BufferedInputStream.pos

BufferedInputStream.pos

Class Overview | Class Members | This Package | All Packages

Syntax
protected int pos
Description
The current position in the buffer. This is the index of the next character to be read from the buf array.

See Also
buf


 BufferedInputStream.BufferedInputStream

BufferedInputStream.BufferedInputStream

Class Overview | Class Members | This Package | All Packages

Syntax 1
public BufferedInputStream( InputStream in )
Parameters
in
the underlying input stream.
Description
Creates a new buffered input stream to read data from the specified input stream with a default 512-byte buffer size.

Syntax 2
public BufferedInputStream( InputStream in, int size )
Parameters
in
the underlying input stream.
size
the buffer size.
Description
Creates a new buffered input stream to read data from the specified input stream with the specified buffer size.


 BufferedInputStream.available

BufferedInputStream.available

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized int available() throws IOException
Returns
the number of bytes that can be read from this input stream without blocking.
Description
Returns the number of bytes that can be read from this input stream without blocking.

The available method of BufferedInputStream returns the sum of the the number of bytes remaining to be read in the buffer (count - pos) and the result of calling the available method of the underlying input stream.

Exceptions
IOException if an I/O error occurs.
Overrides
available in class FilterInputStream
See Also
in


 BufferedInputStream.mark

BufferedInputStream.mark

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void mark( int readlimit )
Parameters
readlimit
the maximum limit of bytes that can be read before the mark position becomes invalid.
Description
Marks the current position in this input stream. A subsequent call to the reset method repositions the stream at the last marked position so that subsequent reads re-read the same bytes.

The readlimit argument tells the input stream to allow that many bytes to be read before the mark position gets invalidated.

Overrides
mark in class FilterInputStream
See Also
reset


 BufferedInputStream.markSupported

BufferedInputStream.markSupported

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean markSupported()
Returns
a boolean indicating if this stream type supports the mark and reset methods.
Description
Tests if this input stream supports the mark and reset methods. The markSupported method of BufferedInputStream returns true.

Overrides
markSupported in class FilterInputStream
See Also
mark, reset


 BufferedInputStream.read

BufferedInputStream.read

Class Overview | Class Members | This Package | All Packages

Syntax 1
public synchronized int read() throws IOException
Returns
the next byte of data, or -1 if the end of the stream is reached.
Description
Reads the next byte of data from this buffered input stream. The value byte is returned as an int in the range 0 to 255. If no byte is available because the end of the stream has been reached, the value -1 is returned. This method blocks until input data is available, the end of the stream is detected, or an exception is thrown.

The read method of BufferedInputStream returns the next byte of data from its buffer if the buffer is not empty. Otherwise, it refills the buffer from the underlying input stream and returns the next character, if the underlying stream has not returned an end-of-stream indicator.

Exceptions
IOException if an I/O error occurs.
Overrides
read in class FilterInputStream
See Also
in

Syntax 2
public synchronized int read( byte b[], int off, int len ) throws IOException
Parameters
b
destination buffer.
off
offset at which to start storing bytes.
len
maximum number of bytes to read.
Returns
the number of bytes read, or -1 if the end of the stream has been reached.
Description
Reads bytes into a portion of an array. This method will block until some input is available, an I/O error occurs, or the end of the stream is reached.

If this stream's buffer is not empty, bytes are copied from it into the array argument. Otherwise, the buffer is refilled from the underlying input stream and, unless the stream returns an end-of-stream indication, the array argument is filled with characters from the newly-filled buffer.

As an optimization, if the buffer is empty, the mark is not valid, and len is at least as large as the buffer, then this method will read directly from the underlying stream into the given array. Thus redundant BufferedInputStreams will not copy data unnecessarily.

Exceptions
IOException if an I/O error occurs.
Overrides
read in class FilterInputStream


 BufferedInputStream.reset

BufferedInputStream.reset

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void reset() throws IOException
Description
Repositions this stream to the position at the time the mark method was last called on this input stream.

If the stream has not been marked, or if the mark has been invalidated, an IOException is thrown. Stream marks are intended to be used in situations where you need to read ahead a little to see what's in the stream. Often this is most easily done by invoking some general parser. If the stream is of the type handled by the parser, it just chugs along happily. If the stream is not of that type, the parser should toss an exception when it fails. If an exception gets tossed within readlimit bytes, the parser will allow the outer code to reset the stream and to try another parser.

Exceptions
IOException if this stream has not been marked or if the mark has been invalidated.
Overrides
reset in class FilterInputStream
See Also
mark


 BufferedInputStream.skip

BufferedInputStream.skip

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized long skip( long n ) throws IOException
Parameters
n
the number of bytes to be skipped.
Returns
the actual number of bytes skipped.
Description
Skips over and discards n bytes of data from the input stream. The skip method may, for a variety of reasons, end up skipping over some smaller number of bytes, possibly zero. The actual number of bytes skipped is returned.

The skip method of BufferedInputStream compares the number of bytes it has available in its buffer, k, where k = count - pos, with n. If n ≤ k, then the pos field is incremented by n. Otherwise, the pos field is incremented to have the value count, and the remaining bytes are skipped by calling the skip method on the underlying input stream, supplying the argument n - k.

Exceptions
IOException if an I/O error occurs.
Overrides
skip in class FilterInputStream


 Class BufferedOutputStream

Class java.io.BufferedOutputStream

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.OutputStream
           |
           +----java.io.FilterOutputStream
                   |
                   +----java.io.BufferedOutputStream

public class BufferedOutputStream
extends FilterOutputStream

The class implements a buffered output stream. By setting up such an output stream, an application can write bytes to the underlying output stream without necessarily causing a call to the underlying system for each byte written. The data is written into a buffer, and then written to the underlying stream if the buffer reaches its capacity, the buffer output stream is closed, or the buffer output stream is explicity flushed.


 BufferedOutputStream Members

BufferedOutputStream Members

Class Overview | This Package | All Packages

Fields
Name | Description
buf | The buffer where data is stored.
count | The number of valid bytes in the buffer.

Constructors
Name | Description
BufferedOutputStream(OutputStream) | Creates a new buffered output stream to write data to the specified underlying output stream with a default 512-byte buffer size.
BufferedOutputStream(OutputStream, int) | Creates a new buffered output stream to write data to the specified underlying output stream with the specified buffer size.

Methods
Name | Description
flush() | Flushes this buffered output stream.
write(byte[], int, int) | Writes len bytes from the specified byte array starting at offset off to this buffered output stream.
write(int) | Writes the specified byte to this buffered output stream.


 BufferedOutputStream.buf

BufferedOutputStream.buf

Class Overview | Class Members | This Package | All Packages

Syntax
protected byte buf[]
Description
The buffer where data is stored.


 BufferedOutputStream.count

BufferedOutputStream.count

Class Overview | Class Members | This Package | All Packages

Syntax
protected int count
Description
The number of valid bytes in the buffer.


 BufferedOutputStream.BufferedOutputStream

BufferedOutputStream.BufferedOutputStream

Class Overview | Class Members | This Package | All Packages

Syntax 1
public BufferedOutputStream( OutputStream out )
Parameters
out
the underlying output stream.
Description
Creates a new buffered output stream to write data to the specified underlying output stream with a default 512-byte buffer size.

Syntax 2
public BufferedOutputStream( OutputStream out, int size )
Parameters
out
the underlying output stream.
size
the buffer size.
Description
Creates a new buffered output stream to write data to the specified underlying output stream with the specified buffer size.


 BufferedOutputStream.flush

BufferedOutputStream.flush

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void flush() throws IOException
Description
Flushes this buffered output stream. This forces any buffered output bytes to be written out to the underlying output stream.

Exceptions
IOException if an I/O error occurs.
Overrides
flush in class FilterOutputStream
See Also
out


 BufferedOutputStream.write

BufferedOutputStream.write

Class Overview | Class Members | This Package | All Packages

Syntax 1
public synchronized void write( int b ) throws IOException
Parameters
b
the byte to be written.
Description
Writes the specified byte to this buffered output stream.

Exceptions
IOException if an I/O error occurs.
Overrides
write in class FilterOutputStream

Syntax 2
public synchronized void write( byte b[], int off, int len ) throws IOException
Parameters
b
the data.
off
the start offset in the data.
len
the number of bytes to write.
Description
Writes len bytes from the specified byte array starting at offset off to this buffered output stream.

Ordinarily this method stores bytes from the given array into this stream's buffer, flushing the buffer to the underlying output stream as needed. If the requested length is at least as large as this stream's buffer, however, then this method will flush the buffer and write the bytes directly to the underlying output stream. Thus redundant BufferedOutputStreams will not copy data unnecessarily.

Exceptions
IOException if an I/O error occurs.
Overrides
write in class FilterOutputStream


 Class BufferedReader

Class java.io.BufferedReader

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.Reader
           |
           +----java.io.BufferedReader

public class BufferedReader
extends Reader

Read text from a character-input stream, buffering characters so as to provide for the efficient reading of characters, arrays, and lines.

The buffer size may be specified, or the default size may be used. The default is large enough for most purposes.

In general, each read request made of a Reader causes a corresponding read request to be made of the underlying character or byte stream. It is therefore advisable to wrap a BufferedReader around any Reader whose read() operations may be costly, such as FileReaders and InputStreamReaders. For example,

 BufferedReader in
   = new BufferedReader(new FileReader("foo.in"));
will buffer the input from the specified file. Without buffering, each invocation of read() or readLine() could cause bytes to be read from the file, converted into characters, and then returned, which can be very inefficient.

Programs that use DataInputStreams for textual input can be localized by replacing each DataInputStream with an appropriate BufferedReader.

See Also:
FileReader, InputStreamReader


 BufferedReader Members

BufferedReader Members

Class Overview | This Package | All Packages

Constructors
Name | Description
BufferedReader(Reader) | Create a buffering character-input stream that uses a default-sized input buffer.
BufferedReader(Reader, int) | Create a buffering character-input stream that uses an input buffer of the specified size.

Methods
Name | Description
close() | Close the stream.
mark(int) | Mark the present position in the stream.
markSupported() | Tell whether this stream supports the mark() operation, which it does.
read() | Read a single character.
read(char[], int, int) | Read characters into a portion of an array.
readLine() | Read a line of text.
ready() | Tell whether this stream is ready to be read.
reset() | Reset the stream to the most recent mark.
skip(long) | Skip characters.


 BufferedReader.BufferedReader

BufferedReader.BufferedReader

Class Overview | Class Members | This Package | All Packages

Syntax 1
public BufferedReader( Reader in, int sz )
Parameters
in
A Reader
sz
Input-buffer size
Description
Create a buffering character-input stream that uses an input buffer of the specified size.

Exceptions
IllegalArgumentException If sz is <= 0

Syntax 2
public BufferedReader( Reader in )
Parameters
in
A Reader
Description
Create a buffering character-input stream that uses a default-sized input buffer.


 BufferedReader.close

BufferedReader.close

Class Overview | Class Members | This Package | All Packages

Syntax
public void close() throws IOException
Description
Close the stream.

Exceptions
IOException If an I/O error occurs
Overrides
close in class Reader


 BufferedReader.mark

BufferedReader.mark

Class Overview | Class Members | This Package | All Packages

Syntax
public void mark( int readAheadLimit ) throws IOException
Parameters
readAheadLimit
Limit on the number of characters that may be read while still preserving the mark. After reading this many characters, attempting to reset the stream may fail. A limit value larger than the size of the input buffer will cause a new buffer to be allocated whose size is no smaller than limit. Therefore large values should be used with care.
Description
Mark the present position in the stream. Subsequent calls to reset() will attempt to reposition the stream to this point.

Exceptions
IllegalArgumentException If readAheadLimit is < 0
Exceptions
IOException If an I/O error occurs
Overrides
mark in class Reader


 BufferedReader.markSupported

BufferedReader.markSupported

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean markSupported()
Description
Tell whether this stream supports the mark() operation, which it does.

Overrides
markSupported in class Reader


 BufferedReader.read

BufferedReader.read

Class Overview | Class Members | This Package | All Packages

Syntax 1
public int read() throws IOException
Description
Read a single character.

Exceptions
IOException If an I/O error occurs
Overrides
read in class Reader

Syntax 2
public int read( char cbuf[], int off, int len ) throws IOException
Parameters
cbuf
Destination buffer
off
Offset at which to start storing characters
len
Maximum number of characters to read
Returns
The number of bytes read, or -1 if the end of the stream has been reached
Description
Read characters into a portion of an array.

Ordinarily this method takes characters from this stream's character buffer, filling it from the underlying stream as necessary. If, however, the buffer is empty, the mark is not valid, and the requested length is at least as large as the buffer, then this method will read characters directly from the underlying stream into the given array. Thus redundant BufferedReaders will not copy data unnecessarily.

Exceptions
IOException If an I/O error occurs
Overrides
read in class Reader


 BufferedReader.readLine

BufferedReader.readLine

Class Overview | Class Members | This Package | All Packages

Syntax
public String readLine() throws IOException
Returns
A String containing the contents of the line, not including any line-termination characters, or null if the end of the stream has been reached
Description
Read a line of text. A line is considered to be terminated by any one of a line feed ('\n'), a carriage return ('\r'), or a carriage return followed immediately by a linefeed.

Exceptions
IOException If an I/O error occurs


 BufferedReader.ready

BufferedReader.ready

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean ready() throws IOException
Description
Tell whether this stream is ready to be read. A buffered character stream is ready if the buffer is not empty, or if the underlying character stream is ready.

Exceptions
IOException If an I/O error occurs
Overrides
ready in class Reader


 BufferedReader.reset

BufferedReader.reset

Class Overview | Class Members | This Package | All Packages

Syntax
public void reset() throws IOException
Description
Reset the stream to the most recent mark.

Exceptions
IOException If the stream has never been marked, or if the mark has been invalidated
Overrides
reset in class Reader


 BufferedReader.skip

BufferedReader.skip

Class Overview | Class Members | This Package | All Packages

Syntax
public long skip( long n ) throws IOException
Parameters
n
The number of characters to skip
Returns
The number of characters actually skipped
Description
Skip characters.

Exceptions
IOException If an I/O error occurs
Overrides
skip in class Reader


 Class BufferedWriter

Class java.io.BufferedWriter

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.Writer
           |
           +----java.io.BufferedWriter

public class BufferedWriter
extends Writer

Write text to a character-output stream, buffering characters so as to provide for the efficient writing of single characters, arrays, and strings.

The buffer size may be specified, or the default size may be accepted. The default is large enough for most purposes.

A newLine() method is provided, which uses the platform's own notion of line separator as defined by the system property line.separator. Not all platforms use the newline character ('\n') to terminate lines. Calling this method to terminate each output line is therefore preferred to writing a newline character directly.

In general, a Writer sends its output immediately to the underlying character or byte stream. Unless prompt output is required, it is advisable to wrap a BufferedWriter around any Writer whose write() operations may be costly, such as FileWriters and OutputStreamWriters. For example,

 PrintWriter out
   = new PrintWriter(new BufferedWriter(new FileWriter("foo.out")));
will buffer the PrintWriter's output to the file. Without buffering, each invocation of a print() method would cause characters to be converted into bytes that would then be written immediately to the file, which can be very inefficient.

See Also:
PrintWriter, FileWriter, OutputStreamWriter


 BufferedWriter Members

BufferedWriter Members

Class Overview | This Package | All Packages

Constructors
Name | Description
BufferedWriter(Writer) | Create a buffered character-output stream that uses a default-sized output buffer.
BufferedWriter(Writer, int) | Create a new buffered character-output stream that uses an output buffer of the given size.

Methods
Name | Description
close() | Close the stream.
flush() | Flush the stream.
newLine() | Write a line separator.
write(char[], int, int) | Write a portion of an array of characters.
write(int) | Write a single character.
write(String, int, int) | Write a portion of a String.


 BufferedWriter.BufferedWriter

BufferedWriter.BufferedWriter

Class Overview | Class Members | This Package | All Packages

Syntax 1
public BufferedWriter( Writer out )
Parameters
out
A Writer
Description
Create a buffered character-output stream that uses a default-sized output buffer.

Syntax 2
public BufferedWriter( Writer out, int sz )
Parameters
out
A Writer
sz
Output-buffer size, a positive integer
Description
Create a new buffered character-output stream that uses an output buffer of the given size.

Exceptions
IllegalArgumentException If sz is <= 0


 BufferedWriter.close

BufferedWriter.close

Class Overview | Class Members | This Package | All Packages

Syntax
public void close() throws IOException
Description
Close the stream.

Exceptions
IOException If an I/O error occurs
Overrides
close in class Writer


 BufferedWriter.flush

BufferedWriter.flush

Class Overview | Class Members | This Package | All Packages

Syntax
public void flush() throws IOException
Description
Flush the stream.

Exceptions
IOException If an I/O error occurs
Overrides
flush in class Writer


 BufferedWriter.newLine

BufferedWriter.newLine

Class Overview | Class Members | This Package | All Packages

Syntax
public void newLine() throws IOException
Description
Write a line separator. The line separator string is defined by the system property line.separator, and is not necessarily a single newline ('\n') character.

Exceptions
IOException If an I/O error occurs


 BufferedWriter.write

BufferedWriter.write

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void write( int c ) throws IOException
Description
Write a single character.

Exceptions
IOException If an I/O error occurs
Overrides
write in class Writer

Syntax 2
public void write( char cbuf[], int off, int len ) throws IOException
Parameters
cbuf
A character array
off
Offset from which to start reading characters
len
Number of characters to write
Description
Write a portion of an array of characters.

Ordinarily this method stores characters from the given array into this stream's buffer, flushing the buffer to the underlying stream as needed. If the requested length is at least as large as the buffer, however, then this method will flush the buffer and write the characters directly to the underlying stream. Thus redundant BufferedWriters will not copy data unnecessarily.

Exceptions
IOException If an I/O error occurs
Overrides
write in class Writer

Syntax 3
public void write( String s, int off, int len ) throws IOException
Parameters
s
String to be written
off
Offset from which to start reading characters
len
Number of characters to be written
Description
Write a portion of a String.

Exceptions
IOException If an I/O error occurs
Overrides
write in class Writer


 Class ByteArrayInputStream

Class java.io.ByteArrayInputStream

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.InputStream
           |
           +----java.io.ByteArrayInputStream

public class ByteArrayInputStream
extends InputStream

This class allows an application to create an input stream in which the bytes read are supplied by the contents of a byte array. Applications can also read bytes from a string by using a StringBufferInputStream.

See Also:
StringBufferInputStream


 ByteArrayInputStream Members

ByteArrayInputStream Members

Class Overview | This Package | All Packages

Fields
Name | Description
buf | The byte array containing the data.
count | The index one greater than the last valid character in the input stream buffer.
mark | The currently marked position in the stream.
pos | The index of the next character to read from the input stream buffer.

Constructors
Name | Description
ByteArrayInputStream(byte[]) | Creates a new byte array input stream that reads data from the specified byte array.
ByteArrayInputStream(byte[], int, int) | Creates a new byte array input stream that reads data from the specified byte array.

Methods
Name | Description
available() | Returns the number of bytes that can be read from this input stream without blocking.
mark(int) | Set the current marked position in the stream.
markSupported() | Tests if ByteArrayInputStream supports mark/reset.
read() | Reads the next byte of data from this input stream.
read(byte[], int, int) | Reads up to len bytes of data into an array of bytes from this input stream.
reset() | Resets the buffer to the marked position.
skip(long) | Skips n bytes of input from this input stream.


 ByteArrayInputStream.buf

ByteArrayInputStream.buf

Class Overview | Class Members | This Package | All Packages

Syntax
protected byte buf[]
Description
The byte array containing the data.


 ByteArrayInputStream.count

ByteArrayInputStream.count

Class Overview | Class Members | This Package | All Packages

Syntax
protected int count
Description
The index one greater than the last valid character in the input stream buffer.


 ByteArrayInputStream.mark

ByteArrayInputStream.mark

Class Overview | Class Members | This Package | All Packages

Syntax
protected int mark
Description
The currently marked position in the stream. ByteArrayInputStreams are marked at position zero by default when constructed. They may be marked at another position within the buffer by the mark() method. The current buffer position is set to this point by the reset() method.


 ByteArrayInputStream.pos

ByteArrayInputStream.pos

Class Overview | Class Members | This Package | All Packages

Syntax
protected int pos
Description
The index of the next character to read from the input stream buffer.


 ByteArrayInputStream.ByteArrayInputStream

ByteArrayInputStream.ByteArrayInputStream

Class Overview | Class Members | This Package | All Packages

Syntax 1
public ByteArrayInputStream( byte buf[] )
Parameters
buf
the input buffer.
Description
Creates a new byte array input stream that reads data from the specified byte array. The byte array is not copied.

Syntax 2
public ByteArrayInputStream( byte buf[], int offset, int length )
Parameters
buf
the input buffer.
offset
the offset in the buffer of the first byte to read.
length
the maximum number of bytes to read from the buffer.
Description
Creates a new byte array input stream that reads data from the specified byte array. Up to length characters are to be read from the byte array, starting at the indicated offset.

The byte array is not copied.


 ByteArrayInputStream.available

ByteArrayInputStream.available

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized int available()
Returns
the number of bytes that can be read from the input stream without blocking.
Description
Returns the number of bytes that can be read from this input stream without blocking.

The available method of ByteArrayInputStream returns the value of count - pos, which is the number of bytes remaining to be read from the input buffer.

Overrides
available in class InputStream


 ByteArrayInputStream.mark

ByteArrayInputStream.mark

Class Overview | Class Members | This Package | All Packages

Syntax
public void mark( int markpos )
Description
Set the current marked position in the stream. ByteArrayInputStreams are marked at position zero by default when constructed. They may be marked at another position within the buffer by this method.

Overrides
mark in class InputStream


 ByteArrayInputStream.markSupported

ByteArrayInputStream.markSupported

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean markSupported()
Description
Tests if ByteArrayInputStream supports mark/reset.

Overrides
markSupported in class InputStream


 ByteArrayInputStream.read

ByteArrayInputStream.read

Class Overview | Class Members | This Package | All Packages

Syntax 1
public synchronized int read()
Returns
the next byte of data, or -1 if the end of the stream has been reached.
Description
Reads the next byte of data from this input stream. The value byte is returned as an int in the range 0 to 255. If no byte is available because the end of the stream has been reached, the value -1 is returned.

The read method of ByteArrayInputStream cannot block.

Overrides
read in class InputStream

Syntax 2
public synchronized int read( byte b[], int off, int len )
Parameters
b
the buffer into which the data is read.
off
the start offset of the data.
len
the maximum number of bytes read.
Returns
the total number of bytes read into the buffer, or -1 if there is no more data because the end of the stream has been reached.
Description
Reads up to len bytes of data into an array of bytes from this input stream. This read method cannot block.

Overrides
read in class InputStream


 ByteArrayInputStream.reset

ByteArrayInputStream.reset

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void reset()
Description
Resets the buffer to the marked position. The marked position is the beginning unless another position was marked.

Overrides
reset in class InputStream


 ByteArrayInputStream.skip

ByteArrayInputStream.skip

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized long skip( long n )
Parameters
n
the number of bytes to be skipped.
Returns
the actual number of bytes skipped.
Description
Skips n bytes of input from this input stream. Fewer bytes might be skipped if the end of the input stream is reached.

Overrides
skip in class InputStream


 Class ByteArrayOutputStream

Class java.io.ByteArrayOutputStream

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.OutputStream
           |
           +----java.io.ByteArrayOutputStream

public class ByteArrayOutputStream
extends OutputStream

This class implements an output stream in which the data is written into a byte array. The buffer automatically grows as data is written to it. The data can be retrieved using toByteArray() and toString().


 ByteArrayOutputStream Members

ByteArrayOutputStream Members

Class Overview | This Package | All Packages

Fields
Name | Description
buf | The buffer where data is stored.
count | The number of valid bytes in the buffer.

Constructors
Name | Description
ByteArrayOutputStream() | Creates a new byte array output stream.
ByteArrayOutputStream(int) | Creates a new byte array output stream, with a buffer capacity of the specified size, in bytes.

Methods
Name | Description
reset() | Resets the count field of this byte array output stream to zero, so that all currently accumulated output in the ouput stream is discarded.
size() | Returns the current size of the buffer.
toByteArray() | Creates a newly allocated byte array.
toString() | Converts the buffer's contents into a string, translating bytes into characters according to the platform's default character encoding.
toString(int) | Creates a newly allocated string. Deprecated.
toString(String) | Converts the buffer's contents into a string, translating bytes into characters according to the specified character encoding.
write(byte[], int, int) | Writes len bytes from the specified byte array starting at offset off to this byte array output stream.
write(int) | Writes the specified byte to this byte array output stream.
writeTo(OutputStream) | Writes the complete contents of this byte array output stream to the specified output stream argument, as if by calling the output stream's write method using out.write(buf, 0, count).


 ByteArrayOutputStream.buf

ByteArrayOutputStream.buf

Class Overview | Class Members | This Package | All Packages

Syntax
protected byte buf[]
Description
The buffer where data is stored.


 ByteArrayOutputStream.count

ByteArrayOutputStream.count

Class Overview | Class Members | This Package | All Packages

Syntax
protected int count
Description
The number of valid bytes in the buffer.


 ByteArrayOutputStream.ByteArrayOutputStream

ByteArrayOutputStream.ByteArrayOutputStream

Class Overview | Class Members | This Package | All Packages

Syntax 1
public ByteArrayOutputStream()
Description
Creates a new byte array output stream. The buffer capacity is initially 32 bytes, though its size increases if necessary.

Syntax 2
public ByteArrayOutputStream( int size )
Parameters
size
the initial size.
Description
Creates a new byte array output stream, with a buffer capacity of the specified size, in bytes.


 ByteArrayOutputStream.reset

ByteArrayOutputStream.reset

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void reset()
Description
Resets the count field of this byte array output stream to zero, so that all currently accumulated output in the ouput stream is discarded. The output stream can be used again, reusing the already allocated buffer space.

See Also
count


 ByteArrayOutputStream.size

ByteArrayOutputStream.size

Class Overview | Class Members | This Package | All Packages

Syntax
public int size()
Returns
the value of the count field, which is the number of valid bytes in this output stream.
Description
Returns the current size of the buffer.

See Also
count


 ByteArrayOutputStream.toByteArray

ByteArrayOutputStream.toByteArray

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized byte[] toByteArray()
Returns
the current contents of this output stream, as a byte array.
Description
Creates a newly allocated byte array. Its size is the current size of this output stream and the valid contents of the buffer have been copied into it.

See Also
size


 ByteArrayOutputStream.toString

ByteArrayOutputStream.toString

Class Overview | Class Members | This Package | All Packages

Syntax 1
public String toString()
Description
Converts the buffer's contents into a string, translating bytes into characters according to the platform's default character encoding.

Overrides
toString in class Object

Syntax 2
public String toString( String enc ) throws UnsupportedEncodingException
Parameters
enc
a character-encoding name.
Description
Converts the buffer's contents into a string, translating bytes into characters according to the specified character encoding.

Syntax 3
public String toString( int hibyte )
Parameters
hibyte
the high byte of each resulting Unicode character.
Returns
the current contents of the output stream, as a string.
Description
Note: toString() is deprecated. This method does not properly convert bytes into characters. As of JDK 1.1, the preferred way to do this is via the toString(String enc) method, which takes an encoding-name argument, or the toString() method, which uses the platform's default character encoding.

Creates a newly allocated string. Its size is the current size of the output stream and the valid contents of the buffer have been copied into it. Each character c in the resulting string is constructed from the corresponding element b in the byte array such that:

    c == (char)(((hibyte & 0xff) << 8) | (b & 0xff))

See Also
size, toString, toString


 ByteArrayOutputStream.write

ByteArrayOutputStream.write

Class Overview | Class Members | This Package | All Packages

Syntax 1
public synchronized void write( int b )
Parameters
b
the byte to be written.
Description
Writes the specified byte to this byte array output stream.

Overrides
write in class OutputStream

Syntax 2
public synchronized void write( byte b[], int off, int len )
Parameters
b
the data.
off
the start offset in the data.
len
the number of bytes to write.
Description
Writes len bytes from the specified byte array starting at offset off to this byte array output stream.

Overrides
write in class OutputStream


 ByteArrayOutputStream.writeTo

ByteArrayOutputStream.writeTo

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void writeTo( OutputStream out ) throws IOException
Parameters
out
the output stream to which to write the data.
Description
Writes the complete contents of this byte array output stream to the specified output stream argument, as if by calling the output stream's write method using out.write(buf, 0, count).

Exceptions
IOException if an I/O error occurs.


 Class CharArrayReader

Class java.io.CharArrayReader

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.Reader
           |
           +----java.io.CharArrayReader

public class CharArrayReader
extends Reader

This class implements a character buffer that can be used as a character-input stream.


 CharArrayReader Members

CharArrayReader Members

Class Overview | This Package | All Packages

Fields
Name | Description
buf | Character buffer
count | Number of valid characters in buffer
markedPos | Position of mark in buffer
pos | Current buffer position

Constructors
Name | Description
CharArrayReader(char[]) | Create an CharArrayReader from the specified array of chars.
CharArrayReader(char[], int, int) | Create an CharArrayReader from the specified array of chars.

Methods
Name | Description
close() | Close the stream.
mark(int) | Mark the present position in the stream.
markSupported() | Tell whether this stream supports the mark() operation, which it does.
read() | Read a single character.
read(char[], int, int) | Read characters into a portion of an array.
ready() | Tell whether this stream is ready to be read.
reset() | Reset the stream to the most recent mark, or to the beginning if it has never been marked.
skip(long) | Skip characters.


 CharArrayReader.buf

CharArrayReader.buf

Class Overview | Class Members | This Package | All Packages

Syntax
protected char buf[]
Description
Character buffer


 CharArrayReader.count

CharArrayReader.count

Class Overview | Class Members | This Package | All Packages

Syntax
protected int count
Description
Number of valid characters in buffer


 CharArrayReader.markedPos

CharArrayReader.markedPos

Class Overview | Class Members | This Package | All Packages

Syntax
protected int markedPos
Description
Position of mark in buffer


 CharArrayReader.pos

CharArrayReader.pos

Class Overview | Class Members | This Package | All Packages

Syntax
protected int pos
Description
Current buffer position


 CharArrayReader.CharArrayReader

CharArrayReader.CharArrayReader

Class Overview | Class Members | This Package | All Packages

Syntax 1
public CharArrayReader( char buf[] )
Parameters
buf
Input buffer (not copied)
Description
Create an CharArrayReader from the specified array of chars.

Syntax 2
public CharArrayReader( char buf[], int offset, int length )
Parameters
buf
Input buffer (not copied)
offset
Offset of the first char to read
length
Number of chars to read
Description
Create an CharArrayReader from the specified array of chars.


 CharArrayReader.close

CharArrayReader.close

Class Overview | Class Members | This Package | All Packages

Syntax
public void close()
Description
Close the stream.

Overrides
close in class Reader


 CharArrayReader.mark

CharArrayReader.mark

Class Overview | Class Members | This Package | All Packages

Syntax
public void mark( int readAheadLimit ) throws IOException
Parameters
readAheadLimit
Limit on the number of characters that may be read while still preserving the mark. Because the stream's input comes from a character array, there is no actual limit; hence this argument is ignored.
Description
Mark the present position in the stream. Subsequent calls to reset() will reposition the stream to this point.

Exceptions
IOException If an I/O error occurs
Overrides
mark in class Reader


 CharArrayReader.markSupported

CharArrayReader.markSupported

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean markSupported()
Description
Tell whether this stream supports the mark() operation, which it does.

Overrides
markSupported in class Reader


 CharArrayReader.read

CharArrayReader.read

Class Overview | Class Members | This Package | All Packages

Syntax 1
public int read() throws IOException
Description
Read a single character.

Exceptions
IOException If an I/O error occurs
Overrides
read in class Reader

Syntax 2
public int read( char b[], int off, int len ) throws IOException
Parameters
b
Destination buffer
off
Offset at which to start storing characters
len
Maximum number of characters to read
Returns
The actual number of characters read, or -1 if the end of the stream has been reached
Description
Read characters into a portion of an array.

Exceptions
IOException If an I/O error occurs
Overrides
read in class Reader


 CharArrayReader.ready

CharArrayReader.ready

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean ready() throws IOException
Description
Tell whether this stream is ready to be read. Character-array readers are always ready to be read.

Exceptions
IOException If an I/O error occurs
Overrides
ready in class Reader


 CharArrayReader.reset

CharArrayReader.reset

Class Overview | Class Members | This Package | All Packages

Syntax
public void reset() throws IOException
Description
Reset the stream to the most recent mark, or to the beginning if it has never been marked.

Exceptions
IOException If an I/O error occurs
Overrides
reset in class Reader


 CharArrayReader.skip

CharArrayReader.skip

Class Overview | Class Members | This Package | All Packages

Syntax
public long skip( long n ) throws IOException
Parameters
n
The number of characters to skip
Returns
The number of characters actually skipped
Description
Skip characters.

Exceptions
IOException If an I/O error occurs
Overrides
skip in class Reader


 Class CharArrayWriter

Class java.io.CharArrayWriter

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.Writer
           |
           +----java.io.CharArrayWriter

public class CharArrayWriter
extends Writer

This class implements a character buffer that can be used as an Writer. The buffer automatically grows when data is written to the stream. The data can be retrieved using toCharArray() and toString().


 CharArrayWriter Members

CharArrayWriter Members

Class Overview | This Package | All Packages

Fields
Name | Description
buf | The buffer where data is stored.
count | The number of chars in the buffer.

Constructors
Name | Description
CharArrayWriter() | Creates a new CharArrayWriter.
CharArrayWriter(int) | Creates a new CharArrayWriter with the specified initial size.

Methods
Name | Description
close() | Close the stream.
flush() | Flush the stream.
reset() | Resets the buffer so that you can use it again without throwing away the already allocated buffer.
size() | Returns the current size of the buffer.
toCharArray() | Returns a copy of the input data.
toString() | Converts input data to a string.
write(char[], int, int) | Writes characters to the buffer.
write(int) | Writes a character to the buffer.
write(String, int, int) | Write a portion of a string to the buffer.
writeTo(Writer) | Writes the contents of the buffer to another character stream.


 CharArrayWriter.buf

CharArrayWriter.buf

Class Overview | Class Members | This Package | All Packages

Syntax
protected char buf[]
Description
The buffer where data is stored.


 CharArrayWriter.count

CharArrayWriter.count

Class Overview | Class Members | This Package | All Packages

Syntax
protected int count
Description
The number of chars in the buffer.


 CharArrayWriter.CharArrayWriter

CharArrayWriter.CharArrayWriter

Class Overview | Class Members | This Package | All Packages

Syntax 1
public CharArrayWriter()
Description
Creates a new CharArrayWriter.

Syntax 2
public CharArrayWriter( int initialSize )
Description
Creates a new CharArrayWriter with the specified initial size.


 CharArrayWriter.close

CharArrayWriter.close

Class Overview | Class Members | This Package | All Packages

Syntax
public void close()
Description
Close the stream. This method does not release the buffer, since its contents might still be required.

Overrides
close in class Writer


 CharArrayWriter.flush

CharArrayWriter.flush

Class Overview | Class Members | This Package | All Packages

Syntax
public void flush()
Description
Flush the stream.

Overrides
flush in class Writer


 CharArrayWriter.reset

CharArrayWriter.reset

Class Overview | Class Members | This Package | All Packages

Syntax
public void reset()
Description
Resets the buffer so that you can use it again without throwing away the already allocated buffer.


 CharArrayWriter.size

CharArrayWriter.size

Class Overview | Class Members | This Package | All Packages

Syntax
public int size()
Description
Returns the current size of the buffer.


 CharArrayWriter.toCharArray

CharArrayWriter.toCharArray

Class Overview | Class Members | This Package | All Packages

Syntax
public char[] toCharArray()
Description
Returns a copy of the input data.


 CharArrayWriter.toString

CharArrayWriter.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
the string.
Description
Converts input data to a string.

Overrides
toString in class Object


 CharArrayWriter.write

CharArrayWriter.write

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void write( int c )
Description
Writes a character to the buffer.

Overrides
write in class Writer

Syntax 2
public void write( char c[], int off, int len )
Parameters
c
the data to be written
off
the start offset in the data
len
the number of chars that are written
Description
Writes characters to the buffer.

Overrides
write in class Writer

Syntax 3
public void write( String str, int off, int len )
Parameters
str
String to be written from
off
Offset from which to start reading characters
len
Number of characters to be written
Description
Write a portion of a string to the buffer.

Overrides
write in class Writer


 CharArrayWriter.writeTo

CharArrayWriter.writeTo

Class Overview | Class Members | This Package | All Packages

Syntax
public void writeTo( Writer out ) throws IOException
Parameters
out
the output stream to write to
Description
Writes the contents of the buffer to another character stream.


 Class CharConversionException

Class java.io.CharConversionException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.io.IOException
                           |
                           +----java.io.CharConversionException

public class CharConversionException
extends IOException

base class for character conversion exceptions


 CharConversionException Members

CharConversionException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
CharConversionException() | provides no detailed message
CharConversionException(String) | provides a detailed message


 CharConversionException.CharConversionException

CharConversionException.CharConversionException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public CharConversionException()
Description
provides no detailed message

Syntax 2
public CharConversionException( String s )
Parameters
s
detailed message
Description
provides a detailed message


 Interface DataInput

Interface java.io.DataInput

Interface Members | This Package | All Packages

public interface DataInput

The data input interface is implemented by streams that can read primitive Java data types from a stream in a machine-independent manner.

See Also:
DataInputStream, DataOutput


 DataInput Members

DataInput Members

Interface Overview | This Package | All Packages

Methods
Name | Description
readBoolean() | Reads a boolean value from the input stream.
readByte() | Reads a signed 8-bit value from the input stream.
readChar() | Reads a Unicode char value from the input stream.
readDouble() | Reads a double value from the input stream.
readFloat() | Reads a float value from the input stream.
readFully(byte[]) | Reads b.length bytes into the byte array.
readFully(byte[], int, int) | Reads b.length bytes into the byte array.
readInt() | Reads an int value from the input stream.
readLine() | Reads the next line of text from the input stream.
readLong() | Reads a long value from the input stream.
readShort() | Reads a 16-bit value from the input stream.
readUnsignedByte() | Reads an unsigned 8-bit value from the input stream.
readUnsignedShort() | Reads an unsigned 16-bit value from the input stream.
readUTF() | Reads in a string that has been encoded using a modified UTF-8 format.
skipBytes(int) | Skips exactly n bytes of input.


 DataInput.readBoolean

DataInput.readBoolean

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean readBoolean() throws IOException
Returns
the boolean value read.
Description
Reads a boolean value from the input stream.

Exceptions
EOFException if this stream reaches the end before reading all the bytes.
Exceptions
IOException if an I/O error occurs.


 DataInput.readByte

DataInput.readByte

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract byte readByte() throws IOException
Returns
the 8-bit value read.
Description
Reads a signed 8-bit value from the input stream.

Exceptions
EOFException if this stream reaches the end before reading all the bytes.
Exceptions
IOException if an I/O error occurs.


 DataInput.readChar

DataInput.readChar

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract char readChar() throws IOException
Returns
the Unicode char read.
Description
Reads a Unicode char value from the input stream.

Exceptions
EOFException if this stream reaches the end before reading all the bytes.
Exceptions
IOException if an I/O error occurs.


 DataInput.readDouble

DataInput.readDouble

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract double readDouble() throws IOException
Returns
the double value read.
Description
Reads a double value from the input stream.

Exceptions
EOFException if this stream reaches the end before reading all the bytes.
Exceptions
IOException if an I/O error occurs.


 DataInput.readFloat

DataInput.readFloat

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract float readFloat() throws IOException
Returns
the float value read.
Description
Reads a float value from the input stream.

Exceptions
EOFException if this stream reaches the end before reading all the bytes.
Exceptions
IOException if an I/O error occurs.


 DataInput.readFully

DataInput.readFully

Interface Overview | Interface Members | This Package | All Packages

Syntax 1
public abstract void readFully( byte b[] ) throws IOException
Parameters
b
the buffer into which the data is read.
Description
Reads b.length bytes into the byte array. This method blocks until all the bytes are read.

Exceptions
EOFException if this stream reaches the end before reading all the bytes.
Exceptions
IOException if an I/O error occurs.

Syntax 2
public abstract void readFully( byte b[], int off, int len ) throws IOException
Parameters
b
the buffer into which the data is read.
Description
Reads b.length bytes into the byte array. This method blocks until all the bytes are read.

Exceptions
EOFException if this stream reaches the end before reading all the bytes.
Exceptions
IOException if an I/O error occurs.


 DataInput.readInt

DataInput.readInt

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int readInt() throws IOException
Returns
the int value read.
Description
Reads an int value from the input stream.

Exceptions
EOFException if this stream reaches the end before reading all the bytes.
Exceptions
IOException if an I/O error occurs.


 DataInput.readLine

DataInput.readLine

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String readLine() throws IOException
Returns
if this stream reaches the end before reading all the bytes.
Description
Reads the next line of text from the input stream.

Exceptions
IOException if an I/O error occurs.


 DataInput.readLong

DataInput.readLong

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract long readLong() throws IOException
Returns
the long value read.
Description
Reads a long value from the input stream.

Exceptions
EOFException if this stream reaches the end before reading all the bytes.
Exceptions
IOException if an I/O error occurs.


 DataInput.readShort

DataInput.readShort

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract short readShort() throws IOException
Returns
the 16-bit value read.
Description
Reads a 16-bit value from the input stream.

Exceptions
EOFException if this stream reaches the end before reading all the bytes.
Exceptions
IOException if an I/O error occurs.


 DataInput.readUnsignedByte

DataInput.readUnsignedByte

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int readUnsignedByte() throws IOException
Returns
the unsigned 8-bit value read.
Description
Reads an unsigned 8-bit value from the input stream.

Exceptions
EOFException if this stream reaches the end before reading all the bytes.
Exceptions
IOException if an I/O error occurs.


 DataInput.readUnsignedShort

DataInput.readUnsignedShort

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int readUnsignedShort() throws IOException
Returns
the unsigned 16-bit value read.
Description
Reads an unsigned 16-bit value from the input stream.

Exceptions
EOFException if this stream reaches the end before reading all the bytes.
Exceptions
IOException if an I/O error occurs.


 DataInput.readUTF

DataInput.readUTF

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String readUTF() throws IOException
Returns
a Unicode string.
Description
Reads in a string that has been encoded using a modified UTF-8 format.

For an exact description of this method, see the discussion in Gosling, Joy, and Steele, The Java Language Specification.

Exceptions
EOFException if this stream reaches the end before reading all the bytes.
Exceptions
IOException if an I/O error occurs.
Exceptions
UTFDataFormatException if the bytes do not represent a valid UTF-8 encoding of a string.


 DataInput.skipBytes

DataInput.skipBytes

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int skipBytes( int n ) throws IOException
Parameters
n
the number of bytes to be skipped.
Returns
the number of bytes skipped, which is always n.
Description
Skips exactly n bytes of input.

Exceptions
EOFException if this stream reaches the end before skipping all the bytes.
Exceptions
IOException if an I/O error occurs.


 Class DataInputStream

Class java.io.DataInputStream

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.InputStream
           |
           +----java.io.FilterInputStream
                   |
                   +----java.io.DataInputStream

public class DataInputStream
extends FilterInputStream
implements DataInput

A data input stream lets an application read primitive Java data types from an underlying input stream in a machine-independent way. An application uses a data output stream to write data that can later be read by a data input stream.

Data input streams and data output streams represent Unicode strings in a format that is a slight modification of UTF-8. (For more information, see X/Open Company Ltd., "File System Safe UCS Transformation Format (FSS_UTF)", X/Open Preliminary Specification, Document Number: P316. This information also appears in ISO/IEC 10646, Annex P.)

All characters in the range '\u0001' to '\u007F' are represented by a single byte:

0 bits 0-7

The null character '\u0000' and characters in the range '\u0080' to '\u07FF' are represented by a pair of bytes:

1 | 1 | 0 | bits 6-10
1 | 0 | bits 0-5

Characters in the range '\u0800' to '\uFFFF' are represented by three bytes:
1 | 1 | 1 | 0 | bits 12-15
1 | 0 | bits 6-11
1 | 0 | bits 0-5

The two differences between this format and the "standard" UTF-8 format are the following:

  • The null byte '\u0000' is encoded in 2-byte format rather than 1-byte, so that the encoded strings never have embedded nulls.
  • Only the 1-byte, 2-byte, and 3-byte formats are used.

See Also:
DataOutputStream


 DataInputStream Members

DataInputStream Members

Class Overview | This Package | All Packages

Constructors
Name | Description
DataInputStream(InputStream) | Creates a new data input stream to read data from the specified input stream.

Methods
Name | Description
read(byte[]) | Reads up to byte.length bytes of data from this data input stream into an array of bytes.
read(byte[], int, int) | Reads up to len bytes of data from this data input stream into an array of bytes.
readBoolean() | Reads a boolean from this data input stream.
readByte() | Reads a signed 8-bit value from this data input stream.
readChar() | Reads a Unicode character from this data input stream.
readDouble() | Reads a double from this data input stream.
readFloat() | Reads a float from this data input stream.
readFully(byte[]) | Reads b.length bytes from this data input stream into the byte array.
readFully(byte[], int, int) | Reads exactly len bytes from this data input stream into the byte array.
readInt() | Reads a signed 32-bit integer from this data input stream.
readLine() | Reads the next line of text from this data input stream. Deprecated.
readLong() | Reads a signed 64-bit integer from this data input stream.
readShort() | Reads a signed 16-bit number from this data input stream.
readUnsignedByte() | Reads an unsigned 8-bit number from this data input stream.
readUnsignedShort() | Reads an unsigned 16-bit number from this data input stream.
readUTF() | Reads in a string that has been encoded using a modified UTF-8 format from this data input stream.
readUTF(DataInput) | Reads in a string from the specified data input stream.
skipBytes(int) | Skips exactly n bytes of input in the underlying input stream.


 DataInputStream.DataInputStream

DataInputStream.DataInputStream

Class Overview | Class Members | This Package | All Packages

Syntax
public DataInputStream( InputStream in )
Parameters
in
the input stream.
Description
Creates a new data input stream to read data from the specified input stream.


 DataInputStream.read

DataInputStream.read

Class Overview | Class Members | This Package | All Packages

Syntax 1
public final int read( byte b[] ) throws IOException
Parameters
b
the buffer into which the data is read.
Returns
the total number of bytes read into the buffer, or -1 if there is no more data because the end of the stream has been reached.
Description
Reads up to byte.length bytes of data from this data input stream into an array of bytes. This method blocks until some input is available.

The read method of DataInputStream calls the read method of its underlying input stream with the three arguments b, 0, and b.length and returns whatever value that method returns.

Exceptions
IOException if an I/O error occurs.
Overrides
read in class FilterInputStream
See Also
in, read

Syntax 2
public final int read( byte b[], int off, int len ) throws IOException
Parameters
b
the buffer into which the data is read.
off
the start offset of the data.
len
the maximum number of bytes read.
Returns
the total number of bytes read into the buffer, or -1 if there is no more data because the end of the stream has been reached.
Description
Reads up to len bytes of data from this data input stream into an array of bytes. This method blocks until some input is available.

The read method of DataInputStream calls the read method of its underlying input stream with the same arguments and returns whatever value that method returns.

Exceptions
IOException if an I/O error occurs.
Overrides
read in class FilterInputStream
See Also
in, read


 DataInputStream.readBoolean

DataInputStream.readBoolean

Class Overview | Class Members | This Package | All Packages

Syntax
public final boolean readBoolean() throws IOException
Returns
the boolean value read.
Description
Reads a boolean from this data input stream. This method reads a single byte from the underlying input stream. A value of 0 represents false. Any other value represents true. This method blocks until either the byte is read, the end of the stream is detected, or an exception is thrown.

Exceptions
EOFException if this input stream has reached the end.
Exceptions
IOException if an I/O error occurs.
See Also
in


 DataInputStream.readByte

DataInputStream.readByte

Class Overview | Class Members | This Package | All Packages

Syntax
public final byte readByte() throws IOException
Returns
the next byte of this input stream as a signed 8-bit byte.
Description
Reads a signed 8-bit value from this data input stream. This method reads a byte from the underlying input stream. If the byte read is b, where 0 <= b <= 255, then the result is:
    (byte)(b)

This method blocks until either the byte is read, the end of the stream is detected, or an exception is thrown.

Exceptions
EOFException if this input stream has reached the end.
Exceptions
IOException if an I/O error occurs.
See Also
in


 DataInputStream.readChar

DataInputStream.readChar

Class Overview | Class Members | This Package | All Packages

Syntax
public final char readChar() throws IOException
Returns
the next two bytes of this input stream as a Unicode character.
Description
Reads a Unicode character from this data input stream. This method reads two bytes from the underlying input stream. If the bytes read, in order, are b1 and b2, where 0 <= b1, b1 <= 255, then the result is equal to:
    (char)((b1 << 8) | b2)

This method blocks until either the two bytes are read, the end of the stream is detected, or an exception is thrown.

Exceptions
EOFException if this input stream reaches the end before reading two bytes.
Exceptions
IOException if an I/O error occurs.
See Also
in


 DataInputStream.readDouble

DataInputStream.readDouble

Class Overview | Class Members | This Package | All Packages

Syntax
public final double readDouble() throws IOException
Returns
the next eight bytes of this input stream, interpreted as a double.
Description
Reads a double from this data input stream. This method reads a long value as if by the readLong method and then converts that long to a double using the longBitsToDouble method in class Double.

This method blocks until the eight bytes are read, the end of the stream is detected, or an exception is thrown.

Exceptions
EOFException if this input stream reaches the end before reading eight bytes.
Exceptions
IOException if an I/O error occurs.
See Also
readLong, longBitsToDouble


 DataInputStream.readFloat

DataInputStream.readFloat

Class Overview | Class Members | This Package | All Packages

Syntax
public final float readFloat() throws IOException
Returns
the next four bytes of this input stream, interpreted as a float.
Description
Reads a float from this data input stream. This method reads an int value as if by the readInt method and then converts that int to a float using the intBitsToFloat method in class Float. This method blocks until the four bytes are read, the end of the stream is detected, or an exception is thrown.

Exceptions
EOFException if this input stream reaches the end before reading four bytes.
Exceptions
IOException if an I/O error occurs.
See Also
readInt, intBitsToFloat


 DataInputStream.readFully

DataInputStream.readFully

Class Overview | Class Members | This Package | All Packages

Syntax 1
public final void readFully( byte b[] ) throws IOException
Parameters
b
the buffer into which the data is read.
Description
Reads b.length bytes from this data input stream into the byte array. This method reads repeatedly from the underlying stream until all the bytes are read. This method blocks until all the bytes are read, the end of the stream is detected, or an exception is thrown.

Exceptions
EOFException if this input stream reaches the end before reading all the bytes.
Exceptions
IOException if an I/O error occurs.
See Also
in

Syntax 2
public final void readFully( byte b[], int off, int len ) throws IOException
Parameters
b
the buffer into which the data is read.
off
the start offset of the data.
len
the number of bytes to read.
Description
Reads exactly len bytes from this data input stream into the byte array. This method reads repeatedly from the underlying stream until all the bytes are read. This method blocks until all the bytes are read, the end of the stream is detected, or an exception is thrown.

Exceptions
EOFException if this input stream reaches the end before reading all the bytes.
Exceptions
IOException if an I/O error occurs.
See Also
in


 DataInputStream.readInt

DataInputStream.readInt

Class Overview | Class Members | This Package | All Packages

Syntax
public final int readInt() throws IOException
Returns
the next four bytes of this input stream, interpreted as an int.
Description
Reads a signed 32-bit integer from this data input stream. This method reads four bytes from the underlying input stream. If the bytes read, in order, are b1, b2, b3, and b4, where 0 <= b1, b2, b3, b4 <= 255, then the result is equal to:
    (b1 << 24) | (b2 << 16) + (b3 << 8) +b4

This method blocks until the four bytes are read, the end of the stream is detected, or an exception is thrown.

Exceptions
EOFException if this input stream reaches the end before reading four bytes.
Exceptions
IOException if an I/O error occurs.
See Also
in


 DataInputStream.readLine

DataInputStream.readLine

Class Overview | Class Members | This Package | All Packages

Syntax
public final String readLine() throws IOException
Returns
the next line of text from this input stream.
Description
Note: readLine() is deprecated. This method does not properly convert bytes to characters. As of JDK 1.1, the preferred way to read lines of text is via the BufferedReader.readLine() method. Programs that use the DataInputStream class to read lines can be converted to use the BufferedReader class by replacing code of the form
    DataInputStream d = new DataInputStream(in);
with
    BufferedReader d = new BufferedReader(new InputStreamReader(in));

Reads the next line of text from this data input stream. This method successively reads bytes from the underlying input stream until it reaches the end of a line of text.

A line of text is terminated by a carriage return character ('\r'), a newline character ('\n'), a carriage return character immediately followed by a newline character, or the end of the input stream. The line-terminating character(s), if any, are not returned as part of the string that is returned.

This method blocks until a newline character is read, a carriage return and the byte following it are read (to see if it is a newline), the end of the stream is detected, or an exception is thrown.

Exceptions
IOException if an I/O error occurs.
See Also
readLine, in


 DataInputStream.readLong

DataInputStream.readLong

Class Overview | Class Members | This Package | All Packages

Syntax
public final long readLong() throws IOException
Returns
the next eight bytes of this input stream, interpreted as a long.
Description
Reads a signed 64-bit integer from this data input stream. This method reads eight bytes from the underlying input stream. If the bytes read, in order, are b1, b2, b3, b4, b5, b6, b7, and b8, where
    0 <= b1, b2, b3, b4, b5, b6, b7, b8 <= 255,

then the result is equal to:

     ((long)b1 << 56) + ((long)b2 << 48) +
        ((long)b3 << 40) + ((long)b4 << 32) +
        ((long)b5 << 24) + (b6 << 16) +
        (b7 << 8) + b8

This method blocks until the eight bytes are read, the end of the stream is detected, or an exception is thrown.

Exceptions
EOFException if this input stream reaches the end before reading eight bytes.
Exceptions
IOException if an I/O error occurs.
See Also
in


 DataInputStream.readShort

DataInputStream.readShort

Class Overview | Class Members | This Package | All Packages

Syntax
public final short readShort() throws IOException
Returns
the next two bytes of this input stream, interpreted as a signed 16-bit number.
Description
Reads a signed 16-bit number from this data input stream. The method reads two bytes from the underlying input stream. If the two bytes read, in order, are b1 and b2, where each of the two values is between 0 and 255, inclusive, then the result is equal to:
    (short)((b1 << 8) | b2)

This method blocks until the two bytes are read, the end of the stream is detected, or an exception is thrown.

Exceptions
EOFException if this input stream reaches the end before reading two bytes.
Exceptions
IOException if an I/O error occurs.
See Also
in


 DataInputStream.readUnsignedByte

DataInputStream.readUnsignedByte

Class Overview | Class Members | This Package | All Packages

Syntax
public final int readUnsignedByte() throws IOException
Returns
the next byte of this input stream, interpreted as an unsigned 8-bit number.
Description
Reads an unsigned 8-bit number from this data input stream. This method reads a byte from this data input stream's underlying input stream and returns that byte. This method blocks until the byte is read, the end of the stream is detected, or an exception is thrown.

Exceptions
EOFException if this input stream has reached the end.
Exceptions
IOException if an I/O error occurs.
See Also
in


 DataInputStream.readUnsignedShort

DataInputStream.readUnsignedShort

Class Overview | Class Members | This Package | All Packages

Syntax
public final int readUnsignedShort() throws IOException
Returns
the next two bytes of this input stream, interpreted as an unsigned 16-bit integer.
Description
Reads an unsigned 16-bit number from this data input stream. This method reads two bytes from the underlying input stream. If the bytes read, in order, are b1 and b2, where 0 <= b1, b2 <= 255, then the result is equal to:
    (b1 << 8) | b2

This method blocks until the two bytes are read, the end of the stream is detected, or an exception is thrown.

Exceptions
EOFException if this input stream reaches the end before reading two bytes.
Exceptions
IOException if an I/O error occurs.
See Also
in


 DataInputStream.readUTF

DataInputStream.readUTF

Class Overview | Class Members | This Package | All Packages

Syntax 1
public final String readUTF() throws IOException
Returns
a Unicode string.
Description
Reads in a string that has been encoded using a modified UTF-8 format from this data input stream. This method calls readUTF(this). See readUTF(java.io.DataInput) for a more complete description of the format.

This method blocks until all the bytes are read, the end of the stream is detected, or an exception is thrown.

Exceptions
EOFException if this input stream reaches the end before reading all the bytes.
Exceptions
IOException if an I/O error occurs.
See Also
readUTF

Syntax 2
public static final String readUTF( DataInput in ) throws IOException
Parameters
in
a data input stream.
Returns
a Unicode string.
Description
Reads in a string from the specified data input stream. The string has been encoded using a modified UTF-8 format.

The first two bytes are read as if by readUnsignedShort. This value gives the number of following bytes that are in the encoded string, not the length of the resulting string. The following bytes are then interpreted as bytes encoding characters in the UTF-8 format and are converted into characters.

This method blocks until all the bytes are read, the end of the stream is detected, or an exception is thrown.

Exceptions
EOFException if the input stream reaches the end before all the bytes.
Exceptions
IOException if an I/O error occurs.
Exceptions
UTFDataFormatException if the bytes do not represent a valid UTF-8 encoding of a Unicode string.
See Also
readUnsignedShort


 DataInputStream.skipBytes

DataInputStream.skipBytes

Class Overview | Class Members | This Package | All Packages

Syntax
public final int skipBytes( int n ) throws IOException
Parameters
n
the number of bytes to be skipped.
Returns
the number of bytes skipped, which is always n.
Description
Skips exactly n bytes of input in the underlying input stream. This method blocks until all the bytes are skipped, the end of the stream is detected, or an exception is thrown.

Exceptions
EOFException if this input stream reaches the end before skipping all the bytes.
Exceptions
IOException if an I/O error occurs.


 Interface DataOutput

Interface java.io.DataOutput

Interface Members | This Package | All Packages

public interface DataOutput

The data output interface is implemented by streams that can write primitive Java data types to an output stream in a machine-independent manner.

See Also:
DataInput, DataOutputStream


 DataOutput Members

DataOutput Members

Interface Overview | This Package | All Packages

Methods
Name | Description
write(byte[]) | Writes b.length bytes from the specified byte array to this output stream.
write(byte[], int, int) | Writes len bytes from the specified byte array starting at offset off to this output stream.
write(int) | Writes the specified byte to this data output stream.
writeBoolean(boolean) | Writes a boolean value to this output stream.
writeByte(int) | Writes an 8-bit value to this output stream.
writeBytes(String) | Writes a string to this output stream.
writeChar(int) | Writes a char value to this output stream.
writeChars(String) | Writes a string to this output stream.
writeDouble(double) | Writes a double value to this output stream.
writeFloat(float) | Writes a float value to this output stream.
writeInt(int) | Writes an int value to this output stream.
writeLong(long) | Writes a long value to this output stream.
writeShort(int) | Writes a 16-bit value to this output stream.
writeUTF(String) | Writes a Unicode string by encoding it using modified UTF-8 format.


 DataOutput.write

DataOutput.write

Interface Overview | Interface Members | This Package | All Packages

Syntax 1
public abstract void write( int b ) throws IOException
Parameters
b
the byte to be written.
Description
Writes the specified byte to this data output stream.

Exceptions
IOException if an I/O error occurs.

Syntax 2
public abstract void write( byte b[] ) throws IOException
Parameters
b
the data.
Description
Writes b.length bytes from the specified byte array to this output stream.

Exceptions
IOException if an I/O error occurs.

Syntax 3
public abstract void write( byte b[], int off, int len ) throws IOException
Parameters
b
the data.
off
the start offset in the data.
len
the number of bytes to write.
Description
Writes len bytes from the specified byte array starting at offset off to this output stream.

Exceptions
IOException if an I/O error occurs.


 DataOutput.writeBoolean

DataOutput.writeBoolean

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void writeBoolean( boolean v ) throws IOException
Parameters
v
the boolean to be written.
Description
Writes a boolean value to this output stream.

Exceptions
IOException if an I/O error occurs.


 DataOutput.writeByte

DataOutput.writeByte

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void writeByte( int v ) throws IOException
Parameters
v
the byte value to be written.
Description
Writes an 8-bit value to this output stream.

Exceptions
IOException if an I/O error occurs.


 DataOutput.writeBytes

DataOutput.writeBytes

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void writeBytes( String s ) throws IOException
Parameters
s
the string of bytes to be written.
Description
Writes a string to this output stream.

Exceptions
IOException if an I/O error occurs.


 DataOutput.writeChar

DataOutput.writeChar

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void writeChar( int v ) throws IOException
Parameters
v
the char value to be written.
Description
Writes a char value to this output stream.

Exceptions
IOException if an I/O error occurs.


 DataOutput.writeChars

DataOutput.writeChars

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void writeChars( String s ) throws IOException
Parameters
s
the string value to be written.
Description
Writes a string to this output stream.

Exceptions
IOException if an I/O error occurs.


 DataOutput.writeDouble

DataOutput.writeDouble

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void writeDouble( double v ) throws IOException
Parameters
v
the double value to be written.
Description
Writes a double value to this output stream.

Exceptions
IOException if an I/O error occurs.


 DataOutput.writeFloat

DataOutput.writeFloat

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void writeFloat( float v ) throws IOException
Parameters
v
the float value to be written.
Description
Writes a float value to this output stream.

Exceptions
IOException if an I/O error occurs.


 DataOutput.writeInt

DataOutput.writeInt

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void writeInt( int v ) throws IOException
Parameters
v
the int value to be written.
Description
Writes an int value to this output stream.

Exceptions
IOException if an I/O error occurs.


 DataOutput.writeLong

DataOutput.writeLong

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void writeLong( long v ) throws IOException
Parameters
v
the long value to be written.
Description
Writes a long value to this output stream.

Exceptions
IOException if an I/O error occurs.


 DataOutput.writeShort

DataOutput.writeShort

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void writeShort( int v ) throws IOException
Parameters
v
the short value to be written.
Description
Writes a 16-bit value to this output stream.

Exceptions
IOException if an I/O error occurs.


 DataOutput.writeUTF

DataOutput.writeUTF

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void writeUTF( String str ) throws IOException
Parameters
str
the string value to be written.
Description
Writes a Unicode string by encoding it using modified UTF-8 format.

Exceptions
IOException if an I/O error occurs.


 Class DataOutputStream

Class java.io.DataOutputStream

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.OutputStream
           |
           +----java.io.FilterOutputStream
                   |
                   +----java.io.DataOutputStream

public class DataOutputStream
extends FilterOutputStream
implements DataOutput

A data input stream lets an application write primitive Java data types to an output stream in a portable way. An application can then use a data input stream to read the data back in.

See Also:
DataInputStream


 DataOutputStream Members

DataOutputStream Members

Class Overview | This Package | All Packages

Fields
Name | Description
written | The number of bytes written to the data output stream.

Constructors
Name | Description
DataOutputStream(OutputStream) | Creates a new data output stream to write data to the specified underlying output stream.

Methods
Name | Description
flush() | Flushes this data output stream.
size() | Returns the number of bytes written to this data output stream.
write(byte[], int, int) | Writes len bytes from the specified byte array starting at offset off to the underlying output stream.
write(int) | Writes the specified byte to the underlying output stream.
writeBoolean(boolean) | Writes a boolean to the underlying output stream as a 1-byte value.
writeByte(int) | Writes out a byte to the underlying output stream as a 1-byte value.
writeBytes(String) | Writes out the string to the underlying output stream as a sequence of bytes.
writeChar(int) | Writes a char to the underlying output stream as a 2-byte value, high byte first.
writeChars(String) | Writes a string to the underlying output stream as a sequence of characters.
writeDouble(double) | Converts the double argument to a long using the doubleToLongBits method in class Double, and then writes that long value to the underlying output stream as an 8-byte quantity, high byte first.
writeFloat(float) | Converts the float argument to an int using the floatToIntBits method in class Float, and then writes that int value to the underlying output stream as a 4-byte quantity, high byte first.
writeInt(int) | Writes an int to the underlying output stream as four bytes, high byte first.
writeLong(long) | Writes a long to the underlying output stream as eight bytes, high byte first.
writeShort(int) | Writes a short to the underlying output stream as two bytes, high byte first.
writeUTF(String) | Writes a string to the underlying output stream using UTF-8 encoding in a machine-independent manner.


 DataOutputStream.written

DataOutputStream.written

Class Overview | Class Members | This Package | All Packages

Syntax
protected int written
Description
The number of bytes written to the data output stream.


 DataOutputStream.DataOutputStream

DataOutputStream.DataOutputStream

Class Overview | Class Members | This Package | All Packages

Syntax
public DataOutputStream( OutputStream out )
Parameters
out
the underlying output stream.
Description
Creates a new data output stream to write data to the specified underlying output stream.

See Also
out


 DataOutputStream.flush

DataOutputStream.flush

Class Overview | Class Members | This Package | All Packages

Syntax
public void flush() throws IOException
Description
Flushes this data output stream. This forces any buffered output bytes to be written out to the stream.

The flush method of DataOuputStream calls the flush method of its underlying output stream.

Exceptions
IOException if an I/O error occurs.
Overrides
flush in class FilterOutputStream
See Also
out, flush


 DataOutputStream.size

DataOutputStream.size

Class Overview | Class Members | This Package | All Packages

Syntax
public final int size()
Returns
the value of the written field.
Description
Returns the number of bytes written to this data output stream.

See Also
written


 DataOutputStream.write

DataOutputStream.write

Class Overview | Class Members | This Package | All Packages

Syntax 1
public synchronized void write( int b ) throws IOException
Parameters
b
the byte to be written.
Description
Writes the specified byte to the underlying output stream.

Exceptions
IOException if an I/O error occurs.
Overrides
write in class FilterOutputStream
See Also
out

Syntax 2
public synchronized void write( byte b[], int off, int len ) throws IOException
Parameters
b
the data.
off
the start offset in the data.
len
the number of bytes to write.
Description
Writes len bytes from the specified byte array starting at offset off to the underlying output stream.

Exceptions
IOException if an I/O error occurs.
Overrides
write in class FilterOutputStream
See Also
out


 DataOutputStream.writeBoolean

DataOutputStream.writeBoolean

Class Overview | Class Members | This Package | All Packages

Syntax
public final void writeBoolean( boolean v ) throws IOException
Parameters
v
a boolean value to be written.
Description
Writes a boolean to the underlying output stream as a 1-byte value. The value true is written out as the value (byte)1; the value false is written out as the value (byte)0.

Exceptions
IOException if an I/O error occurs.
See Also
out


 DataOutputStream.writeByte

DataOutputStream.writeByte

Class Overview | Class Members | This Package | All Packages

Syntax
public final void writeByte( int v ) throws IOException
Parameters
v
a byte value to be written.
Description
Writes out a byte to the underlying output stream as a 1-byte value.

Exceptions
IOException if an I/O error occurs.
See Also
out


 DataOutputStream.writeBytes

DataOutputStream.writeBytes

Class Overview | Class Members | This Package | All Packages

Syntax
public final void writeBytes( String s ) throws IOException
Parameters
s
a string of bytes to be written.
Description
Writes out the string to the underlying output stream as a sequence of bytes. Each character in the string is written out, in sequence, by discarding its high eight bits.

Exceptions
IOException if an I/O error occurs.
See Also
out


 DataOutputStream.writeChar

DataOutputStream.writeChar

Class Overview | Class Members | This Package | All Packages

Syntax
public final void writeChar( int v ) throws IOException
Parameters
v
a char value to be written.
Description
Writes a char to the underlying output stream as a 2-byte value, high byte first.

Exceptions
IOException if an I/O error occurs.
See Also
out


 DataOutputStream.writeChars

DataOutputStream.writeChars

Class Overview | Class Members | This Package | All Packages

Syntax
public final void writeChars( String s ) throws IOException
Parameters
s
a String value to be written.
Description
Writes a string to the underlying output stream as a sequence of characters. Each character is written to the data output stream as if by the writeChar method.

Exceptions
IOException if an I/O error occurs.
See Also
writeChar, out


 DataOutputStream.writeDouble

DataOutputStream.writeDouble

Class Overview | Class Members | This Package | All Packages

Syntax
public final void writeDouble( double v ) throws IOException
Parameters
v
a double value to be written.
Description
Converts the double argument to a long using the doubleToLongBits method in class Double, and then writes that long value to the underlying output stream as an 8-byte quantity, high byte first.

Exceptions
IOException if an I/O error occurs.
See Also
out, doubleToLongBits


 DataOutputStream.writeFloat

DataOutputStream.writeFloat

Class Overview | Class Members | This Package | All Packages

Syntax
public final void writeFloat( float v ) throws IOException
Parameters
v
a float value to be written.
Description
Converts the float argument to an int using the floatToIntBits method in class Float, and then writes that int value to the underlying output stream as a 4-byte quantity, high byte first.

Exceptions
IOException if an I/O error occurs.
See Also
out, floatToIntBits


 DataOutputStream.writeInt

DataOutputStream.writeInt

Class Overview | Class Members | This Package | All Packages

Syntax
public final void writeInt( int v ) throws IOException
Parameters
v
an int to be written.
Description
Writes an int to the underlying output stream as four bytes, high byte first.

Exceptions
IOException if an I/O error occurs.
See Also
out


 DataOutputStream.writeLong

DataOutputStream.writeLong

Class Overview | Class Members | This Package | All Packages

Syntax
public final void writeLong( long v ) throws IOException
Parameters
v
a long to be written.
Description
Writes a long to the underlying output stream as eight bytes, high byte first.

Exceptions
IOException if an I/O error occurs.
See Also
out


 DataOutputStream.writeShort

DataOutputStream.writeShort

Class Overview | Class Members | This Package | All Packages

Syntax
public final void writeShort( int v ) throws IOException
Parameters
v
a short to be written.
Description
Writes a short to the underlying output stream as two bytes, high byte first.

Exceptions
IOException if an I/O error occurs.
See Also
out


 DataOutputStream.writeUTF

DataOutputStream.writeUTF

Class Overview | Class Members | This Package | All Packages

Syntax
public final void writeUTF( String str ) throws IOException
Parameters
str
a string to be written.
Description
Writes a string to the underlying output stream using UTF-8 encoding in a machine-independent manner.

First, two bytes are written to the output stream as if by the writeShort method giving the number of bytes to follow. This value is the number of bytes actually written out, not the length of the string. Following the length, each character of the string is output, in sequence, using the UTF-8 encoding for the character.

Exceptions
IOException if an I/O error occurs.


 Class EOFException

Class java.io.EOFException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.io.IOException
                           |
                           +----java.io.EOFException

public class EOFException
extends IOException

Signals that an end of file or end of stream has been reached unexpectedly during input.

This exception is mainly used by data input streams, which generally expect a binary file in a specific format, and for which an end of stream is an unusual condition. Most other input streams return a special value on end of stream.

See Also:
DataInputStream, IOException


 EOFException Members

EOFException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
EOFException() | Constructs an EOFException with no detail message.
EOFException(String) | Constructs an EOFException with the specified detail message.


 EOFException.EOFException

EOFException.EOFException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public EOFException()
Description
Constructs an EOFException with no detail message.

Syntax 2
public EOFException( String s )
Parameters
s
the detail message.
Description
Constructs an EOFException with the specified detail message.


 Interface Externalizable

Interface java.io.Externalizable

Interface Members | This Package | All Packages

public interface Externalizable
extends Serializable

Externalization allows a class to specify the methods to be used to write the object's contents to a stream and to read them back. The Externalizable interface's writeExternal and readExternal methods are implemented by a class to give the class complete control over the format and contents of the stream for an object and its supertypes. These methods must explicitly coordinate with the supertype to save its state.
Object Serialization uses the Serializable and Externalizable interfaces. Object persistence mechanisms may use them also. Each object to be stored is tested for the Externalizable interface. If the object supports it, the writeExternal method is called. If the object does not support Externalizable and does implement Serializable the object should be saved using ObjectOutputStream.
When an Externalizable object is to be reconstructed, an instance is created using the public no-arg constructor and the readExternal method called. Serializable objects are restored by reading them from an ObjectInputStream.

See Also:
ObjectOutputStream, ObjectInputStream, ObjectOutput, ObjectInput, Serializable


 Externalizable Members

Externalizable Members

Interface Overview | This Package | All Packages

Methods
Name | Description
readExternal(ObjectInput) | The object implements the readExternal method to restore its contents by calling the methods of DataInput for primitive types and readObject for objects, strings and arrays.
writeExternal(ObjectOutput) | The object implements the writeExternal method to save its contents by calling the methods of DataOutput for its primitive values or calling the writeObject method of ObjectOutput for objects, strings and arrays.


 Externalizable.readExternal

Externalizable.readExternal

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void readExternal( ObjectInput in ) throws IOException, ClassNotFoundException
Description
The object implements the readExternal method to restore its contents by calling the methods of DataInput for primitive types and readObject for objects, strings and arrays. The readExternal method must read the values in the same sequence and with the same types as were written by writeExternal.

Exceptions
ClassNotFoundException If the class for an object being restored cannot be found.


 Externalizable.writeExternal

Externalizable.writeExternal

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void writeExternal( ObjectOutput out ) throws IOException
Description
The object implements the writeExternal method to save its contents by calling the methods of DataOutput for its primitive values or calling the writeObject method of ObjectOutput for objects, strings and arrays.

Exceptions
IOException Includes any I/O exceptions that may occur


 Class File

Class java.io.File

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.File

public class File
extends Object
implements Serializable

Instances of this class represent the name of a file or directory on the host file system. A file is specified by a pathname, which can either be an absolute pathname or a pathname relative to the current working directory. The pathname must follow the naming conventions of the host platform.

The File class is intended to provide an abstraction that deals with most of the machine dependent complexities of files and pathnames in a machine-independent fashion.

Note that whenever a filename or path is used it is assumed that the host's file naming conventions are used.


 File Members

File Members

Class Overview | This Package | All Packages

Fields
Name | Description
pathSeparator | The system-dependent path separator string.
pathSeparatorChar | The system-dependent path separator character.
separator | The system-dependent path separator character.
separatorChar | The system-dependent path separator string.

Constructors
Name | Description
File(File, String) | Creates a File instance that represents the file with the specified name in the specified directory.
File(String) | Creates a File instance that represents the file whose pathname is the given path argument.
File(String, String) | Creates a File instance whose pathname is the pathname of the specified directory, followed by the separator character, followed by the name argument.

Methods
Name | Description
canRead() | Tests if the application can read from the specified file.
canWrite() | Tests if the application can write to this file.
delete() | Deletes the file specified by this object.
equals(Object) | Compares this object against the specified object.
exists() | Tests if this File exists.
getAbsolutePath() | Returns the absolute pathname of the file represented by this object.
getCanonicalPath() | Returns the canonical form of this File object's pathname.
getName() | Returns the name of the file represented by this object.
getParent() | Returns the parent part of the pathname of this File object, or null if the name has no parent part.
getPath() | Returns the pathname of the file represented by this object.
hashCode() | Computes a hashcode for the file.
isAbsolute() | Tests if the file represented by this File object is an absolute pathname.
isDirectory() | Tests if the file represented by this File object is a directory.
isFile() | Tests if the file represented by this File object is a "normal" file.
lastModified() | Returns the time that the file represented by this File object was last modified.
length() | Returns the length of the file represented by this File object.
list() | Returns a list of the files in the directory specified by this File object.
list(FilenameFilter) | Returns a list of the files in the directory specified by this File that satisfy the specified filter.
mkdir() | Creates a directory whose pathname is specified by this File object.
mkdirs() | Creates a directory whose pathname is specified by this File object, including any necessary parent directories.
renameTo(File) | Renames the file specified by this File object to have the pathname given by the File argument.
toString() | Returns a string representation of this object.


 File.pathSeparator

File.pathSeparator

Class Overview | Class Members | This Package | All Packages

Syntax
public static final String pathSeparator
Description
The system-dependent path separator string. This field is initialized to contain the value of the system property path.separator.

See Also
getProperty


 File.pathSeparatorChar

File.pathSeparatorChar

Class Overview | Class Members | This Package | All Packages

Syntax
public static final char pathSeparatorChar
Description
The system-dependent path separator character. This field is initialized to contain the first character of the value of the system property path.separator. This character is often used to separate filenames in a sequence of files given as a "path list".

See Also
getProperty


 File.separator

File.separator

Class Overview | Class Members | This Package | All Packages

Syntax
public static final String separator
Description
The system-dependent path separator character. This field is initialized to contain the value of the system property file.separator.

See Also
getProperty


 File.separatorChar

File.separatorChar

Class Overview | Class Members | This Package | All Packages

Syntax
public static final char separatorChar
Description
The system-dependent path separator string. This field is initialized to contain the first character of the value of the system property file.separator. This character separates the directory and file components in a filename.

See Also
getProperty


 File.File

File.File

Class Overview | Class Members | This Package | All Packages

Syntax 1
public File( String path )
Parameters
path
the file pathname.
Description
Creates a File instance that represents the file whose pathname is the given path argument.

Exceptions
NullPointerException if the file path is equal to null.
See Also
getPath

Syntax 2
public File( String path, String name )
Parameters
path
the directory pathname.
name
the file pathname.
Description
Creates a File instance whose pathname is the pathname of the specified directory, followed by the separator character, followed by the name argument.

See Also
getPath, separator

Syntax 3
public File( File dir, String name )
Parameters
dir
the directory.
name
the file pathname.
Description
Creates a File instance that represents the file with the specified name in the specified directory.

If the directory argument is null, the resulting File instance represents a file in the (system-dependent) current directory whose pathname is the name argument. Otherwise, the File instance represents a file whose pathname is the pathname of the directory, followed by the separator character, followed by the name argument.

See Also
getPath, separator


 File.canRead

File.canRead

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean canRead()
Returns
true if the file specified by this object exists and the application can read the file; false otherwise.
Description
Tests if the application can read from the specified file.

Exceptions
SecurityException if a security manager exists, its checkRead method is called with the pathname of this File to see if the application is allowed read access to the file.
See Also
getPath, checkRead


 File.canWrite

File.canWrite

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean canWrite()
Returns
true if the application is allowed to write to a file whose name is specified by this object; false otherwise.
Description
Tests if the application can write to this file.

Exceptions
SecurityException if a security manager exists, its checkWrite method is called with the pathname of this File to see if the application is allowed write access to the file.
See Also
getPath, checkWrite


 File.delete

File.delete

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean delete()
Returns
true if the file is successfully deleted; false otherwise.
Description
Deletes the file specified by this object. If the target file to be deleted is a directory, it must be empty for deletion to succeed.

Exceptions
SecurityException if a security manager exists, its checkDelete method is called with the pathname of this File to see if the application is allowed to delete the file.
See Also
getPath, checkDelete


 File.equals

File.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Parameters
obj
the object to compare with.
Returns
true if the objects are the same; false otherwise.
Description
Compares this object against the specified object. Returns true if and only if the argument is not null and is a File object whose pathname is equal to the pathname of this object.

Overrides
equals in class Object


 File.exists

File.exists

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean exists()
Returns
true if the file specified by this object exists; false otherwise.
Description
Tests if this File exists.

Exceptions
SecurityException if a security manager exists, its checkRead method is called with the pathname of this File to see if the application is allowed read access to the file.
See Also
getPath, checkRead


 File.getAbsolutePath

File.getAbsolutePath

Class Overview | Class Members | This Package | All Packages

Syntax
public String getAbsolutePath()
Returns
a system-dependent absolute pathname for this File.
Description
Returns the absolute pathname of the file represented by this object. If this object represents an absolute pathname, then return the pathname. Otherwise, return a pathname that is a concatenation of the current user directory, the separator character, and the pathname of this file object.

The system property user.dir contains the current user directory.

See Also
getPath, isAbsolute, getProperty


 File.getCanonicalPath

File.getCanonicalPath

Class Overview | Class Members | This Package | All Packages

Syntax
public String getCanonicalPath() throws IOException
Description
Returns the canonical form of this File object's pathname. The precise definition of canonical form is system-dependent, but it usually specifies an absolute pathname in which all relative references and references to the current user directory have been completely resolved. The canonical form of a pathname of a nonexistent file may not be defined.

Exceptions
IOException If an I/O error occurs, which is possible because the construction of the canonical path may require filesystem queries.


 File.getName

File.getName

Class Overview | Class Members | This Package | All Packages

Syntax
public String getName()
Returns
the name of the file (without any directory components) represented by this File object.
Description
Returns the name of the file represented by this object. The name is everything in the pathame after the last occurrence of the separator character.

See Also
getPath, separator


 File.getParent

File.getParent

Class Overview | Class Members | This Package | All Packages

Syntax
public String getParent()
Description
Returns the parent part of the pathname of this File object, or null if the name has no parent part. The parent part is generally everything leading up to the last occurrence of the separator character, although the precise definition is system dependent. On UNIX, for example, the parent part of "/usr/lib" is "/usr", whose parent part is "/", which in turn has no parent. On Windows platforms, the parent part of "c:\java" is "c:\", which in turn has no parent.

See Also
getPath, getCanonicalPath, separator


 File.getPath

File.getPath

Class Overview | Class Members | This Package | All Packages

Syntax
public String getPath()
Returns
the pathname represented by this File object.
Description
Returns the pathname of the file represented by this object.


 File.hashCode

File.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int hashCode()
Returns
a hash code value for this File object.
Description
Computes a hashcode for the file.

Overrides
hashCode in class Object


 File.isAbsolute

File.isAbsolute

Class Overview | Class Members | This Package | All Packages

Syntax
public native boolean isAbsolute()
Returns
true if the pathname indicated by the File object is an absolute pathname; false otherwise.
Description
Tests if the file represented by this File object is an absolute pathname. The definition of an absolute pathname is system dependent. For example, on UNIX, a pathname is absolute if its first character is the separator character. On Windows platforms, a pathname is absolute if its first character is an ASCII '\' or '/', or if it begins with a letter followed by a colon.

See Also
getPath, separator


 File.isDirectory

File.isDirectory

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isDirectory()
Returns
true if this File exists and is a directory; false otherwise.
Description
Tests if the file represented by this File object is a directory.

Exceptions
SecurityException if a security manager exists, its checkRead method is called with the pathname of this File to see if the application is allowed read access to the file.
See Also
getPath, checkRead


 File.isFile

File.isFile

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isFile()
Returns
true if the file specified by this object exists and is a "normal" file; false otherwise.
Description
Tests if the file represented by this File object is a "normal" file.

A file is "normal" if it is not a directory and, in addition, satisfies other system-dependent criteria. Any non-directory file created by a Java application is guaranteed to be a normal file.

Exceptions
SecurityException If a security manager exists, its checkRead method is called with the pathname of this File to see if the application is allowed read access to the file.
See Also
getPath, checkRead


 File.lastModified

File.lastModified

Class Overview | Class Members | This Package | All Packages

Syntax
public long lastModified()
Returns
the time the file specified by this object was last modified, or 0L if the specified file does not exist.
Description
Returns the time that the file represented by this File object was last modified.

The return value is system dependent and should only be used to compare with other values returned by last modified. It should not be interpreted as an absolute time.

Exceptions
SecurityException if a security manager exists, its checkRead method is called with the pathname of this File to see if the application is allowed read access to the file.
See Also
getPath, checkRead


 File.length

File.length

Class Overview | Class Members | This Package | All Packages

Syntax
public long length()
Returns
the length, in bytes, of the file specified by this object, or 0L if the specified file does not exist.
Description
Returns the length of the file represented by this File object.

Exceptions
SecurityException if a security manager exists, its checkRead method is called with the pathname of this File to see if the application is allowed read access to the file.
See Also
getPath, checkRead


 File.list

File.list

Class Overview | Class Members | This Package | All Packages

Syntax 1
public String[] list()
Returns
an array of file names in the specified directory. This list does not include the current directory or the parent directory ("." and ".." on Unix systems).
Description
Returns a list of the files in the directory specified by this File object.

Exceptions
SecurityException If a security manager exists, its checkRead method is called with the pathname of this File to see if the application is allowed read access to the file.
See Also
getPath, checkRead

Syntax 2
public String[] list( FilenameFilter filter )
Parameters
filter
a filename filter.
Returns
an array of file names in the specified directory. This list does not include the current directory or the parent directory ("." and ".." on Unix systems).
Description
Returns a list of the files in the directory specified by this File that satisfy the specified filter.

Exceptions
SecurityException If a security manager exists, its checkRead method is called with the pathname of this File to see if the application is allowed read access to the file.
See Also
getPath, FilenameFilter, checkRead


 File.mkdir

File.mkdir

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean mkdir()
Returns
true if the directory could be created; false otherwise.
Description
Creates a directory whose pathname is specified by this File object.

Exceptions
SecurityException if a security manager exists, its checkWrite method is called with the pathname of this File to see if the application is allowed write access to the file.
See Also
getPath, checkWrite


 File.mkdirs

File.mkdirs

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean mkdirs()
Returns
true if the directory (or directories) could be created; false otherwise.
Description
Creates a directory whose pathname is specified by this File object, including any necessary parent directories.

Exceptions
SecurityException if a security manager exists, its checkWrite method is called with the pathname of each of the directories that is to be created, before any of the directories are created.
See Also
getPath, checkWrite


 File.renameTo

File.renameTo

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean renameTo( File dest )
Parameters
dest
the new filename.
Returns
true if the renaming succeeds; false otherwise.
Description
Renames the file specified by this File object to have the pathname given by the File argument.

Exceptions
SecurityException if a security manager exists, its checkWrite method is called both with the pathname of this file object and with the pathname of the destination target object to see if the application is allowed to write to both files.
See Also
getPath, checkWrite


 File.toString

File.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string giving the pathname of this object.
Description
Returns a string representation of this object.

Overrides
toString in class Object
See Also
getPath


 Class FileDescriptor

Class java.io.FileDescriptor

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.FileDescriptor

public final class FileDescriptor
extends Object

Instances of the file descriptor class serve as an opaque handle to the underlying machine-specific structure representing an open file or an open socket.

Applications should not create their own file descriptors.

See Also:
FileInputStream, FileOutputStream, SocketInputStream, SocketOutputStream


 FileDescriptor Members

FileDescriptor Members

Class Overview | This Package | All Packages

Fields
Name | Description
err | A handle to the standard error stream.
in | A handle to the standard input stream.
out | A handle to the standard output stream.

Constructors
Name | Description
FileDescriptor() |

Methods
Name | Description
sync() | Force all system buffers to synchronize with the underlying device.
valid() | Tests if this file descriptor object is valid.


 FileDescriptor.err

FileDescriptor.err

Class Overview | Class Members | This Package | All Packages

Syntax
public static final FileDescriptor err
Description
A handle to the standard error stream.


 FileDescriptor.in

FileDescriptor.in

Class Overview | Class Members | This Package | All Packages

Syntax
public static final FileDescriptor in
Description
A handle to the standard input stream.


 FileDescriptor.out

FileDescriptor.out

Class Overview | Class Members | This Package | All Packages

Syntax
public static final FileDescriptor out
Description
A handle to the standard output stream.


 FileDescriptor.FileDescriptor

FileDescriptor.FileDescriptor

Class Overview | Class Members | This Package | All Packages

Syntax
public FileDescriptor()


 FileDescriptor.sync

FileDescriptor.sync

Class Overview | Class Members | This Package | All Packages

Syntax
public native void sync() throws SyncFailedException
Description
Force all system buffers to synchronize with the underlying device. This method returns after all modified data and attributes of this FileDescriptor have been written to the relevant device(s). In particular, if this FileDescriptor refers to a physical storage medium, such as a file in a file system, sync will not return until all in-memory modified copies of buffers associated with this FileDesecriptor have been written to the physical medium. sync is meant to be used by code that requires physical storage (such as a file) to be in a known state For example, a class that provided a simple transaction facility might use sync to ensure that all changes to a file caused by a given transaction were recorded on a storage medium. sync only affects buffers downstream of this FileDescriptor. If any in-memory buffering is being done by the application (for example, by a BufferedOutputStream object), those buffers must be flushed into the FileDescriptor (for example, by invoking OutputStream.flush) before that data will be affected by sync.

Exceptions
SyncFailedException Thrown when the buffers cannot be flushed, or because the system cannot guarantee that all the buffers have been synchronized with physical media.


 FileDescriptor.valid

FileDescriptor.valid

Class Overview | Class Members | This Package | All Packages

Syntax
public native boolean valid()
Returns
true if the file descriptor object represents a valid, open file or socket; false otherwise.
Description
Tests if this file descriptor object is valid.


 Class FileInputStream

Class java.io.FileInputStream

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.InputStream
           |
           +----java.io.FileInputStream

public class FileInputStream
extends InputStream

A file input stream is an input stream for reading data from a File or from a FileDescriptor.

See Also:
File, FileDescriptor, FileOutputStream


 FileInputStream Members

FileInputStream Members

Class Overview | This Package | All Packages

Constructors
Name | Description
FileInputStream(File) | Creates an input file stream to read from the specified File object.
FileInputStream(FileDescriptor) | Creates an input file stream to read from the specified file descriptor.
FileInputStream(String) | Creates an input file stream to read from a file with the specified name.

Methods
Name | Description
available() | Returns the number of bytes that can be read from this file input stream without blocking.
close() | Closes this file input stream and releases any system resources associated with the stream.
finalize() | Ensures that the close method of this file input stream is called when there are no more references to it.
getFD() | Returns the opaque file descriptor object associated with this stream.
read() | Reads a byte of data from this input stream.
read(byte[]) | Reads up to b.length bytes of data from this input stream into an array of bytes.
read(byte[], int, int) | Reads up to len bytes of data from this input stream into an array of bytes.
skip(long) | Skips over and discards n bytes of data from the input stream.


 FileInputStream.FileInputStream

FileInputStream.FileInputStream

Class Overview | Class Members | This Package | All Packages

Syntax 1
public FileInputStream( String name ) throws FileNotFoundException
Parameters
name
the system-dependent file name.
Description
Creates an input file stream to read from a file with the specified name.

Exceptions
FileNotFoundException if the file is not found.
Exceptions
SecurityException if a security manager exists, its checkRead method is called with the name argument to see if the application is allowed read access to the file.
See Also
checkRead

Syntax 2
public FileInputStream( File file ) throws FileNotFoundException
Parameters
file
the file to be opened for reading.
Description
Creates an input file stream to read from the specified File object.

Exceptions
FileNotFoundException if the file is not found.
Exceptions
SecurityException if a security manager exists, its checkRead method is called with the pathname of this File argument to see if the application is allowed read access to the file.
See Also
getPath, checkRead

Syntax 3
public FileInputStream( FileDescriptor fdObj )
Parameters
fdObj
the file descriptor to be opened for reading.
Description
Creates an input file stream to read from the specified file descriptor.

Exceptions
SecurityException if a security manager exists, its checkRead method is called with the file descriptor to see if the application is allowed to read from the specified file descriptor.
See Also
checkRead


 FileInputStream.available

FileInputStream.available

Class Overview | Class Members | This Package | All Packages

Syntax
public native int available() throws IOException
Returns
the number of bytes that can be read from this file input stream without blocking.
Description
Returns the number of bytes that can be read from this file input stream without blocking.

Exceptions
IOException if an I/O error occurs.
Overrides
available in class InputStream


 FileInputStream.close

FileInputStream.close

Class Overview | Class Members | This Package | All Packages

Syntax
public native void close() throws IOException
Description
Closes this file input stream and releases any system resources associated with the stream.

Exceptions
IOException if an I/O error occurs.
Overrides
close in class InputStream


 FileInputStream.finalize

FileInputStream.finalize

Class Overview | Class Members | This Package | All Packages

Syntax
protected void finalize() throws IOException
Description
Ensures that the close method of this file input stream is called when there are no more references to it.

Exceptions
IOException if an I/O error occurs.
Overrides
finalize in class Object
See Also
close


 FileInputStream.getFD

FileInputStream.getFD

Class Overview | Class Members | This Package | All Packages

Syntax
public final FileDescriptor getFD() throws IOException
Returns
the file descriptor object associated with this stream.
Description
Returns the opaque file descriptor object associated with this stream.

Exceptions
IOException if an I/O error occurs.
See Also
FileDescriptor


 FileInputStream.read

FileInputStream.read

Class Overview | Class Members | This Package | All Packages

Syntax 1
public native int read() throws IOException
Returns
the next byte of data, or -1 if the end of the file is reached.
Description
Reads a byte of data from this input stream. This method blocks if no input is yet available.

Exceptions
IOException if an I/O error occurs.
Overrides
read in class InputStream

Syntax 2
public int read( byte b[] ) throws IOException
Parameters
b
the buffer into which the data is read.
Returns
the total number of bytes read into the buffer, or -1 if there is no more data because the end of the file has been reached.
Description
Reads up to b.length bytes of data from this input stream into an array of bytes. This method blocks until some input is available.

Exceptions
IOException if an I/O error occurs.
Overrides
read in class InputStream

Syntax 3
public int read( byte b[], int off, int len ) throws IOException
Parameters
b
the buffer into which the data is read.
off
the start offset of the data.
len
the maximum number of bytes read.
Returns
the total number of bytes read into the buffer, or -1 if there is no more data because the end of the file has been reached.
Description
Reads up to len bytes of data from this input stream into an array of bytes. This method blocks until some input is available.

Exceptions
IOException if an I/O error occurs.
Overrides
read in class InputStream


 FileInputStream.skip

FileInputStream.skip

Class Overview | Class Members | This Package | All Packages

Syntax
public native long skip( long n ) throws IOException
Parameters
n
the number of bytes to be skipped.
Returns
the actual number of bytes skipped.
Description
Skips over and discards n bytes of data from the input stream. The skip method may, for a variety of reasons, end up skipping over some smaller number of bytes, possibly 0. The actual number of bytes skipped is returned.

Exceptions
IOException if an I/O error occurs.
Overrides
skip in class InputStream


 Class FileNotFoundException

Class java.io.FileNotFoundException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.io.IOException
                           |
                           +----java.io.FileNotFoundException

public class FileNotFoundException
extends IOException

Signals that a file could not be found.


 FileNotFoundException Members

FileNotFoundException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
FileNotFoundException() | Constructs a FileNotFoundException with no detail message.
FileNotFoundException(String) | Constructs a FileNotFoundException with the specified detail message.


 FileNotFoundException.FileNotFoundException

FileNotFoundException.FileNotFoundException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public FileNotFoundException()
Description
Constructs a FileNotFoundException with no detail message.

Syntax 2
public FileNotFoundException( String s )
Parameters
s
the detail message.
Description
Constructs a FileNotFoundException with the specified detail message.


 Class FileOutputStream

Class java.io.FileOutputStream

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.OutputStream
           |
           +----java.io.FileOutputStream

public class FileOutputStream
extends OutputStream

A file output stream is an output stream for writing data to a File or to a FileDescriptor.

See Also:
File, FileDescriptor, FileInputStream


 FileOutputStream Members

FileOutputStream Members

Class Overview | This Package | All Packages

Constructors
Name | Description
FileOutputStream(File) | Creates a file output stream to write to the specified File object.
FileOutputStream(FileDescriptor) | Creates an output file stream to write to the specified file descriptor.
FileOutputStream(String) | Creates an output file stream to write to the file with the specified name.
FileOutputStream(String, boolean) | Creates an output file with the specified system dependent file name.

Methods
Name | Description
close() | Closes this file output stream and releases any system resources associated with this stream.
finalize() | Ensures that the close method of this file output stream is called when there are no more references to this stream.
getFD() | Returns the file descriptor associated with this stream.
write(byte[]) | Writes b.length bytes from the specified byte array to this file output stream.
write(byte[], int, int) | Writes len bytes from the specified byte array starting at offset off to this file output stream.
write(int) | Writes the specified byte to this file output stream.


 FileOutputStream.FileOutputStream

FileOutputStream.FileOutputStream

Class Overview | Class Members | This Package | All Packages

Syntax 1
public FileOutputStream( String name ) throws IOException
Parameters
name
the system-dependent filename.
Description
Creates an output file stream to write to the file with the specified name.

Exceptions
IOException if the file could not be opened for writing.
Exceptions
SecurityException if a security manager exists, its checkWrite method is called with the name argument to see if the application is allowed write access to the file.
See Also
checkWrite

Syntax 2
public FileOutputStream( String name, boolean append ) throws IOException
Parameters
name
the system dependent file name
Description
Creates an output file with the specified system dependent file name.

Exceptions
IOException If the file is not found.

Syntax 3
public FileOutputStream( File file ) throws IOException
Parameters
file
the file to be opened for writing.
Description
Creates a file output stream to write to the specified File object.

Exceptions
IOException if the file could not be opened for writing.
Exceptions
SecurityException if a security manager exists, its checkWrite method is called with the pathname of the File argument to see if the application is allowed write access to the file. This may result in a security exception.
See Also
getPath, SecurityException, checkWrite

Syntax 4
public FileOutputStream( FileDescriptor fdObj )
Parameters
fdObj
the file descriptor to be opened for writing.
Description
Creates an output file stream to write to the specified file descriptor.

Exceptions
SecurityException if a security manager exists, its checkWrite method is called with the file descriptor to see if the application is allowed to write to the specified file descriptor.
See Also
checkWrite


 FileOutputStream.close

FileOutputStream.close

Class Overview | Class Members | This Package | All Packages

Syntax
public native void close() throws IOException
Description
Closes this file output stream and releases any system resources associated with this stream.

Exceptions
IOException if an I/O error occurs.
Overrides
close in class OutputStream


 FileOutputStream.finalize

FileOutputStream.finalize

Class Overview | Class Members | This Package | All Packages

Syntax
protected void finalize() throws IOException
Description
Ensures that the close method of this file output stream is called when there are no more references to this stream.

Exceptions
IOException if an I/O error occurs.
Overrides
finalize in class Object
See Also
close


 FileOutputStream.getFD

FileOutputStream.getFD

Class Overview | Class Members | This Package | All Packages

Syntax
public final FileDescriptor getFD() throws IOException
Returns
the file descriptor object associated with this stream.
Description
Returns the file descriptor associated with this stream.

Exceptions
IOException if an I/O error occurs.
See Also
FileDescriptor


 FileOutputStream.write

FileOutputStream.write

Class Overview | Class Members | This Package | All Packages

Syntax 1
public native void write( int b ) throws IOException
Parameters
b
the byte to be written.
Description
Writes the specified byte to this file output stream.

Exceptions
IOException if an I/O error occurs.
Overrides
write in class OutputStream

Syntax 2
public void write( byte b[] ) throws IOException
Parameters
b
the data.
Description
Writes b.length bytes from the specified byte array to this file output stream.

Exceptions
IOException if an I/O error occurs.
Overrides
write in class OutputStream

Syntax 3
public void write( byte b[], int off, int len ) throws IOException
Parameters
b
the data.
off
the start offset in the data.
len
the number of bytes to write.
Description
Writes len bytes from the specified byte array starting at offset off to this file output stream.

Exceptions
IOException if an I/O error occurs.
Overrides
write in class OutputStream


 Class FileReader

Class java.io.FileReader

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.Reader
           |
           +----java.io.InputStreamReader
                   |
                   +----java.io.FileReader

public class FileReader
extends InputStreamReader

Convenience class for reading character files. The constructors of this class assume that the default character encoding and the default byte-buffer size are appropriate. To specify these values yourself, construct an InputStreamReader on a FileInputStream.

See Also:
InputStreamReader, FileInputStream


 FileReader Members

FileReader Members

Class Overview | This Package | All Packages

Constructors
Name | Description
FileReader(File) |
FileReader(FileDescriptor) |
FileReader(String) |


 FileReader.FileReader

FileReader.FileReader

Class Overview | Class Members | This Package | All Packages

Syntax 1
public FileReader( String fileName ) throws FileNotFoundException

Syntax 2
public FileReader( File file ) throws FileNotFoundException

Syntax 3
public FileReader( FileDescriptor fd )


 Class FileWriter

Class java.io.FileWriter

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.Writer
           |
           +----java.io.OutputStreamWriter
                   |
                   +----java.io.FileWriter

public class FileWriter
extends OutputStreamWriter

Convenience class for writing character files. The constructors of this class assume that the default character encoding and the default byte-buffer size are acceptable. To specify these values yourself, construct an OutputStreamWriter on a FileOutputStream.

See Also:
OutputStreamWriter, FileOutputStream


 FileWriter Members

FileWriter Members

Class Overview | This Package | All Packages

Constructors
Name | Description
FileWriter(File) |
FileWriter(FileDescriptor) |
FileWriter(String) |
FileWriter(String, boolean) |


 FileWriter.FileWriter

FileWriter.FileWriter

Class Overview | Class Members | This Package | All Packages

Syntax 1
public FileWriter( String fileName ) throws IOException

Syntax 2
public FileWriter( String fileName, boolean append ) throws IOException

Syntax 3
public FileWriter( File file ) throws IOException

Syntax 4
public FileWriter( FileDescriptor fd )


 Interface FilenameFilter

Interface java.io.FilenameFilter

Interface Members | This Package | All Packages

public interface FilenameFilter

Instances of classes that implement this interface are used to filter filenames. These instances are used to filter directory listings in the list method of class File, and by the Abstract Window Toolkit's file dialog component.

See Also:
setFilenameFilter, File, list


 FilenameFilter Members

FilenameFilter Members

Interface Overview | This Package | All Packages

Methods
Name | Description
accept(File, String) | Tests if a specified file should be included in a file list.


 FilenameFilter.accept

FilenameFilter.accept

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean accept( File dir, String name )
Parameters
dir
the directory in which the file was found.
name
the name of the file.
Returns
true if the name should be included in the file list; false otherwise.
Description
Tests if a specified file should be included in a file list.


 Class FilterInputStream

Class java.io.FilterInputStream

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.InputStream
           |
           +----java.io.FilterInputStream

public class FilterInputStream
extends InputStream

This class is the superclass of all classes that filter input streams. These streams sit on top of an already existing input stream (the underlying input stream), but provide additional functionality.

The class FilterInputStream itself simply overrides all methods of InputStream with versions that pass all requests to the underlying input stream. Subclasses of FilterInputStream may further override some of these methods as well as provide additional methods and fields.


 FilterInputStream Members

FilterInputStream Members

Class Overview | This Package | All Packages

Fields
Name | Description
in | The underlying input stream.

Constructors
Name | Description
FilterInputStream(InputStream) | Creates an input stream filter built on top of the specified input stream.

Methods
Name | Description
available() | Returns the number of bytes that can be read from this input stream without blocking.
close() | Closes this input stream and releases any system resources associated with the stream.
mark(int) | Marks the current position in this input stream.
markSupported() | Tests if this input stream supports the mark and reset methods.
read() | Reads the next byte of data from this input stream.
read(byte[]) | Reads up to byte.length bytes of data from this input stream into an array of bytes.
read(byte[], int, int) | Reads up to len bytes of data from this input stream into an array of bytes.
reset() | Repositions this stream to the position at the time the mark method was last called on this input stream.
skip(long) | Skips over and discards n bytes of data from the input stream.


 FilterInputStream.in

FilterInputStream.in

Class Overview | Class Members | This Package | All Packages

Syntax
protected InputStream in
Description
The underlying input stream.


 FilterInputStream.FilterInputStream

FilterInputStream.FilterInputStream

Class Overview | Class Members | This Package | All Packages

Syntax
protected FilterInputStream( InputStream in )
Parameters
in
the underlying input stream.
Description
Creates an input stream filter built on top of the specified input stream.


 FilterInputStream.available

FilterInputStream.available

Class Overview | Class Members | This Package | All Packages

Syntax
public int available() throws IOException
Returns
the number of bytes that can be read from the input stream without blocking.
Description
Returns the number of bytes that can be read from this input stream without blocking.

The available method of FilterInputStream calls the available method of its underlying input stream and returns whatever value that method returns.

Exceptions
IOException if an I/O error occurs.
Overrides
available in class InputStream
See Also
in


 FilterInputStream.close

FilterInputStream.close

Class Overview | Class Members | This Package | All Packages

Syntax
public void close() throws IOException
Description
Closes this input stream and releases any system resources associated with the stream. The close method of FilterInputStream calls the close method of its underlying input stream.

Exceptions
IOException if an I/O error occurs.
Overrides
close in class InputStream
See Also
in


 FilterInputStream.mark

FilterInputStream.mark

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void mark( int readlimit )
Parameters
readlimit
the maximum limit of bytes that can be read before the mark position becomes invalid.
Description
Marks the current position in this input stream. A subsequent call to the reset method repositions this stream at the last marked position so that subsequent reads re-read the same bytes.

The readlimit argument tells this input stream to allow that many bytes to be read before the mark position gets invalidated.

The mark method of FilterInputStream calls the mark method of its underlying input stream with the readlimit argument.

Overrides
mark in class InputStream
See Also
in, reset


 FilterInputStream.markSupported

FilterInputStream.markSupported

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean markSupported()
Returns
true if this stream type supports the mark and reset method; false otherwise.
Description
Tests if this input stream supports the mark and reset methods. The markSupported method of FilterInputStream calls the markSupported method of its underlying input stream and returns whatever value that method returns.

Overrides
markSupported in class InputStream
See Also
in, mark, reset


 FilterInputStream.read

FilterInputStream.read

Class Overview | Class Members | This Package | All Packages

Syntax 1
public int read() throws IOException
Returns
the next byte of data, or -1 if the end of the stream is reached.
Description
Reads the next byte of data from this input stream. The value byte is returned as an int in the range 0 to 255. If no byte is available because the end of the stream has been reached, the value -1 is returned. This method blocks until input data is available, the end of the stream is detected, or an exception is thrown.

The read method of FilterInputStream calls the read method of its underlying input stream and returns whatever value that method returns.

Exceptions
IOException if an I/O error occurs.
Overrides
read in class InputStream
See Also
in

Syntax 2
public int read( byte b[] ) throws IOException
Parameters
b
the buffer into which the data is read.
Returns
the total number of bytes read into the buffer, or -1 if there is no more data because the end of the stream has been reached.
Description
Reads up to byte.length bytes of data from this input stream into an array of bytes. This method blocks until some input is available.

The read method of FilterInputStream calls the read method of three arguments with the arguments b, 0, and b.length, and returns whatever value that method returns.

Note that this method does not call the one-argument read method of its underlying stream with the single argument b. Subclasses of FilterInputStream do not need to override this method if they have overridden the three-argument read method.

Exceptions
IOException if an I/O error occurs.
Overrides
read in class InputStream
See Also
read

Syntax 3
public int read( byte b[], int off, int len ) throws IOException
Parameters
b
the buffer into which the data is read.
off
the start offset of the data.
len
the maximum number of bytes read.
Returns
the total number of bytes read into the buffer, or -1 if there is no more data because the end of the stream has been reached.
Description
Reads up to len bytes of data from this input stream into an array of bytes. This method blocks until some input is available.

The read method of FilterInputStream calls the read method of its underlying input stream with the same arguments and returns whatever value that method returns.

Exceptions
IOException if an I/O error occurs.
Overrides
read in class InputStream
See Also
in


 FilterInputStream.reset

FilterInputStream.reset

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void reset() throws IOException
Description
Repositions this stream to the position at the time the mark method was last called on this input stream.

The reset method of FilterInputStream calls the reset method of its underlying input stream.

Stream marks are intended to be used in situations where you need to read ahead a little to see what's in the stream. Often this is most easily done by invoking some general parser. If the stream is of the type handled by the parse, it just chugs along happily. If the stream is not of that type, the parser should toss an exception when it fails. If this happens within readlimit bytes, it allows the outer code to reset the stream and try another parser.

Exceptions
IOException if the stream has not been marked or if the mark has been invalidated.
Overrides
reset in class InputStream
See Also
in, mark


 FilterInputStream.skip

FilterInputStream.skip

Class Overview | Class Members | This Package | All Packages

Syntax
public long skip( long n ) throws IOException
Parameters
n
the number of bytes to be skipped.
Returns
the actual number of bytes skipped.
Description
Skips over and discards n bytes of data from the input stream. The skip method may, for a variety of reasons, end up skipping over some smaller number of bytes, possibly 0. The actual number of bytes skipped is returned.

The skip method of FilterInputStream calls the skip method of its underlying input stream with the same argument, and returns whatever value that method does.

Exceptions
IOException if an I/O error occurs.
Overrides
skip in class InputStream


 Class FilterOutputStream

Class java.io.FilterOutputStream

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.OutputStream
           |
           +----java.io.FilterOutputStream

public class FilterOutputStream
extends OutputStream

This class is the superclass of all classes that filter output streams. These streams sit on top of an already existing output stream (the underlying output stream), but provide additional functionality.

The class FilterOutputStream itself simply overrides all methods of OutputStream with versions that pass all requests to the underlying output stream. Subclasses of FilterOutputStream may further override some of these methods as well as provide additional methods and fields.


 FilterOutputStream Members

FilterOutputStream Members

Class Overview | This Package | All Packages

Fields
Name | Description
out | The underlying output stream.

Constructors
Name | Description
FilterOutputStream(OutputStream) | Creates an output stream filter built on top of the specified underlying output stream.

Methods
Name | Description
close() | Closes this output stream and releases any system resources associated with the stream.
flush() | Flushes this output stream and forces any buffered output bytes to be written out to the stream.
write(byte[]) | Writes b.length bytes to this output stream.
write(byte[], int, int) | Writes len bytes from the specified byte array starting at offset off to this output stream.
write(int) | Writes the specified byte to this output stream.


 FilterOutputStream.out

FilterOutputStream.out

Class Overview | Class Members | This Package | All Packages

Syntax
protected OutputStream out
Description
The underlying output stream.


 FilterOutputStream.FilterOutputStream

FilterOutputStream.FilterOutputStream

Class Overview | Class Members | This Package | All Packages

Syntax
public FilterOutputStream( OutputStream out )
Parameters
out
the underlying output stream.
Description
Creates an output stream filter built on top of the specified underlying output stream.


 FilterOutputStream.close

FilterOutputStream.close

Class Overview | Class Members | This Package | All Packages

Syntax
public void close() throws IOException
Description
Closes this output stream and releases any system resources associated with the stream.

The close method of FilterOutputStream calls its flush method, and then calls the close method of its underlying output stream.

Exceptions
IOException if an I/O error occurs.
Overrides
close in class OutputStream
See Also
flush, out


 FilterOutputStream.flush

FilterOutputStream.flush

Class Overview | Class Members | This Package | All Packages

Syntax
public void flush() throws IOException
Description
Flushes this output stream and forces any buffered output bytes to be written out to the stream.

The flush method of FilterOutputStream calls the flush method of its underlying output stream.

Exceptions
IOException if an I/O error occurs.
Overrides
flush in class OutputStream
See Also
out


 FilterOutputStream.write

FilterOutputStream.write

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void write( int b ) throws IOException
Parameters
b
the byte.
Description
Writes the specified byte to this output stream.

The write method of FilterOutputStream calls the write method of its underlying output stream.

Exceptions
IOException if an I/O error occurs.
Overrides
write in class OutputStream

Syntax 2
public void write( byte b[] ) throws IOException
Parameters
b
the data to be written.
Description
Writes b.length bytes to this output stream.

The write method of FilterOutputStream calls its write method of three arguments with the arguments b, 0, and b.length.

Note that this method does not call the one-argument write method of its underlying stream with the single argument b.

Exceptions
IOException if an I/O error occurs.
Overrides
write in class OutputStream
See Also
write

Syntax 3
public void write( byte b[], int off, int len ) throws IOException
Parameters
b
the data.
off
the start offset in the data.
len
the number of bytes to write.
Description
Writes len bytes from the specified byte array starting at offset off to this output stream.

The write method of FilterOutputStream calls the write method of one argument on each byte to output.

Note that this method does not call the write method of its underlying input stream with the same arguments. Subclasses of FilterOutputStream should provide a more efficient implementation of this method.

Exceptions
IOException if an I/O error occurs.
Overrides
write in class OutputStream
See Also
write


 Class FilterReader

Class java.io.FilterReader

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.Reader
           |
           +----java.io.FilterReader

public abstract class FilterReader
extends Reader

Abstract class for reading filtered character streams.


 FilterReader Members

FilterReader Members

Class Overview | This Package | All Packages

Fields
Name | Description
in | The underlying character-input stream, or null if the stream has been closed

Constructors
Name | Description
FilterReader(Reader) | Create a new filtered reader.

Methods
Name | Description
close() | Close the stream.
mark(int) | Mark the present position in the stream.
markSupported() | Tell whether this stream supports the mark() operation.
read() | Read a single character.
read(char[], int, int) | Read characters into a portion of an array.
ready() | Tell whether this stream is ready to be read.
reset() | Reset the stream.
skip(long) | Skip characters.


 FilterReader.in

FilterReader.in

Class Overview | Class Members | This Package | All Packages

Syntax
protected Reader in
Description
The underlying character-input stream, or null if the stream has been closed


 FilterReader.FilterReader

FilterReader.FilterReader

Class Overview | Class Members | This Package | All Packages

Syntax
protected FilterReader( Reader in )
Description
Create a new filtered reader.


 FilterReader.close

FilterReader.close

Class Overview | Class Members | This Package | All Packages

Syntax
public void close() throws IOException
Description
Close the stream.

Exceptions
IOException If an I/O error occurs
Overrides
close in class Reader


 FilterReader.mark

FilterReader.mark

Class Overview | Class Members | This Package | All Packages

Syntax
public void mark( int readAheadLimit ) throws IOException
Description
Mark the present position in the stream.

Exceptions
IOException If an I/O error occurs
Overrides
mark in class Reader


 FilterReader.markSupported

FilterReader.markSupported

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean markSupported()
Description
Tell whether this stream supports the mark() operation.

Overrides
markSupported in class Reader


 FilterReader.read

FilterReader.read

Class Overview | Class Members | This Package | All Packages

Syntax 1
public int read() throws IOException
Description
Read a single character.

Exceptions
IOException If an I/O error occurs
Overrides
read in class Reader

Syntax 2
public int read( char cbuf[], int off, int len ) throws IOException
Description
Read characters into a portion of an array.

Exceptions
IOException If an I/O error occurs
Overrides
read in class Reader


 FilterReader.ready

FilterReader.ready

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean ready() throws IOException
Description
Tell whether this stream is ready to be read.

Exceptions
IOException If an I/O error occurs
Overrides
ready in class Reader


 FilterReader.reset

FilterReader.reset

Class Overview | Class Members | This Package | All Packages

Syntax
public void reset() throws IOException
Description
Reset the stream.

Exceptions
IOException If an I/O error occurs
Overrides
reset in class Reader


 FilterReader.skip

FilterReader.skip

Class Overview | Class Members | This Package | All Packages

Syntax
public long skip( long n ) throws IOException
Description
Skip characters.

Exceptions
IOException If an I/O error occurs
Overrides
skip in class Reader


 Class FilterWriter

Class java.io.FilterWriter

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.Writer
           |
           +----java.io.FilterWriter

public abstract class FilterWriter
extends Writer

Abstract class for writing filtered character streams.


 FilterWriter Members

FilterWriter Members

Class Overview | This Package | All Packages

Fields
Name | Description
out | The underlying character-output stream.

Constructors
Name | Description
FilterWriter(Writer) | Create a new filtered writer.

Methods
Name | Description
close() | Close the stream.
flush() | Flush the stream.
write(char[], int, int) | Write a portion of an array of characters.
write(int) | Write a single character.
write(String, int, int) | Write a portion of a string.


 FilterWriter.out

FilterWriter.out

Class Overview | Class Members | This Package | All Packages

Syntax
protected Writer out
Description
The underlying character-output stream.


 FilterWriter.FilterWriter

FilterWriter.FilterWriter

Class Overview | Class Members | This Package | All Packages

Syntax
protected FilterWriter( Writer out )
Description
Create a new filtered writer.


 FilterWriter.close

FilterWriter.close

Class Overview | Class Members | This Package | All Packages

Syntax
public void close() throws IOException
Description
Close the stream.

Exceptions
IOException If an I/O error occurs
Overrides
close in class Writer


 FilterWriter.flush

FilterWriter.flush

Class Overview | Class Members | This Package | All Packages

Syntax
public void flush() throws IOException
Description
Flush the stream.

Exceptions
IOException If an I/O error occurs
Overrides
flush in class Writer


 FilterWriter.write

FilterWriter.write

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void write( int c ) throws IOException
Description
Write a single character.

Exceptions
IOException If an I/O error occurs
Overrides
write in class Writer

Syntax 2
public void write( char cbuf[], int off, int len ) throws IOException
Parameters
cbuf
Buffer of characters to be written
off
Offset from which to start reading characters
len
Number of characters to be written
Description
Write a portion of an array of characters.

Exceptions
IOException If an I/O error occurs
Overrides
write in class Writer

Syntax 3
public void write( String str, int off, int len ) throws IOException
Parameters
str
String to be written
off
Offset from which to start reading characters
len
Number of characters to be written
Description
Write a portion of a string.

Exceptions
IOException If an I/O error occurs
Overrides
write in class Writer


 Class IOException

Class java.io.IOException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.io.IOException

public class IOException
extends Exception

Signals that an I/O exception of some sort has occurred.

See Also:
InputStream, OutputStream


 IOException Members

IOException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
IOException() | Constructs an IOException with no detail message.
IOException(String) | Constructs an IOException with the specified detail message.


 IOException.IOException

IOException.IOException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public IOException()
Description
Constructs an IOException with no detail message.

Syntax 2
public IOException( String s )
Parameters
s
the detail message.
Description
Constructs an IOException with the specified detail message.


 Class InputStream

Class java.io.InputStream

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.InputStream

public abstract class InputStream
extends Object

This abstract class is the superclass of all classes representing an input stream of bytes.

Applications that need to define a subclass of InputStream must always provide a method that returns the next byte of input.

See Also:
BufferedInputStream, ByteArrayInputStream, DataInputStream, FilterInputStream, read, OutputStream, PushbackInputStream


 InputStream Members

InputStream Members

Class Overview | This Package | All Packages

Constructors
Name | Description
InputStream() |

Methods
Name | Description
available() | Returns the number of bytes that can be read from this input stream without blocking.
close() | Closes this input stream and releases any system resources associated with the stream.
mark(int) | Marks the current position in this input stream.
markSupported() | Tests if this input stream supports the mark and reset methods.
read() | Reads the next byte of data from this input stream.
read(byte[]) | Reads up to b.length bytes of data from this input stream into an array of bytes.
read(byte[], int, int) | Reads up to len bytes of data from this input stream into an array of bytes.
reset() | Repositions this stream to the position at the time the mark method was last called on this input stream.
skip(long) | Skips over and discards n bytes of data from this input stream.


 InputStream.InputStream

InputStream.InputStream

Class Overview | Class Members | This Package | All Packages

Syntax
public InputStream()


 InputStream.available

InputStream.available

Class Overview | Class Members | This Package | All Packages

Syntax
public int available() throws IOException
Returns
the number of bytes that can be read from this input stream without blocking.
Description
Returns the number of bytes that can be read from this input stream without blocking. The available method of InputStream returns 0. This method should be overridden by subclasses.

Exceptions
IOException if an I/O error occurs.


 InputStream.close

InputStream.close

Class Overview | Class Members | This Package | All Packages

Syntax
public void close() throws IOException
Description
Closes this input stream and releases any system resources associated with the stream.

The close method of InputStream does nothing.

Exceptions
IOException if an I/O error occurs.


 InputStream.mark

InputStream.mark

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void mark( int readlimit )
Parameters
readlimit
the maximum limit of bytes that can be read before the mark position becomes invalid.
Description
Marks the current position in this input stream. A subsequent call to the reset method repositions this stream at the last marked position so that subsequent reads re-read the same bytes.

The readlimit arguments tells this input stream to allow that many bytes to be read before the mark position gets invalidated.

The mark method of InputStream does nothing.

See Also
reset


 InputStream.markSupported

InputStream.markSupported

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean markSupported()
Returns
true if this true type supports the mark and reset method; false otherwise.
Description
Tests if this input stream supports the mark and reset methods. The markSupported method of InputStream returns false.

See Also
mark, reset


 InputStream.read

InputStream.read

Class Overview | Class Members | This Package | All Packages

Syntax 1
public abstract int read() throws IOException
Returns
the next byte of data, or -1 if the end of the stream is reached.
Description
Reads the next byte of data from this input stream. The value byte is returned as an int in the range 0 to 255. If no byte is available because the end of the stream has been reached, the value -1 is returned. This method blocks until input data is available, the end of the stream is detected, or an exception is thrown.

A subclass must provide an implementation of this method.

Exceptions
IOException if an I/O error occurs.

Syntax 2
public int read( byte b[] ) throws IOException
Parameters
b
the buffer into which the data is read.
Returns
the total number of bytes read into the buffer, or -1 is there is no more data because the end of the stream has been reached.
Description
Reads up to b.length bytes of data from this input stream into an array of bytes.

The read method of InputStream calls the read method of three arguments with the arguments b, 0, and b.length.

Exceptions
IOException if an I/O error occurs.
See Also
read

Syntax 3
public int read( byte b[], int off, int len ) throws IOException
Parameters
b
the buffer into which the data is read.
off
the start offset of the data.
len
the maximum number of bytes read.
Returns
the total number of bytes read into the buffer, or -1 if there is no more data because the end of the stream has been reached.
Description
Reads up to len bytes of data from this input stream into an array of bytes. This method blocks until some input is available. If the first argument is null, up to len bytes are read and discarded.

The read method of InputStream reads a single byte at a time using the read method of zero arguments to fill in the array. Subclasses are encouraged to provide a more efficient implementation of this method.

Exceptions
IOException if an I/O error occurs.
See Also
read


 InputStream.reset

InputStream.reset

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void reset() throws IOException
Description
Repositions this stream to the position at the time the mark method was last called on this input stream.

The reset method of InputStream throws an IOException, because input streams, by default, do not support mark and reset.

Stream marks are intended to be used in situations where you need to read ahead a little to see what's in the stream. Often this is most easily done by invoking some general parser. If the stream is of the type handled by the parser, it just chugs along happily. If the stream is not of that type, the parser should toss an exception when it fails, which, if it happens within readlimit bytes, allows the outer code to reset the stream and try another parser.

Exceptions
IOException if this stream has not been marked or if the mark has been invalidated.
See Also
mark, IOException


 InputStream.skip

InputStream.skip

Class Overview | Class Members | This Package | All Packages

Syntax
public long skip( long n ) throws IOException
Parameters
n
the number of bytes to be skipped.
Returns
the actual number of bytes skipped.
Description
Skips over and discards n bytes of data from this input stream. The skip method may, for a variety of reasons, end up skipping over some smaller number of bytes, possibly 0. The actual number of bytes skipped is returned.

The skip method of InputStream creates a byte array of length n and then reads into it until n bytes have been read or the end of the stream has been reached. Subclasses are encouraged to provide a more efficient implementation of this method.

Exceptions
IOException if an I/O error occurs.


 Class InputStreamReader

Class java.io.InputStreamReader

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.Reader
           |
           +----java.io.InputStreamReader

public class InputStreamReader
extends Reader

An InputStreamReader is a bridge from byte streams to character streams: It reads bytes and translates them into characters according to a specified character encoding. The encoding that it uses may be specified by name, or the platform's default encoding may be accepted.

Each invocation of one of an InputStreamReader's read() methods may cause one or more bytes to be read from the underlying byte-input stream. For top efficiency, consider wrapping an InputStreamReader within a BufferedReader; for example,

 BufferedReader in
   = new BufferedReader(new InputStreamReader(System.in));

See Also:
BufferedReader, InputStream


 InputStreamReader Members

InputStreamReader Members

Class Overview | This Package | All Packages

Constructors
Name | Description
InputStreamReader(InputStream) | Create an InputStreamReader that uses the default character encoding.
InputStreamReader(InputStream, String) | Create an InputStreamReader that uses the named character encoding.

Methods
Name | Description
close() | Close the stream.
getEncoding() | Return the name of the encoding being used by this stream.
read() | Read a single character.
read(char[], int, int) | Read characters into a portion of an array.
ready() | Tell whether this stream is ready to be read.


 InputStreamReader.InputStreamReader

InputStreamReader.InputStreamReader

Class Overview | Class Members | This Package | All Packages

Syntax 1
public InputStreamReader( InputStream in )
Parameters
in
An InputStream
Description
Create an InputStreamReader that uses the default character encoding.

Syntax 2
public InputStreamReader( InputStream in, String enc ) throws UnsupportedEncodingException
Parameters
in
An InputStream
enc
Name of encoding to be used
Description
Create an InputStreamReader that uses the named character encoding.

Exceptions
UnsupportedEncodingException If the named encoding is not supported


 InputStreamReader.close

InputStreamReader.close

Class Overview | Class Members | This Package | All Packages

Syntax
public void close() throws IOException
Description
Close the stream.

Exceptions
IOException If an I/O error occurs
Overrides
close in class Reader


 InputStreamReader.getEncoding

InputStreamReader.getEncoding

Class Overview | Class Members | This Package | All Packages

Syntax
public String getEncoding()
Description
Return the name of the encoding being used by this stream. May return null if the stream has been closed.


 InputStreamReader.read

InputStreamReader.read

Class Overview | Class Members | This Package | All Packages

Syntax 1
public int read() throws IOException
Returns
The character read, or -1 if the end of the stream has been reached
Description
Read a single character.

Exceptions
IOException If an I/O error occurs
Overrides
read in class Reader

Syntax 2
public int read( char cbuf[], int off, int len ) throws IOException
Parameters
cbuf
Destination buffer
off
Offset at which to start storing characters
len
Maximum number of characters to read
Returns
The number of characters read, or -1 if the end of the stream has been reached
Description
Read characters into a portion of an array.

Exceptions
IOException If an I/O error occurs
Overrides
read in class Reader


 InputStreamReader.ready

InputStreamReader.ready

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean ready() throws IOException
Description
Tell whether this stream is ready to be read. An InputStreamReader is ready if its input buffer is not empty, or if bytes are available to be read from the underlying byte stream.

Exceptions
IOException If an I/O error occurs
Overrides
ready in class Reader


 Class InterruptedIOException

Class java.io.InterruptedIOException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.io.IOException
                           |
                           +----java.io.InterruptedIOException

public class InterruptedIOException
extends IOException

Signals that an I/O operation has been interrupted.

See Also:
InputStream, OutputStream, interrupt


 InterruptedIOException Members

InterruptedIOException Members

Class Overview | This Package | All Packages

Fields
Name | Description
bytesTransferred | Reports how many bytes had been transferred as part of the I/O operation before it was interrupted.

Constructors
Name | Description
InterruptedIOException() | Constructs an InterruptedIOException with no detail message.
InterruptedIOException(String) | Constructs an InterruptedIOException with the specified detail message.


 InterruptedIOException.bytesTransferred

InterruptedIOException.bytesTransferred

Class Overview | Class Members | This Package | All Packages

Syntax
public int bytesTransferred
Description
Reports how many bytes had been transferred as part of the I/O operation before it was interrupted.


 InterruptedIOException.InterruptedIOException

InterruptedIOException.InterruptedIOException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public InterruptedIOException()
Description
Constructs an InterruptedIOException with no detail message.

Syntax 2
public InterruptedIOException( String s )
Parameters
s
the detail message.
Description
Constructs an InterruptedIOException with the specified detail message.


 Class InvalidClassException

Class java.io.InvalidClassException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.io.IOException
                           |
                           +----java.io.ObjectStreamException
                                   |
                                   +----java.io.InvalidClassException

public class InvalidClassException
extends ObjectStreamException

Raised when the Serialization runtime detects a problem with a Class. The class may:

  • not match the serial version of the class in the stream
  • the class contains unknown datatypes
  • the class implements only one of writeObject or readObject methods
  • the class is not public
  • the class does not have an accessible no-arg constructor


 InvalidClassException Members

InvalidClassException Members

Class Overview | This Package | All Packages

Fields
Name | Description
classname |

Constructors
Name | Description
InvalidClassException(String) | Report a InvalidClassException for the specified reason.
InvalidClassException(String, String) |

Methods
Name | Description
getMessage() | Produce the message, include the classname if present.


 InvalidClassException.classname

InvalidClassException.classname

Class Overview | Class Members | This Package | All Packages

Syntax
public String classname


 InvalidClassException.InvalidClassException

InvalidClassException.InvalidClassException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public InvalidClassException( String reason )
Description
Report a InvalidClassException for the specified reason.

Syntax 2
public InvalidClassException( String cname, String reason )


 InvalidClassException.getMessage

InvalidClassException.getMessage

Class Overview | Class Members | This Package | All Packages

Syntax
public String getMessage()
Description
Produce the message, include the classname if present.

Overrides
getMessage in class Throwable


 Class InvalidObjectException

Class java.io.InvalidObjectException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.io.IOException
                           |
                           +----java.io.ObjectStreamException
                                   |
                                   +----java.io.InvalidObjectException

public class InvalidObjectException
extends ObjectStreamException

Indicates that one or more deserialized objects failed validation tests. The argument should be the reason for the failure.

See Also:
ObjectInputValidation


 InvalidObjectException Members

InvalidObjectException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
InvalidObjectException(String) | Constructs an InvalidObjectException with a detail message.


 InvalidObjectException.InvalidObjectException

InvalidObjectException.InvalidObjectException

Class Overview | Class Members | This Package | All Packages

Syntax
public InvalidObjectException( String reason )
Description
Constructs an InvalidObjectException with a detail message. The argument should be the reason why the validation of the object failed.

See Also
ObjectInputValidation


 Class LineNumberInputStream

Class java.io.LineNumberInputStream

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.InputStream
           |
           +----java.io.FilterInputStream
                   |
                   +----java.io.LineNumberInputStream

public class LineNumberInputStream
extends FilterInputStream

Note: LineNumberInputStream is deprecated. This class incorrectly assumes that bytes adequately represent characters. As of JDK 1.1, the preferred way to operate on character streams is via the new character-stream classes, which include a class for counting line numbers.

This class is an input stream filter that provides the added functionality of keeping track of the current line number.

A line is a sequence of bytes ending with a carriage return character ('\r'), a newline character ('\n'), or a carriage return character followed immediately by a linefeed character. In all three cases, the line terminating character(s) are returned as a single newline character.

The line number begins at 0, and is incremented by 1 when a read returns a newline character.

See Also:
LineNumberReader


 LineNumberInputStream Members

LineNumberInputStream Members

Class Overview | This Package | All Packages

Constructors
Name | Description
LineNumberInputStream(InputStream) | Constructs a newline number input stream that reads its input from the specified input stream.

Methods
Name | Description
available() | Returns the number of bytes that can be read from this input stream without blocking.
getLineNumber() | Returns the current line number.
mark(int) | Marks the current position in this input stream.
read() | Reads the next byte of data from this input stream.
read(byte[], int, int) | Reads up to len bytes of data from this input stream into an array of bytes.
reset() | Repositions this stream to the position at the time the mark method was last called on this input stream.
setLineNumber(int) | Sets the line number to the specified argument.
skip(long) | Skips over and discards n bytes of data from the input stream.


 LineNumberInputStream.LineNumberInputStream

LineNumberInputStream.LineNumberInputStream

Class Overview | Class Members | This Package | All Packages

Syntax
public LineNumberInputStream( InputStream in )
Parameters
in
the underlying input stream.
Description
Constructs a newline number input stream that reads its input from the specified input stream.


 LineNumberInputStream.available

LineNumberInputStream.available

Class Overview | Class Members | This Package | All Packages

Syntax
public int available() throws IOException
Returns
the number of bytes that can be read from this input stream without blocking.
Description
Returns the number of bytes that can be read from this input stream without blocking.

Note that if the underlying input stream is able to supply k input characters without blocking, the LineNumberInputStream can guarantee only to provide k/2 characters without blocking, because the k characters from the underlyhing input stream might consist of k/2 pairs of '\r' and '\n', which are converted to just k/2 '\n' characters.

Exceptions
IOException if an I/O error occurs.
Overrides
available in class FilterInputStream
See Also
in


 LineNumberInputStream.getLineNumber

LineNumberInputStream.getLineNumber

Class Overview | Class Members | This Package | All Packages

Syntax
public int getLineNumber()
Returns
the current line number.
Description
Returns the current line number.


 LineNumberInputStream.mark

LineNumberInputStream.mark

Class Overview | Class Members | This Package | All Packages

Syntax
public void mark( int readlimit )
Parameters
readlimit
the maximum limit of bytes that can be read before the mark position becomes invalid.
Description
Marks the current position in this input stream. A subsequent call to the reset method repositions this stream at the last marked position so that subsequent reads re-read the same bytes.

The mark method of LineNumberInputStream remembers the current line number in a private variable, and then calls the mark method of the underlying input stream.

Overrides
mark in class FilterInputStream
See Also
in, reset


 LineNumberInputStream.read

LineNumberInputStream.read

Class Overview | Class Members | This Package | All Packages

Syntax 1
public int read() throws IOException
Returns
the next byte of data, or -1 if the end of this stream is reached.
Description
Reads the next byte of data from this input stream. The value byte is returned as an int in the range 0 to 255. If no byte is available because the end of the stream has been reached, the value -1 is returned. This method blocks until input data is available, the end of the stream is detected, or an exception is thrown.

The read method of LineNumberInputStream calls the read method of the underlying input stream. It checks for carriage returns and newline characters in the input, and modifies the current line number as appropriate. A carriage-return character or a carriage return followed by a newline character are both converted into a single newline character.

Exceptions
IOException if an I/O error occurs.
Overrides
read in class FilterInputStream
See Also
in, getLineNumber

Syntax 2
public int read( byte b[], int off, int len ) throws IOException
Parameters
b
the buffer into which the data is read.
off
the start offset of the data.
len
the maximum number of bytes read.
Returns
the total number of bytes read into the buffer, or -1 if there is no more data because the end of this stream has been reached.
Description
Reads up to len bytes of data from this input stream into an array of bytes. This method blocks until some input is available.

The read method of LineNumberInputStream repeatedly calls the read method of zero arguments to fill in the byte array.

Exceptions
IOException if an I/O error occurs.
Overrides
read in class FilterInputStream
See Also
read


 LineNumberInputStream.reset

LineNumberInputStream.reset

Class Overview | Class Members | This Package | All Packages

Syntax
public void reset() throws IOException
Description
Repositions this stream to the position at the time the mark method was last called on this input stream.

The reset method of LineNumberInputStream resets the line number to be the line number at the time the mark method was called, and then calls the reset method of the underlying input stream.

Stream marks are intended to be used in situations where you need to read ahead a little to see what's in the stream. Often this is most easily done by invoking some general parser. If the stream is of the type handled by the parser, it just chugs along happily. If the stream is not of that type, the parser should toss an exception when it fails, which, if it happens within readlimit bytes, allows the outer code to reset the stream and try another parser.

Exceptions
IOException if an I/O error occurs.
Overrides
reset in class FilterInputStream
See Also
in, mark


 LineNumberInputStream.setLineNumber

LineNumberInputStream.setLineNumber

Class Overview | Class Members | This Package | All Packages

Syntax
public void setLineNumber( int lineNumber )
Parameters
lineNumber
the new line number.
Description
Sets the line number to the specified argument.


 LineNumberInputStream.skip

LineNumberInputStream.skip

Class Overview | Class Members | This Package | All Packages

Syntax
public long skip( long n ) throws IOException
Parameters
n
the number of bytes to be skipped.
Returns
the actual number of bytes skipped.
Description
Skips over and discards n bytes of data from the input stream. The skip method may, for a variety of reasons, end up skipping over some smaller number of bytes, possibly 0. The actual number of bytes skipped is returned.

The skip method of LineNumberInputStream creates a byte array of length n and then reads into it until n bytes have been read or the end of the stream has been reached.

Exceptions
IOException if an I/O error occurs.
Overrides
skip in class FilterInputStream


 Class LineNumberReader

Class java.io.LineNumberReader

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.Reader
           |
           +----java.io.BufferedReader
                   |
                   +----java.io.LineNumberReader

public class LineNumberReader
extends BufferedReader

A buffered character-input stream that keeps track of line numbers. A line is considered to be terminated by any one of a line feed ('\n'), a carriage return ('\r'), or a carriage return followed immediately by a linefeed.


 LineNumberReader Members

LineNumberReader Members

Class Overview | This Package | All Packages

Constructors
Name | Description
LineNumberReader(Reader) | Create a new line-numbering reader, using the default input-buffer size.
LineNumberReader(Reader, int) | Create a new line-numbering reader, reading characters into a buffer of the given size.

Methods
Name | Description
getLineNumber() | Get the current line number.
mark(int) | Mark the present position in the stream.
read() | Read a single character.
read(char[], int, int) | Read characters into a portion of an array.
readLine() | Read a line of text.
reset() | Reset the stream to the most recent mark.
setLineNumber(int) | Set the current line number.
skip(long) | Skip characters.


 LineNumberReader.LineNumberReader

LineNumberReader.LineNumberReader

Class Overview | Class Members | This Package | All Packages

Syntax 1
public LineNumberReader( Reader in )
Description
Create a new line-numbering reader, using the default input-buffer size.

Syntax 2
public LineNumberReader( Reader in, int sz )
Description
Create a new line-numbering reader, reading characters into a buffer of the given size.


 LineNumberReader.getLineNumber

LineNumberReader.getLineNumber

Class Overview | Class Members | This Package | All Packages

Syntax
public int getLineNumber()
Description
Get the current line number.


 LineNumberReader.mark

LineNumberReader.mark

Class Overview | Class Members | This Package | All Packages

Syntax
public void mark( int readAheadLimit ) throws IOException
Parameters
readAheadLimit
Limit on the number of characters that may be read while still preserving the mark. After reading this many characters, attempting to reset the stream may fail.
Description
Mark the present position in the stream. Subsequent calls to reset() will attempt to reposition the stream to this point, and will also reset the line number appropriately.

Exceptions
IOException If an I/O error occurs
Overrides
mark in class BufferedReader


 LineNumberReader.read

LineNumberReader.read

Class Overview | Class Members | This Package | All Packages

Syntax 1
public int read() throws IOException
Returns
The character read, or -1 if the end of the stream has been reached
Description
Read a single character. Line terminators are compressed into single newline ('\n') characters.

Exceptions
IOException If an I/O error occurs
Overrides
read in class BufferedReader

Syntax 2
public int read( char cbuf[], int off, int len ) throws IOException
Parameters
cbuf
Destination buffer
off
Offset at which to start storing characters
len
Maximum number of characters to read
Returns
The number of bytes read, or -1 if the end of the stream has already been reached
Description
Read characters into a portion of an array.

Exceptions
IOException If an I/O error occurs
Overrides
read in class BufferedReader


 LineNumberReader.readLine

LineNumberReader.readLine

Class Overview | Class Members | This Package | All Packages

Syntax
public String readLine() throws IOException
Returns
A String containing the contents of the line, not including any line-termination characters, or null if the end of the stream has been reached
Description
Read a line of text. A line is considered to be terminated by any one of a line feed ('\n'), a carriage return ('\r'), or a carriage return followed immediately by a linefeed.

Exceptions
IOException If an I/O error occurs
Overrides
readLine in class BufferedReader


 LineNumberReader.reset

LineNumberReader.reset

Class Overview | Class Members | This Package | All Packages

Syntax
public void reset() throws IOException
Description
Reset the stream to the most recent mark.

Exceptions
IOException If the stream has not been marked, or if the mark has been invalidated
Overrides
reset in class BufferedReader


 LineNumberReader.setLineNumber

LineNumberReader.setLineNumber

Class Overview | Class Members | This Package | All Packages

Syntax
public void setLineNumber( int lineNumber )
Description
Set the current line number.


 LineNumberReader.skip

LineNumberReader.skip

Class Overview | Class Members | This Package | All Packages

Syntax
public long skip( long n ) throws IOException
Parameters
n
The number of characters to skip
Returns
The number of characters actually skipped
Description
Skip characters.

Exceptions
IOException If an I/O error occurs
Overrides
skip in class BufferedReader


 Class NotActiveException

Class java.io.NotActiveException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.io.IOException
                           |
                           +----java.io.ObjectStreamException
                                   |
                                   +----java.io.NotActiveException

public class NotActiveException
extends ObjectStreamException

The NotActiveException is thrown when serialization or deserialization is not active.


 NotActiveException Members

NotActiveException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
NotActiveException() | Constructor to create a new NotActiveException with no reason.
NotActiveException(String) | Constructor to create a new NotActiveException with the reason given.


 NotActiveException.NotActiveException

NotActiveException.NotActiveException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public NotActiveException( String reason )
Description
Constructor to create a new NotActiveException with the reason given.

Syntax 2
public NotActiveException()
Description
Constructor to create a new NotActiveException with no reason.


 Class NotSerializableException

Class java.io.NotSerializableException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.io.IOException
                           |
                           +----java.io.ObjectStreamException
                                   |
                                   +----java.io.NotSerializableException

public class NotSerializableException
extends ObjectStreamException

Raised by a class or the serialization runtime when a class may not be serialized. The argument should be the name of the class.


 NotSerializableException Members

NotSerializableException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
NotSerializableException() |
NotSerializableException(String) |


 NotSerializableException.NotSerializableException

NotSerializableException.NotSerializableException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public NotSerializableException( String classname )

Syntax 2
public NotSerializableException()


 Interface ObjectInput

Interface java.io.ObjectInput

Interface Members | This Package | All Packages

public interface ObjectInput
extends DataInput

ObjectInput extends the DataInput interface to include the writing of objects. DataInput includes methods for the input of primitive types, ObjectInput extends that interface to include objects, arrays, and Strings.

See Also:
InputStream, ObjectOutputStream, ObjectInputStream


 ObjectInput Members

ObjectInput Members

Interface Overview | This Package | All Packages

Methods
Name | Description
available() | Returns the number of bytes that can be read without blocking.
close() | Closes the input stream.
read() | Reads a byte of data.
read(byte[]) | Reads into an array of bytes.
read(byte[], int, int) | Reads into an array of bytes.
readObject() | Read and return an object.
skip(long) | Skips n bytes of input.


 ObjectInput.available

ObjectInput.available

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int available() throws IOException
Returns
the number of available bytes.
Description
Returns the number of bytes that can be read without blocking.


 ObjectInput.close

ObjectInput.close

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void close() throws IOException
Description
Closes the input stream. Must be called to release any resources associated with the stream.

Exceptions
IOException If an I/O error has occurred.


 ObjectInput.read

ObjectInput.read

Interface Overview | Interface Members | This Package | All Packages

Syntax 1
public abstract int read() throws IOException
Returns
the byte read, or -1 if the end of the stream is reached.
Description
Reads a byte of data. This method will block if no input is available.

Exceptions
IOException If an I/O error has occurred.

Syntax 2
public abstract int read( byte b[] ) throws IOException
Parameters
b
the buffer into which the data is read
Returns
the actual number of bytes read, -1 is returned when the end of the stream is reached.
Description
Reads into an array of bytes. This method will block until some input is available.

Exceptions
IOException If an I/O error has occurred.

Syntax 3
public abstract int read( byte b[], int off, int len ) throws IOException
Parameters
b
the buffer into which the data is read
off
the start offset of the data
len
the maximum number of bytes read
Returns
the actual number of bytes read, -1 is returned when the end of the stream is reached.
Description
Reads into an array of bytes. This method will block until some input is available.

Exceptions
IOException If an I/O error has occurred.


 ObjectInput.readObject

ObjectInput.readObject

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Object readObject() throws ClassNotFoundException, IOException
Description
Read and return an object. The class that implements this interface defines where the object is "read" from.

Exceptions
ClassNotFoundException If the class of a serialized object cannot be found.
Exceptions
IOException If any of the usual Input/Output related exceptions occur.


 ObjectInput.skip

ObjectInput.skip

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract long skip( long n ) throws IOException
Parameters
n
the number of bytes to be skipped
Returns
the actual number of bytes skipped.
Description
Skips n bytes of input.

Exceptions
IOException If an I/O error has occurred.


 Class ObjectInputStream

Class java.io.ObjectInputStream

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.InputStream
           |
           +----java.io.ObjectInputStream

public class ObjectInputStream
extends InputStream
implements ObjectInput, ObjectStreamConstants

An ObjectInputStream deserializes primitive data and objects previously written using an ObjectOutputStream. ObjectOutputStream and ObjectInputStream can provide an application with persistent storage for graphs of objects when used with a FileOutputStream and FileInputStream respectively. ObjectInputStream is used to recover those objects previously serialized. Other uses include passing objects between hosts using a socket stream or for marshaling and unmarshaling arguments and parameters in a remote communication system.

ObjectInputStream ensures that the types of all objects in the graph created from the stream match the classes present in the Java Virtual Machine. Classes are loaded as required using the standard mechanisms.

Only objects that support the java.io.Serializable or java.io.Externalizable interface can be read from streams. The method readObject is used to read an object from the stream. Java's safe casting should be used to get the desired type. In Java, strings and arrays are objects and are treated as objects during serialization. When read they need to be cast to the expected type.

Primitive data types can be read from the stream using the appropriate method on DataInput.

The default deserialization mechanism for objects restores the contents of each field to the value and type it had when it was written. Fields declared as transient or static are ignored by the deserialization process. References to other objects cause those objects to be read from the stream as necessary. Graphs of objects are restored correctly using a reference sharing mechanism. New objects are always allocated when deserializing, which prevents existing objects from being overwritten.

Reading an object is analogous to running the constructors of a new object. Memory is allocated for the object and initialized to zero (NULL). No-arg constructors are invoked for the non-serializable classes and then the fields of the serializable classes are restored from the stream starting with the serializable class closest to java.lang.object and finishing with the object's most specifiec class.

For example to read from a stream as written by the example in ObjectOutputStream:

    FileInputStream istream = new FileInputStream("t.tmp");
    ObjectInputStream p = new ObjectInputStream(istream);
    int i = p.readInt();
    String today = (String)p.readObject();
    Date date = (Date)p.readObject();
    istream.close();
Classes control how they are serialized by implementing either the java.io.Serializable or java.io.Externalizable interfaces.

Implementing the Serializable interface allows object serialization to save and restore the entire state of the object and it allows classes to evolve between the time the stream is written and the time it is read. It automatically traverses references between objects, saving and restoring entire graphs. Serializable classes that require special handling during the serialization and deserialization process should implement both of these methods:

 private void writeObject(java.io.ObjectOutputStream stream)
     throws IOException;
 private void readObject(java.io.ObjectInputStream stream)
     throws IOException, ClassNotFoundException;

The readObject method is responsible for reading and restoring the state of the object for its particular class using data written to the stream by the corresponding writeObject method. The method does not need to concern itself with the state belonging to its superclasses or subclasses. State is restored by reading data from the ObjectInputStream for the individual fields and making assignments to the appropriate fields of the object. Reading primitive data types is supported by DataInput.

Serialization does not read or assign values to the fields of any object that does not implement the java.io.Serializable interface. Subclasses of Objects that are not serializable can be serializable. In this case the non-serializable class must have a no-arg constructor to allow its fields to be initialized. In this case it is the responsibility of the subclass to save and restore the state of the non-serializable class. It is frequently the case that the fields of that class are accessible (public, package, or protected) or that there are get and set methods that can be used to restore the state.

Any exception that occurs while deserializing an object will be caught by the ObjectInputStream and abort the reading process.

Implementing the Externalizable interface allows the object to assume complete control over the contents and format of the object's serialized form. The methods of the Externalizable interface, writeExternal and readExternal, are called to save and restore the objects state. When implemented by a class they can write and read their own state using all of the methods of ObjectOutput and ObjectInput. It is the responsibility of the objects to handle any versioning that occurs.

See Also:
DataInput, ObjectOutputStream, Serializable


 ObjectInputStream Members

ObjectInputStream Members

Class Overview | This Package | All Packages

Constructors
Name | Description
ObjectInputStream(InputStream) | Create an ObjectInputStream that reads from the specified InputStream.

Methods
Name | Description
available() | Returns the number of bytes that can be read without blocking.
close() | Closes the input stream.
defaultReadObject() | Read the non-static and non-transient fields of the current class from this stream.
enableResolveObject(boolean) | Enable the stream to allow objects read from the stream to be replaced.
read() | Reads a byte of data.
read(byte[], int, int) | Reads into an array of bytes.
readBoolean() | Reads in a boolean.
readByte() | Reads an 8 bit byte.
readChar() | Reads a 16 bit char.
readDouble() | Reads a 64 bit double.
readFloat() | Reads a 32 bit float.
readFully(byte[]) | Reads bytes, blocking until all bytes are read.
readFully(byte[], int, int) | Reads bytes, blocking until all bytes are read.
readInt() | Reads a 32 bit int.
readLine() | Reads in a line that has been terminated by a \n, \r, \r\n or EOF.
readLong() | Reads a 64 bit long.
readObject() | Read an object from the ObjectInputStream.
readShort() | Reads a 16 bit short.
readStreamHeader() | The readStreamHeader method is provided to allow subclasses to read and verify their own stream headers.
readUnsignedByte() | Reads an unsigned 8 bit byte.
readUnsignedShort() | Reads an unsigned 16 bit short.
readUTF() | Reads a UTF format String.
registerValidation(ObjectInputValidation, int) | Register an object to be validated before the graph is returned.
resolveClass(ObjectStreamClass) | Subclasses may implement this method to allow classes to be fetched from an alternate source.
resolveObject(Object) | This method will allow trusted subclasses of ObjectInputStream to substitute one object for another during deserialization.
skipBytes(int) | Skips bytes, block until all bytes are skipped.


 ObjectInputStream.ObjectInputStream

ObjectInputStream.ObjectInputStream

Class Overview | Class Members | This Package | All Packages

Syntax
public ObjectInputStream( InputStream in ) throws IOException, StreamCorruptedException
Description
Create an ObjectInputStream that reads from the specified InputStream. The stream header containing the magic number and version number are read from the stream and verified. This method will block until the corresponding ObjectOutputStream has written and flushed the header.

Exceptions
StreamCorruptedException The version or magic number are incorrect.
Exceptions
IOException An exception occurred in the underlying stream.


 ObjectInputStream.available

ObjectInputStream.available

Class Overview | Class Members | This Package | All Packages

Syntax
public int available() throws IOException
Returns
the number of available bytes.
Description
Returns the number of bytes that can be read without blocking.

Overrides
available in class InputStream


 ObjectInputStream.close

ObjectInputStream.close

Class Overview | Class Members | This Package | All Packages

Syntax
public void close() throws IOException
Description
Closes the input stream. Must be called to release any resources associated with the stream.

Exceptions
IOException If an I/O error has occurred.
Overrides
close in class InputStream


 ObjectInputStream.defaultReadObject

ObjectInputStream.defaultReadObject

Class Overview | Class Members | This Package | All Packages

Syntax
public final void defaultReadObject() throws IOException, ClassNotFoundException, NotActiveException
Description
Read the non-static and non-transient fields of the current class from this stream. This may only be called from the readObject method of the class being deserialized. It will throw the NotActiveException if it is called otherwise.

Exceptions
ClassNotFoundException if the class of a serialized object could not be found.
Exceptions
IOException if an I/O error occurs.
Exceptions
NotActiveException if the stream is not currently reading objects.


 ObjectInputStream.enableResolveObject

ObjectInputStream.enableResolveObject

Class Overview | Class Members | This Package | All Packages

Syntax
protected final boolean enableResolveObject( boolean enable ) throws SecurityException
Description
Enable the stream to allow objects read from the stream to be replaced. If the stream is a trusted class it is allowed to enable replacment. Trusted classes are those classes with a classLoader equals null.

When enabled the resolveObject method is called for every object being deserialized.

Exceptions
SecurityException The classloader of this stream object is non-null.


 ObjectInputStream.read

ObjectInputStream.read

Class Overview | Class Members | This Package | All Packages

Syntax 1
public int read() throws IOException
Returns
the byte read, or -1 if the end of the stream is reached.
Description
Reads a byte of data. This method will block if no input is available.

Exceptions
IOException If an I/O error has occurred.
Overrides
read in class InputStream

Syntax 2
public int read( byte data[], int offset, int length ) throws IOException
Parameters
b
the buffer into which the data is read
off
the start offset of the data
len
the maximum number of bytes read
Returns
the actual number of bytes read, -1 is returned when the end of the stream is reached.
Description
Reads into an array of bytes. This method will block until some input is available.

Exceptions
IOException If an I/O error has occurred.
Overrides
read in class InputStream


 ObjectInputStream.readBoolean

ObjectInputStream.readBoolean

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean readBoolean() throws IOException
Returns
the boolean read.
Description
Reads in a boolean.

Exceptions
EOFException If end of file is reached.
Exceptions
IOException If other I/O error has occurred.


 ObjectInputStream.readByte

ObjectInputStream.readByte

Class Overview | Class Members | This Package | All Packages

Syntax
public byte readByte() throws IOException
Returns
the 8 bit byte read.
Description
Reads an 8 bit byte.

Exceptions
EOFException If end of file is reached.
Exceptions
IOException If other I/O error has occurred.


 ObjectInputStream.readChar

ObjectInputStream.readChar

Class Overview | Class Members | This Package | All Packages

Syntax
public char readChar() throws IOException
Returns
the 16 bit char read.
Description
Reads a 16 bit char.

Exceptions
EOFException If end of file is reached.
Exceptions
IOException If other I/O error has occurred.


 ObjectInputStream.readDouble

ObjectInputStream.readDouble

Class Overview | Class Members | This Package | All Packages

Syntax
public double readDouble() throws IOException
Returns
the 64 bit double read.
Description
Reads a 64 bit double.

Exceptions
EOFException If end of file is reached.
Exceptions
IOException If other I/O error has occurred.


 ObjectInputStream.readFloat

ObjectInputStream.readFloat

Class Overview | Class Members | This Package | All Packages

Syntax
public float readFloat() throws IOException
Returns
the 32 bit float read.
Description
Reads a 32 bit float.

Exceptions
EOFException If end of file is reached.
Exceptions
IOException If other I/O error has occurred.


 ObjectInputStream.readFully

ObjectInputStream.readFully

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void readFully( byte data[] ) throws IOException
Parameters
b
the buffer into which the data is read
Description
Reads bytes, blocking until all bytes are read.

Exceptions
EOFException If end of file is reached.
Exceptions
IOException If other I/O error has occurred.

Syntax 2
public void readFully( byte data[], int offset, int size ) throws IOException
Parameters
b
the buffer into which the data is read
off
the start offset of the data
len
the maximum number of bytes to read
Description
Reads bytes, blocking until all bytes are read.

Exceptions
EOFException If end of file is reached.
Exceptions
IOException If other I/O error has occurred.


 ObjectInputStream.readInt

ObjectInputStream.readInt

Class Overview | Class Members | This Package | All Packages

Syntax
public int readInt() throws IOException
Returns
the 32 bit integer read.
Description
Reads a 32 bit int.

Exceptions
EOFException If end of file is reached.
Exceptions
IOException If other I/O error has occurred.


 ObjectInputStream.readLine

ObjectInputStream.readLine

Class Overview | Class Members | This Package | All Packages

Syntax
public String readLine() throws IOException
Returns
a String copy of the line.
Description
Reads in a line that has been terminated by a \n, \r, \r\n or EOF.


 ObjectInputStream.readLong

ObjectInputStream.readLong

Class Overview | Class Members | This Package | All Packages

Syntax
public long readLong() throws IOException
Returns
the read 64 bit long.
Description
Reads a 64 bit long.

Exceptions
EOFException If end of file is reached.
Exceptions
IOException If other I/O error has occurred.


 ObjectInputStream.readObject

ObjectInputStream.readObject

Class Overview | Class Members | This Package | All Packages

Syntax
public final Object readObject() throws OptionalDataException, ClassNotFoundException, IOException
Description
Read an object from the ObjectInputStream. The class of the object, the signature of the class, and the values of the non-transient and non-static fields of the class and all of its supertypes are read. Default deserializing for a class can be overriden using the writeObject and readObject methods. Objects referenced by this object are read transitively so that a complete equivalent graph of objects is reconstructed by readObject.

The root object is completly restored when all of its fields and the objects it references are completely restored. At this point the object validation callbacks are executed in order based on their registered priorities. The callbacks are registered by objects (in the readObject special methods) as they are individually restored. Exceptions are thrown for problems with the InputStream and for classes that should not be deserialized. All exceptions are fatal to the InputStream and leave it in an indeterminate state; it is up to the caller to ignore or recover the stream state.

Exceptions
ClassNotFoundException Class of a serialized object cannot be found.
Exceptions
InvalidClassException Something is wrong with a class used by serialization.
Exceptions
StreamCorruptedException Control information in the stream is inconsistent.
Exceptions
OptionalDataException Primitive data was found in the stream instead of objects.
Exceptions
IOException Any of the usual Input/Output related exceptions.


 ObjectInputStream.readShort

ObjectInputStream.readShort

Class Overview | Class Members | This Package | All Packages

Syntax
public short readShort() throws IOException
Returns
the 16 bit short read.
Description
Reads a 16 bit short.

Exceptions
EOFException If end of file is reached.
Exceptions
IOException If other I/O error has occurred.


 ObjectInputStream.readStreamHeader

ObjectInputStream.readStreamHeader

Class Overview | Class Members | This Package | All Packages

Syntax
protected void readStreamHeader() throws IOException, StreamCorruptedException
Description
The readStreamHeader method is provided to allow subclasses to read and verify their own stream headers. It reads and verifies the magic number and version number.


 ObjectInputStream.readUnsignedByte

ObjectInputStream.readUnsignedByte

Class Overview | Class Members | This Package | All Packages

Syntax
public int readUnsignedByte() throws IOException
Returns
the 8 bit byte read.
Description
Reads an unsigned 8 bit byte.

Exceptions
EOFException If end of file is reached.
Exceptions
IOException If other I/O error has occurred.


 ObjectInputStream.readUnsignedShort

ObjectInputStream.readUnsignedShort

Class Overview | Class Members | This Package | All Packages

Syntax
public int readUnsignedShort() throws IOException
Returns
the 16 bit short read.
Description
Reads an unsigned 16 bit short.

Exceptions
EOFException If end of file is reached.
Exceptions
IOException If other I/O error has occurred.


 ObjectInputStream.readUTF

ObjectInputStream.readUTF

Class Overview | Class Members | This Package | All Packages

Syntax
public String readUTF() throws IOException
Returns
the String.
Description
Reads a UTF format String.


 ObjectInputStream.registerValidation

ObjectInputStream.registerValidation

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void registerValidation( ObjectInputValidation obj, int prio ) throws NotActiveException, InvalidObjectException
Parameters
obj
the object to receive the validation callback.
prio
controls the order of callbacks;zero is a good default. Use higher numbers to be called back earlier, lower numbers for later callbacks. Within a priority, callbacks are processed in no particular order.
Description
Register an object to be validated before the graph is returned. While similar to resolveObject these validations are called after the entire graph has been reconstituted. Typically, a readObject method will register the object with the stream so that when all of the objects are restored a final set of validations can be performed.

Exceptions
NotActiveException The stream is not currently reading objects so it is invalid to register a callback.
Exceptions
InvalidObjectException The validation object is null.


 ObjectInputStream.resolveClass

ObjectInputStream.resolveClass

Class Overview | Class Members | This Package | All Packages

Syntax
protected Class resolveClass( ObjectStreamClass v ) throws IOException, ClassNotFoundException
Description
Subclasses may implement this method to allow classes to be fetched from an alternate source. The corresponding method in ObjectOutputStream is annotateClass. This method will be invoked only once for each unique class in the stream. This method can be implemented by subclasses to use an alternate loading mechanism but must return a Class object. Once returned, the serialVersionUID of the class is compared to the serialVersionUID of the serialized class. If there is a mismatch, the deserialization fails and an exception is raised.

By default the class name is resolved relative to the class that called readObject.

Exceptions
ClassNotFoundException If class of a serialized object cannot be found.


 ObjectInputStream.resolveObject

ObjectInputStream.resolveObject

Class Overview | Class Members | This Package | All Packages

Syntax
protected Object resolveObject( Object obj ) throws IOException
Description
This method will allow trusted subclasses of ObjectInputStream to substitute one object for another during deserialization. Replacing objects is disabled until enableResolveObject is called. The enableResolveObject method checks that the stream requesting to resolve object can be trusted. Every reference to serializable objects is passed to resolveObject. To insure that the private state of objects is not unintentionally exposed only trusted streams may use resolveObject.

This method is called after an object has been read but before it is returned from readObject. The default resolveObject method just returns the new object.

When a subclass is replacing objects it must insure that the substituted object is compatible with every field where the reference will be stored. Objects whose type is not a subclass of the type of the field or array element abort the serialization by raising an exception and the object is not be stored.

This method is called only once when each object is first encountered. All subsequent references to the object will be redirected to the new object.

Exceptions
IOException Any of the usual Input/Output exceptions.


 ObjectInputStream.skipBytes

ObjectInputStream.skipBytes

Class Overview | Class Members | This Package | All Packages

Syntax
public int skipBytes( int len ) throws IOException
Parameters
n
the number of bytes to be skipped
Returns
the actual number of bytes skipped.
Description
Skips bytes, block until all bytes are skipped.

Exceptions
EOFException If end of file is reached.
Exceptions
IOException If other I/O error has occurred.


 Interface ObjectInputValidation

Interface java.io.ObjectInputValidation

Interface Members | This Package | All Packages

public interface ObjectInputValidation

Callback interface to allow validation of objects within a graph. Allows an object to be called when a complete graph of objects has been deserialized.

See Also:
ObjectInputStream, registerValidation


 ObjectInputValidation Members

ObjectInputValidation Members

Interface Overview | This Package | All Packages

Methods
Name | Description
validateObject() | Validates the object


 ObjectInputValidation.validateObject

ObjectInputValidation.validateObject

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void validateObject() throws InvalidObjectException
Description
Validates the object

Exceptions
InvalidObjectException If the object cannot validate itself.


 Interface ObjectOutput

Interface java.io.ObjectOutput

Interface Members | This Package | All Packages

public interface ObjectOutput
extends DataOutput

ObjectOutput extends the DataOutput interface to include writing of objects. DataOutput includes methods for output of primitive types, ObjectOutput extends that interface to include objects, arrays, and Strings.

See Also:
InputStream, ObjectOutputStream, ObjectInputStream


 ObjectOutput Members

ObjectOutput Members

Interface Overview | This Package | All Packages

Methods
Name | Description
close() | Closes the stream.
flush() | Flushes the stream.
write(byte[]) | Writes an array of bytes.
write(byte[], int, int) | Writes a sub array of bytes.
write(int) | Writes a byte.
writeObject(Object) | Write an object to the underlying storage or stream.


 ObjectOutput.close

ObjectOutput.close

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void close() throws IOException
Description
Closes the stream. This method must be called to release any resources associated with the stream.

Exceptions
IOException If an I/O error has occurred.


 ObjectOutput.flush

ObjectOutput.flush

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void flush() throws IOException
Description
Flushes the stream. This will write any buffered output bytes.

Exceptions
IOException If an I/O error has occurred.


 ObjectOutput.write

ObjectOutput.write

Interface Overview | Interface Members | This Package | All Packages

Syntax 1
public abstract void write( int b ) throws IOException
Parameters
b
the byte
Description
Writes a byte. This method will block until the byte is actually written.

Exceptions
IOException If an I/O error has occurred.

Syntax 2
public abstract void write( byte b[] ) throws IOException
Parameters
b
the data to be written
Description
Writes an array of bytes. This method will block until the bytes are actually written.

Exceptions
IOException If an I/O error has occurred.

Syntax 3
public abstract void write( byte b[], int off, int len ) throws IOException
Parameters
b
the data to be written
off
the start offset in the data
len
the number of bytes that are written
Description
Writes a sub array of bytes.

Exceptions
IOException If an I/O error has occurred.


 ObjectOutput.writeObject

ObjectOutput.writeObject

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void writeObject( Object obj ) throws IOException
Description
Write an object to the underlying storage or stream. The class that implements this interface defines how the object is written.

Exceptions
IOException Any of the usual Input/Output related exceptions.


 Class ObjectOutputStream

Class java.io.ObjectOutputStream

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.OutputStream
           |
           +----java.io.ObjectOutputStream

public class ObjectOutputStream
extends OutputStream
implements ObjectOutput, ObjectStreamConstants

An ObjectOutputStream writes primitive data types and graphs of Java objects to an OutputStream. The objects can be read (reconstituted) using an ObjectInputStream. Persistent storage of objects can be accomplished by using a file for the stream. If the stream is a network socket stream, the objects can be reconsituted on another host or in another process.

Only objects that support the java.io.Serializable interface can be written to streams. The class of each serializable object is encoded including the class name and signature of the class, the values of the object's fields and arrays, and the closure of any other objects referenced from the initial objects.

The method writeObject is used to write an object to the stream. Any object, including Strings and arrays, is written with writeObject. Multiple objects or primitives can be written to the stream. The objects must be read back from the corresponding ObjectInputstream with the same types and in the same order as they were written.

Primitive data types can also be written to the stream using the appropriate methods from DataOutput. Strings can also be written using the writeUTF method.

The default serialization mechanism for an object writes the class of the object, the class signature, and the values of all non-transient and non-static fields. References to other objects (except in transient or static fields) cause those objects to be written also. Multiple references to a single object are encoded using a reference sharing mechanism so that graphs of objects can be restored to the same shape as when the original was written.

For example to write an object that can be read by the example in ObjectInputStream:

    FileOutputStream ostream = new FileOutputStream("t.tmp");
    ObjectOutputStream p = new ObjectOutputStream(ostream);
    p.writeInt(12345);
    p.writeObject("Today");
    p.writeObject(new Date());
    p.flush();
    ostream.close();
Classes that require special handling during the serialization and deserialization process must implement special methods with these exact signatures:

 private void readObject(java.io.ObjectInputStream stream)
     throws IOException, ClassNotFoundException;
 private void writeObject(java.io.ObjectOutputStream stream)
     throws IOException

The writeObject method is responsible for writing the state of the object for its particular class so that the corresponding readObject method can restore it. The method does not need to concern itself with the state belonging to the object's superclasses or subclasses. State is saved by writing the individual fields to the ObjectOutputStream using the writeObject method or by using the methods for primitive data types supported by DataOutput.

Serialization does not write out the fields of any object that does not implement the java.io.Serializable interface. Subclasses of Objects that are not serializable can be serializable. In this case the non-serializable class must have a no-arg constructor to allow its fields to be initialized. In this case it is the responsibility of the subclass to save and restore the state of the non-serializable class. It is frequently the case that the fields of that class are accessible (public, package, or protected) or that there are get and set methods that can be used to restore the state.

Serialization of an object can be prevented by implementing writeObject and readObject methods that throw the NotSerializableException. The exception will be caught by the ObjectOutputStream and abort the serialization process. Implementing the Externalizable interface allows the object to assume complete control over the contents and format of the object's serialized form. The methods of the Externalizable interface, writeExternal and readExternal, are called to save and restore the objects state. When implemented by a class they can write and read their own state using all of the methods of ObjectOutput and ObjectInput. It is the responsibility of the objects to handle any versioning that occurs.

See Also:
DataOutput, ObjectInputStream, Serializable, Externalizable


 ObjectOutputStream Members

ObjectOutputStream Members

Class Overview | This Package | All Packages

Constructors
Name | Description
ObjectOutputStream(OutputStream) | Creates an ObjectOutputStream that writes to the specified OutputStream.

Methods
Name | Description
annotateClass(Class) | Subclasses may implement this method to allow class data to be stored in the stream.
close() | Closes the stream.
defaultWriteObject() | Write the non-static and non-transient fields of the current class to this stream.
drain() | Drain any buffered data in ObjectOutputStream.
enableReplaceObject(boolean) | Enable the stream to do replacement of objects in the stream.
flush() | Flushes the stream.
replaceObject(Object) | This method will allow trusted subclasses of ObjectOutputStream to substitute one object for another during serialization.
reset() | Reset will disregard the state of any objects already written to the stream.
write(byte[]) | Writes an array of bytes.
write(byte[], int, int) | Writes a sub array of bytes.
write(int) | Writes a byte.
writeBoolean(boolean) | Writes a boolean.
writeByte(int) | Writes an 8 bit byte.
writeBytes(String) | Writes a String as a sequence of bytes.
writeChar(int) | Writes a 16 bit char.
writeChars(String) | Writes a String as a sequence of chars.
writeDouble(double) | Writes a 64 bit double.
writeFloat(float) | Writes a 32 bit float.
writeInt(int) | Writes a 32 bit int.
writeLong(long) | Writes a 64 bit long.
writeObject(Object) | Write the specified object to the ObjectOutputStream.
writeShort(int) | Writes a 16 bit short.
writeStreamHeader() | The writeStreamHeader method is provided so subclasses can append or prepend their own header to the stream.
writeUTF(String) | Writes a String in UTF format.


 ObjectOutputStream.ObjectOutputStream

ObjectOutputStream.ObjectOutputStream

Class Overview | Class Members | This Package | All Packages

Syntax
public ObjectOutputStream( OutputStream out ) throws IOException
Description
Creates an ObjectOutputStream that writes to the specified OutputStream. The stream header is written to the stream. The caller may want to call flush immediately so that the corresponding ObjectInputStream can read the header immediately.

Exceptions
IOException Any exception thrown by the underlying OutputStream.


 ObjectOutputStream.annotateClass

ObjectOutputStream.annotateClass

Class Overview | Class Members | This Package | All Packages

Syntax
protected void annotateClass( Class cl ) throws IOException
Description
Subclasses may implement this method to allow class data to be stored in the stream. By default this method does nothing. The corresponding method in ObjectInputStream is resolveClass. This method is called exactly once for each unique class in the stream. The class name and signature will have already been written to the stream. This method may make free use of the ObjectOutputStream to save any representation of the class it deems suitable (for example, the bytes of the class file). The resolveClass method in the corresponding subclass of ObjectInputStream must read and use any data or objects written by annotateClass. annotateClass is called only for normal classes. Arrays are not normal classes.

Exceptions
IOException Any exception thrown by the underlying OutputStream.


 ObjectOutputStream.close

ObjectOutputStream.close

Class Overview | Class Members | This Package | All Packages

Syntax
public void close() throws IOException
Description
Closes the stream. This method must be called to release any resources associated with the stream.

Exceptions
IOException If an I/O error has occurred.
Overrides
close in class OutputStream


 ObjectOutputStream.defaultWriteObject

ObjectOutputStream.defaultWriteObject

Class Overview | Class Members | This Package | All Packages

Syntax
public final void defaultWriteObject() throws IOException
Description
Write the non-static and non-transient fields of the current class to this stream. This may only be called from the writeObject method of the class being serialized. It will throw the NotActiveException if it is called otherwise.


 ObjectOutputStream.drain

ObjectOutputStream.drain

Class Overview | Class Members | This Package | All Packages

Syntax
protected void drain() throws IOException
Description
Drain any buffered data in ObjectOutputStream. Similar to flush but does not propagate the flush to the underlaying stream.


 ObjectOutputStream.enableReplaceObject

ObjectOutputStream.enableReplaceObject

Class Overview | Class Members | This Package | All Packages

Syntax
protected final boolean enableReplaceObject( boolean enable ) throws SecurityException
Description
Enable the stream to do replacement of objects in the stream. If the stream is a trusted class it is allowed to enable replacement. Trusted classes are those classes with a classLoader equals null.

When enabled the replaceObject method is called for every object being serialized.

Exceptions
SecurityException The classloader of this stream object is non-null.


 ObjectOutputStream.flush

ObjectOutputStream.flush

Class Overview | Class Members | This Package | All Packages

Syntax
public void flush() throws IOException
Description
Flushes the stream. This will write any buffered output bytes and flush through to the underlying stream.

Exceptions
IOException If an I/O error has occurred.
Overrides
flush in class OutputStream


 ObjectOutputStream.replaceObject

ObjectOutputStream.replaceObject

Class Overview | Class Members | This Package | All Packages

Syntax
protected Object replaceObject( Object obj ) throws IOException
Description
This method will allow trusted subclasses of ObjectOutputStream to substitute one object for another during serialization. Replacing objects is disabled until enableReplaceObject is called. The enableReplaceObject method checks that the stream requesting to do replacment can be trusted. Every reference to serializable objects is passed to replaceObject. To insure that the private state of objects is not unintentionally exposed only trusted streams may use replaceObject.

When a subclass is replacing objects it must insure that either a complementary substitution must be made during deserialization or that the substituted object is compatible with every field where the reference will be stored. Objects whose type is not a subclass of the type of the field or array element abort the serialization by raising an exception and the object is not be stored.

This method is called only once when each object is first encountered. All subsequent references to the object will be redirected to the new object. This method should return the object to be substituted or the original object.

Null can be returned as the object to be substituted, but may cause NullReferenceException in classes that contain references to the original object since they may be expecting an object instead of null.

Exceptions
IOException Any exception thrown by the underlying OutputStream.


 ObjectOutputStream.reset

ObjectOutputStream.reset

Class Overview | Class Members | This Package | All Packages

Syntax
public void reset() throws IOException
Description
Reset will disregard the state of any objects already written to the stream. The state is reset to be the same as a new ObjectOutputStream. The current point in the stream is marked as reset so the corresponding ObjectInputStream will be reset at the same point. Objects previously written to the stream will not be refered to as already being in the stream. They will be written to the stream again.


 ObjectOutputStream.write

ObjectOutputStream.write

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void write( int data ) throws IOException
Parameters
b
the byte
Description
Writes a byte. This method will block until the byte is actually written.

Exceptions
IOException If an I/O error has occurred.
Overrides
write in class OutputStream

Syntax 2
public void write( byte b[] ) throws IOException
Parameters
b
the data to be written
Description
Writes an array of bytes. This method will block until the bytes are actually written.

Exceptions
IOException If an I/O error has occurred.
Overrides
write in class OutputStream

Syntax 3
public void write( byte b[], int off, int len ) throws IOException
Parameters
b
the data to be written
off
the start offset in the data
len
the number of bytes that are written
Description
Writes a sub array of bytes.

Exceptions
IOException If an I/O error has occurred.
Overrides
write in class OutputStream


 ObjectOutputStream.writeBoolean

ObjectOutputStream.writeBoolean

Class Overview | Class Members | This Package | All Packages

Syntax
public void writeBoolean( boolean data ) throws IOException
Parameters
data
the boolean to be written
Description
Writes a boolean.


 ObjectOutputStream.writeByte

ObjectOutputStream.writeByte

Class Overview | Class Members | This Package | All Packages

Syntax
public void writeByte( int data ) throws IOException
Parameters
data
the byte value to be written
Description
Writes an 8 bit byte.


 ObjectOutputStream.writeBytes

ObjectOutputStream.writeBytes

Class Overview | Class Members | This Package | All Packages

Syntax
public void writeBytes( String data ) throws IOException
Parameters
s
the String of bytes to be written
Description
Writes a String as a sequence of bytes.


 ObjectOutputStream.writeChar

ObjectOutputStream.writeChar

Class Overview | Class Members | This Package | All Packages

Syntax
public void writeChar( int data ) throws IOException
Parameters
data
the char value to be written
Description
Writes a 16 bit char.


 ObjectOutputStream.writeChars

ObjectOutputStream.writeChars

Class Overview | Class Members | This Package | All Packages

Syntax
public void writeChars( String data ) throws IOException
Parameters
s
the String of chars to be written
Description
Writes a String as a sequence of chars.


 ObjectOutputStream.writeDouble

ObjectOutputStream.writeDouble

Class Overview | Class Members | This Package | All Packages

Syntax
public void writeDouble( double data ) throws IOException
Parameters
data
the double value to be written
Description
Writes a 64 bit double.


 ObjectOutputStream.writeFloat

ObjectOutputStream.writeFloat

Class Overview | Class Members | This Package | All Packages

Syntax
public void writeFloat( float data ) throws IOException
Parameters
data
the float value to be written
Description
Writes a 32 bit float.


 ObjectOutputStream.writeInt

ObjectOutputStream.writeInt

Class Overview | Class Members | This Package | All Packages

Syntax
public void writeInt( int data ) throws IOException
Parameters
data
the integer value to be written
Description
Writes a 32 bit int.


 ObjectOutputStream.writeLong

ObjectOutputStream.writeLong

Class Overview | Class Members | This Package | All Packages

Syntax
public void writeLong( long data ) throws IOException
Parameters
data
the long value to be written
Description
Writes a 64 bit long.


 ObjectOutputStream.writeObject

ObjectOutputStream.writeObject

Class Overview | Class Members | This Package | All Packages

Syntax
public final void writeObject( Object obj ) throws IOException
Description
Write the specified object to the ObjectOutputStream. The class of the object, the signature of the class, and the values of the non-transient and non-static fields of the class and all of its supertypes are written. Default serialization for a class can be overridden using the writeObject and the readObject methods. Objects referenced by this object are written transitively so that a complete equivalent graph of objects can be reconstructed by an ObjectInputStream.

Exceptions are thrown for problems with the OutputStream and for classes that should not be serialized. All exceptions are fatal to the OutputStream, which is left in an indeterminate state, and it is up to the caller to ignore or recover the stream state.

Exceptions
InvalidClassException Something is wrong with a class used by serialization.
Exceptions
NotSerializableException Some object to be serialized does not implement the java.io.Serializable interface.
Exceptions
IOException Any exception thrown by the underlying OutputStream.


 ObjectOutputStream.writeShort

ObjectOutputStream.writeShort

Class Overview | Class Members | This Package | All Packages

Syntax
public void writeShort( int data ) throws IOException
Parameters
data
the short value to be written
Description
Writes a 16 bit short.


 ObjectOutputStream.writeStreamHeader

ObjectOutputStream.writeStreamHeader

Class Overview | Class Members | This Package | All Packages

Syntax
protected void writeStreamHeader() throws IOException
Description
The writeStreamHeader method is provided so subclasses can append or prepend their own header to the stream. It writes the magic number and version to the stream.


 ObjectOutputStream.writeUTF

ObjectOutputStream.writeUTF

Class Overview | Class Members | This Package | All Packages

Syntax
public void writeUTF( String data ) throws IOException
Parameters
str
the String in UTF format
Description
Writes a String in UTF format.


 Class ObjectStreamClass

Class java.io.ObjectStreamClass

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.ObjectStreamClass

public class ObjectStreamClass
extends Object
implements Serializable

A ObjectStreamClass describes a class that can be serialized to a stream or a class that was serialized to a stream. It contains the name and the serialVersionUID of the class.
The ObjectStreamClass for a specific class loaded in this Java VM can be found using the lookup method.


 ObjectStreamClass Members

ObjectStreamClass Members

Class Overview | This Package | All Packages

Methods
Name | Description
forClass() | Return the class in the local VM that this version is mapped to.
getName() | The name of the class described by this descriptor.
getSerialVersionUID() | Return the serialVersionUID for this class.
lookup(Class) | Find the descriptor for a class that can be serialized.
toString() | Return a string describing this ObjectStreamClass.


 ObjectStreamClass.forClass

ObjectStreamClass.forClass

Class Overview | Class Members | This Package | All Packages

Syntax
public Class forClass()
Description
Return the class in the local VM that this version is mapped to. Null is returned if there is no corresponding local class.


 ObjectStreamClass.getName

ObjectStreamClass.getName

Class Overview | Class Members | This Package | All Packages

Syntax
public String getName()
Description
The name of the class described by this descriptor.


 ObjectStreamClass.getSerialVersionUID

ObjectStreamClass.getSerialVersionUID

Class Overview | Class Members | This Package | All Packages

Syntax
public long getSerialVersionUID()
Description
Return the serialVersionUID for this class. The serialVersionUID defines a set of classes all with the same name that have evolved from a common root class and agree to be serialized and deserialized using a common format.


 ObjectStreamClass.lookup

ObjectStreamClass.lookup

Class Overview | Class Members | This Package | All Packages

Syntax
public static ObjectStreamClass lookup( Class cl )
Description
Find the descriptor for a class that can be serialized. Null is returned if the specified class does not implement java.io.Serializable or java.io.Externalizable.


 ObjectStreamClass.toString

ObjectStreamClass.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Description
Return a string describing this ObjectStreamClass.

Overrides
toString in class Object


 Class ObjectStreamException

Class java.io.ObjectStreamException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.io.IOException
                           |
                           +----java.io.ObjectStreamException

public abstract class ObjectStreamException
extends IOException

Superclass of all exceptions specific to Object Stream classes.


 ObjectStreamException Members

ObjectStreamException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
ObjectStreamException() | Create an ObjectStreamException.
ObjectStreamException(String) | Create an ObjectStreamException with the specified argument.


 ObjectStreamException.ObjectStreamException

ObjectStreamException.ObjectStreamException

Class Overview | Class Members | This Package | All Packages

Syntax 1
protected ObjectStreamException( String classname )
Description
Create an ObjectStreamException with the specified argument.

Syntax 2
protected ObjectStreamException()
Description
Create an ObjectStreamException.


 Class OptionalDataException

Class java.io.OptionalDataException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.io.IOException
                           |
                           +----java.io.ObjectStreamException
                                   |
                                   +----java.io.OptionalDataException

public class OptionalDataException
extends ObjectStreamException

Unexpected data appeared in an ObjectInputStream trying to read an Object. This exception occurs when the stream contains primitive data instead of the object expected by readObject. The eof flag in the exception is true to indicate that no more primitive data is available. The count field contains the number of bytes available to read.


 OptionalDataException Members

OptionalDataException Members

Class Overview | This Package | All Packages

Fields
Name | Description
eof | True if there is no more data in the buffered part of the stream.
length | The number of bytes of primitive data available to be read in the current buffer.


 OptionalDataException.eof

OptionalDataException.eof

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean eof
Description
True if there is no more data in the buffered part of the stream.


 OptionalDataException.length

OptionalDataException.length

Class Overview | Class Members | This Package | All Packages

Syntax
public int length
Description
The number of bytes of primitive data available to be read in the current buffer.


 Class OutputStream

Class java.io.OutputStream

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.OutputStream

public abstract class OutputStream
extends Object

This abstract class is the superclass of all classes representing an output stream of bytes.

Applications that need to define a subclass of OutputStream must always provide at least a method that writes one byte of output.

See Also:
BufferedOutputStream, ByteArrayOutputStream, DataOutputStream, FilterOutputStream, InputStream, write


 OutputStream Members

OutputStream Members

Class Overview | This Package | All Packages

Constructors
Name | Description
OutputStream() |

Methods
Name | Description
close() | Closes this output stream and releases any system resources associated with this stream.
flush() | Flushes this output stream and forces any buffered output bytes to be written out.
write(byte[]) | Writes b.length bytes from the specified byte array to this output stream.
write(byte[], int, int) | Writes len bytes from the specified byte array starting at offset off to this output stream.
write(int) | Writes the specified byte to this output stream.


 OutputStream.OutputStream

OutputStream.OutputStream

Class Overview | Class Members | This Package | All Packages

Syntax
public OutputStream()


 OutputStream.close

OutputStream.close

Class Overview | Class Members | This Package | All Packages

Syntax
public void close() throws IOException
Description
Closes this output stream and releases any system resources associated with this stream.

The close method of OutputStream does nothing.

Exceptions
IOException if an I/O error occurs.


 OutputStream.flush

OutputStream.flush

Class Overview | Class Members | This Package | All Packages

Syntax
public void flush() throws IOException
Description
Flushes this output stream and forces any buffered output bytes to be written out.

The flush method of OutputStream does nothing.

Exceptions
IOException if an I/O error occurs.


 OutputStream.write

OutputStream.write

Class Overview | Class Members | This Package | All Packages

Syntax 1
public abstract void write( int b ) throws IOException
Parameters
b
the byte.
Description
Writes the specified byte to this output stream.

Subclasses of OutputStream must provide an implementation for this method.

Exceptions
IOException if an I/O error occurs.

Syntax 2
public void write( byte b[] ) throws IOException
Parameters
b
the data.
Description
Writes b.length bytes from the specified byte array to this output stream.

The write method of OutputStream calls the write method of three arguments with the three arguments b, 0, and b.length.

Exceptions
IOException if an I/O error occurs.
See Also
write

Syntax 3
public void write( byte b[], int off, int len ) throws IOException
Parameters
b
the data.
off
the start offset in the data.
len
the number of bytes to write.
Description
Writes len bytes from the specified byte array starting at offset off to this output stream.

The write method of OutputStream calls the write method of one argument on each of the bytes to be written out. Subclasses are encouraged to override this method and provide a more efficient implementation.

Exceptions
IOException if an I/O error occurs.


 Class OutputStreamWriter

Class java.io.OutputStreamWriter

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.Writer
           |
           +----java.io.OutputStreamWriter

public class OutputStreamWriter
extends Writer

Write characters to an output stream, translating characters into bytes according to a specified character encoding. Each OutputStreamWriter incorporates its own CharToByteConverter, and is thus a bridge from character streams to byte streams.

The encoding used by an OutputStreamWriter may be specified by name, by providing a CharToByteConverter, or by accepting the default encoding, which is defined by the system property file.encoding.

Each invocation of a write() method causes the encoding converter to be invoked on the given character(s). The resulting bytes are accumulated in a buffer before being written to the underlying output stream. The size of this buffer may be specified, but by default it is large enough for most purposes. Note that the characters passed to the write() methods are not buffered. For top efficiency, consider wrapping an OutputStreamWriter within a BufferedWriter so as to avoid frequent converter invocations. For example,

 Writer out
   = new BufferedWriter(new OutputStreamWriter(System.out));

See Also:
BufferedWriter, OutputStream


 OutputStreamWriter Members

OutputStreamWriter Members

Class Overview | This Package | All Packages

Constructors
Name | Description
OutputStreamWriter(OutputStream) | Create an OutputStreamWriter that uses the default character encoding.
OutputStreamWriter(OutputStream, String) | Create an OutputStreamWriter that uses the named character encoding.

Methods
Name | Description
close() | Close the stream.
flush() | Flush the stream.
getEncoding() | Return the name of the encoding being used by this stream.
write(char[], int, int) | Write a portion of an array of characters.
write(int) | Write a single character.
write(String, int, int) | Write a portion of a string.


 OutputStreamWriter.OutputStreamWriter

OutputStreamWriter.OutputStreamWriter

Class Overview | Class Members | This Package | All Packages

Syntax 1
public OutputStreamWriter( OutputStream out, String enc ) throws UnsupportedEncodingException
Parameters
out
An OutputStream
enc
Name of the encoding to be used
Description
Create an OutputStreamWriter that uses the named character encoding.

Exceptions
UnsupportedEncodingException If the named encoding is not supported

Syntax 2
public OutputStreamWriter( OutputStream out )
Parameters
out
An OutputStream
Description
Create an OutputStreamWriter that uses the default character encoding.


 OutputStreamWriter.close

OutputStreamWriter.close

Class Overview | Class Members | This Package | All Packages

Syntax
public void close() throws IOException
Description
Close the stream.

Exceptions
IOException If an I/O error occurs
Overrides
close in class Writer


 OutputStreamWriter.flush

OutputStreamWriter.flush

Class Overview | Class Members | This Package | All Packages

Syntax
public void flush() throws IOException
Description
Flush the stream.

Exceptions
IOException If an I/O error occurs
Overrides
flush in class Writer


 OutputStreamWriter.getEncoding

OutputStreamWriter.getEncoding

Class Overview | Class Members | This Package | All Packages

Syntax
public String getEncoding()
Description
Return the name of the encoding being used by this stream. May return null if the stream has been closed.


 OutputStreamWriter.write

OutputStreamWriter.write

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void write( int c ) throws IOException
Description
Write a single character.

Exceptions
IOException If an I/O error occurs
Overrides
write in class Writer

Syntax 2
public void write( char cbuf[], int off, int len ) throws IOException
Parameters
cbuf
Buffer of characters
off
Offset from which to start writing characters
len
Number of characters to write
Description
Write a portion of an array of characters.

Exceptions
IOException If an I/O error occurs
Overrides
write in class Writer

Syntax 3
public void write( String str, int off, int len ) throws IOException
Parameters
str
A String
off
Offset from which to start writing characters
len
Number of characters to write
Description
Write a portion of a string.

Exceptions
IOException If an I/O error occurs
Overrides
write in class Writer


 Class PipedInputStream

Class java.io.PipedInputStream

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.InputStream
           |
           +----java.io.PipedInputStream

public class PipedInputStream
extends InputStream

A piped input stream is the receiving end of a communications pipe. Two threads can communicate by having one thread send data through a piped output stream and having the other thread read the data through a piped input stream.

See Also:
PipedOutputStream


 PipedInputStream Members

PipedInputStream Members

Class Overview | This Package | All Packages

Fields
Name | Description
buffer | The circular buffer into which incoming data is placed.
in |
out |
PIPE_SIZE |

Constructors
Name | Description
PipedInputStream() | Creates a piped input stream that is not yet connected to a piped output stream.
PipedInputStream(PipedOutputStream) | Creates a piped input stream connected to the specified piped output stream.

Methods
Name | Description
available() | Returns the number of bytes that can be read from this input stream without blocking.
close() | Closes this piped input stream and releases any system resources associated with the stream.
connect(PipedOutputStream) | Connects this piped input stream to a sender.
read() | Reads the next byte of data from this piped input stream.
read(byte[], int, int) | Reads up to len bytes of data from this piped input stream into an array of bytes.
receive(int) | Receives a byte of data.


 PipedInputStream.buffer

PipedInputStream.buffer

Class Overview | Class Members | This Package | All Packages

Syntax
protected byte buffer[]
Description
The circular buffer into which incoming data is placed.


 PipedInputStream.in

PipedInputStream.in

Class Overview | Class Members | This Package | All Packages

Syntax
protected int in


 PipedInputStream.out

PipedInputStream.out

Class Overview | Class Members | This Package | All Packages

Syntax
protected int out


 PipedInputStream.PIPE_SIZE

PipedInputStream.PIPE_SIZE

Class Overview | Class Members | This Package | All Packages

Syntax
protected static final int PIPE_SIZE


 PipedInputStream.PipedInputStream

PipedInputStream.PipedInputStream

Class Overview | Class Members | This Package | All Packages

Syntax 1
public PipedInputStream( PipedOutputStream src ) throws IOException
Parameters
src
the stream to connect to.
Description
Creates a piped input stream connected to the specified piped output stream.

Exceptions
IOException if an I/O error occurs.

Syntax 2
public PipedInputStream()
Description
Creates a piped input stream that is not yet connected to a piped output stream. It must be connected to a piped output stream, either by the receiver or the sender, before being used.

See Also
connect, connect


 PipedInputStream.available

PipedInputStream.available

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized int available() throws IOException
Returns
the number of bytes that can be read from this input stream without blocking.
Description
Returns the number of bytes that can be read from this input stream without blocking. This method overrides the available method of the parent class.

Exceptions
IOException if an I/O error occurs.
Overrides
available in class InputStream


 PipedInputStream.close

PipedInputStream.close

Class Overview | Class Members | This Package | All Packages

Syntax
public void close() throws IOException
Description
Closes this piped input stream and releases any system resources associated with the stream.

Exceptions
IOException if an I/O error occurs.
Overrides
close in class InputStream


 PipedInputStream.connect

PipedInputStream.connect

Class Overview | Class Members | This Package | All Packages

Syntax
public void connect( PipedOutputStream src ) throws IOException
Parameters
src
The piped output stream to connect to.
Description
Connects this piped input stream to a sender.

Exceptions
IOException if an I/O error occurs.


 PipedInputStream.read

PipedInputStream.read

Class Overview | Class Members | This Package | All Packages

Syntax 1
public synchronized int read() throws IOException
Returns
the next byte of data, or -1 if the end of the stream is reached.
Description
Reads the next byte of data from this piped input stream. The value byte is returned as an int in the range 0 to 255. If no byte is available because this end of the stream has been reached, the value -1 is returned. This method blocks until input data is available, the end of the stream is detected, or an exception is thrown.

Exceptions
IOException if the pipe is broken.
Overrides
read in class InputStream

Syntax 2
public synchronized int read( byte b[], int off, int len ) throws IOException
Parameters
b
the buffer into which the data is read.
off
the start offset of the data.
len
the maximum number of bytes read.
Returns
the total number of bytes read into the buffer, or -1 if there is no more data because the end of the stream has been reached.
Description
Reads up to len bytes of data from this piped input stream into an array of bytes. This method blocks until at least one byte of input is available.

Exceptions
IOException if an I/O error occurs.
Overrides
read in class InputStream


 PipedInputStream.receive

PipedInputStream.receive

Class Overview | Class Members | This Package | All Packages

Syntax
protected synchronized void receive( int b ) throws IOException
Parameters
b
the byte being received
Description
Receives a byte of data. This method will block if no input is available.

Exceptions
IOException If the pipe is broken.


 Class PipedOutputStream

Class java.io.PipedOutputStream

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.OutputStream
           |
           +----java.io.PipedOutputStream

public class PipedOutputStream
extends OutputStream

A piped output stream is the sending end of a communications pipe. Two threads can communicate by having one thread send data through a piped output stream and having the other thread read the data through a piped input stream.

See Also:
PipedInputStream


 PipedOutputStream Members

PipedOutputStream Members

Class Overview | This Package | All Packages

Constructors
Name | Description
PipedOutputStream() | Creates a piped output stream that is not yet connected to a piped input stream.
PipedOutputStream(PipedInputStream) | Creates a piped output stream connected to the specified piped input stream.

Methods
Name | Description
close() | Closes this piped output stream and releases any system resources associated with this stream.
connect(PipedInputStream) | Connects this piped output stream to a receiver.
flush() | Flushes this output stream and forces any buffered output bytes to be written out.
write(byte[], int, int) | Writes len bytes from the specified byte array starting at offset off to this piped output stream.
write(int) | Writes the specified byte to the piped output stream.


 PipedOutputStream.PipedOutputStream

PipedOutputStream.PipedOutputStream

Class Overview | Class Members | This Package | All Packages

Syntax 1
public PipedOutputStream( PipedInputStream snk ) throws IOException
Parameters
snk
The piped input stream to connect to.
Description
Creates a piped output stream connected to the specified piped input stream.

Exceptions
IOException if an I/O error occurs.

Syntax 2
public PipedOutputStream()
Description
Creates a piped output stream that is not yet connected to a piped input stream. It must be connected to a piped input stream, either by the receiver or the sender, before being used.

See Also
connect, connect


 PipedOutputStream.close

PipedOutputStream.close

Class Overview | Class Members | This Package | All Packages

Syntax
public void close() throws IOException
Description
Closes this piped output stream and releases any system resources associated with this stream.

Exceptions
IOException if an I/O error occurs.
Overrides
close in class OutputStream


 PipedOutputStream.connect

PipedOutputStream.connect

Class Overview | Class Members | This Package | All Packages

Syntax
public void connect( PipedInputStream snk ) throws IOException
Parameters
snk
the piped output stream to connect to.
Description
Connects this piped output stream to a receiver.

Exceptions
IOException if an I/O error occurs.


 PipedOutputStream.flush

PipedOutputStream.flush

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void flush() throws IOException
Description
Flushes this output stream and forces any buffered output bytes to be written out. This will notify any readers that bytes are waiting in the pipe.

Exceptions
IOException if an I/O error occurs.
Overrides
flush in class OutputStream


 PipedOutputStream.write

PipedOutputStream.write

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void write( int b ) throws IOException
Parameters
b
the byte to be written.
Description
Writes the specified byte to the piped output stream.

Exceptions
IOException if an I/O error occurs.
Overrides
write in class OutputStream

Syntax 2
public void write( byte b[], int off, int len ) throws IOException
Parameters
b
the data.
off
the start offset in the data.
len
the number of bytes to write.
Description
Writes len bytes from the specified byte array starting at offset off to this piped output stream.

Exceptions
IOException if an I/O error occurs.
Overrides
write in class OutputStream


 Class PipedReader

Class java.io.PipedReader

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.Reader
           |
           +----java.io.PipedReader

public class PipedReader
extends Reader

Piped character-input streams.


 PipedReader Members

PipedReader Members

Class Overview | This Package | All Packages

Constructors
Name | Description
PipedReader() | Create a reader that is not yet connected to a piped writer.
PipedReader(PipedWriter) | Create a reader for the specified piped character-output stream.

Methods
Name | Description
close() | Close the stream.
connect(PipedWriter) | Connect the specified piped writer to this reader.
read(char[], int, int) | Read characters into a portion of an array.


 PipedReader.PipedReader

PipedReader.PipedReader

Class Overview | Class Members | This Package | All Packages

Syntax 1
public PipedReader()
Description
Create a reader that is not yet connected to a piped writer.

Syntax 2
public PipedReader( PipedWriter src ) throws IOException
Description
Create a reader for the specified piped character-output stream.


 PipedReader.close

PipedReader.close

Class Overview | Class Members | This Package | All Packages

Syntax
public void close() throws IOException
Description
Close the stream.

Exceptions
IOException If an I/O error occurs
Overrides
close in class Reader


 PipedReader.connect

PipedReader.connect

Class Overview | Class Members | This Package | All Packages

Syntax
public void connect( PipedWriter src ) throws IOException
Description
Connect the specified piped writer to this reader.

Exceptions
IOException If this reader is already connected


 PipedReader.read

PipedReader.read

Class Overview | Class Members | This Package | All Packages

Syntax
public int read( char cbuf[], int off, int len ) throws IOException
Parameters
cbuf
Destination buffer
off
Offset at which to start storing characters
len
Maximum number of characters to read
Returns
The number of characters read, or -1 if the end of the stream has been reached
Description
Read characters into a portion of an array.

Exceptions
IOException If an I/O error occurs
Overrides
read in class Reader


 Class PipedWriter

Class java.io.PipedWriter

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.Writer
           |
           +----java.io.PipedWriter

public class PipedWriter
extends Writer

Piped character-output streams.


 PipedWriter Members

PipedWriter Members

Class Overview | This Package | All Packages

Constructors
Name | Description
PipedWriter() | Create a writer that is not yet connected to a piped reader.
PipedWriter(PipedReader) | Create a writer for the specified piped character-input stream.

Methods
Name | Description
close() | Close the stream.
connect(PipedReader) | Connect the specified piped reader to this writer.
flush() | Flush the stream.
write(char[], int, int) | Write a portion of an array of characters.


 PipedWriter.PipedWriter

PipedWriter.PipedWriter

Class Overview | Class Members | This Package | All Packages

Syntax 1
public PipedWriter()
Description
Create a writer that is not yet connected to a piped reader.

Syntax 2
public PipedWriter( PipedReader sink ) throws IOException
Description
Create a writer for the specified piped character-input stream.


 PipedWriter.close

PipedWriter.close

Class Overview | Class Members | This Package | All Packages

Syntax
public void close() throws IOException
Description
Close the stream.

Exceptions
IOException If an I/O error occurs
Overrides
close in class Writer


 PipedWriter.connect

PipedWriter.connect

Class Overview | Class Members | This Package | All Packages

Syntax
public void connect( PipedReader sink ) throws IOException
Description
Connect the specified piped reader to this writer.


 PipedWriter.flush

PipedWriter.flush

Class Overview | Class Members | This Package | All Packages

Syntax
public void flush() throws IOException
Description
Flush the stream.

Exceptions
IOException If an I/O error occurs
Overrides
flush in class Writer


 PipedWriter.write

PipedWriter.write

Class Overview | Class Members | This Package | All Packages

Syntax
public void write( char cbuf[], int off, int len ) throws IOException
Parameters
cbuf
Array of characters
off
Offset from which to start writing characters
len
Number of characters to write
Description
Write a portion of an array of characters.

Exceptions
IOException If an I/O error occurs
Overrides
write in class Writer


 Class PrintStream

Class java.io.PrintStream

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.OutputStream
           |
           +----java.io.FilterOutputStream
                   |
                   +----java.io.PrintStream

public class PrintStream
extends FilterOutputStream

Print values and objects to an output stream, using the platform's default character encoding to convert characters into bytes.

If automatic flushing is enabled at creation time, then the stream will be flushed each time a line is terminated or a newline character is written.

Methods in this class never throw I/O exceptions. Client code may inquire as to whether any errors have occurred by invoking the checkError method.

Note: This class is provided primarily for use in debugging, and for compatibility with existing code; new code should use the PrintWriter class.

See Also:
PrintWriter


 PrintStream Members

PrintStream Members

Class Overview | This Package | All Packages

Constructors
Name | Description
PrintStream(OutputStream) | Create a new print stream. Deprecated.
PrintStream(OutputStream, boolean) | Create a new PrintStream. Deprecated.

Methods
Name | Description
checkError() | Flush the stream and check its error state.
close() | Close the stream.
flush() | Flush the stream.
print(boolean) | Print a boolean value.
print(char) | Print a character.
print(char[]) | Print an array of characters.
print(double) | Print a double-precision floating-point number.
print(float) | Print a floating-point number.
print(int) | Print an integer.
print(long) | Print a long integer.
print(Object) | Print an object.
print(String) | Print a string.
println() | Finish the current line by writing a line separator.
println(boolean) | Print a boolean, and then finish the line.
println(char) | Print a character, and then finish the line.
println(char[]) | Print an array of characters, and then finish the line.
println(double) | Print a double, and then finish the line.
println(float) | Print a float, and then finish the line.
println(int) | Print an integer, and then finish the line.
println(long) | Print a long, and then finish the line.
println(Object) | Print an Object, and then finish the line.
println(String) | Print a String, and then finish the line.
setError() | Indicate that an error has occurred.
write(byte[], int, int) | Write a portion of a byte array, blocking if necessary.
write(int) | Write a byte, blocking if necessary.


 PrintStream.PrintStream

PrintStream.PrintStream

Class Overview | Class Members | This Package | All Packages

Syntax 1
public PrintStream( OutputStream out )
Parameters
out
The output stream to which values and objects will be printed
Description
Note: PrintStream() is deprecated. As of JDK 1.1, the preferred way to print text is via the PrintWriter class. Consider replacing code of the
form PrintStream p = new PrintStream(out);
with PrintWriter p = new PrintWriter(out);

Create a new print stream.

See Also
PrintWriter

Syntax 2
public PrintStream( OutputStream out, boolean autoFlush )
Parameters
out
The output stream to which values and objects will be printed
autoFlush
A boolean; if true, the output buffer will be flushed whenever a line is terminated or a newline character ('\n') is written
Description
Note: PrintStream() is deprecated. As of JDK 1.1, the preferred way to print text is via the PrintWriter class. Consider replacing code of the
form PrintStream p = new PrintStream(out, autoFlush);
with PrintWriter p = new PrintWriter(out, autoFlush);

Create a new PrintStream.

See Also
PrintWriter


 PrintStream.checkError

PrintStream.checkError

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean checkError()
Returns
True if the print stream has encountered an error, either on the underlying output stream or during a format conversion, otherwise false.
Description
Flush the stream and check its error state. Errors are cumulative; once the stream encounters an error, this routine will continue to return true on all successive calls.


 PrintStream.close

PrintStream.close

Class Overview | Class Members | This Package | All Packages

Syntax
public void close()
Description
Close the stream. This is done by flushing the stream and then closing the underlying output stream.

Overrides
close in class FilterOutputStream
See Also
close


 PrintStream.flush

PrintStream.flush

Class Overview | Class Members | This Package | All Packages

Syntax
public void flush()
Description
Flush the stream. This is done by writing any buffered output bytes to the underlying output stream and then flushing that stream.

Overrides
flush in class FilterOutputStream
See Also
flush


 PrintStream.print

PrintStream.print

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void print( boolean b )
Parameters
b
The boolean to be printed
Description
Print a boolean value. If the given value is true, then the string "true" is written to the underlying output stream; otherwise, the string "false" is written.

Syntax 2
public void print( char c )
Parameters
c
The char to be printed
Description
Print a character. The character is translated into one or more bytes according to the platform's default character encoding.

Syntax 3
public void print( int i )
Parameters
i
The int to be printed
Description
Print an integer. The string printed is the same as that returned by the toString method of the Integer class when invoked on the given int value.

See Also
toString

Syntax 4
public void print( long l )
Parameters
l
The long to be printed
Description
Print a long integer. The string printed is the same as that returned by the toString method of the Long class when invoked on the given long value.

See Also
toString

Syntax 5
public void print( float f )
Parameters
f
The float to be printed
Description
Print a floating-point number. The string printed is the same as that returned by the toString method of the Float class when invoked on the given float value.

See Also
toString

Syntax 6
public void print( double d )
Parameters
d
The double to be printed
Description
Print a double-precision floating-point number. The string printed is the same as that returned by the toString method of the Double class when invoked on the given double value.

See Also
toString

Syntax 7
public void print( char s[] )
Parameters
s
The array of chars to be printed
Description
Print an array of characters. The characters are converted into bytes according to the platform's default character encoding.

Syntax 8
public void print( String s )
Parameters
s
The String to be printed
Description
Print a string. If the argument is null, the string "null" is written to the underlying output stream. Otherwise, the string's characters are converted into bytes according to the platform's default character encoding.

Syntax 9
public void print( Object obj )
Parameters
obj
The Object to be printed
Description
Print an object. The string printed is the same as that returned by the given object's toString method.

See Also
toString


 PrintStream.println

PrintStream.println

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void println()
Description
Finish the current line by writing a line separator. The line separator string is defined by the system property line.separator, and is not necessarily a single newline character ('\n').

Syntax 2
public void println( boolean x )
Description
Print a boolean, and then finish the line.

See Also
print

Syntax 3
public void println( char x )
Description
Print a character, and then finish the line.

See Also
print

Syntax 4
public void println( int x )
Description
Print an integer, and then finish the line.

See Also
print

Syntax 5
public void println( long x )
Description
Print a long, and then finish the line.

See Also
print

Syntax 6
public void println( float x )
Description
Print a float, and then finish the line.

See Also
print

Syntax 7
public void println( double x )
Description
Print a double, and then finish the line.

See Also
print

Syntax 8
public void println( char x[] )
Description
Print an array of characters, and then finish the line.

See Also
print

Syntax 9
public void println( String x )
Description
Print a String, and then finish the line.

See Also
print

Syntax 10
public void println( Object x )
Description
Print an Object, and then finish the line.

See Also
print


 PrintStream.setError

PrintStream.setError

Class Overview | Class Members | This Package | All Packages

Syntax
protected void setError()
Description
Indicate that an error has occurred.


 PrintStream.write

PrintStream.write

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void write( int b )
Parameters
b
The byte to be written
Description
Write a byte, blocking if necessary. If the character is a newline and automatic flushing is enabled, the stream's flush method will be called.

Note that the byte is written as given; to write a character that will be translated according to the platform's default character encoding, use the print(char) or println(char) methods.

Overrides
write in class FilterOutputStream
See Also
print, println

Syntax 2
public void write( byte buf[], int off, int len )
Parameters
buf
A byte array
off
Offset from which to start taking bytes
len
Number of bytes to write
Description
Write a portion of a byte array, blocking if necessary.

Overrides
write in class FilterOutputStream


 Class PrintWriter

Class java.io.PrintWriter

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.Writer
           |
           +----java.io.PrintWriter

public class PrintWriter
extends Writer

Print formatted representations of objects to a text-output stream. This class implements all of the print methods found in PrintStream. It does not contain methods for writing raw bytes, for which a program should use unencoded byte streams.

Unlike the PrintStream class, if automatic flushing is enabled it will be done only when one of the println() methods is invoked, rather than whenever a newline character happens to be output. The println() methods use the platform's own notion of line separator rather than the newline character.

Methods in this class never throw I/O exceptions. The client may inquire as to whether any errors have occurred by invoking checkError().


 PrintWriter Members

PrintWriter Members

Class Overview | This Package | All Packages

Constructors
Name | Description
PrintWriter(OutputStream) | Create a new PrintWriter, without automatic line flushing, from an existing OutputStream.
PrintWriter(OutputStream, boolean) | Create a new PrintWriter from an existing OutputStream.
PrintWriter(Writer) | Create a new PrintWriter, without automatic line flushing.
PrintWriter(Writer, boolean) | Create a new PrintWriter.

Methods
Name | Description
checkError() | Flush the stream and check its error state.
close() | Close the stream.
flush() | Flush the stream.
print(boolean) | Print a boolean.
print(char) | Print a character.
print(char[]) | Print an array of chracters.
print(double) | Print a double.
print(float) | Print a float.
print(int) | Print an integer.
print(long) | Print a long.
print(Object) | Print an object.
print(String) | Print a String.
println() | Finish the line.
println(boolean) | Print a boolean, and then finish the line.
println(char) | Print a character, and then finish the line.
println(char[]) | Print an array of characters, and then finish the line.
println(double) | Print a double, and then finish the line.
println(float) | Print a float, and then finish the line.
println(int) | Print an integer, and then finish the line.
println(long) | Print a long, and then finish the line.
println(Object) | Print an Object, and then finish the line.
println(String) | Print a String, and then finish the line.
setError() | Indicate that an error has occurred.
write(char[]) | Write an array of characters.
write(char[], int, int) | Write a portion of an array of characters.
write(int) | Write a single character.
write(String) | Write a string.
write(String, int, int) | Write a portion of a string.


 PrintWriter.PrintWriter

PrintWriter.PrintWriter

Class Overview | Class Members | This Package | All Packages

Syntax 1
public PrintWriter( Writer out )
Parameters
out
A character-output stream
Description
Create a new PrintWriter, without automatic line flushing.

Syntax 2
public PrintWriter( Writer out, boolean autoFlush )
Parameters
out
A character-output stream
autoFlush
A boolean; if true, the println() methods will flush the output buffer
Description
Create a new PrintWriter.

Syntax 3
public PrintWriter( OutputStream out )
Parameters
out
An output stream
Description
Create a new PrintWriter, without automatic line flushing, from an existing OutputStream. This convenience constructor creates the necessary intermediate OutputStreamWriter, which will convert characters into bytes using the default character encoding.

See Also
OutputStreamWriter

Syntax 4
public PrintWriter( OutputStream out, boolean autoFlush )
Parameters
out
An output stream
autoFlush
A boolean; if true, the println() methods will flush the output buffer
Description
Create a new PrintWriter from an existing OutputStream. This convenience constructor creates the necessary intermediate OutputStreamWriter, which will convert characters into bytes using the default character encoding.

See Also
OutputStreamWriter


 PrintWriter.checkError

PrintWriter.checkError

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean checkError()
Returns
True if the print stream has encountered an error, either on the underlying output stream or during a format conversion.
Description
Flush the stream and check its error state. Errors are cumulative; once the stream encounters an error, this routine will return true on all successive calls.


 PrintWriter.close

PrintWriter.close

Class Overview | Class Members | This Package | All Packages

Syntax
public void close()
Description
Close the stream.

Overrides
close in class Writer


 PrintWriter.flush

PrintWriter.flush

Class Overview | Class Members | This Package | All Packages

Syntax
public void flush()
Description
Flush the stream.

Overrides
flush in class Writer


 PrintWriter.print

PrintWriter.print

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void print( boolean b )
Description
Print a boolean.

Syntax 2
public void print( char c )
Description
Print a character.

Syntax 3
public void print( int i )
Description
Print an integer.

Syntax 4
public void print( long l )
Description
Print a long.

Syntax 5
public void print( float f )
Description
Print a float.

Syntax 6
public void print( double d )
Description
Print a double.

Syntax 7
public void print( char s[] )
Description
Print an array of chracters.

Syntax 8
public void print( String s )
Description
Print a String.

Syntax 9
public void print( Object obj )
Description
Print an object.


 PrintWriter.println

PrintWriter.println

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void println()
Description
Finish the line.

Syntax 2
public void println( boolean x )
Description
Print a boolean, and then finish the line.

Syntax 3
public void println( char x )
Description
Print a character, and then finish the line.

Syntax 4
public void println( int x )
Description
Print an integer, and then finish the line.

Syntax 5
public void println( long x )
Description
Print a long, and then finish the line.

Syntax 6
public void println( float x )
Description
Print a float, and then finish the line.

Syntax 7
public void println( double x )
Description
Print a double, and then finish the line.

Syntax 8
public void println( char x[] )
Description
Print an array of characters, and then finish the line.

Syntax 9
public void println( String x )
Description
Print a String, and then finish the line.

Syntax 10
public void println( Object x )
Description
Print an Object, and then finish the line.


 PrintWriter.setError

PrintWriter.setError

Class Overview | Class Members | This Package | All Packages

Syntax
protected void setError()
Description
Indicate that an error has occurred.


 PrintWriter.write

PrintWriter.write

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void write( int c )
Description
Write a single character.

Overrides
write in class Writer

Syntax 2
public void write( char buf[], int off, int len )
Description
Write a portion of an array of characters.

Overrides
write in class Writer

Syntax 3
public void write( char buf[] )
Description
Write an array of characters. This method cannot be inherited from the Writer class because it must suppress I/O exceptions.

Overrides
write in class Writer

Syntax 4
public void write( String s, int off, int len )
Description
Write a portion of a string.

Overrides
write in class Writer

Syntax 5
public void write( String s )
Description
Write a string. This method cannot be inherited from the Writer class because it must suppress I/O exceptions.

Overrides
write in class Writer


 Class PushbackInputStream

Class java.io.PushbackInputStream

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.InputStream
           |
           +----java.io.FilterInputStream
                   |
                   +----java.io.PushbackInputStream

public class PushbackInputStream
extends FilterInputStream

This class is an input stream filter that provides a buffer into which data can be "unread." An application may unread data at any time by pushing it back into the buffer, as long as the buffer has sufficient room. Subsequent reads will read all of the pushed-back data in the buffer before reading from the underlying input stream.

This functionality is useful when a fragment of code should read an indefinite number of data bytes that are delimited by particular byte values. After reading the terminating byte the code fragment can push it back, so that the next read operation on the input stream will re-read that byte.


 PushbackInputStream Members

PushbackInputStream Members

Class Overview | This Package | All Packages

Fields
Name | Description
buf | The pushback buffer.
pos | The position within the pushback buffer from which the next byte will be read.

Constructors
Name | Description
PushbackInputStream(InputStream) | Creates a new pushback input stream with a one-byte pushback buffer.
PushbackInputStream(InputStream, int) | Creates a new pushback input stream with a pushback buffer of the specified size.

Methods
Name | Description
available() | Returns the number of bytes that can be read from this input stream without blocking.
markSupported() | Tests if this input stream supports the mark and reset methods, which it does not.
read() | Reads the next byte of data from this input stream.
read(byte[], int, int) | Reads up to len bytes of data from this input stream into an array of bytes.
unread(byte[]) | Pushes back an array of bytes by copying it to the front of the pushback buffer.
unread(byte[], int, int) | Pushes back a portion of an array of bytes by copying it to the front of the pushback buffer.
unread(int) | Pushes back a byte by copying it to the front of the pushback buffer.


 PushbackInputStream.buf

PushbackInputStream.buf

Class Overview | Class Members | This Package | All Packages

Syntax
protected byte buf[]
Description
The pushback buffer.


 PushbackInputStream.pos

PushbackInputStream.pos

Class Overview | Class Members | This Package | All Packages

Syntax
protected int pos
Description
The position within the pushback buffer from which the next byte will be read. When the buffer is empty, pos is equal to buf.length; when the buffer is full, pos is equal to zero.


 PushbackInputStream.PushbackInputStream

PushbackInputStream.PushbackInputStream

Class Overview | Class Members | This Package | All Packages

Syntax 1
public PushbackInputStream( InputStream in, int size )
Parameters
in
the input stream from which bytes will be read.
size
the size of the pushback buffer.
Description
Creates a new pushback input stream with a pushback buffer of the specified size.

Syntax 2
public PushbackInputStream( InputStream in )
Parameters
in
the input stream from which bytes will be read.
Description
Creates a new pushback input stream with a one-byte pushback buffer.


 PushbackInputStream.available

PushbackInputStream.available

Class Overview | Class Members | This Package | All Packages

Syntax
public int available() throws IOException
Returns
the number of bytes that can be read from the input stream without blocking.
Description
Returns the number of bytes that can be read from this input stream without blocking. This method calls the available method of the underlying input stream; it returns that value plus the number of bytes that have been pushed back.

Exceptions
IOException if an I/O error occurs.
Overrides
available in class FilterInputStream
See Also
in


 PushbackInputStream.markSupported

PushbackInputStream.markSupported

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean markSupported()
Returns
false, since this class does not support the mark and reset methods.
Description
Tests if this input stream supports the mark and reset methods, which it does not.

Overrides
markSupported in class FilterInputStream
See Also
mark, reset


 PushbackInputStream.read

PushbackInputStream.read

Class Overview | Class Members | This Package | All Packages

Syntax 1
public int read() throws IOException
Returns
the next byte of data, or -1 if the end of the stream has been reached.
Description
Reads the next byte of data from this input stream. The value byte is returned as an int in the range 0 to 255. If no byte is available because the end of the stream has been reached, the value -1 is returned. This method blocks until input data is available, the end of the stream is detected, or an exception is thrown.

This method returns the most recently pushed-back byte, if there is one, and otherwise calls the read method of its underlying input stream and returns whatever value that method returns.

Exceptions
IOException if an I/O error occurs.
Overrides
read in class FilterInputStream
See Also
read

Syntax 2
public int read( byte b[], int off, int len ) throws IOException
Parameters
b
the buffer into which the data is read.
off
the start offset of the data.
len
the maximum number of bytes read.
Returns
the total number of bytes read into the buffer, or -1 if there is no more data because the end of the stream has been reached.
Description
Reads up to len bytes of data from this input stream into an array of bytes. This method first reads any pushed-back bytes; after that, if fewer than than len bytes have been read then it reads from the underlying input stream. This method blocks until at least 1 byte of input is available.

Exceptions
IOException if an I/O error occurs.
Overrides
read in class FilterInputStream


 PushbackInputStream.unread

PushbackInputStream.unread

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void unread( int b ) throws IOException
Parameters
b
the int value whose low-order byte is to be pushed back.
Description
Pushes back a byte by copying it to the front of the pushback buffer. After this method returns, the next byte to be read will have the value (byte)b.

Exceptions
IOException If there is not enough room in the pushback buffer for the byte.

Syntax 2
public void unread( byte b[], int off, int len ) throws IOException
Parameters
b
the byte array to push back.
off
the start offset of the data.
len
the number of bytes to push back.
Description
Pushes back a portion of an array of bytes by copying it to the front of the pushback buffer. After this method returns, the next byte to be read will have the value b[off], the byte after that will have the value b[off+1], and so forth.

Exceptions
IOException If there is not enough room in the pushback buffer for the specified number of bytes.

Syntax 3
public void unread( byte b[] ) throws IOException
Parameters
b
the byte array to push back
Description
Pushes back an array of bytes by copying it to the front of the pushback buffer. After this method returns, the next byte to be read will have the value b[0], the byte after that will have the value b[1], and so forth.

Exceptions
IOException If there is not enough room in the pushback buffer for the specified number of bytes.


 Class PushbackReader

Class java.io.PushbackReader

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.Reader
           |
           +----java.io.FilterReader
                   |
                   +----java.io.PushbackReader

public class PushbackReader
extends FilterReader

A character-stream reader that allows characters to be pushed back into the stream.


 PushbackReader Members

PushbackReader Members

Class Overview | This Package | All Packages

Constructors
Name | Description
PushbackReader(Reader) | Create a new pushback reader with a one-character pushback buffer.
PushbackReader(Reader, int) | Create a new pushback reader with a pushback buffer of the given size.

Methods
Name | Description
close() | Close the stream.
markSupported() | Tell whether this stream supports the mark() operation, which it does not.
read() | Read a single character.
read(char[], int, int) | Read characters into a portion of an array.
ready() | Tell whether this stream is ready to be read.
unread(char[]) | Push back an array of characters by copying it to the front of the pushback buffer.
unread(char[], int, int) | Push back a portion of an array of characters by copying it to the front of the pushback buffer.
unread(int) | Push back a single character.


 PushbackReader.PushbackReader

PushbackReader.PushbackReader

Class Overview | Class Members | This Package | All Packages

Syntax 1
public PushbackReader( Reader in, int size )
Parameters
in
The reader from which characters will be read
size
The size of the pushback buffer
Description
Create a new pushback reader with a pushback buffer of the given size.

Syntax 2
public PushbackReader( Reader in )
Parameters
in
The reader from which characters will be read
Description
Create a new pushback reader with a one-character pushback buffer.


 PushbackReader.close

PushbackReader.close

Class Overview | Class Members | This Package | All Packages

Syntax
public void close() throws IOException
Description
Close the stream.

Exceptions
IOException If an I/O error occurs
Overrides
close in class FilterReader


 PushbackReader.markSupported

PushbackReader.markSupported

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean markSupported()
Description
Tell whether this stream supports the mark() operation, which it does not.

Overrides
markSupported in class FilterReader


 PushbackReader.read

PushbackReader.read

Class Overview | Class Members | This Package | All Packages

Syntax 1
public int read() throws IOException
Returns
The character read, or -1 if the end of the stream has been reached
Description
Read a single character.

Exceptions
IOException If an I/O error occurs
Overrides
read in class FilterReader

Syntax 2
public int read( char cbuf[], int off, int len ) throws IOException
Parameters
cbuf
Destination buffer
off
Offset at which to start writing characters
len
Maximum number of characters to read
Returns
The number of characters read, or -1 if the end of the stream has been reached
Description
Read characters into a portion of an array.

Exceptions
IOException If an I/O error occurs
Overrides
read in class FilterReader


 PushbackReader.ready

PushbackReader.ready

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean ready() throws IOException
Description
Tell whether this stream is ready to be read.

Exceptions
IOException If an I/O error occurs
Overrides
ready in class FilterReader


 PushbackReader.unread

PushbackReader.unread

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void unread( int c ) throws IOException
Parameters
c
The character to push back
Description
Push back a single character.

Exceptions
IOException If the pushback buffer is full, or if some other I/O error occurs

Syntax 2
public void unread( char cbuf[], int off, int len ) throws IOException
Parameters
cbuf
Character array
off
Offset of first character to push back
len
Number of characters to push back
Description
Push back a portion of an array of characters by copying it to the front of the pushback buffer. After this method returns, the next character to be read will have the value cbuf[off], the character after that will have the value cbuf[off+1], and so forth.

Exceptions
IOException If there is insufficient room in the pushback buffer, or if some other I/O error occurs

Syntax 3
public void unread( char cbuf[] ) throws IOException
Parameters
cbuf
Character array to push back
Description
Push back an array of characters by copying it to the front of the pushback buffer. After this method returns, the next character to be read will have the value cbuf[0], the character after that will have the value cbuf[1], and so forth.

Exceptions
IOException If there is insufficient room in the pushback buffer, or if some other I/O error occurs


 Class RandomAccessFile

Class java.io.RandomAccessFile

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.RandomAccessFile

public class RandomAccessFile
extends Object
implements DataOutput, DataInput

Instances of this class support both reading and writing to a random access file. An application can modify the position in the file at which the next read or write occurs. This class provides a sense of security by offering methods that allow specified mode accesses of read-only or read-write to files.


 RandomAccessFile Members

RandomAccessFile Members

Class Overview | This Package | All Packages

Constructors
Name | Description
RandomAccessFile(File, String) | Creates a random access file stream to read from, and optionally to write to, the file specified by the File argument.
RandomAccessFile(String, String) | Creates a random access file stream to read from, and optionally to write to, a file with the specified name.

Methods
Name | Description
close() | Closes this random access file stream and releases any system resources associated with the stream.
getFD() | Returns the opaque file descriptor object associated with this stream.
getFilePointer() | Returns the current offset in this file.
length() | Returns the length of this file.
read() | Reads a byte of data from this file.
read(byte[]) | Reads up to b.length bytes of data from this file into an array of bytes.
read(byte[], int, int) | Reads up to len bytes of data from this file into an array of bytes.
readBoolean() | Reads a boolean from this file.
readByte() | Reads a signed 8-bit value from this file.
readChar() | Reads a Unicode character from this file.
readDouble() | Reads a double from this file.
readFloat() | Reads a float from this file.
readFully(byte[]) | Reads b.length bytes from this file into the byte array.
readFully(byte[], int, int) | Reads exactly len bytes from this file into the byte array.
readInt() | Reads a signed 32-bit integer from this file.
readLine() | Reads the next line of text from this file.
readLong() | Reads a signed 64-bit integer from this file.
readShort() | Reads a signed 16-bit number from this file.
readUnsignedByte() | Reads an unsigned 8-bit number from this file.
readUnsignedShort() | Reads an unsigned 16-bit number from this file.
readUTF() | Reads in a string from this file.
seek(long) | Sets the offset from the beginning of this file at which the next read or write occurs.
skipBytes(int) | Skips exactly n bytes of input.
write(byte[]) | Writes b.length bytes from the specified byte array starting at offset off to this file.
write(byte[], int, int) | Writes len bytes from the specified byte array starting at offset off to this file.
write(int) | Writes the specified byte to this file.
writeBoolean(boolean) | Writes a boolean to the file as a 1-byte value.
writeByte(int) | Writes a byte to the file as a 1-byte value.
writeBytes(String) | Writes the string to the file as a sequence of bytes.
writeChar(int) | Writes a char to the file as a 2-byte value, high byte first.
writeChars(String) | Writes a string to the file as a sequence of characters.
writeDouble(double) | Converts the double argument to a long using the doubleToLongBits method in class Double, and then writes that long value to the file as an 8-byte quantity, high byte first.
writeFloat(float) | Converts the float argument to an int using the floatToIntBits method in class Float, and then writes that int value to the file as a 4-byte quantity, high byte first.
writeInt(int) | Writes an int to the file as four bytes, high byte first.
writeLong(long) | Writes a long to the file as eight bytes, high byte first.
writeShort(int) | Writes a short to the file as two bytes, high byte first.
writeUTF(String) | Writes a string to the file using UTF-8 encoding in a machine-independent manner.


 RandomAccessFile.RandomAccessFile

RandomAccessFile.RandomAccessFile

Class Overview | Class Members | This Package | All Packages

Syntax 1
public RandomAccessFile( String name, String mode ) throws IOException
Parameters
name
the system-dependent filename.
mode
the access mode.
Description
Creates a random access file stream to read from, and optionally to write to, a file with the specified name.

The mode argument must either be equal to "r" or "rw", indicating either to open the file for input or for both input and output.

Exceptions
IllegalArgumentException if the mode argument is not equal to "r" or to "rw".
Exceptions
IOException if an I/O error occurs.
Exceptions
SecurityException if a security manager exists, its checkRead method is called with the name argument to see if the application is allowed read access to the file. If the mode argument is equal to "rw", its checkWrite method also is called with the name argument to see if the application is allowed write access to the file. Either of these may result in a security exception.
See Also
SecurityException, checkRead

Syntax 2
public RandomAccessFile( File file, String mode ) throws IOException
Parameters
file
the file object.
mode
the access mode.
Description
Creates a random access file stream to read from, and optionally to write to, the file specified by the File argument.

The mode argument must either be equal to "r" or to "rw", indicating either to open the file for input, or for both input and output, respectively.

Exceptions
IllegalArgumentException if the mode argument is not equal to "r" or to "rw".
Exceptions
IOException if an I/O error occurs.
Exceptions
SecurityException if a security manager exists, its checkRead method is called with the pathname of the File argument to see if the application is allowed read access to the file. If the mode argument is equal to "rw", its checkWrite method also is called with the pathname to see if the application is allowed write access to the file.
See Also
getPath, checkRead


 RandomAccessFile.close

RandomAccessFile.close

Class Overview | Class Members | This Package | All Packages

Syntax
public native void close() throws IOException
Description
Closes this random access file stream and releases any system resources associated with the stream.

Exceptions
IOException if an I/O error occurs.


 RandomAccessFile.getFD

RandomAccessFile.getFD

Class Overview | Class Members | This Package | All Packages

Syntax
public final FileDescriptor getFD() throws IOException
Returns
the file descriptor object associated with this stream.
Description
Returns the opaque file descriptor object associated with this stream.

Exceptions
IOException if an I/O error occurs.
See Also
FileDescriptor


 RandomAccessFile.getFilePointer

RandomAccessFile.getFilePointer

Class Overview | Class Members | This Package | All Packages

Syntax
public native long getFilePointer() throws IOException
Returns
the offset from the beginning of the file, in bytes, at which the next read or write occurs.
Description
Returns the current offset in this file.

Exceptions
IOException if an I/O error occurs.


 RandomAccessFile.length

RandomAccessFile.length

Class Overview | Class Members | This Package | All Packages

Syntax
public native long length() throws IOException
Returns
the length of this file.
Description
Returns the length of this file.

Exceptions
IOException if an I/O error occurs.


 RandomAccessFile.read

RandomAccessFile.read

Class Overview | Class Members | This Package | All Packages

Syntax 1
public native int read() throws IOException
Returns
the next byte of data, or -1 if the end of the file is reached.
Description
Reads a byte of data from this file. This method blocks if no input is yet available.

Exceptions
IOException if an I/O error occurs.

Syntax 2
public int read( byte b[], int off, int len ) throws IOException
Parameters
b
the buffer into which the data is read.
off
the start offset of the data.
len
the maximum number of bytes read.
Returns
the total number of bytes read into the buffer, or -1 if there is no more data because the end of the file has been reached.
Description
Reads up to len bytes of data from this file into an array of bytes. This method blocks until at least one byte of input is available.

Exceptions
IOException if an I/O error occurs.

Syntax 3
public int read( byte b[] ) throws IOException
Parameters
b
the buffer into which the data is read.
Returns
the total number of bytes read into the buffer, or -1 if there is no more data because the end of this file has been reached.
Description
Reads up to b.length bytes of data from this file into an array of bytes. This method blocks until at least one byte of input is available.

Exceptions
IOException if an I/O error occurs.


 RandomAccessFile.readBoolean

RandomAccessFile.readBoolean

Class Overview | Class Members | This Package | All Packages

Syntax
public final boolean readBoolean() throws IOException
Returns
the boolean value read.
Description
Reads a boolean from this file. This method reads a single byte from the file. A value of 0 represents false. Any other value represents true. This method blocks until the byte is read, the end of the stream is detected, or an exception is thrown.

Exceptions
EOFException if this file has reached the end.
Exceptions
IOException if an I/O error occurs.


 RandomAccessFile.readByte

RandomAccessFile.readByte

Class Overview | Class Members | This Package | All Packages

Syntax
public final byte readByte() throws IOException
Returns
the next byte of this file as a signed 8-bit byte.
Description
Reads a signed 8-bit value from this file. This method reads a byte from the file. If the byte read is b, where 0 <= b <= 255, then the result is:
    (byte)(b)

This method blocks until the byte is read, the end of the stream is detected, or an exception is thrown.

Exceptions
EOFException if this file has reached the end.
Exceptions
IOException if an I/O error occurs.


 RandomAccessFile.readChar

RandomAccessFile.readChar

Class Overview | Class Members | This Package | All Packages

Syntax
public final char readChar() throws IOException
Returns
the next two bytes of this file as a Unicode character.
Description
Reads a Unicode character from this file. This method reads two bytes from the file. If the bytes read, in order, are b1 and b2, where 0 <= b1, b2 <= 255, then the result is equal to:
    (char)((b1 << 8) | b2)

This method blocks until the two bytes are read, the end of the stream is detected, or an exception is thrown.

Exceptions
EOFException if this file reaches the end before reading two bytes.
Exceptions
IOException if an I/O error occurs.


 RandomAccessFile.readDouble

RandomAccessFile.readDouble

Class Overview | Class Members | This Package | All Packages

Syntax
public final double readDouble() throws IOException
Returns
the next eight bytes of this file, interpreted as a double.
Description
Reads a double from this file. This method reads a long value as if by the readLong method and then converts that long to a double using the longBitsToDouble method in class Double.

This method blocks until the eight bytes are read, the end of the stream is detected, or an exception is thrown.

Exceptions
EOFException if this file reaches the end before reading eight bytes.
Exceptions
IOException if an I/O error occurs.
See Also
readLong, longBitsToDouble


 RandomAccessFile.readFloat

RandomAccessFile.readFloat

Class Overview | Class Members | This Package | All Packages

Syntax
public final float readFloat() throws IOException
Returns
the next four bytes of this file, interpreted as a float.
Description
Reads a float from this file. This method reads an int value as if by the readInt method and then converts that int to a float using the intBitsToFloat method in class Float.

This method blocks until the four bytes are read, the end of the stream is detected, or an exception is thrown.

Exceptions
EOFException if this file reaches the end before reading four bytes.
Exceptions
IOException if an I/O error occurs.
See Also
readInt, intBitsToFloat


 RandomAccessFile.readFully

RandomAccessFile.readFully

Class Overview | Class Members | This Package | All Packages

Syntax 1
public final void readFully( byte b[] ) throws IOException
Parameters
b
the buffer into which the data is read.
Description
Reads b.length bytes from this file into the byte array. This method reads repeatedly from the file until all the bytes are read. This method blocks until all the bytes are read, the end of the stream is detected, or an exception is thrown.

Exceptions
EOFException if this file reaches the end before reading all the bytes.
Exceptions
IOException if an I/O error occurs.

Syntax 2
public final void readFully( byte b[], int off, int len ) throws IOException
Parameters
b
the buffer into which the data is read.
off
the start offset of the data.
len
the number of bytes to read.
Description
Reads exactly len bytes from this file into the byte array. This method reads repeatedly from the file until all the bytes are read. This method blocks until all the bytes are read, the end of the stream is detected, or an exception is thrown.

Exceptions
EOFException if this file reaches the end before reading all the bytes.
Exceptions
IOException if an I/O error occurs.


 RandomAccessFile.readInt

RandomAccessFile.readInt

Class Overview | Class Members | This Package | All Packages

Syntax
public final int readInt() throws IOException
Returns
the next four bytes of this file, interpreted as an int.
Description
Reads a signed 32-bit integer from this file. This method reads 4 bytes from the file. If the bytes read, in order, are b1, b2, b3, and b4, where 0 <= b1, b2, b3, b4 <= 255, then the result is equal to:
    (b1 << 24) | (b2 << 16) + (b3 << 8) + b4

This method blocks until the four bytes are read, the end of the stream is detected, or an exception is thrown.

Exceptions
EOFException if this file reaches the end before reading four bytes.
Exceptions
IOException if an I/O error occurs.


 RandomAccessFile.readLine

RandomAccessFile.readLine

Class Overview | Class Members | This Package | All Packages

Syntax
public final String readLine() throws IOException
Returns
the next line of text from this file.
Description
Reads the next line of text from this file. This method successively reads bytes from the file until it reaches the end of a line of text.

A line of text is terminated by a carriage-return character ('\r'), a newline character ('\n'), a carriage-return character immediately followed by a newline character, or the end of the input stream. The line-terminating character(s), if any, are included as part of the string returned.

This method blocks until a newline character is read, a carriage return and the byte following it are read (to see if it is a newline), the end of the stream is detected, or an exception is thrown.

Exceptions
IOException if an I/O error occurs.


 RandomAccessFile.readLong

RandomAccessFile.readLong

Class Overview | Class Members | This Package | All Packages

Syntax
public final long readLong() throws IOException
Returns
the next eight bytes of this file, interpreted as a long.
Description
Reads a signed 64-bit integer from this file. This method reads eight bytes from the file. If the bytes read, in order, are b1, b2, b3, b4, b5, b6, b7, and b8, where:
    0 <= b1, b2, b3, b4, b5, b6, b7, b8 <=255,

then the result is equal to:

     ((long)b1 << 56) + ((long)b2 << 48)
     + ((long)b3 << 40) + ((long)b4 << 32)
     + ((long)b5 << 24) + ((long)b6 << 16)
     + ((long)b7 << 8) + b8

This method blocks until the eight bytes are read, the end of the stream is detected, or an exception is thrown.

Exceptions
EOFException if this file reaches the end before reading eight bytes.
Exceptions
IOException if an I/O error occurs.


 RandomAccessFile.readShort

RandomAccessFile.readShort

Class Overview | Class Members | This Package | All Packages

Syntax
public final short readShort() throws IOException
Returns
the next two bytes of this file, interpreted as a signed 16-bit number.
Description
Reads a signed 16-bit number from this file. The method reads 2 bytes from this file. If the two bytes read, in order, are b1 and b2, where each of the two values is between 0 and 255, inclusive, then the result is equal to:
    (short)((b1 << 8) | b2)

This method blocks until the two bytes are read, the end of the stream is detected, or an exception is thrown.

Exceptions
EOFException if this file reaches the end before reading two bytes.
Exceptions
IOException if an I/O error occurs.


 RandomAccessFile.readUnsignedByte

RandomAccessFile.readUnsignedByte

Class Overview | Class Members | This Package | All Packages

Syntax
public final int readUnsignedByte() throws IOException
Returns
the next byte of this file, interpreted as an unsigned 8-bit number.
Description
Reads an unsigned 8-bit number from this file. This method reads a byte from this file and returns that byte.

This method blocks until the byte is read, the end of the stream is detected, or an exception is thrown.

Exceptions
EOFException if this file has reached the end.
Exceptions
IOException if an I/O error occurs.


 RandomAccessFile.readUnsignedShort

RandomAccessFile.readUnsignedShort

Class Overview | Class Members | This Package | All Packages

Syntax
public final int readUnsignedShort() throws IOException
Returns
the next two bytes of this file, interpreted as an unsigned 16-bit integer.
Description
Reads an unsigned 16-bit number from this file. This method reads two bytes from the file. If the bytes read, in order, are b1 and b2, where 0 <= b1, b2 <= 255, then the result is equal to:
    (b1 << 8) | b2

This method blocks until the two bytes are read, the end of the stream is detected, or an exception is thrown.

Exceptions
EOFException if this file reaches the end before reading two bytes.
Exceptions
IOException if an I/O error occurs.


 RandomAccessFile.readUTF

RandomAccessFile.readUTF

Class Overview | Class Members | This Package | All Packages

Syntax
public final String readUTF() throws IOException
Returns
a Unicode string.
Description
Reads in a string from this file. The string has been encoded using a modified UTF-8 format.

The first two bytes are read as if by readUnsignedShort. This value gives the number of following bytes that are in the encoded string, not the length of the resulting string. The following bytes are then interpreted as bytes encoding characters in the UTF-8 format and are converted into characters.

This method blocks until all the bytes are read, the end of the stream is detected, or an exception is thrown.

Exceptions
EOFException if this file reaches the end before reading all the bytes.
Exceptions
IOException if an I/O error occurs.
Exceptions
UTFDataFormatException if the bytes do not represent valid UTF-8 encoding of a Unicode string.
See Also
readUnsignedShort


 RandomAccessFile.seek

RandomAccessFile.seek

Class Overview | Class Members | This Package | All Packages

Syntax
public native void seek( long pos ) throws IOException
Parameters
pos
the absolute position.
Description
Sets the offset from the beginning of this file at which the next read or write occurs.

Exceptions
IOException if an I/O error occurs.


 RandomAccessFile.skipBytes

RandomAccessFile.skipBytes

Class Overview | Class Members | This Package | All Packages

Syntax
public int skipBytes( int n ) throws IOException
Parameters
n
the number of bytes to be skipped.
Returns
the number of bytes skipped, which is always n.
Description
Skips exactly n bytes of input.

This method blocks until all the bytes are skipped, the end of the stream is detected, or an exception is thrown.

Exceptions
EOFException if this file reaches the end before skipping all the bytes.
Exceptions
IOException if an I/O error occurs.


 RandomAccessFile.write

RandomAccessFile.write

Class Overview | Class Members | This Package | All Packages

Syntax 1
public native void write( int b ) throws IOException
Parameters
b
the byte to be written.
Description
Writes the specified byte to this file.

Exceptions
IOException if an I/O error occurs.

Syntax 2
public void write( byte b[] ) throws IOException
Parameters
b
the data.
Description
Writes b.length bytes from the specified byte array starting at offset off to this file.

Exceptions
IOException if an I/O error occurs.

Syntax 3
public void write( byte b[], int off, int len ) throws IOException
Parameters
b
the data.
off
the start offset in the data.
len
the number of bytes to write.
Description
Writes len bytes from the specified byte array starting at offset off to this file.

Exceptions
IOException if an I/O error occurs.


 RandomAccessFile.writeBoolean

RandomAccessFile.writeBoolean

Class Overview | Class Members | This Package | All Packages

Syntax
public final void writeBoolean( boolean v ) throws IOException
Parameters
v
a boolean value to be written.
Description
Writes a boolean to the file as a 1-byte value. The value true is written out as the value (byte)1; the value false is written out as the value (byte)0.

Exceptions
IOException if an I/O error occurs.


 RandomAccessFile.writeByte

RandomAccessFile.writeByte

Class Overview | Class Members | This Package | All Packages

Syntax
public final void writeByte( int v ) throws IOException
Parameters
v
a byte value to be written.
Description
Writes a byte to the file as a 1-byte value.

Exceptions
IOException if an I/O error occurs.


 RandomAccessFile.writeBytes

RandomAccessFile.writeBytes

Class Overview | Class Members | This Package | All Packages

Syntax
public final void writeBytes( String s ) throws IOException
Parameters
s
a string of bytes to be written.
Description
Writes the string to the file as a sequence of bytes. Each character in the string is written out, in sequence, by discarding its high eight bits.

Exceptions
IOException if an I/O error occurs.


 RandomAccessFile.writeChar

RandomAccessFile.writeChar

Class Overview | Class Members | This Package | All Packages

Syntax
public final void writeChar( int v ) throws IOException
Parameters
v
a char value to be written.
Description
Writes a char to the file as a 2-byte value, high byte first.

Exceptions
IOException if an I/O error occurs.


 RandomAccessFile.writeChars

RandomAccessFile.writeChars

Class Overview | Class Members | This Package | All Packages

Syntax
public final void writeChars( String s ) throws IOException
Parameters
s
a String value to be written.
Description
Writes a string to the file as a sequence of characters. Each character is written to the data output stream as if by the writeChar method.

Exceptions
IOException if an I/O error occurs.
See Also
writeChar


 RandomAccessFile.writeDouble

RandomAccessFile.writeDouble

Class Overview | Class Members | This Package | All Packages

Syntax
public final void writeDouble( double v ) throws IOException
Parameters
v
a double value to be written.
Description
Converts the double argument to a long using the doubleToLongBits method in class Double, and then writes that long value to the file as an 8-byte quantity, high byte first.

Exceptions
IOException if an I/O error occurs.
See Also
doubleToLongBits


 RandomAccessFile.writeFloat

RandomAccessFile.writeFloat

Class Overview | Class Members | This Package | All Packages

Syntax
public final void writeFloat( float v ) throws IOException
Parameters
v
a float value to be written.
Description
Converts the float argument to an int using the floatToIntBits method in class Float, and then writes that int value to the file as a 4-byte quantity, high byte first.

Exceptions
IOException if an I/O error occurs.
See Also
floatToIntBits


 RandomAccessFile.writeInt

RandomAccessFile.writeInt

Class Overview | Class Members | This Package | All Packages

Syntax
public final void writeInt( int v ) throws IOException
Parameters
v
an int to be written.
Description
Writes an int to the file as four bytes, high byte first.

Exceptions
IOException if an I/O error occurs.


 RandomAccessFile.writeLong

RandomAccessFile.writeLong

Class Overview | Class Members | This Package | All Packages

Syntax
public final void writeLong( long v ) throws IOException
Parameters
v
a long to be written.
Description
Writes a long to the file as eight bytes, high byte first.

Exceptions
IOException if an I/O error occurs.


 RandomAccessFile.writeShort

RandomAccessFile.writeShort

Class Overview | Class Members | This Package | All Packages

Syntax
public final void writeShort( int v ) throws IOException
Parameters
v
a short to be written.
Description
Writes a short to the file as two bytes, high byte first.

Exceptions
IOException if an I/O error occurs.


 RandomAccessFile.writeUTF

RandomAccessFile.writeUTF

Class Overview | Class Members | This Package | All Packages

Syntax
public final void writeUTF( String str ) throws IOException
Parameters
str
a string to be written.
Description
Writes a string to the file using UTF-8 encoding in a machine-independent manner.

First, two bytes are written to the file as if by the writeShort method giving the number of bytes to follow. This value is the number of bytes actually written out, not the length of the string. Following the length, each character of the string is output, in sequence, using the UTF-8 encoding for each character.

Exceptions
IOException if an I/O error occurs.


 Class Reader

Class java.io.Reader

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.Reader

public abstract class Reader
extends Object

Abstract class for reading character streams. The only methods that a subclass must implement are read(char[], int, int) and close(). Most subclasses, however, will override some of the methods defined here in order to provide higher efficiency, additional functionality, or both.

See Also:
BufferedReader, LineNumberReader, CharArrayReader, InputStreamReader, FileReader, FilterReader, PushbackReader, PipedReader, StringReader, Writer


 Reader Members

Reader Members

Class Overview | This Package | All Packages

Fields
Name | Description
lock | The object used to synchronize operations on this stream.

Constructors
Name | Description
Reader() | Create a new character-stream reader whose critical sections will synchronize on the reader itself.
Reader(Object) | Create a new character-stream reader whose critical sections will synchronize on the given object.

Methods
Name | Description
close() | Close the stream.
mark(int) | Mark the present position in the stream.
markSupported() | Tell whether this stream supports the mark() operation.
read() | Read a single character.
read(char[]) | Read characters into an array.
read(char[], int, int) | Read characters into a portion of an array.
ready() | Tell whether this stream is ready to be read.
reset() | Reset the stream.
skip(long) | Skip characters.


 Reader.lock

Reader.lock

Class Overview | Class Members | This Package | All Packages

Syntax
protected Object lock
Description
The object used to synchronize operations on this stream. For efficiency, a character-stream object may use an object other than itself to protect critical sections. A subclass should therefore use the object in this field rather than this or a synchronized method.


 Reader.Reader

Reader.Reader

Class Overview | Class Members | This Package | All Packages

Syntax 1
protected Reader()
Description
Create a new character-stream reader whose critical sections will synchronize on the reader itself.

Syntax 2
protected Reader( Object lock )
Description
Create a new character-stream reader whose critical sections will synchronize on the given object.


 Reader.close

Reader.close

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void close() throws IOException
Description
Close the stream. Once a stream has been closed, further read(), ready(), mark(), or reset() invocations will throw an IOException. Closing a previously-closed stream, however, has no effect.

Exceptions
IOException If an I/O error occurs


 Reader.mark

Reader.mark

Class Overview | Class Members | This Package | All Packages

Syntax
public void mark( int readAheadLimit ) throws IOException
Parameters
readAheadLimit
Limit on the number of characters that may be read while still preserving the mark. After reading this many characters, attempting to reset the stream may fail.
Description
Mark the present position in the stream. Subsequent calls to reset() will attempt to reposition the stream to this point. Not all character-input streams support the mark() operation.

Exceptions
IOException If the stream does not support mark(), or if some other I/O error occurs


 Reader.markSupported

Reader.markSupported

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean markSupported()
Description
Tell whether this stream supports the mark() operation.


 Reader.read

Reader.read

Class Overview | Class Members | This Package | All Packages

Syntax 1
public int read() throws IOException
Returns
The character read, as an integer in the range 0 to 16383 (0x00-0xffff), or -1 if the end of the stream has been reached
Description
Read a single character. This method will block until a character is available, an I/O error occurs, or the end of the stream is reached.

Subclasses that intend to support efficient single-character input should override this method.

Exceptions
IOException If an I/O error occurs

Syntax 2
public int read( char cbuf[] ) throws IOException
Parameters
cbuf
Destination buffer
Returns
The number of bytes read, or -1 if the end of the stream has been reached
Description
Read characters into an array. This method will block until some input is available, an I/O error occurs, or the end of the stream is reached.

Exceptions
IOException If an I/O error occurs

Syntax 3
public abstract int read( char cbuf[], int off, int len ) throws IOException
Parameters
cbuf
Destination buffer
off
Offset at which to start storing characters
len
Maximum number of characters to read
Returns
The number of characters read, or -1 if the end of the stream has been reached
Description
Read characters into a portion of an array. This method will block until some input is available, an I/O error occurs, or the end of the stream is reached.

Exceptions
IOException If an I/O error occurs


 Reader.ready

Reader.ready

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean ready() throws IOException
Returns
True if the next read() is guaranteed not to block for input, false otherwise. Note that returning false does not guarantee that the next read will block.
Description
Tell whether this stream is ready to be read.

Exceptions
IOException If an I/O error occurs


 Reader.reset

Reader.reset

Class Overview | Class Members | This Package | All Packages

Syntax
public void reset() throws IOException
Description
Reset the stream. If the stream has been marked, then attempt to reposition it at the mark. If the stream has not been marked, then attempt to reset it in some way appropriate to the particular stream, for example by repositioning it to its starting point. Not all character-input streams support the reset() operation, and some support reset() without supporting mark().

Exceptions
IOException If the stream has not been marked, or if the mark has been invalidated, or if the stream does not support reset(), or if some other I/O error occurs


 Reader.skip

Reader.skip

Class Overview | Class Members | This Package | All Packages

Syntax
public long skip( long n ) throws IOException
Parameters
n
The number of characters to skip
Returns
The number of characters actually skipped
Description
Skip characters. This method will block until some characters are available, an I/O error occurs, or the end of the stream is reached.

Exceptions
IOException If an I/O error occurs


 Class SequenceInputStream

Class java.io.SequenceInputStream

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.InputStream
           |
           +----java.io.SequenceInputStream

public class SequenceInputStream
extends InputStream

The sequence input stream class allows an application to combine several input streams serially and make them appear as if they were a single input stream. Each input stream is read from, in turn, until it reaches the end of the stream. The sequence input stream class then closes that stream and automatically switches to the next input stream.


 SequenceInputStream Members

SequenceInputStream Members

Class Overview | This Package | All Packages

Constructors
Name | Description
SequenceInputStream(Enumeration) | Constructs a new sequence input stream initialized to the specified enumeration of input streams.
SequenceInputStream(InputStream, InputStream) | Constructs a new sequence input stream initialized to read first from the input stream s1, and then from the input stream s2.

Methods
Name | Description
available() | Returns the number of bytes available on the current stream.
close() | Closes this input stream and releases any system resources associated with the stream.
read() | Reads the next byte of data from this input stream.
read(byte[], int, int) | Reads up to len bytes of data from this input stream into an array of bytes.


 SequenceInputStream.SequenceInputStream

SequenceInputStream.SequenceInputStream

Class Overview | Class Members | This Package | All Packages

Syntax 1
public SequenceInputStream( Enumeration e )
Parameters
e
an enumeration of input streams.
Description
Constructs a new sequence input stream initialized to the specified enumeration of input streams. Each object in the enumeration must be an InputStream.

See Also
Enumeration

Syntax 2
public SequenceInputStream( InputStream s1, InputStream s2 )
Parameters
s1
the first input stream to read.
s2
the second input stream to read.
Description
Constructs a new sequence input stream initialized to read first from the input stream s1, and then from the input stream s2.


 SequenceInputStream.available

SequenceInputStream.available

Class Overview | Class Members | This Package | All Packages

Syntax
public int available() throws IOException
Description
Returns the number of bytes available on the current stream.

Overrides
available in class InputStream


 SequenceInputStream.close

SequenceInputStream.close

Class Overview | Class Members | This Package | All Packages

Syntax
public void close() throws IOException
Description
Closes this input stream and releases any system resources associated with the stream.

The close method of SequenceInputStream calls the close method of both the substream from which it is currently reading and the close method of all the substreams that it has not yet begun to read from.

Exceptions
IOException if an I/O error occurs.
Overrides
close in class InputStream


 SequenceInputStream.read

SequenceInputStream.read

Class Overview | Class Members | This Package | All Packages

Syntax 1
public int read() throws IOException
Returns
the next byte of data, or -1 if the end of the stream is reached.
Description
Reads the next byte of data from this input stream. The byte is returned as an int in the range 0 to 255. If no byte is available because the end of the stream has been reached, the value -1 is returned. This method blocks until input data is available, the end of the stream is detected, or an exception is thrown.

The read method of SequenceInputStream tries to read one character from the current substream. If it reaches the end of the stream, it calls the close method of the current substream and begins reading from the next substream.

Exceptions
IOException if an I/O error occurs.
Overrides
read in class InputStream

Syntax 2
public int read( byte buf[], int pos, int len ) throws IOException
Parameters
b
the buffer into which the data is read.
off
the start offset of the data.
len
the maximum number of bytes read.
Description
Reads up to len bytes of data from this input stream into an array of bytes. This method blocks until at least 1 byte of input is available. If the first argument is null, up to len bytes are read and discarded.

The read method of SequenceInputStream tries to read the data from the current substream. If it fails to read any characters because the substream has reached the end of the stream, it calls the close method of the current substream and begins reading from the next substream.

Exceptions
IOException if an I/O error occurs.
Overrides
read in class InputStream


 Interface Serializable

Interface java.io.Serializable

This Package | All Packages

public interface Serializable

Serializability of a class is enabled by the class implementing the java.io.Serializable interface. Classes that do not implement this interface will not have any of their state serialized or deserialized. All subtypes of a serializable class are themselves serializable. The serialization interface has no methods or fields and serves only to identify the semantics of being serializable.

To allow subtypes of non-serializable classes to be serialized, the subtype may assume responsibility for saving and restoring the state of the supertype's public, protected, and (if accessible) package fields. The subtype may assume this responsibility only if the class it extends has an accessible no-arg constructor to initialize the class's state. It is an error to declare a class Serializable in this case. The error will be detected at runtime.

During deserialization, the fields of non-serializable classes will be initialized using the public or protected no-arg constructor of the class. A no-arg constructor must be accessible to the subclass that is serializable. The fields of serializable subclasses will be restored from the stream.

When traversing a graph, an object may be encountered that does not support the Serializable interface. In this case the NotSerializableException will be thrown and will identify the class of the non-serializable object.

Classes that require special handling during the serialization and deserialization process must implement special methods with these exact signatures:

 private void writeObject(java.io.ObjectOutputStream out)
     throws IOException
 private void readObject(java.io.ObjectInputStream in)
     throws IOException, ClassNotFoundException;

The writeObject method is responsible for writing the state of the object for its particular class so that the corresponding readObject method can restore it. The default mechanism for saving the Object's fields can be invoked by calling out.defaultWriteObject. The method does not need to concern itself with the state belonging to its superclasses or subclasses. State is saved by writing the individual fields to the ObjectOutputStream using the writeObject method or by using the methods for primitive data types supported by DataOutput.

The readObject method is responsible for reading from the stream and restoring the classes fields. It may call in.defaultReadObject to invoke the default mechanism for restoring the object's non-static and non-transient fields. The defaultReadObject method uses information in the stream to assign the fields of the object saved in the stream with the correspondingly named fields in the current object. This handles the case when the class has evolved to add new fields. The method does not need to concern itself with the state belonging to its superclasses or subclasses. State is saved by writing the individual fields to the ObjectOutputStream using the writeObject method or by using the methods for primitive data types supported by DataOutput.

See Also:
ObjectOutputStream, ObjectInputStream, ObjectOutput, ObjectInput, Externalizable


 Class StreamCorruptedException

Class java.io.StreamCorruptedException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.io.IOException
                           |
                           +----java.io.ObjectStreamException
                                   |
                                   +----java.io.StreamCorruptedException

public class StreamCorruptedException
extends ObjectStreamException

Raised when control information read from an object stream violates internal consistency checks.


 StreamCorruptedException Members

StreamCorruptedException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
StreamCorruptedException() | Create a StreamCorruptedException with no reason.
StreamCorruptedException(String) | Create a StreamCorruptedException with a reason.


 StreamCorruptedException.StreamCorruptedException

StreamCorruptedException.StreamCorruptedException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public StreamCorruptedException( String reason )
Description
Create a StreamCorruptedException with a reason.

Syntax 2
public StreamCorruptedException()
Description
Create a StreamCorruptedException with no reason.


 Class StreamTokenizer

Class java.io.StreamTokenizer

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.StreamTokenizer

public class StreamTokenizer
extends Object

The StreamTokenizer class takes an input stream and parses it into "tokens", allowing the tokens to be read one at a time. The parsing process is controlled by a table and a number of flags that can be set to various states. The stream tokenizer can recognize identifiers, numbers, quoted strings, and various comment styles.

Each byte read from the input stream is regarded as a character in the range '\u0000' through '\u00FF'. The character value is used to look up five possible attributes of the character: white space, alphabetic, numeric, string quote, and comment character. Each character can have zero or more of these attributes.

In addition, an instance has four flags. These flags indicate:

  • Whether line terminators are to be returned as tokens or treated as white space that merely separates tokens.
  • Whether C-style comments are to be recognized and skipped.
  • Whether C++-style comments are to be recognized and skipped.
  • Whether the characters of identifiers are converted to lowercase.

A typical application first constructs an instance of this class, sets up the syntax tables, and then repeatedly loops calling the nextToken method in each iteration of the loop until it returns the value TT_EOF.

See Also:
nextToken, TT_EOF


 StreamTokenizer Members

StreamTokenizer Members

Class Overview | This Package | All Packages

Fields
Name | Description
nval | If the current token is a number, this field contains the value of that number.
sval | If the current token is a word token, this field contains a string giving the characters of the word token.
TT_EOF | A constant indicating that the end of the stream has been read.
TT_EOL | A constant indicating that the end of the line has been read.
TT_NUMBER | A constant indicating that a number token has been read.
TT_WORD | A constant indicating that a word token has been read.
ttype | After a call to the nextToken method, this field contains the type of the token just read.

Constructors
Name | Description
StreamTokenizer(InputStream) | Creates a stream tokenizer that parses the specified input stream. Deprecated.
StreamTokenizer(Reader) | Create a tokenizer that parses the given character stream.

Methods
Name | Description
commentChar(int) | Specified that the character argument starts a single-line comment.
eolIsSignificant(boolean) | Determines whether or not ends of line are treated as tokens.
lineno() | Return the current line number.
lowerCaseMode(boolean) | Determines whether or not word token are automatically lowercased.
nextToken() | Parses the next token from the input stream of this tokenizer.
ordinaryChar(int) | Specifies that the character argument is "ordinary" in this tokenizer.
ordinaryChars(int, int) | Specifies that all characters c in the range low <= c <= high are "ordinary" in this tokenizer.
parseNumbers() | Specifies that numbers should be parsed by this tokenizer.
pushBack() | Causes the next call to the nextToken method of this tokenizer to return the current value in the ttype field, and not to modify the value in the nval or sval field.
quoteChar(int) | Specifies that matching pairs of this character delimit string constants in this tokenizer.
resetSyntax() | Resets this tokenizer's syntax table so that all characters are "ordinary." See the ordinaryChar method for more information on a character being ordinary.
slashSlashComments(boolean) | Determines whether or not the tokenizer recognizes C++-style comments.
slashStarComments(boolean) | Determines whether or not the tokenizer recognizes C-style comments.
toString() | Returns the string representation of the current stream token.
whitespaceChars(int, int) | Specifies that all characters c in the range low <= c <= high are white space characters.
wordChars(int, int) | Specifies that all characters c in the range low <= c <= high are word constituents.


 StreamTokenizer.nval

StreamTokenizer.nval

Class Overview | Class Members | This Package | All Packages

Syntax
public double nval
Description
If the current token is a number, this field contains the value of that number. The current token is a number when the value of the ttype field is TT_NUMBER.

See Also
TT_NUMBER, ttype


 StreamTokenizer.sval

StreamTokenizer.sval

Class Overview | Class Members | This Package | All Packages

Syntax
public String sval
Description
If the current token is a word token, this field contains a string giving the characters of the word token. When the current token is a quoted string token, this field contains the body of the string.

The current token is a word when the value of the ttype field is TT_WORD. The current token is a quoted string token when the value of the ttype field is a quote character.

See Also
quoteChar, TT_WORD, ttype


 StreamTokenizer.TT_EOF

StreamTokenizer.TT_EOF

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int TT_EOF
Description
A constant indicating that the end of the stream has been read.


 StreamTokenizer.TT_EOL

StreamTokenizer.TT_EOL

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int TT_EOL
Description
A constant indicating that the end of the line has been read.


 StreamTokenizer.TT_NUMBER

StreamTokenizer.TT_NUMBER

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int TT_NUMBER
Description
A constant indicating that a number token has been read.


 StreamTokenizer.TT_WORD

StreamTokenizer.TT_WORD

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int TT_WORD
Description
A constant indicating that a word token has been read.


 StreamTokenizer.ttype

StreamTokenizer.ttype

Class Overview | Class Members | This Package | All Packages

Syntax
public int ttype
Description
After a call to the nextToken method, this field contains the type of the token just read. For a single character token, its value is the single character, converted to an integer. For a quoted string token (see , its value is the quote character. Otherwise, its value is one of the following:
  • TT_WORD indicates that the token is a word.
  • TT_NUMBER indicates that the token is a number.
  • TT_EOL indicates that the end of line has been read. The field can only have this value if the eolIsSignificant method has been called with the argument true.
  • TT_EOF indicates that the end of the input stream has been reached.

See Also
eolIsSignificant, nextToken, quoteChar, TT_EOF, TT_EOL, TT_NUMBER, TT_WORD


 StreamTokenizer.StreamTokenizer

StreamTokenizer.StreamTokenizer

Class Overview | Class Members | This Package | All Packages

Syntax 1
public StreamTokenizer( InputStream is )
Parameters
is
an input stream.
Description
Note: StreamTokenizer() is deprecated. As of JDK version 1.1, the preferred way to tokenize an input stream is to convert it into a character stream, for example:

   Reader r = new BufferedReader(new InputStreamReader(is));
   StreamTokenizer st = new StreamTokenizer(r);

Creates a stream tokenizer that parses the specified input stream. The stream tokenizer is initialized to the following default state:

  • All byte values 'A' through 'Z', 'a' through 'z', and '\u00A0' through '\u00FF' are considered to be alphabetic.
  • All byte values '\u0000' through '\u0020' are considered to be white space.
  • '/' is a comment character.
  • Single quote '\'' and double quote '"' are string quote characters.
  • Numbers are parsed.
  • Ends of lines are treated as white space, not as separate tokens.
  • C-style and C++-style comments are not recognized.

See Also
BufferedReader, InputStreamReader, StreamTokenizer

Syntax 2
public StreamTokenizer( Reader r )
Description
Create a tokenizer that parses the given character stream.


 StreamTokenizer.commentChar

StreamTokenizer.commentChar

Class Overview | Class Members | This Package | All Packages

Syntax
public void commentChar( int ch )
Parameters
ch
the character.
Description
Specified that the character argument starts a single-line comment. All characters from the comment character to the end of the line are ignored by this stream tokenizer.


 StreamTokenizer.eolIsSignificant

StreamTokenizer.eolIsSignificant

Class Overview | Class Members | This Package | All Packages

Syntax
public void eolIsSignificant( boolean flag )
Parameters
flag
true indicates that end-of-line characters are separate tokens; false indicates that end-of-line characters are white space.
Description
Determines whether or not ends of line are treated as tokens. If the flag argument is true, this tokenizer treats end of lines as tokens; the nextToken method returns TT_EOL and also sets the ttype field to this value when an end of line is read.

A line is a sequence of characters ending with either a carriage-return character ('\r') or a newline character ('\n'). In addition, a carriage-return character followed immediately by a newline character is treated as a single end-of-line token.

If the flag is false, end-of-line characters are treated as white space and serve only to separate tokens.

See Also
nextToken, ttype, TT_EOL


 StreamTokenizer.lineno

StreamTokenizer.lineno

Class Overview | Class Members | This Package | All Packages

Syntax
public int lineno()
Returns
the current line number of this stream tokenizer.
Description
Return the current line number.


 StreamTokenizer.lowerCaseMode

StreamTokenizer.lowerCaseMode

Class Overview | Class Members | This Package | All Packages

Syntax
public void lowerCaseMode( boolean fl )
Parameters
fl
true indicates that all word tokens should be lowercased.
Description
Determines whether or not word token are automatically lowercased. If the flag argument is true, then the value in the sval field is lowercased whenever a word token is returned (the ttype field has the value TT_WORD by the nextToken method of this tokenizer.

If the flag argument is false, then the sval field is not modified.

See Also
nextToken, ttype, TT_WORD


 StreamTokenizer.nextToken

StreamTokenizer.nextToken

Class Overview | Class Members | This Package | All Packages

Syntax
public int nextToken() throws IOException
Returns
the value of the ttype field.
Description
Parses the next token from the input stream of this tokenizer. The type of the next token is returned in the ttype field. Additional information about the token may be in the nval field or the sval field of this tokenizer.

Typical clients of this class first set up the syntax tables and then sit in a loop calling nextToken to parse successive tokens until TT_EOF is returned.

Exceptions
IOException if an I/O error occurs.
See Also
nval, sval, ttype


 StreamTokenizer.ordinaryChar

StreamTokenizer.ordinaryChar

Class Overview | Class Members | This Package | All Packages

Syntax
public void ordinaryChar( int ch )
Parameters
ch
the character.
Description
Specifies that the character argument is "ordinary" in this tokenizer. It removes any special significance the character has as a comment character, word component, string delimiter, white space, or number character. When such a character is encountered by the parser, the parser treates it as a single-character token and sets ttype field to the character value.

See Also
ttype


 StreamTokenizer.ordinaryChars

StreamTokenizer.ordinaryChars

Class Overview | Class Members | This Package | All Packages

Syntax
public void ordinaryChars( int low, int hi )
Parameters
low
the low end of the range.
hi
the high end of the range.
Description
Specifies that all characters c in the range low <= c <= high are "ordinary" in this tokenizer. See the ordinaryChar method for more information on a character being ordinary.

See Also
ordinaryChar


 StreamTokenizer.parseNumbers

StreamTokenizer.parseNumbers

Class Overview | Class Members | This Package | All Packages

Syntax
public void parseNumbers()
Description
Specifies that numbers should be parsed by this tokenizer. The syntax table of this tokenizer is modified so that each of the twelve characters:
    0 1 2 3 4 5 6 7 8 9 . -

has the "numeric" attribute.

When the parser encounters a word token that has the format of a double precision floating-point number, it treats the token as a number rather than a word, by setting the the ttype field to the value TT_NUMBER and putting the numeric value of the token into the nval field.

See Also
nval, TT_NUMBER, ttype


 StreamTokenizer.pushBack

StreamTokenizer.pushBack

Class Overview | Class Members | This Package | All Packages

Syntax
public void pushBack()
Description
Causes the next call to the nextToken method of this tokenizer to return the current value in the ttype field, and not to modify the value in the nval or sval field.

See Also
nextToken, nval, sval, ttype


 StreamTokenizer.quoteChar

StreamTokenizer.quoteChar

Class Overview | Class Members | This Package | All Packages

Syntax
public void quoteChar( int ch )
Parameters
ch
the character.
Description
Specifies that matching pairs of this character delimit string constants in this tokenizer.

When the nextToken method encounters a string constant, the ttype field is set to the string delimiter and the sval field is set to the body of the string.

If a string quote character is encountered, then a string is recognized, consisting of all characters after (but not including) the string quote character, up to (but not including) the next occurrence of that same string quote character, or a line terminator, or end of file. The usual escape sequences such as "\n" and "\t" are recognized and converted to single characters as the string is parsed.

See Also
nextToken, sval, ttype


 StreamTokenizer.resetSyntax

StreamTokenizer.resetSyntax

Class Overview | Class Members | This Package | All Packages

Syntax
public void resetSyntax()
Description
Resets this tokenizer's syntax table so that all characters are "ordinary." See the ordinaryChar method for more information on a character being ordinary.

See Also
ordinaryChar


 StreamTokenizer.slashSlashComments

StreamTokenizer.slashSlashComments

Class Overview | Class Members | This Package | All Packages

Syntax
public void slashSlashComments( boolean flag )
Parameters
flag
true indicates to recognize and ignore C++-style comments.
Description
Determines whether or not the tokenizer recognizes C++-style comments. If the flag argument is true, this stream tokenizer recognizes C++-style comments. Any occurrence of two consecutive slash characters ('/') is treated as the beginning of a comment that extends to the end of the line.

If the flag argument is false, then C++-style comments are not treated specially.


 StreamTokenizer.slashStarComments

StreamTokenizer.slashStarComments

Class Overview | Class Members | This Package | All Packages

Syntax
public void slashStarComments( boolean flag )
Parameters
flag
true indicates to recognize and ignore C-style comments.
Description
Determines whether or not the tokenizer recognizes C-style comments. If the flag argument is true, this stream tokenizer recognizes C-style comments. All text between successive occurrences of /* and */ are discarded.

If the flag argument is false, then C-style comments are not treated specially.


 StreamTokenizer.toString

StreamTokenizer.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string representation of the token specified by the ttype, nval, and sval fields.
Description
Returns the string representation of the current stream token.

Overrides
toString in class Object
See Also
nval, sval, ttype


 StreamTokenizer.whitespaceChars

StreamTokenizer.whitespaceChars

Class Overview | Class Members | This Package | All Packages

Syntax
public void whitespaceChars( int low, int hi )
Parameters
low
the low end of the range.
hi
the high end of the range.
Description
Specifies that all characters c in the range low <= c <= high are white space characters. White space characters serve only to separate tokens in the input stream.


 StreamTokenizer.wordChars

StreamTokenizer.wordChars

Class Overview | Class Members | This Package | All Packages

Syntax
public void wordChars( int low, int hi )
Parameters
low
the low end of the range.
hi
the high end of the range.
Description
Specifies that all characters c in the range low <= c <= high are word constituents. A word token consists of a word constituent followed by zero or more word constituents or number constituents.


 Class StringBufferInputStream

Class java.io.StringBufferInputStream

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.InputStream
           |
           +----java.io.StringBufferInputStream

public class StringBufferInputStream
extends InputStream

Note: StringBufferInputStream is deprecated. This class does not properly convert characters into bytes. As of JDK 1.1, the preferred way to create a stream from a string is via the StringReader class.

This class allows an application to create an input stream in which the bytes read are supplied by the contents of a string. Applications can also read bytes from a byte array by using a ByteArrayInputStream.

Only the low eight bits of each character in the string are used by this class.

See Also:
ByteArrayInputStream, StringReader


 StringBufferInputStream Members

StringBufferInputStream Members

Class Overview | This Package | All Packages

Fields
Name | Description
buffer | The string from which bytes are read.
count | The number of valid characters in the input stream buffer.
pos | The index of the next character to read from the input stream buffer.

Constructors
Name | Description
StringBufferInputStream(String) | Creates a string input stream to read data from the specified string.

Methods
Name | Description
available() | Returns the number of bytes that can be read from the input stream without blocking.
read() | Reads the next byte of data from this input stream.
read(byte[], int, int) | Reads up to len bytes of data from this input stream into an array of bytes.
reset() | Resets the input stream to begin reading from the first character of this input stream's underlying buffer.
skip(long) | Skips n bytes of input from this input stream.


 StringBufferInputStream.buffer

StringBufferInputStream.buffer

Class Overview | Class Members | This Package | All Packages

Syntax
protected String buffer
Description
The string from which bytes are read.


 StringBufferInputStream.count

StringBufferInputStream.count

Class Overview | Class Members | This Package | All Packages

Syntax
protected int count
Description
The number of valid characters in the input stream buffer.

See Also
buffer


 StringBufferInputStream.pos

StringBufferInputStream.pos

Class Overview | Class Members | This Package | All Packages

Syntax
protected int pos
Description
The index of the next character to read from the input stream buffer.

See Also
buffer


 StringBufferInputStream.StringBufferInputStream

StringBufferInputStream.StringBufferInputStream

Class Overview | Class Members | This Package | All Packages

Syntax
public StringBufferInputStream( String s )
Parameters
s
the underlying input buffer.
Description
Creates a string input stream to read data from the specified string.


 StringBufferInputStream.available

StringBufferInputStream.available

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized int available()
Returns
the value of count - pos, which is the number of bytes remaining to be read from the input buffer.
Description
Returns the number of bytes that can be read from the input stream without blocking.

Overrides
available in class InputStream


 StringBufferInputStream.read

StringBufferInputStream.read

Class Overview | Class Members | This Package | All Packages

Syntax 1
public synchronized int read()
Returns
the next byte of data, or -1 if the end of the stream is reached.
Description
Reads the next byte of data from this input stream. The value byte is returned as an int in the range 0 to 255. If no byte is available because the end of the stream has been reached, the value -1 is returned.

The read method of StringBufferInputStream cannot block. It returns the low eight bits of the next character in this input stream's buffer.

Overrides
read in class InputStream

Syntax 2
public synchronized int read( byte b[], int off, int len )
Parameters
b
the buffer into which the data is read.
off
the start offset of the data.
len
the maximum number of bytes read.
Returns
the total number of bytes read into the buffer, or -1 if there is no more data because the end of the stream has been reached.
Description
Reads up to len bytes of data from this input stream into an array of bytes.

The read method of StringBufferInputStream cannot block. It copies the low eight bits from the characters in this input stream's buffer into the byte array argument.

Overrides
read in class InputStream


 StringBufferInputStream.reset

StringBufferInputStream.reset

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void reset()
Description
Resets the input stream to begin reading from the first character of this input stream's underlying buffer.

Overrides
reset in class InputStream


 StringBufferInputStream.skip

StringBufferInputStream.skip

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized long skip( long n )
Parameters
n
the number of bytes to be skipped.
Returns
the actual number of bytes skipped.
Description
Skips n bytes of input from this input stream. Fewer bytes might be skipped if the end of the input stream is reached.

Overrides
skip in class InputStream


 Class StringReader

Class java.io.StringReader

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.Reader
           |
           +----java.io.StringReader

public class StringReader
extends Reader

A character stream whose source is a string.


 StringReader Members

StringReader Members

Class Overview | This Package | All Packages

Constructors
Name | Description
StringReader(String) | Create a new string reader.

Methods
Name | Description
close() | Close the stream.
mark(int) | Mark the present position in the stream.
markSupported() | Tell whether this stream supports the mark() operation, which it does.
read() | Read a single character.
read(char[], int, int) | Read characters into a portion of an array.
ready() | Tell whether this stream is ready to be read.
reset() | Reset the stream to the most recent mark, or to the beginning of the string if it has never been marked.
skip(long) | Skip characters.


 StringReader.StringReader

StringReader.StringReader

Class Overview | Class Members | This Package | All Packages

Syntax
public StringReader( String s )
Description
Create a new string reader.


 StringReader.close

StringReader.close

Class Overview | Class Members | This Package | All Packages

Syntax
public void close()
Description
Close the stream.

Overrides
close in class Reader


 StringReader.mark

StringReader.mark

Class Overview | Class Members | This Package | All Packages

Syntax
public void mark( int readAheadLimit ) throws IOException
Parameters
readAheadLimit
Limit on the number of characters that may be read while still preserving the mark. Because the stream's input comes from a string, there is no actual limit, so this argument is ignored.
Description
Mark the present position in the stream. Subsequent calls to reset() will reposition the stream to this point.

Exceptions
IOException If an I/O error occurs
Overrides
mark in class Reader


 StringReader.markSupported

StringReader.markSupported

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean markSupported()
Description
Tell whether this stream supports the mark() operation, which it does.

Overrides
markSupported in class Reader


 StringReader.read

StringReader.read

Class Overview | Class Members | This Package | All Packages

Syntax 1
public int read() throws IOException
Returns
The character read, or -1 if the end of the stream has been reached
Description
Read a single character.

Exceptions
IOException If an I/O error occurs
Overrides
read in class Reader

Syntax 2
public int read( char cbuf[], int off, int len ) throws IOException
Parameters
cbuf
Destination buffer
off
Offset at which to start writing characters
len
Maximum number of characters to read
Returns
The number of characters read, or -1 if the end of the stream has been reached
Description
Read characters into a portion of an array.

Exceptions
IOException If an I/O error occurs
Overrides
read in class Reader


 StringReader.ready

StringReader.ready

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean ready()
Description
Tell whether this stream is ready to be read. String readers are always ready to be read.

Overrides
ready in class Reader


 StringReader.reset

StringReader.reset

Class Overview | Class Members | This Package | All Packages

Syntax
public void reset() throws IOException
Description
Reset the stream to the most recent mark, or to the beginning of the string if it has never been marked.

Exceptions
IOException If an I/O error occurs
Overrides
reset in class Reader


 StringReader.skip

StringReader.skip

Class Overview | Class Members | This Package | All Packages

Syntax
public long skip( long ns ) throws IOException
Description
Skip characters.

Exceptions
IOException If an I/O error occurs
Overrides
skip in class Reader


 Class StringWriter

Class java.io.StringWriter

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.Writer
           |
           +----java.io.StringWriter

public class StringWriter
extends Writer

A character stream that collects its output in a string buffer, which can then be used to construct a string.


 StringWriter Members

StringWriter Members

Class Overview | This Package | All Packages

Constructors
Name | Description
StringWriter() | Create a new string writer, using the default initial string-buffer size.
StringWriter(int) | Create a new string writer, using the specified initial string-buffer size.

Methods
Name | Description
close() | Close the stream.
flush() | Flush the stream.
getBuffer() | Return the string buffer itself.
toString() | Return the buffer's current value as a string.
write(char[], int, int) | Write a portion of an array of characters.
write(int) | Write a single character.
write(String) | Write a string.
write(String, int, int) | Write a portion of a string.


 StringWriter.StringWriter

StringWriter.StringWriter

Class Overview | Class Members | This Package | All Packages

Syntax 1
public StringWriter()
Description
Create a new string writer, using the default initial string-buffer size.

Syntax 2
protected StringWriter( int initialSize )
Description
Create a new string writer, using the specified initial string-buffer size.


 StringWriter.close

StringWriter.close

Class Overview | Class Members | This Package | All Packages

Syntax
public void close()
Description
Close the stream. This method does not release the buffer, since its contents might still be required.

Overrides
close in class Writer


 StringWriter.flush

StringWriter.flush

Class Overview | Class Members | This Package | All Packages

Syntax
public void flush()
Description
Flush the stream.

Overrides
flush in class Writer


 StringWriter.getBuffer

StringWriter.getBuffer

Class Overview | Class Members | This Package | All Packages

Syntax
public StringBuffer getBuffer()
Description
Return the string buffer itself.


 StringWriter.toString

StringWriter.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Description
Return the buffer's current value as a string.

Overrides
toString in class Object


 StringWriter.write

StringWriter.write

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void write( int c )
Description
Write a single character.

Overrides
write in class Writer

Syntax 2
public void write( char cbuf[], int off, int len )
Parameters
cbuf
Array of characters
off
Offset from which to start writing characters
len
Number of characters to write
Description
Write a portion of an array of characters.

Overrides
write in class Writer

Syntax 3
public void write( String str )
Description
Write a string.

Overrides
write in class Writer

Syntax 4
public void write( String str, int off, int len )
Parameters
str
String to be written
off
Offset from which to start writing characters
len
Number of characters to write
Description
Write a portion of a string.

Overrides
write in class Writer


 Class SyncFailedException

Class java.io.SyncFailedException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.io.IOException
                           |
                           +----java.io.SyncFailedException

public class SyncFailedException
extends IOException


 SyncFailedException Members

SyncFailedException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
SyncFailedException(String) | Constructs an SyncFailedException with a detail message.


 SyncFailedException.SyncFailedException

SyncFailedException.SyncFailedException

Class Overview | Class Members | This Package | All Packages

Syntax
public SyncFailedException( String desc )
Description
Constructs an SyncFailedException with a detail message. A detail message is a String that describes this particular exception.


 Class UTFDataFormatException

Class java.io.UTFDataFormatException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.io.IOException
                           |
                           +----java.io.UTFDataFormatException

public class UTFDataFormatException
extends IOException

Signals that a malformed UTF-8 string has been read in a data input stream or by any class that implements the data input interface. See the writeUTF method for the format in which UTF-8 strings are read and written.

See Also:
DataInput, readUTF, IOException


 UTFDataFormatException Members

UTFDataFormatException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
UTFDataFormatException() | Constructs a UTFDataFormatException with no detail message.
UTFDataFormatException(String) | Constructs a UTFDataFormatException with the specified detail message.


 UTFDataFormatException.UTFDataFormatException

UTFDataFormatException.UTFDataFormatException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public UTFDataFormatException()
Description
Constructs a UTFDataFormatException with no detail message.

Syntax 2
public UTFDataFormatException( String s )
Parameters
s
the detail message.
Description
Constructs a UTFDataFormatException with the specified detail message.


 Class UnsupportedEncodingException

Class java.io.UnsupportedEncodingException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.io.IOException
                           |
                           +----java.io.UnsupportedEncodingException

public class UnsupportedEncodingException
extends IOException

The Character Encoding is not supported


 UnsupportedEncodingException Members

UnsupportedEncodingException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
UnsupportedEncodingException() | no detailed message
UnsupportedEncodingException(String) | detailed message


 UnsupportedEncodingException.UnsupportedEncodingException

UnsupportedEncodingException.UnsupportedEncodingException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public UnsupportedEncodingException()
Description
no detailed message

Syntax 2
public UnsupportedEncodingException( String s )
Parameters
s
- detailed message
Description
detailed message


 Class WriteAbortedException

Class java.io.WriteAbortedException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.io.IOException
                           |
                           +----java.io.ObjectStreamException
                                   |
                                   +----java.io.WriteAbortedException

public class WriteAbortedException
extends ObjectStreamException


 WriteAbortedException Members

WriteAbortedException Members

Class Overview | This Package | All Packages

Fields
Name | Description
detail |

Constructors
Name | Description
WriteAbortedException(String, Exception) | A WriteAbortedException is thrown during a read when one of the ObjectStreamExceptions was thrown during writing.

Methods
Name | Description
getMessage() | Produce the message, include the message from the nested exception if there is one.


 WriteAbortedException.detail

WriteAbortedException.detail

Class Overview | Class Members | This Package | All Packages

Syntax
public Exception detail


 WriteAbortedException.WriteAbortedException

WriteAbortedException.WriteAbortedException

Class Overview | Class Members | This Package | All Packages

Syntax
public WriteAbortedException( String s, Exception ex )
Description
A WriteAbortedException is thrown during a read when one of the ObjectStreamExceptions was thrown during writing. The exception that terminated the write can be found in the detail field. The stream is reset to it's initial state, all references to objects already deserialized are discarded.


 WriteAbortedException.getMessage

WriteAbortedException.getMessage

Class Overview | Class Members | This Package | All Packages

Syntax
public String getMessage()
Description
Produce the message, include the message from the nested exception if there is one.

Overrides
getMessage in class Throwable


 Class Writer

Class java.io.Writer

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.Writer

public abstract class Writer
extends Object

Abstract class for writing to character streams. The only methods that a subclass must implement are write(char[], int, int), flush(), and close(). Most subclasses, however, will override some of the methods defined here in order to provide higher efficiency, additional functionality, or both.

See Also:
Writer, BufferedWriter, CharArrayWriter, FilterWriter, OutputStreamWriter, FileWriter, PipedWriter, PrintWriter, StringWriter, Reader


 Writer Members

Writer Members

Class Overview | This Package | All Packages

Fields
Name | Description
lock | The object used to synchronize operations on this stream.

Constructors
Name | Description
Writer() | Create a new character-stream writer whose critical sections will synchronize on the writer itself.
Writer(Object) | Create a new character-stream writer whose critical sections will synchronize on the given object.

Methods
Name | Description
close() | Close the stream, flushing it first.
flush() | Flush the stream.
write(char[]) | Write an array of characters.
write(char[], int, int) | Write a portion of an array of characters.
write(int) | Write a single character.
write(String) | Write a string.
write(String, int, int) | Write a portion of a string.


 Writer.lock

Writer.lock

Class Overview | Class Members | This Package | All Packages

Syntax
protected Object lock
Description
The object used to synchronize operations on this stream. For efficiency, a character-stream object may use an object other than itself to protect critical sections. A subclass should therefore use the object in this field rather than this or a synchronized method.


 Writer.Writer

Writer.Writer

Class Overview | Class Members | This Package | All Packages

Syntax 1
protected Writer()
Description
Create a new character-stream writer whose critical sections will synchronize on the writer itself.

Syntax 2
protected Writer( Object lock )
Description
Create a new character-stream writer whose critical sections will synchronize on the given object.


 Writer.close

Writer.close

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void close() throws IOException
Description
Close the stream, flushing it first. Once a stream has been closed, further write() or flush() invocations will cause an IOException to be thrown. Closing a previously-closed stream, however, has no effect.

Exceptions
IOException If an I/O error occurs


 Writer.flush

Writer.flush

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void flush() throws IOException
Description
Flush the stream. If the stream has saved any characters from the various write() methods in a buffer, write them immediately to their intended destination. Then, if that destination is another character or byte stream, flush it. Thus one flush() invocation will flush all the buffers in a chain of Writers and OutputStreams.

Exceptions
IOException If an I/O error occurs


 Writer.write

Writer.write

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void write( int c ) throws IOException
Description
Write a single character. The character to be written is contained in the 16 low-order bits of the given integer value; the 16 high-order bits are ignored.

Subclasses that intend to support efficient single-character output should override this method.

Exceptions
IOException If an I/O error occurs

Syntax 2
public void write( char cbuf[] ) throws IOException
Parameters
cbuf
Array of characters to be written
Description
Write an array of characters.

Exceptions
IOException If an I/O error occurs

Syntax 3
public abstract void write( char cbuf[], int off, int len ) throws IOException
Parameters
cbuf
Array of characters
off
Offset from which to start writing characters
len
Number of characters to write
Description
Write a portion of an array of characters.

Exceptions
IOException If an I/O error occurs

Syntax 4
public void write( String str ) throws IOException
Parameters
str
String to be written
Description
Write a string.

Exceptions
IOException If an I/O error occurs

Syntax 5
public void write( String str, int off, int len ) throws IOException
Parameters
str
A String
off
Offset from which to start writing characters
len
Number of characters to write
Description
Write a portion of a string.

Exceptions
IOException If an I/O error occurs


 Package java.lang

Package java.lang

All Packages

Interfaces

  • Cloneable
  • Runnable

    • Classes

  • Boolean
  • Byte
  • Character
  • Class
  • ClassLoader
  • Compiler
  • Double
  • Float
  • Integer
  • Long
  • Math
  • Number
  • Object
  • Process
  • Runtime
  • SecurityManager
  • Short
  • String
  • StringBuffer
  • System
  • Thread
  • ThreadGroup
  • Throwable
  • Void

    • Exceptions

  • ArithmeticException
  • ArrayIndexOutOfBoundsException
  • ArrayStoreException
  • ClassCastException
  • ClassNotFoundException
  • CloneNotSupportedException
  • Exception
  • IllegalAccessException
  • IllegalArgumentException
  • IllegalMonitorStateException
  • IllegalStateException
  • IllegalThreadStateException
  • IndexOutOfBoundsException
  • InstantiationException
  • InterruptedException
  • NegativeArraySizeException
  • NoSuchFieldException
  • NoSuchMethodException
  • NullPointerException
  • NumberFormatException
  • RuntimeException
  • SecurityException
  • StringIndexOutOfBoundsException

    • Errors

  • AbstractMethodError
  • ClassCircularityError
  • ClassFormatError
  • Error
  • ExceptionInInitializerError
  • IllegalAccessError
  • IncompatibleClassChangeError
  • InstantiationError
  • InternalError
  • LinkageError
  • NoClassDefFoundError
  • NoSuchFieldError
  • NoSuchMethodError
  • OutOfMemoryError
  • StackOverflowError
  • ThreadDeath
  • UnknownError
  • UnsatisfiedLinkError
  • VerifyError
  • VirtualMachineError


 Class AbstractMethodError

Class java.lang.AbstractMethodError

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Error
                   |
                   +----java.lang.LinkageError
                           |
                           +----java.lang.IncompatibleClassChangeError
                                   |
                                   +----java.lang.AbstractMethodError

public class AbstractMethodError
extends IncompatibleClassChangeError

Thrown when an application tries to call an abstract method. Normally, this error is caught by the compiler; this error can only occur at run time if the definition of some class has incompatibly changed since the currently executing method was last compiled.


 AbstractMethodError Members

AbstractMethodError Members

Class Overview | This Package | All Packages

Constructors
Name | Description
AbstractMethodError() | Constructs an AbstractMethodError with no detail message.
AbstractMethodError(String) | Constructs an AbstractMethodError with the specified detail message.


 AbstractMethodError.AbstractMethodError

AbstractMethodError.AbstractMethodError

Class Overview | Class Members | This Package | All Packages

Syntax 1
public AbstractMethodError()
Description
Constructs an AbstractMethodError with no detail message.

Syntax 2
public AbstractMethodError( String s )
Parameters
s
the detail message.
Description
Constructs an AbstractMethodError with the specified detail message.


 Class ArithmeticException

Class java.lang.ArithmeticException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.lang.RuntimeException
                           |
                           +----java.lang.ArithmeticException

public class ArithmeticException
extends RuntimeException

Thrown when an exceptional arithmetic condition has occurred. For example, an integer "divide by zero" throws an instance of this class.


 ArithmeticException Members

ArithmeticException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
ArithmeticException() | Constructs an ArithmeticException with no detail message.
ArithmeticException(String) | Constructs an ArithmeticException with the specified detail message.


 ArithmeticException.ArithmeticException

ArithmeticException.ArithmeticException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public ArithmeticException()
Description
Constructs an ArithmeticException with no detail message.

Syntax 2
public ArithmeticException( String s )
Parameters
s
the detail message.
Description
Constructs an ArithmeticException with the specified detail message.


 Class ArrayIndexOutOfBoundsException

Class java.lang.ArrayIndexOutOfBoundsException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.lang.RuntimeException
                           |
                           +----java.lang.IndexOutOfBoundsException
                                   |
                                   +----java.lang.ArrayIndexOutOfBoundsException

public class ArrayIndexOutOfBoundsException
extends IndexOutOfBoundsException

Thrown to indicate that an array has been accessed with an illegal index. The index is either negative or greater than or equal to the size of the array.


 ArrayIndexOutOfBoundsException Members

ArrayIndexOutOfBoundsException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
ArrayIndexOutOfBoundsException() | Constructs an ArrayIndexOutOfBoundsException with no detail message.
ArrayIndexOutOfBoundsException(int) | Constructs a new ArrayIndexOutOfBoundsException class with an argument indicating the illegal index.
ArrayIndexOutOfBoundsException(String) | Constructs an ArrayIndexOutOfBoundsException class with the specified detail message.


 ArrayIndexOutOfBoundsException.ArrayIndexOutOfBoundsException

ArrayIndexOutOfBoundsException.ArrayIndexOutOfBoundsException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public ArrayIndexOutOfBoundsException()
Description
Constructs an ArrayIndexOutOfBoundsException with no detail message.

Syntax 2
public ArrayIndexOutOfBoundsException( int index )
Parameters
index
the illegal index.
Description
Constructs a new ArrayIndexOutOfBoundsException class with an argument indicating the illegal index.

Syntax 3
public ArrayIndexOutOfBoundsException( String s )
Parameters
s
the detail message.
Description
Constructs an ArrayIndexOutOfBoundsException class with the specified detail message.


 Class ArrayStoreException

Class java.lang.ArrayStoreException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.lang.RuntimeException
                           |
                           +----java.lang.ArrayStoreException

public class ArrayStoreException
extends RuntimeException

Thrown to indicate that an attempt has been made to store the wrong type of object into an array of objects. For example, the following code generates an ArrayStoreException:

     Object x[] = new String[3];
     x[0] = new Integer(0);


 ArrayStoreException Members

ArrayStoreException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
ArrayStoreException() | Constructs an ArrayStoreException with no detail message.
ArrayStoreException(String) | Constructs an ArrayStoreException with the specified detail message.


 ArrayStoreException.ArrayStoreException

ArrayStoreException.ArrayStoreException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public ArrayStoreException()
Description
Constructs an ArrayStoreException with no detail message.

Syntax 2
public ArrayStoreException( String s )
Parameters
s
the detail message.
Description
Constructs an ArrayStoreException with the specified detail message.


 Class Boolean

Class java.lang.Boolean

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Boolean

public final class Boolean
extends Object
implements Serializable

The Boolean class wraps a value of the primitive type boolean in an object. An object of type Boolean contains a single field whose type is boolean.

In addition, this class provides many methods for converting a boolean to a String and a String to a boolean, as well as other constants and methods useful when dealing with a boolean.


 Boolean Members

Boolean Members

Class Overview | This Package | All Packages

Fields
Name | Description
FALSE | The Boolean object corresponding to the primitive value false.
TRUE | The Boolean object corresponding to the primitive value true.
TYPE | The Class object representing the primitive type boolean.

Constructors
Name | Description
Boolean(boolean) | Allocates a Boolean object representing the value argument.
Boolean(String) | Allocates a Boolean object representing the value true if the string argument is not null and is equal, ignoring case, to the string "true".

Methods
Name | Description
booleanValue() | Returns the value of this Boolean object as a boolean.
equals(Object) | Returns true if and only if the argument is not null and is a Boolean object that contains the same boolean value as this object.
getBoolean(String) | Returns is true if and only if the system property named by the argument exists and is equal to the string "true".
hashCode() | Returns a hash code for this Boolean.
toString() | Returns a String object representing this Boolean's value.
valueOf(String) | Returns the boolean value represented by the specified String.


 Boolean.FALSE

Boolean.FALSE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Boolean FALSE
Description
The Boolean object corresponding to the primitive value false.


 Boolean.TRUE

Boolean.TRUE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Boolean TRUE
Description
The Boolean object corresponding to the primitive value true.


 Boolean.TYPE

Boolean.TYPE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Class TYPE
Description
The Class object representing the primitive type boolean.


 Boolean.Boolean

Boolean.Boolean

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Boolean( boolean value )
Parameters
value
the value of the Boolean.
Description
Allocates a Boolean object representing the value argument.

Syntax 2
public Boolean( String s )
Parameters
s
the string to be converted to a Boolean.
Description
Allocates a Boolean object representing the value true if the string argument is not null and is equal, ignoring case, to the string "true". Otherwise, allocate a Boolean object representing the value false.


 Boolean.booleanValue

Boolean.booleanValue

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean booleanValue()
Returns
the primitive boolean value of this object.
Description
Returns the value of this Boolean object as a boolean.


 Boolean.equals

Boolean.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Parameters
obj
the object to compare with.
Returns
true if the objects are the same; false otherwise.
Description
Returns true if and only if the argument is not null and is a Boolean object that contains the same boolean value as this object.

Overrides
equals in class Object


 Boolean.getBoolean

Boolean.getBoolean

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean getBoolean( String name )
Parameters
name
the system property name.
Returns
the boolean value of the system property.
Description
Returns is true if and only if the system property named by the argument exists and is equal to the string "true". (Beginning with Java 1.0.2, the test of this string is case insensitive.) A system property is accessible through getProperty, a method defined by the System class.

See Also
getProperty, getProperty


 Boolean.hashCode

Boolean.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int hashCode()
Returns
a hash code value for this object.
Description
Returns a hash code for this Boolean.

Overrides
hashCode in class Object


 Boolean.toString

Boolean.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string representation of this object.
Description
Returns a String object representing this Boolean's value. If this object contains the value true, a string equal to "true" is returned. Otherwise, a string equal to "false" is returned.

Overrides
toString in class Object


 Boolean.valueOf

Boolean.valueOf

Class Overview | Class Members | This Package | All Packages

Syntax
public static Boolean valueOf( String s )
Parameters
s
a string.
Returns
the Boolean value represented by the string.
Description
Returns the boolean value represented by the specified String. A new Boolean object is constructed. This Boolean contains the value true if the string argument is not null and is equal, ignoring case, to the string "true".


 Class Byte

Class java.lang.Byte

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Number
           |
           +----java.lang.Byte

public final class Byte
extends Number

The Byte class is the standard wrapper for byte values.

See Also:
Number


 Byte Members

Byte Members

Class Overview | This Package | All Packages

Fields
Name | Description
MAX_VALUE | The maximum value a Byte can have.
MIN_VALUE | The minimum value a Byte can have.
TYPE | The Class object representing the primitive type byte.

Constructors
Name | Description
Byte(byte) | Constructs a Byte object initialized to the specified byte value.
Byte(String) | Constructs a Byte object initialized to the value specified by the String parameter.

Methods
Name | Description
byteValue() | Returns the value of this Byte as a byte.
decode(String) | Decodes a String into a Byte.
doubleValue() | Returns the value of this Byte as a double.
equals(Object) | Compares this object to the specified object.
floatValue() | Returns the value of this Byte as a float.
hashCode() | Returns a hashcode for this Byte.
intValue() | Returns the value of this Byte as an int.
longValue() | Returns the value of this Byte as a long.
parseByte(String) | Assuming the specified String represents a byte, returns that byte's value.
parseByte(String, int) | Assuming the specified String represents a byte, returns that byte's value.
shortValue() | Returns the value of this Byte as a short.
toString() | Returns a String object representing this Byte's value.
toString(byte) | Returns a new String object representing the specified Byte.
valueOf(String) | Assuming the specified String represents a byte, returns a new Byte object initialized to that value.
valueOf(String, int) | Assuming the specified String represents a byte, returns a new Byte object initialized to that value.


 Byte.MAX_VALUE

Byte.MAX_VALUE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final byte MAX_VALUE
Description
The maximum value a Byte can have.


 Byte.MIN_VALUE

Byte.MIN_VALUE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final byte MIN_VALUE
Description
The minimum value a Byte can have.


 Byte.TYPE

Byte.TYPE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Class TYPE
Description
The Class object representing the primitive type byte.


 Byte.Byte

Byte.Byte

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Byte( byte value )
Parameters
value
the initial value of the Byte
Description
Constructs a Byte object initialized to the specified byte value.

Syntax 2
public Byte( String s ) throws NumberFormatException
Parameters
s
the String to be converted to a Byte
Description
Constructs a Byte object initialized to the value specified by the String parameter. The radix is assumed to be 10.

Exceptions
NumberFormatException If the String does not contain a parsable byte.


 Byte.byteValue

Byte.byteValue

Class Overview | Class Members | This Package | All Packages

Syntax
public byte byteValue()
Description
Returns the value of this Byte as a byte.

Overrides
byteValue in class Number


 Byte.decode

Byte.decode

Class Overview | Class Members | This Package | All Packages

Syntax
public static Byte decode( String nm ) throws NumberFormatException
Parameters
nm
the string to decode
Description
Decodes a String into a Byte. The String may represent decimal, hexadecimal, and octal numbers.


 Byte.doubleValue

Byte.doubleValue

Class Overview | Class Members | This Package | All Packages

Syntax
public double doubleValue()
Description
Returns the value of this Byte as a double.

Overrides
doubleValue in class Number


 Byte.equals

Byte.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Parameters
obj
the object to compare with
Returns
true if the objects are the same; false otherwise.
Description
Compares this object to the specified object.

Overrides
equals in class Object


 Byte.floatValue

Byte.floatValue

Class Overview | Class Members | This Package | All Packages

Syntax
public float floatValue()
Description
Returns the value of this Byte as a float.

Overrides
floatValue in class Number


 Byte.hashCode

Byte.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int hashCode()
Description
Returns a hashcode for this Byte.

Overrides
hashCode in class Object


 Byte.intValue

Byte.intValue

Class Overview | Class Members | This Package | All Packages

Syntax
public int intValue()
Description
Returns the value of this Byte as an int.

Overrides
intValue in class Number


 Byte.longValue

Byte.longValue

Class Overview | Class Members | This Package | All Packages

Syntax
public long longValue()
Description
Returns the value of this Byte as a long.

Overrides
longValue in class Number


 Byte.parseByte

Byte.parseByte

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static byte parseByte( String s ) throws NumberFormatException
Parameters
s
the String containing the byte
Description
Assuming the specified String represents a byte, returns that byte's value. Throws an exception if the String cannot be parsed as a byte. The radix is assumed to be 10.

Exceptions
NumberFormatException If the string does not contain a parsable byte.

Syntax 2
public static byte parseByte( String s, int radix ) throws NumberFormatException
Parameters
s
the String containing the byte
radix
the radix to be used
Description
Assuming the specified String represents a byte, returns that byte's value. Throws an exception if the String cannot be parsed as a byte.

Exceptions
NumberFormatException If the String does not contain a parsable byte.


 Byte.shortValue

Byte.shortValue

Class Overview | Class Members | This Package | All Packages

Syntax
public short shortValue()
Description
Returns the value of this Byte as a short.

Overrides
shortValue in class Number


 Byte.toString

Byte.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public static String toString( byte b )
Parameters
b
the byte to be converted
Description
Returns a new String object representing the specified Byte. The radix is assumed to be 10.


 Byte.toString

Byte.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Description
Returns a String object representing this Byte's value.

Overrides
toString in class Object


 Byte.valueOf

Byte.valueOf

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static Byte valueOf( String s, int radix ) throws NumberFormatException
Parameters
s
the String containing the integer
radix
the radix to be used
Description
Assuming the specified String represents a byte, returns a new Byte object initialized to that value. Throws an exception if the String cannot be parsed as a byte.

Exceptions
NumberFormatException If the String does not contain a parsable byte.

Syntax 2
public static Byte valueOf( String s ) throws NumberFormatException
Parameters
s
the String containing the integer
Description
Assuming the specified String represents a byte, returns a new Byte object initialized to that value. Throws an exception if the String cannot be parsed as a byte. The radix is assumed to be 10.

Exceptions
NumberFormatException If the String does not contain a parsable byte.


 Class Character

Class java.lang.Character

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Character

public final class Character
extends Object
implements Serializable

The Character class wraps a value of the primitive type char in an object. An object of type Character contains a single field whose type is char.

In addition, this class provides several methods for determining the type of a character and converting characters from uppercase to lowercase and vice versa.

Many of the methods of class Character are defined in terms of a "Unicode attribute table" that specifies a name for every defined Unicode code point. The table also includes other attributes, such as a decimal value, an uppercase equivalent, a lowercase equivalent, and/or a titlecase equivalent. The Unicode attribute table is available on the World Wide Web as the file:

    ftp://unicode.org/pub/MappingTables/UnicodeData1.1.5.txt

For a more detailed specification of the Character class, one that encompasses the exact behavior of methods such as isDigit, isLetter, isLowerCase, and isUpperCase over the full range of Unicode values, see Gosling, Joy, and Steele, The Java Language Specification.


 Character Members

Character Members

Class Overview | This Package | All Packages

Fields
Name | Description
COMBINING_SPACING_MARK |
CONNECTOR_PUNCTUATION |
CONTROL |
CURRENCY_SYMBOL |
DASH_PUNCTUATION |
DECIMAL_DIGIT_NUMBER |
ENCLOSING_MARK |
END_PUNCTUATION |
FORMAT |
LETTER_NUMBER |
LINE_SEPARATOR |
LOWERCASE_LETTER |
MATH_SYMBOL |
MAX_RADIX | The maximum radix available for conversion to and from Strings.
MAX_VALUE | The constant value of this field is the largest value of type char.
MIN_RADIX | The minimum radix available for conversion to and from Strings.
MIN_VALUE | The constant value of this field is the smallest value of type char.
MODIFIER_LETTER |
MODIFIER_SYMBOL |
NON_SPACING_MARK |
OTHER_LETTER |
OTHER_NUMBER |
OTHER_PUNCTUATION |
OTHER_SYMBOL |
PARAGRAPH_SEPARATOR |
PRIVATE_USE |
SPACE_SEPARATOR |
START_PUNCTUATION |
SURROGATE |
TITLECASE_LETTER |
TYPE | The Class object representing the primitive type char.
UNASSIGNED |
UPPERCASE_LETTER |

Constructors
Name | Description
Character(char) | Constructs a Character object and initializes it so that it represents the primitive value argument.

Methods
Name | Description
charValue() | Returns the value of this Character object.
digit(char, int) | Returns the numeric value of the character ch in the specified radix.
equals(Object) | Compares this object against the specified object.
forDigit(int, int) | Determines the character representation for a specific digit in the specified radix.
getNumericValue(char) | Returns the Unicode numeric value of the character as a nonnegative integer.
getType(char) | Returns a value indicating a character category.
hashCode() | Returns a hash code for this Character.
isDefined(char) | Determines if a character has a defined meaning in Unicode.
isDigit(char) | Determines if the specified character is a digit.
isIdentifierIgnorable(char) | Determines if the specified character should be regarded as an ignorable character in a Java identifier or a Unicode identifier.
isISOControl(char) | Determines if the specified character is an ISO control character.
isJavaIdentifierPart(char) | Determines if the specified character may be part of a Java identifier as other than the first character.
isJavaIdentifierStart(char) | Determines if the specified character is permissible as the first character in a Java identifier.
isJavaLetter(char) | Determines if the specified character is a "Java" letter, that is, the character is permissible as the first character in an identifier in the Java language. Deprecated.
isJavaLetterOrDigit(char) | Determines if the specified character is a "Java" letter or digit, that is, the character is permissible as a non-initial character in an identifier in the Java language. Deprecated.
isLetter(char) | Determines if the specified character is a letter.
isLetterOrDigit(char) | Determines if the specified character is a letter or digit.
isLowerCase(char) | Determines if the specified character is a lowercase character.
isSpace(char) | Determines if the specified character is ISO-LATIN-1 white space. Deprecated.
isSpaceChar(char) | Determines if the specified character is a Unicode space character.
isTitleCase(char) | Determines if the specified character is a titlecase character.
isUnicodeIdentifierPart(char) | Determines if the specified character may be part of a Unicode identifier as other than the first character.
isUnicodeIdentifierStart(char) | Determines if the specified character is permissible as the first character in a Unicode identifier.
isUpperCase(char) | Determines if the specified character is an uppercase character.
isWhitespace(char) | Determines if the specified character is white space according to Java.
toLowerCase(char) | The given character is mapped to its lowercase equivalent; if the character has no lowercase equivalent, the character itself is returned.
toString() | Returns a String object representing this character's value.
toTitleCase(char) | Converts the character argument to titlecase.
toUpperCase(char) | Converts the character argument to uppercase.


 Character.COMBINING_SPACING_MARK

Character.COMBINING_SPACING_MARK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final byte COMBINING_SPACING_MARK


 Character.CONNECTOR_PUNCTUATION

Character.CONNECTOR_PUNCTUATION

Class Overview | Class Members | This Package | All Packages

Syntax
public static final byte CONNECTOR_PUNCTUATION


 Character.CONTROL

Character.CONTROL

Class Overview | Class Members | This Package | All Packages

Syntax
public static final byte CONTROL


 Character.CURRENCY_SYMBOL

Character.CURRENCY_SYMBOL

Class Overview | Class Members | This Package | All Packages

Syntax
public static final byte CURRENCY_SYMBOL


 Character.DASH_PUNCTUATION

Character.DASH_PUNCTUATION

Class Overview | Class Members | This Package | All Packages

Syntax
public static final byte DASH_PUNCTUATION


 Character.DECIMAL_DIGIT_NUMBER

Character.DECIMAL_DIGIT_NUMBER

Class Overview | Class Members | This Package | All Packages

Syntax
public static final byte DECIMAL_DIGIT_NUMBER


 Character.ENCLOSING_MARK

Character.ENCLOSING_MARK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final byte ENCLOSING_MARK


 Character.END_PUNCTUATION

Character.END_PUNCTUATION

Class Overview | Class Members | This Package | All Packages

Syntax
public static final byte END_PUNCTUATION


 Character.FORMAT

Character.FORMAT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final byte FORMAT


 Character.LETTER_NUMBER

Character.LETTER_NUMBER

Class Overview | Class Members | This Package | All Packages

Syntax
public static final byte LETTER_NUMBER


 Character.LINE_SEPARATOR

Character.LINE_SEPARATOR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final byte LINE_SEPARATOR


 Character.LOWERCASE_LETTER

Character.LOWERCASE_LETTER

Class Overview | Class Members | This Package | All Packages

Syntax
public static final byte LOWERCASE_LETTER


 Character.MATH_SYMBOL

Character.MATH_SYMBOL

Class Overview | Class Members | This Package | All Packages

Syntax
public static final byte MATH_SYMBOL


 Character.MAX_RADIX

Character.MAX_RADIX

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int MAX_RADIX
Description
The maximum radix available for conversion to and from Strings. The constant value of this field is the largest value permitted for the radix argument in radix-conversion methods such as the digit method, the forDigit method, and the toString method of class Integer.

See Also
digit, forDigit, toString, valueOf


 Character.MAX_VALUE

Character.MAX_VALUE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final char MAX_VALUE
Description
The constant value of this field is the largest value of type char.


 Character.MIN_RADIX

Character.MIN_RADIX

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int MIN_RADIX
Description
The minimum radix available for conversion to and from Strings. The constant value of this field is the smallest value permitted for the radix argument in radix-conversion methods such as the digit method, the forDigit method, and the toString method of class Integer.

See Also
digit, forDigit, toString, valueOf


 Character.MIN_VALUE

Character.MIN_VALUE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final char MIN_VALUE
Description
The constant value of this field is the smallest value of type char.


 Character.MODIFIER_LETTER

Character.MODIFIER_LETTER

Class Overview | Class Members | This Package | All Packages

Syntax
public static final byte MODIFIER_LETTER


 Character.MODIFIER_SYMBOL

Character.MODIFIER_SYMBOL

Class Overview | Class Members | This Package | All Packages

Syntax
public static final byte MODIFIER_SYMBOL


 Character.NON_SPACING_MARK

Character.NON_SPACING_MARK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final byte NON_SPACING_MARK


 Character.OTHER_LETTER

Character.OTHER_LETTER

Class Overview | Class Members | This Package | All Packages

Syntax
public static final byte OTHER_LETTER


 Character.OTHER_NUMBER

Character.OTHER_NUMBER

Class Overview | Class Members | This Package | All Packages

Syntax
public static final byte OTHER_NUMBER


 Character.OTHER_PUNCTUATION

Character.OTHER_PUNCTUATION

Class Overview | Class Members | This Package | All Packages

Syntax
public static final byte OTHER_PUNCTUATION


 Character.OTHER_SYMBOL

Character.OTHER_SYMBOL

Class Overview | Class Members | This Package | All Packages

Syntax
public static final byte OTHER_SYMBOL


 Character.PARAGRAPH_SEPARATOR

Character.PARAGRAPH_SEPARATOR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final byte PARAGRAPH_SEPARATOR


 Character.PRIVATE_USE

Character.PRIVATE_USE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final byte PRIVATE_USE


 Character.SPACE_SEPARATOR

Character.SPACE_SEPARATOR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final byte SPACE_SEPARATOR


 Character.START_PUNCTUATION

Character.START_PUNCTUATION

Class Overview | Class Members | This Package | All Packages

Syntax
public static final byte START_PUNCTUATION


 Character.SURROGATE

Character.SURROGATE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final byte SURROGATE


 Character.TITLECASE_LETTER

Character.TITLECASE_LETTER

Class Overview | Class Members | This Package | All Packages

Syntax
public static final byte TITLECASE_LETTER


 Character.TYPE

Character.TYPE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Class TYPE
Description
The Class object representing the primitive type char.


 Character.UNASSIGNED

Character.UNASSIGNED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final byte UNASSIGNED


 Character.UPPERCASE_LETTER

Character.UPPERCASE_LETTER

Class Overview | Class Members | This Package | All Packages

Syntax
public static final byte UPPERCASE_LETTER


 Character.Character

Character.Character

Class Overview | Class Members | This Package | All Packages

Syntax
public Character( char value )
Parameters
value
value for the new Character object.
Description
Constructs a Character object and initializes it so that it represents the primitive value argument.


 Character.charValue

Character.charValue

Class Overview | Class Members | This Package | All Packages

Syntax
public char charValue()
Returns
the primitive char value represented by this object.
Description
Returns the value of this Character object.


 Character.digit

Character.digit

Class Overview | Class Members | This Package | All Packages

Syntax
public static int digit( char ch, int radix )
Parameters
ch
the character to be converted.
radix
the radix.
Returns
the numeric value represented by the character in the specified radix.
Description
Returns the numeric value of the character ch in the specified radix.

If the radix is not in the range MIN_RADIX <= radix <= MAX_RADIX or if the value of ch is not a valid digit in the specified radix, -1 is returned. A character is a valid digit if at least one of the following is true:

  • The method isDigit is true of the character and the Unicode decimal digit value of the character (or its single-character decomposition) is less than the specified radix. In this case the decimal digit value is returned.
  • The character is one of the uppercase Latin letters 'A' through 'Z' and its code is less than radix + 'A' - 10. In this case, ch - 'A' + 10 is returned.
  • The character is one of the lowercase Latin letters 'a' through 'z' and its code is less than radix + 'a' - 10. In this case, ch - 'a' + 10 is returned.

See Also
forDigit, isDigit


 Character.equals

Character.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Parameters
obj
the object to compare with.
Returns
true if the objects are the same; false otherwise.
Description
Compares this object against the specified object. The result is true if and only if the argument is not null and is a Character object that represents the same char value as this object.

Overrides
equals in class Object


 Character.forDigit

Character.forDigit

Class Overview | Class Members | This Package | All Packages

Syntax
public static char forDigit( int digit, int radix )
Parameters
digit
the number to convert to a character.
radix
the radix.
Returns
the char representation of the specified digit in the specified radix.
Description
Determines the character representation for a specific digit in the specified radix. If the value of radix is not a valid radix, or the value of digit is not a valid digit in the specified radix, the null character ('\u0000') is returned.

The radix argument is valid if it is greater than or equal to MIN_RADIX and less than or equal to MAX_RADIX. The digit argument is valid if 0 <= digit <= radix.

If the digit is less than 10, then '0' + digit is returned. Otherwise, the value 'a' + digit - 10 is returned.

See Also
MIN_RADIX, MAX_RADIX, digit


 Character.getNumericValue

Character.getNumericValue

Class Overview | Class Members | This Package | All Packages

Syntax
public static int getNumericValue( char ch )
Parameters
ch
the character to be converted.
radix
the radix.
Returns
the numeric value of the character, as a nonnegative int value; -2 if the character has a numeric value that is not a nonnegative integer; -1 if the character has no numeric value.
Description
Returns the Unicode numeric value of the character as a nonnegative integer. If the character does not have a numeric value, then -1 is returned. If the character has a numeric value that cannot be represented as a nonnegative integer (for example, a fractional value), then -2 is returned.

See Also
forDigit, isDigit


 Character.getType

Character.getType

Class Overview | Class Members | This Package | All Packages

Syntax
public static int getType( char ch )
Parameters
ch
the character to be tested.
Returns
a value of type int, the character category.
Description
Returns a value indicating a character category.

See Also
COMBINING_SPACING_MARK, CONNECTOR_PUNCTUATION, CONTROL, CURRENCY_SYMBOL, DASH_PUNCTUATION, DECIMAL_DIGIT_NUMBER, ENCLOSING_MARK, END_PUNCTUATION, FORMAT, LETTER_NUMBER, LINE_SEPARATOR, LOWERCASE_LETTER, MATH_SYMBOL, MODIFIER_LETTER, MODIFIER_SYMBOL, NON_SPACING_MARK, OTHER_LETTER, OTHER_NUMBER, OTHER_PUNCTUATION, OTHER_SYMBOL, PARAGRAPH_SEPARATOR, PRIVATE_USE, SPACE_SEPARATOR, START_PUNCTUATION, SURROGATE, TITLECASE_LETTER, UNASSIGNED, UPPERCASE_LETTER


 Character.hashCode

Character.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int hashCode()
Returns
a hash code value for this object.
Description
Returns a hash code for this Character.

Overrides
hashCode in class Object


 Character.isDefined

Character.isDefined

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isDefined( char ch )
Parameters
ch
the character to be tested
Returns
true if the character has a defined meaning in Unicode; false otherwise.
Description
Determines if a character has a defined meaning in Unicode. A character is defined if at least one of the following is true:
  • It has an entry in the Unicode attribute table.
  • Its value is in the range '\u3040' <= ch <= '\u9FA5'.
  • Its value is in the range '\uF900' <= ch <= '\uFA2D'.

See Also
isDigit, isLetter, isLetterOrDigit, isLowerCase, isTitleCase, isUpperCase


 Character.isDigit

Character.isDigit

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isDigit( char ch )
Parameters
ch
the character to be tested.
Returns
true if the character is a digit; false otherwise.
Description
Determines if the specified character is a digit. A character is considered to be a digit if it is not in the range '\u2000' <= ch <= '\u2FFF' and its Unicode name contains the word "DIGIT". For a more complete specification that encompasses all Unicode characters that are defined as digits, see Gosling, Joy, and Steele, The Java Language Specification.

These are the ranges of Unicode characters that are considered digits:
0x0030 through 0x0039 | ISO-LATIN-1 digits ('0' through '9')
0x0660 through 0x0669 | Arabic-Indic digits
0x06F0 through 0x06F9 | Extended Arabic-Indic digits
0x0966 through 0x096F | Devanagari digits
0x09E6 through 0x09EF | Bengali digits
0x0A66 through 0x0A6F | Gurmukhi digits
0x0AE6 through 0x0AEF | Gujarati digits
0x0B66 through 0x0B6F | Oriya digits
0x0BE7 through 0x0BEF | Tamil digits
0x0C66 through 0x0C6F | Telugu digits
0x0CE6 through 0x0CEF | Kannada digits
0x0D66 through 0x0D6F | Malayalam digits
0x0E50 through 0x0E59 | Thai digits
0x0ED0 through 0x0ED9 | Lao digits
0x0F20 through 0x0F29 | Tibetan digits
0xFF10 through 0xFF19 | Fullwidth digits

See Also
digit, forDigit


 Character.isIdentifierIgnorable

Character.isIdentifierIgnorable

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isIdentifierIgnorable( char ch )
Parameters
ch
the character to be tested.
Returns
true if the character may be part of a Unicode identifier; false otherwise.
Description
Determines if the specified character should be regarded as an ignorable character in a Java identifier or a Unicode identifier. The following Unicode characters are ignorable in a Java identifier or a Unicode identifier:
0x0000 through 0x0008, | ISO control characters that
0x000E through 0x001B, | are not whitespace
and 0x007F through 0x009F
0x200C through 0x200F | join controls
0x200A through 0x200E | bidirectional controls
0x206A through 0x206F | format controls
0xFEFF | zero-width no-break space

See Also
isJavaIdentifierPart, isUnicodeIdentifierPart


 Character.isISOControl

Character.isISOControl

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isISOControl( char ch )
Parameters
ch
the character to be tested.
Returns
true if the character is an ISO control character; false otherwise.
Description
Determines if the specified character is an ISO control character. A character is considered to be an ISO control character if its code is in the range \u0000 through \u001F or in the range \u007F through \u009F.

See Also
isSpaceChar, isWhitespace


 Character.isJavaIdentifierPart

Character.isJavaIdentifierPart

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isJavaIdentifierPart( char ch )
Parameters
ch
the character to be tested.
Returns
true if the character may be part of a Unicode identifier; false otherwise.
Description
Determines if the specified character may be part of a Java identifier as other than the first character. A character may be part of a Java identifier if and only if it is one of the following:
  • a letter
  • a currency symbol (such as "$")
  • a connecting punctuation character (such as "_").
  • a digit
  • a numeric letter (such as a Roman numeral character)
  • a combining mark
  • a non-spacing mark
  • an ignorable control character

See Also
isIdentifierIgnorable, isJavaIdentifierStart, isLetterOrDigit, isUnicodeIdentifierPart


 Character.isJavaIdentifierStart

Character.isJavaIdentifierStart

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isJavaIdentifierStart( char ch )
Parameters
ch
the character to be tested.
Returns
true if the character may start a Java identifier; false otherwise.
Description
Determines if the specified character is permissible as the first character in a Java identifier. A character may start a Java identifier if and only if it is one of the following:
  • a letter
  • a currency symbol (such as "$")
  • a connecting punctuation character (such as "_").

See Also
isJavaIdentifierPart, isLetter, isUnicodeIdentifierStart


 Character.isJavaLetter

Character.isJavaLetter

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isJavaLetter( char ch )
Parameters
ch
the character to be tested.
Returns
true if the character is a Java letter; false otherwise.
Description
Note: isJavaLetter() is deprecated. Replaced by isJavaIdentifierStart(char).

Determines if the specified character is a "Java" letter, that is, the character is permissible as the first character in an identifier in the Java language.

A character is considered to be a Java letter if and only if it is a letter, the ASCII dollar sign character '$', or the underscore character '_'.

See Also
isJavaIdentifierStart, isJavaLetterOrDigit, isLetter, isLetterOrDigit, isUnicodeIdentifierStart


 Character.isJavaLetterOrDigit

Character.isJavaLetterOrDigit

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isJavaLetterOrDigit( char ch )
Parameters
ch
the character to be tested.
Returns
true if the character is a Java letter or digit; false otherwise.
Description
Note: isJavaLetterOrDigit() is deprecated. Replaced by isJavaIdentifierPart(char).

Determines if the specified character is a "Java" letter or digit, that is, the character is permissible as a non-initial character in an identifier in the Java language.

A character is considered to be a Java letter or digit if and only if it is a letter, a digit, the ASCII dollar sign character '$', or the underscore character '_'.

See Also
isJavaIdentifierPart, isJavaLetter, isLetter, isLetterOrDigit, isUnicodeIdentifierPart


 Character.isLetter

Character.isLetter

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isLetter( char ch )
Parameters
ch
the character to be tested.
Returns
true if the character is a letter; false otherwise.
Description
Determines if the specified character is a letter. For a more complete specification that encompasses all Unicode characters, see Gosling, Joy, and Steele, The Java Language Specification.

A character is considered to be a letter if and only if it is specified to be a letter by the Unicode 2.0 standard (category "Lu", "Ll", "Lt", "Lm", or "Lo" in the Unicode specification data file).

Note that most ideographic characters are considered to be letters (category "Lo") for this purpose.

Note also that not all letters have case: many Unicode characters are letters but are neither uppercase nor lowercase nor titlecase.

See Also
isDigit, isJavaIdentifierStart, isJavaLetter, isJavaLetterOrDigit, isLetterOrDigit, isLowerCase, isTitleCase, isUnicodeIdentifierStart, isUpperCase


 Character.isLetterOrDigit

Character.isLetterOrDigit

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isLetterOrDigit( char ch )
Parameters
ch
the character to be tested.
Returns
true if the character is a letter or digit; false otherwise.
Description
Determines if the specified character is a letter or digit. For a more complete specification that encompasses all Unicode characters, see Gosling, Joy, and Steele, The Java Language Specification.

A character is considered to be a letter if and only if it is specified to be a letter or a digit by the Unicode 2.0 standard (category "Lu", "Ll", "Lt", "Lm", "Lo", or "Nd" in the Unicode specification data file). In other words, isLetterOrDigit is true of a character if and only if either isLetter is true of the character or isDigit is true of the character.

See Also
isDigit, isJavaIdentifierPart, isJavaLetter, isJavaLetterOrDigit, isLetter, isUnicodeIdentifierPart


 Character.isLowerCase

Character.isLowerCase

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isLowerCase( char ch )
Parameters
ch
the character to be tested.
Returns
true if the character is lowercase; false otherwise.
Description
Determines if the specified character is a lowercase character. A character is lowercase if it is not in the range '\u2000' through '\u2FFF', the Unicode attribute table does not specify a mapping to lowercase for the character, and at least one of the following is true:
  • The attribute table specifies a mapping to uppercase for the character.
  • The name for the character contains the words "SMALL LETTER".
  • The name for the character contains the words "SMALL LIGATURE".

A character is considered to be lowercase if and only if it is specified to be lowercase by the Unicode 2.0 standard (category "Ll" in the Unicode specification data file).

Of the ISO-LATIN-1 characters (character codes 0x0000 through 0x00FF), the following are lowercase:

 a b c d e f g h i j k l m n o p q r s t u v w x y z
 \u00DF \u00E0 \u00E1 \u00E2 \u00E3 \u00E4 \u00E5 \u00E6 \u00E7
 \u00E8 \u00E9 \u00EA \u00EB \u00EC \u00ED \u00EE \u00EF \u00F0
 \u00F1 \u00F2 \u00F3 \u00F4 \u00F5 \u00F6 \u00F8 \u00F9 \u00FA
 \u00FB \u00FC \u00FD \u00FE \u00FF

Many other Unicode characters are lowercase, too.

See Also
isLowerCase, isTitleCase, toLowerCase


 Character.isSpace

Character.isSpace

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isSpace( char ch )
Parameters
ch
the character to be tested.
Returns
true if the character is ISO-LATIN-1 white space; false otherwise.
Description
Note: isSpace() is deprecated. Replaced by isWhitespace(char).

Determines if the specified character is ISO-LATIN-1 white space. This method returns true for the following five characters only:
'\t' | \u0009 | HORIZONTAL TABULATION
'\n' | \u000A | NEW LINE
'\f' | \u000C | FORM FEED
'\r' | \u000D | CARRIAGE RETURN
' ' | \u0020 | SPACE

See Also
isSpaceChar, isWhitespace


 Character.isSpaceChar

Character.isSpaceChar

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isSpaceChar( char ch )
Parameters
ch
the character to be tested.
Returns
true if the character is a space character; false otherwise.
Description
Determines if the specified character is a Unicode space character. A character is considered to be a space character if and only if it is specified to be a space character by the Unicode 2.0 standard (category "Zs", "Zl, or "Zp" in the Unicode specification data file).

See Also
isWhitespace


 Character.isTitleCase

Character.isTitleCase

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isTitleCase( char ch )
Parameters
ch
the character to be tested.
Returns
true if the character is titlecase; false otherwise.
Description
Determines if the specified character is a titlecase character. A character is considered to be titlecase if and only if it is specified to be titlecase by the Unicode 2.0 standard (category "Lt" in the Unicode specification data file).

The printed representations of four Unicode characters look like pairs of Latin letters. For example, there is an uppercase letter that looks like "LJ" and has a corresponding lowercase letter that looks like "lj". A third form, which looks like "Lj", is the appropriate form to use when rendering a word in lowercase with initial capitals, as for a book title.

These are the Unicode characters for which this method returns true:

  • LATIN CAPITAL LETTER D WITH SMALL LETTER Z WITH CARON
  • LATIN CAPITAL LETTER L WITH SMALL LETTER J
  • LATIN CAPITAL LETTER N WITH SMALL LETTER J
  • LATIN CAPITAL LETTER D WITH SMALL LETTER Z

See Also
isLowerCase, isUpperCase, toTitleCase


 Character.isUnicodeIdentifierPart

Character.isUnicodeIdentifierPart

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isUnicodeIdentifierPart( char ch )
Parameters
ch
the character to be tested.
Returns
true if the character may be part of a Unicode identifier; false otherwise.
Description
Determines if the specified character may be part of a Unicode identifier as other than the first character. A character may be part of a Unicode identifier if and only if it is one of the following:
  • a letter
  • a connecting punctuation character (such as "_").
  • a digit
  • a numeric letter (such as a Roman numeral character)
  • a combining mark
  • a non-spacing mark
  • an ignorable control character

See Also
isIdentifierIgnorable, isJavaIdentifierPart, isLetterOrDigit, isUnicodeIdentifierStart


 Character.isUnicodeIdentifierStart

Character.isUnicodeIdentifierStart

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isUnicodeIdentifierStart( char ch )
Parameters
ch
the character to be tested.
Returns
true if the character may start a Unicode identifier; false otherwise.
Description
Determines if the specified character is permissible as the first character in a Unicode identifier. A character may start a Unicode identifier if and only if it is a letter.

See Also
isJavaIdentifierStart, isLetter, isUnicodeIdentifierPart


 Character.isUpperCase

Character.isUpperCase

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isUpperCase( char ch )
Parameters
ch
the character to be tested.
Returns
true if the character is uppercase; false otherwise.
Description
Determines if the specified character is an uppercase character. A character is uppercase if it is not in the range '\u2000' through '\u2FFF', the Unicode attribute table does not specify a mapping to uppercase for the character, and at least one of the following is true:
  • The attribute table specifies a mapping to lowercase for the character.
  • The name for the character contains the words "CAPITAL LETTER".
  • The name for the character contains the words "CAPITAL LIGATURE".

Of the ISO-LATIN-1 characters (character codes 0x0000 through 0x00FF), the following are uppercase:

 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
 \u00C0 \u00C1 \u00C2 \u00C3 \u00C4 \u00C5 \u00C6 \u00C7
 \u00C8 \u00C9 \u00CA \u00CB \u00CC \u00CD \u00CE \u00CF \u00D0
 \u00D1 \u00D2 \u00D3 \u00D4 \u00D5 \u00D6 \u00D8 \u00D9 \u00DA
 \u00DB \u00DC \u00DD \u00DE

Many other Unicode characters are uppercase, too.

See Also
isLowerCase, isTitleCase, toUpperCase


 Character.isWhitespace

Character.isWhitespace

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isWhitespace( char ch )
Parameters
ch
the character to be tested.
Returns
true if the character is a Java whitespace character; false otherwise.
Description
Determines if the specified character is white space according to Java. A character is considered to be a Java whitespace character if and only if it satisfies one of the following criteria:
  • It is a Unicode space separator (category "Zs"), but is not a no-break space (\u00A0 or \uFEFF).
  • It is a Unicode line separator (category "Zl").
  • It is a Unicode paragraph separator (category "Zp").
  • It is \u0009, HORIZONTAL TABULATION.
  • It is \u000A, LINE FEED.
  • It is \u000B, VERTICAL TABULATION.
  • It is \u000C, FORM FEED.
  • It is \u000D, CARRIAGE RETURN.
  • It is \u001C, FILE SEPARATOR.
  • It is \u001D, GROUP SEPARATOR.
  • It is \u001E, RECORD SEPARATOR.
  • It is \u001F, UNIT SEPARATOR.

See Also
isSpaceChar


 Character.toLowerCase

Character.toLowerCase

Class Overview | Class Members | This Package | All Packages

Syntax
public static char toLowerCase( char ch )
Parameters
ch
the character to be converted.
Returns
the lowercase equivalent of the character, if any; otherwise the character itself.
Description
The given character is mapped to its lowercase equivalent; if the character has no lowercase equivalent, the character itself is returned.

A character has a lowercase equivalent if and only if a lowercase mapping is specified for the character in the Unicode attribute table.

Note that some Unicode characters in the range '\u2000' to '\u2FFF' have lowercase mappings; this method does map such characters to their lowercase equivalents even though the method isUpperCase does not return true for such characters.

See Also
isLowerCase, isUpperCase, toTitleCase, toUpperCase


 Character.toString

Character.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string representation of this object.
Description
Returns a String object representing this character's value. Converts this Character object to a string. The result is a string whose length is 1. The string's sole component is the primitive char value represented by this object.

Overrides
toString in class Object


 Character.toTitleCase

Character.toTitleCase

Class Overview | Class Members | This Package | All Packages

Syntax
public static char toTitleCase( char ch )
Parameters
ch
the character to be converted.
Returns
the titlecase equivalent of the character, if any; otherwise the character itself.
Description
Converts the character argument to titlecase. A character has a titlecase equivalent if and only if a titlecase mapping is specified for the character in the Unicode attribute table.

Note that some Unicode characters in the range '\u2000' through '\u2FFF' have titlecase mappings; this method does map such characters to their titlecase equivalents even though the method isTitleCase does not return true for such characters.

There are only four Unicode characters that are truly titlecase forms that are distinct from uppercase forms. As a rule, if a character has no true titlecase equivalent but does have an uppercase mapping, then the Unicode 2.0 attribute table specifies a titlecase mapping that is the same as the uppercase mapping.

See Also
isTitleCase, toLowerCase, toUpperCase


 Character.toUpperCase

Character.toUpperCase

Class Overview | Class Members | This Package | All Packages

Syntax
public static char toUpperCase( char ch )
Parameters
ch
the character to be converted.
Returns
the uppercase equivalent of the character, if any; otherwise the character itself.
Description
Converts the character argument to uppercase. A character has an uppercase equivalent if and only if an uppercase mapping is specified for the character in the Unicode attribute table.

Note that some Unicode characters in the range '\u2000' to '\u2000FFF' have uppercase mappings; this method does map such characters to their titlecase equivalents even though the method isLowerCase does not return true for such characters.

See Also
isLowerCase, isUpperCase, toLowerCase, toTitleCase


 Class Class

Class java.lang.Class

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Class

public final class Class
extends Object
implements Serializable

Instances of the class Class represent classes and interfaces in a running Java application. Every array also belongs to a class that is reflected as a Class object that is shared by all arrays with the same element type and number of dimensions. Finally, the either primitive Java types (boolean, byte, char, short, int, long, float, and double) and the keyword void are also represented as Class objects.

There is no public constructor for the class Class. Class objects are constructed automatically by the Java Virtual Machine as classes are loaded and by calls to the defineClass method in the class loader.

The following example uses a Class object to print the Class name of an object:

     void printClassName(Object obj) {
         System.out.println("The class of " + obj +
                            " is " + obj.getClass().getName());
     }

See Also:
defineClass


 Class Members

Class Members

Class Overview | This Package | All Packages

Methods
Name | Description
forName(String) | Returns the Class object associated with the class with the given string name.
getClasses() | Returns an array containing Class objects representing all the public classes and interfaces that are members of the class represented by this Class object.
getClassLoader() | Determines the class loader for the class.
getComponentType() | If this class represents an array type, returns the Class object representing the component type of the array; otherwise returns null.
getConstructor(Class[]) | Returns a Constructor object that reflects the specified public constructor of the class represented by this Class object.
getConstructors() | Returns an array containing Constructor objects reflecting all the public constructors of the class represented by this Class object.
getDeclaredClasses() | Returns an array of Class objects reflecting all the classes and interfaces declared as members of the class represented by this Class object.
getDeclaredConstructor(Class[]) | Returns a Constructor object that reflects the specified declared constructor of the class or interface represented by this Class object.
getDeclaredConstructors() | Returns an array of Constructor objects reflecting all the constructors declared by the class represented by this Class object.
getDeclaredField(String) | Returns a Field object that reflects the specified declared field of the class or interface represented by this Class object.
getDeclaredFields() | Returns an array of Field objects reflecting all the fields declared by the class or interface represented by this Class object.
getDeclaredMethod(String, Class[]) | Returns a Method object that reflects the specified declared method of the class or interface represented by this Class object.
getDeclaredMethods() | Returns an array of Method objects reflecting all the methods declared by the class or interface represented by this Class object.
getDeclaringClass() | If the class or interface represented by this Class object is a member of another class, returns the Class object representing the class of which it is a member (its declaring class).
getField(String) | Returns a Field object that reflects the specified public member field of the class or interface represented by this Class object.
getFields() | Returns an array containing Field objects reflecting all the accessible public fields of the class or interface represented by this Class object.
getInterfaces() | Determines the interfaces implemented by the class or interface represented by this object.
getMethod(String, Class[]) | Returns a Method object that reflects the specified public member method of the class or interface represented by this Class object.
getMethods() | Returns an array containing Method objects reflecting all the public member methods of the class or interface represented by this Class object, including those declared by the class or interface and and those inherited from superclasses and superinterfaces.
getModifiers() | Returns the Java language modifiers for this class or interface, encoded in an integer.
getName() | Returns the fully-qualified name of the type (class, interface, array, or primitive) represented by this Class object, as a String.
getResource(String) |
getResourceAsStream(String) | Find a resource with a given name.
getSigners() | Get the signers of this class.
getSuperclass() | If this object represents any class other than the class Object, then the object that represents the superclass of that class is returned.
isArray() | If this Class object represents an array type, returns true, otherwise returns false.
isAssignableFrom(Class) | Determines if the class or interface represented by this Class object is either the same as, or is a superclass or superinterface of, the class or interface represented by the specified Class parameter.
isInstance(Object) | This method is the dynamic equivalent of the Java language instanceof operator.
isInterface() | Determines if the specified Class object represents an interface type.
isPrimitive() | Determines if the specified Class object represents a primitive Java type.
newInstance() | Creates a new instance of a class.
toString() | Converts the object to a string.


 Class.forName

Class.forName

Class Overview | Class Members | This Package | All Packages

Syntax
public static native Class forName( String className ) throws ClassNotFoundException
Parameters
className
the fully qualified name of the desired class.
Returns
the Class descriptor for the class with the specified name.
Description
Returns the Class object associated with the class with the given string name. Given the fully-qualified name for a class or interface, this method attempts to locate, load and link the class. If it succeeds, returns the Class object representing the class. If it fails, the method throws a ClassNotFoundException.

For example, the following code fragment returns the runtime Class descriptor for the class named java.lang.Thread:

    Class t = Class.forName("java.lang.Thread")

Exceptions
ClassNotFoundException if the class could not be found.


 Class.getClasses

Class.getClasses

Class Overview | Class Members | This Package | All Packages

Syntax
public Class[] getClasses()
Description
Returns an array containing Class objects representing all the public classes and interfaces that are members of the class represented by this Class object. This includes public class and interface members inherited from superclasses and public class and interface members declared by the class. Returns an array of length 0 if the class has no public member classes or interfaces, or if this Class object represents a primitive type.


 Class.getClassLoader

Class.getClassLoader

Class Overview | Class Members | This Package | All Packages

Syntax
public native ClassLoader getClassLoader()
Returns
the class loader that created the class or interface represented by this object, or null if the class was not created by a class loader.
Description
Determines the class loader for the class.

See Also
ClassLoader


 Class.getComponentType

Class.getComponentType

Class Overview | Class Members | This Package | All Packages

Syntax
public native Class getComponentType()
Description
If this class represents an array type, returns the Class object representing the component type of the array; otherwise returns null.

See Also
Array


 Class.getConstructor

Class.getConstructor

Class Overview | Class Members | This Package | All Packages

Syntax
public Constructor getConstructor( Class parameterTypes[] ) throws NoSuchMethodException, SecurityException
Description
Returns a Constructor object that reflects the specified public constructor of the class represented by this Class object. The parameterTypes parameter is an array of Class objects that identify the constructor's formal parameter types, in declared order.

The constructor to reflect is located by searching all the constructors of the class represented by this Class object for a public constructor with the exactly the same formal parameter types.

Exceptions
NoSuchMethodException if a matching method is not found.
Exceptions
SecurityException if access to the information is denied.
See Also
Constructor


 Class.getConstructors

Class.getConstructors

Class Overview | Class Members | This Package | All Packages

Syntax
public Constructor[] getConstructors() throws SecurityException
Description
Returns an array containing Constructor objects reflecting all the public constructors of the class represented by this Class object. An array of length 0 is returned if the class has no public constructors.

Exceptions
SecurityException if access to the information is denied.
See Also
Constructor


 Class.getDeclaredClasses

Class.getDeclaredClasses

Class Overview | Class Members | This Package | All Packages

Syntax
public Class[] getDeclaredClasses() throws SecurityException
Description
Returns an array of Class objects reflecting all the classes and interfaces declared as members of the class represented by this Class object. This includes public, protected, default (package) access, and private classes and interfaces declared by the class, but excludes inherited classes and interfaces. Returns an array of length 0 if the class declares no classes or interfaces as members, or if this Class object represents a primitive type.

Exceptions
SecurityException if access to the information is denied.


 Class.getDeclaredConstructor

Class.getDeclaredConstructor

Class Overview | Class Members | This Package | All Packages

Syntax
public Constructor getDeclaredConstructor( Class parameterTypes[] ) throws NoSuchMethodException, SecurityException
Description
Returns a Constructor object that reflects the specified declared constructor of the class or interface represented by this Class object. The parameterTypes parameter is an array of Class objects that identify the constructor's formal parameter types, in declared order.

Exceptions
NoSuchMethodException if a matching method is not found.
Exceptions
SecurityException if access to the information is denied.
See Also
Constructor


 Class.getDeclaredConstructors

Class.getDeclaredConstructors

Class Overview | Class Members | This Package | All Packages

Syntax
public Constructor[] getDeclaredConstructors() throws SecurityException
Description
Returns an array of Constructor objects reflecting all the constructors declared by the class represented by this Class object. These are public, protected, default (package) access, and private constructors. Returns an array of length 0 if this Class object represents an interface or a primitive type.

See The Java Language Specification, section 8.2.

Exceptions
SecurityException if access to the information is denied.
See Also
Constructor


 Class.getDeclaredField

Class.getDeclaredField

Class Overview | Class Members | This Package | All Packages

Syntax
public Field getDeclaredField( String name ) throws NoSuchFieldException, SecurityException
Description
Returns a Field object that reflects the specified declared field of the class or interface represented by this Class object. The name parameter is a String that specifies the simple name of the desired field.

Exceptions
NoSuchFieldException if a field with the specified name is not found.
Exceptions
SecurityException if access to the information is denied.
See Also
Field


 Class.getDeclaredFields

Class.getDeclaredFields

Class Overview | Class Members | This Package | All Packages

Syntax
public Field[] getDeclaredFields() throws SecurityException
Description
Returns an array of Field objects reflecting all the fields declared by the class or interface represented by this Class object. This includes public, protected, default (package) access, and private fields, but excludes inherited fields. Returns an array of length 0 if the class or interface declares no fields, or if this Class object represents a primitive type. See The Java Language Specification, sections 8.2 and 8.3.

Exceptions
SecurityException if access to the information is denied.
See Also
Field


 Class.getDeclaredMethod

Class.getDeclaredMethod

Class Overview | Class Members | This Package | All Packages

Syntax
public Method getDeclaredMethod( String name, Class parameterTypes[] ) throws NoSuchMethodException, SecurityException
Description
Returns a Method object that reflects the specified declared method of the class or interface represented by this Class object. The name parameter is a String that specifies the simple name of the desired method, and the parameterTypes parameter is an array of Class objects that identify the method's formal parameter types, in declared order.

Exceptions
NoSuchMethodException if a matching method is not found.
Exceptions
SecurityException if access to the information is denied.
See Also
Method


 Class.getDeclaredMethods

Class.getDeclaredMethods

Class Overview | Class Members | This Package | All Packages

Syntax
public Method[] getDeclaredMethods() throws SecurityException
Description
Returns an array of Method objects reflecting all the methods declared by the class or interface represented by this Class object. This includes public, protected, default (package) access, and private methods, but excludes inherited methods. Returns an array of length 0 if the class or interface declares no methods, or if this Class object represents a primitive type.

See The Java Language Specification, section 8.2.

Exceptions
SecurityException if access to the information is denied.
See Also
Method


 Class.getDeclaringClass

Class.getDeclaringClass

Class Overview | Class Members | This Package | All Packages

Syntax
public Class getDeclaringClass()
Description
If the class or interface represented by this Class object is a member of another class, returns the Class object representing the class of which it is a member (its declaring class). Returns null if this class or interface is not a member of any other class.


 Class.getField

Class.getField

Class Overview | Class Members | This Package | All Packages

Syntax
public Field getField( String name ) throws NoSuchFieldException, SecurityException
Description
Returns a Field object that reflects the specified public member field of the class or interface represented by this Class object. The name parameter is a String specifying the simple name of the desired field.

The field to be reflected is located by searching all the member fields of the class or interface represented by this Class object for a public field with the specified name.

See The Java Language Specification, sections 8.2 and 8.3.

Exceptions
NoSuchFieldException if a field with the specified name is not found.
Exceptions
SecurityException if access to the information is denied.
See Also
Field


 Class.getFields

Class.getFields

Class Overview | Class Members | This Package | All Packages

Syntax
public Field[] getFields() throws SecurityException
Description
Returns an array containing Field objects reflecting all the accessible public fields of the class or interface represented by this Class object. Returns an array of length 0 if the class or interface has no accessible public fields, or if it represents an array type or a primitive type.

Specifically, if this Class object represents a class, returns the public fields of this class and of all its superclasses. If this Class object represents an interface, returns the fields of this interface and of all its superinterfaces. If this Class object represents an array type or a primitive type, returns an array of length 0.

The implicit length field for array types is not reflected by this method. User code should use the methods of class Array to manipulate arrays.

See The Java Language Specification, sections 8.2 and 8.3.

Exceptions
SecurityException if access to the information is denied.
See Also
Field


 Class.getInterfaces

Class.getInterfaces

Class Overview | Class Members | This Package | All Packages

Syntax
public native Class[] getInterfaces()
Returns
an array of interfaces implemented by this class.
Description
Determines the interfaces implemented by the class or interface represented by this object.

If this object represents a class, the return value is an array containing objects representing all interfaces implemented by the class. The order of the interface objects in the array corresponds to the order of the interface names in the implements clause of the declaration of the class represented by this object.

If this object represents an interface, the array contains objects representing all interfaces extended by the interface. The order of the interface objects in the array corresponds to the order of the interface names in the extends clause of the declaration of the interface represented by this object.

If the class or interface implements no interfaces, the method returns an array of length 0.


 Class.getMethod

Class.getMethod

Class Overview | Class Members | This Package | All Packages

Syntax
public Method getMethod( String name, Class parameterTypes[] ) throws NoSuchMethodException, SecurityException
Description
Returns a Method object that reflects the specified public member method of the class or interface represented by this Class object. The name parameter is a String specifying the simple name the desired method, and the parameterTypes parameter is an array of Class objects that identify the method's formal parameter types, in declared order.

The method to reflect is located by searching all the member methods of the class or interface represented by this Class object for a public method with the specified name and exactly the same formal parameter types.

See The Java Language Specification, sections 8.2 and 8.4.

Exceptions
NoSuchMethodException if a matching method is not found.
Exceptions
SecurityException if access to the information is denied.
See Also
Method


 Class.getMethods

Class.getMethods

Class Overview | Class Members | This Package | All Packages

Syntax
public Method[] getMethods() throws SecurityException
Description
Returns an array containing Method objects reflecting all the public member methods of the class or interface represented by this Class object, including those declared by the class or interface and and those inherited from superclasses and superinterfaces. Returns an array of length 0 if the class or interface has no public member methods.

See The Java Language Specification, sections 8.2 and 8.4.

Exceptions
SecurityException if access to the information is denied.
See Also
Method


 Class.getModifiers

Class.getModifiers

Class Overview | Class Members | This Package | All Packages

Syntax
public native int getModifiers()
Description
Returns the Java language modifiers for this class or interface, encoded in an integer. The modifiers consist of the Java Virtual Machine's constants for public, protected, private, final, and interface; they should be decoded using the methods of class Modifier.

The modifier encodings are defined in The Java Virtual Machine Specification, table 4.1.

See Also
Modifier


 Class.getName

Class.getName

Class Overview | Class Members | This Package | All Packages

Syntax
public native String getName()
Returns
the fully qualified name of the class or interface represented by this object.
Description
Returns the fully-qualified name of the type (class, interface, array, or primitive) represented by this Class object, as a String.


 Class.getResource

Class.getResource

Class Overview | Class Members | This Package | All Packages

Syntax
public URL getResource( String name )


 Class.getResourceAsStream

Class.getResourceAsStream

Class Overview | Class Members | This Package | All Packages

Syntax
public InputStream getResourceAsStream( String name )
Description
Find a resource with a given name. Will return null if no resource with this name is found. The rules for searching a resources associated with a given class are implemented by the ClassLoader of the class.

The Class methods delegate to ClassLoader methods, after applying a naming convention: if the resource name starts with "/", it is used as is. Otherwise, the name of the package is prepended, after converting "." to "/".

See Also
ClassLoader


 Class.getSigners

Class.getSigners

Class Overview | Class Members | This Package | All Packages

Syntax
public native Object[] getSigners()
Description
Get the signers of this class.


 Class.getSuperclass

Class.getSuperclass

Class Overview | Class Members | This Package | All Packages

Syntax
public native Class getSuperclass()
Returns
the superclass of the class represented by this object.
Description
If this object represents any class other than the class Object, then the object that represents the superclass of that class is returned.

If this object is the one that represents the class Object or this object represents an interface, null is returned.


 Class.isArray

Class.isArray

Class Overview | Class Members | This Package | All Packages

Syntax
public native boolean isArray()
Description
If this Class object represents an array type, returns true, otherwise returns false.


 Class.isAssignableFrom

Class.isAssignableFrom

Class Overview | Class Members | This Package | All Packages

Syntax
public native boolean isAssignableFrom( Class cls )
Description
Determines if the class or interface represented by this Class object is either the same as, or is a superclass or superinterface of, the class or interface represented by the specified Class parameter. It returns true if so, false otherwise. If this Class object represents a primitive type, returns true if the specified Class parameter is exactly this Class object, false otherwise.

Specifically, this method tests whether the type represented by the specified Class parameter can be converted to the type represented by this Class object via an identity conversion or via a widening reference conversion. See The Java Language Specification, sections 5.1.1 and 5.1.4 , for details.

Exceptions
NullPointerException if the specified Class parameter is null.


 Class.isInstance

Class.isInstance

Class Overview | Class Members | This Package | All Packages

Syntax
public native boolean isInstance( Object obj )
Parameters
obj
The object to check
Description
This method is the dynamic equivalent of the Java language instanceof operator. The method returns true if the specified Object argument is non-null and can be cast to the reference type represented by this Class object without raising a ClassCastException. It returns false otherwise.

Specifically, if this Class object represents a declared class, returns true if the specified Object argument is an instance of the represented class (or of any of its subclasses); false otherwise. If this Class object represents an array class, returns true if the specified Object argument can be converted to an object of the array type by an identity conversion or by a widening reference conversion; false otherwise. If this Class object represents an interface, returns true if the class or any superclass of the specified Object argument implements this interface; false otherwise. If this Class object represents a primitive type, returns false.


 Class.isInterface

Class.isInterface

Class Overview | Class Members | This Package | All Packages

Syntax
public native boolean isInterface()
Returns
true if this object represents an interface; false otherwise.
Description
Determines if the specified Class object represents an interface type.


 Class.isPrimitive

Class.isPrimitive

Class Overview | Class Members | This Package | All Packages

Syntax
public native boolean isPrimitive()
Description
Determines if the specified Class object represents a primitive Java type.

There are nine predefined Class objects to represent the eight primitive Java types and void. These are created by the Java Virtual Machine, and have the same names as the primitive types that they represent, namely boolean, byte, char, short, int, long, float, and double, and void.

These objects may only be accessed via the following public static final variables, and are the only Class objects for which this method returns true.

See Also
TYPE, TYPE, TYPE, TYPE, TYPE, TYPE, TYPE, TYPE, TYPE


 Class.newInstance

Class.newInstance

Class Overview | Class Members | This Package | All Packages

Syntax
public native Object newInstance() throws InstantiationException, IllegalAccessException
Returns
a newly allocated instance of the class represented by this object. This is done exactly as if by a new expression with an empty argument list.
Description
Creates a new instance of a class.

Exceptions
IllegalAccessException if the class or initializer is not accessible.
Exceptions
InstantiationException if an application tries to instantiate an abstract class or an interface, or if the instantiation fails for some other reason.


 Class.toString

Class.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string representation of this class object.
Description
Converts the object to a string. The string representation is the string "class" or "interface" followed by a space and then the fully qualified name of the class. If this Class object represents a primitive type, returns the name of the primitive type.

Overrides
toString in class Object


 Class ClassCastException

Class java.lang.ClassCastException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.lang.RuntimeException
                           |
                           +----java.lang.ClassCastException

public class ClassCastException
extends RuntimeException

Thrown to indicate that the code has attempted to cast an object to a subclass of which it is not an instance. For example, the following code generates a ClassCastException:

     Object x = new Integer(0);
     System.out.println((String)x);


 ClassCastException Members

ClassCastException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
ClassCastException() | Constructs a ClassCastException with no detail message.
ClassCastException(String) | Constructs a ClassCastException with the specified detail message.


 ClassCastException.ClassCastException

ClassCastException.ClassCastException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public ClassCastException()
Description
Constructs a ClassCastException with no detail message.

Syntax 2
public ClassCastException( String s )
Parameters
s
the detail message.
Description
Constructs a ClassCastException with the specified detail message.


 Class ClassCircularityError

Class java.lang.ClassCircularityError

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Error
                   |
                   +----java.lang.LinkageError
                           |
                           +----java.lang.ClassCircularityError

public class ClassCircularityError
extends LinkageError

Thrown when a circularity has been detected while initializing a class.


 ClassCircularityError Members

ClassCircularityError Members

Class Overview | This Package | All Packages

Constructors
Name | Description
ClassCircularityError() | Constructs a ClassCircularityError with no detail message.
ClassCircularityError(String) | Constructs a ClassCircularityError with the specified detail message.


 ClassCircularityError.ClassCircularityError

ClassCircularityError.ClassCircularityError

Class Overview | Class Members | This Package | All Packages

Syntax 1
public ClassCircularityError()
Description
Constructs a ClassCircularityError with no detail message.

Syntax 2
public ClassCircularityError( String s )
Parameters
s
the detail message.
Description
Constructs a ClassCircularityError with the specified detail message.


 Class ClassFormatError

Class java.lang.ClassFormatError

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Error
                   |
                   +----java.lang.LinkageError
                           |
                           +----java.lang.ClassFormatError

public class ClassFormatError
extends LinkageError

Thrown when the Java Virtual Machine attempts to read a class file and determines that the file is malformed or otherwise cannot be interpreted as a class file.


 ClassFormatError Members

ClassFormatError Members

Class Overview | This Package | All Packages

Constructors
Name | Description
ClassFormatError() | Constructs a ClassFormatError with no detail message.
ClassFormatError(String) | Constructs a ClassFormatError with the specified detail message.


 ClassFormatError.ClassFormatError

ClassFormatError.ClassFormatError

Class Overview | Class Members | This Package | All Packages

Syntax 1
public ClassFormatError()
Description
Constructs a ClassFormatError with no detail message.

Syntax 2
public ClassFormatError( String s )
Parameters
s
the detail message.
Description
Constructs a ClassFormatError with the specified detail message.


 Class ClassLoader

Class java.lang.ClassLoader

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.ClassLoader

public abstract class ClassLoader
extends Object

The class ClassLoader is an abstract class. Applications implement subclasses of ClassLoader in order to extend the manner in which the Java Virtual Machine dynamically loads classes.

Normally, the Java Virtual Machine loads classes from the local file system in a platform-dependent manner. For example, on UNIX systems, the Virtual Machine loads classes from the directory defined by the CLASSPATH environment variable.

However, some classes may not originate from a file; they may originate from other sources, such as the network, or they could be constructed by an application. The method defineClass converts an array of bytes into an instance of class Class. Instances of this newly defined class can be created using the newInstance method in class Class.

The methods and constructors of objects created by a class loader may reference other classes. To determine the class(es) referred to, the Java Virtual Machine calls the loadClass method of the class loader that originally created the class. If the Java Virtual Machine only needs to determine if the class exists and if it does exist to know its superclass, the resolve flag is set to false. However, if an instance of the class is being created or any of its methods are being called, the class must also be resolved. In this case the resolve flag is set to true, and the resolveClass method should be called.

For example, an application could create a network class loader to download class files from a server. Sample code might look like:

    ClassLoader loader = new NetworkClassLoader(host, port);
    Object main = loader.loadClass("Main", true).newInstance();
    . . .

The network class loader subclass must define the method loadClass to load a class from the network. Once it has downloaded the bytes that make up the class, it should use the method defineClass to create a class instance. A sample implementation is:

     class NetworkClassLoader {
         String host;
         int port;
         Hashtable cache = new Hashtable();
         private byte loadClassData(String name)[] {
         // load the class data from the connection
          . . .
         }
         public synchronized Class loadClass(String name,
                                             boolean resolve) {
             Class c = cache.get(name);
             if (c == null) {
                 byte data[] = loadClassData(name);
                 c = defineClass(data, 0, data.length);
                 cache.put(name, c);
             }
             if (resolve)
                 resolveClass(c);
             return c;
         }
     }

See Also:
Class, newInstance, defineClass, loadClass, resolveClass


 ClassLoader Members

ClassLoader Members

Class Overview | This Package | All Packages

Constructors
Name | Description
ClassLoader() | Constructs a new class loader and initializes it.

Methods
Name | Description
defineClass(byte[], int, int) | Converts an array of bytes into an instance of class Class. Deprecated.
defineClass(String, byte[], int, int) | Converts an array of bytes to an instance of class Class.
findLoadedClass(String) |
findSystemClass(String) | Finds the system class with the specified name, loading it in if necessary.
getResource(String) | Find a resource with a given name.
getResourceAsStream(String) | Get an InputStream on a given resource.
getSystemResource(String) | Find a resource with a given name.
getSystemResourceAsStream(String) | Get an InputStream on a given resource..
loadClass(String) | Requests the class loader to load a class with the specified name.
loadClass(String, boolean) | Resolves the specified name to a Class.
resolveClass(Class) | Resolves the class so that an instance of the class can be created, or so that one of its methods can be called.
setSigners(Class, Object[]) | Sets the signers of a class.


 ClassLoader.ClassLoader

ClassLoader.ClassLoader

Class Overview | Class Members | This Package | All Packages

Syntax
protected ClassLoader()
Description
Constructs a new class loader and initializes it.

If there is a security manager, its checkCreateClassLoader method is called. This may result in a security exception.

Exceptions
SecurityException if the current thread does not have permission to create a new class loader.
See Also
SecurityException, checkCreateClassLoader


 ClassLoader.defineClass

ClassLoader.defineClass

Class Overview | Class Members | This Package | All Packages

Syntax 1
protected final Class defineClass( byte data[], int offset, int length )
Parameters
data
the bytes that make up the Class.
offset
the start offset of the Class data.
length
the length of the Class data.
Returns
the Class object that was created from the data.
Description
Note: defineClass() is deprecated. Replaced by defineClass(java.lang.String, byte[], int, int).

Converts an array of bytes into an instance of class Class. Before the Class can be used it must be resolved. This method is deprecated in favor of the version that takes a "name" as a first argument, and is more secure.

Exceptions
ClassFormatError if the data does not contain a valid Class.
See Also
loadClass, resolveClass

Syntax 2
protected final Class defineClass( String name, byte data[], int offset, int length )
Parameters
name
the expected name of the class; null if unknown; using '.' and not '/' as separator, and without a trailing ".class" suffix.
data
the bytes that make up the Class.
offset
the start offset of the Class data.
length
the length of the Class data.
Returns
the Class object that was created from the data.
Description
Converts an array of bytes to an instance of class Class. Before the Class can be used it must be resolved.

Exceptions
ClassFormatError if the data does not contain a valid Class.
See Also
loadClass, resolveClass


 ClassLoader.findLoadedClass

ClassLoader.findLoadedClass

Class Overview | Class Members | This Package | All Packages

Syntax
protected final Class findLoadedClass( String name )


 ClassLoader.findSystemClass

ClassLoader.findSystemClass

Class Overview | Class Members | This Package | All Packages

Syntax
protected final Class findSystemClass( String name ) throws ClassNotFoundException
Parameters
name
the name of the system class.
Returns
a system class with the given name.
Description
Finds the system class with the specified name, loading it in if necessary.

A system class is a class loaded from the local file system in a platform- dependent way. It has no class loader.

Exceptions
ClassNotFoundException if it could not find a definition for the class.
Exceptions
NoClassDefFoundError if the class is not found.


 ClassLoader.getResource

ClassLoader.getResource

Class Overview | Class Members | This Package | All Packages

Syntax
public URL getResource( String name )
Parameters
name
the name of the resource, to be used as is.
Returns
an InputStream on the resource, or null if not found.
Description
Find a resource with a given name. The return is a URL to the resource. Doing a getContent() on the URL may return an Image, an AudioClip, or an InputStream.

The class loader can choose what to do to locate the resource.


 ClassLoader.getResourceAsStream

ClassLoader.getResourceAsStream

Class Overview | Class Members | This Package | All Packages

Syntax
public InputStream getResourceAsStream( String name )
Parameters
name
the name of the resource, to be used as is.
Returns
an InputStream on the resource, or null if not found.
Description
Get an InputStream on a given resource. Will return null if no resource with this name is found.

The class loader can choose what to do to locate the resource.


 ClassLoader.getSystemResource

ClassLoader.getSystemResource

Class Overview | Class Members | This Package | All Packages

Syntax
public static final URL getSystemResource( String name )
Parameters
name
the name of the resource, to be used as is.
Returns
the URL on the resource, or null if not found.
Description
Find a resource with a given name. The return is a URL to the resource Doing a getContent() on the URL may return an Image, an AudioClip, or an InputStream.

The resource name may be any system resource (e.g. follows CLASSPATH order).


 ClassLoader.getSystemResourceAsStream

ClassLoader.getSystemResourceAsStream

Class Overview | Class Members | This Package | All Packages

Syntax
public static final InputStream getSystemResourceAsStream( String name )
Parameters
name
the name of the resource, to be used as is.
Returns
an InputStream on the resource, or null if not found.
Description
Get an InputStream on a given resource.. Will return null if no resource with this name is found.

The resource name may be any system resource (e.g. follows CLASSPATH order).


 ClassLoader.loadClass

ClassLoader.loadClass

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Class loadClass( String name ) throws ClassNotFoundException
Parameters
name
the name of the desired Class.
resolve
true if the Class must be resolved.
Returns
the resulting Class, or null if it was not found.
Description
Requests the class loader to load a class with the specified name. The loadClass method is called by the Java Virtual Machine when a class loaded by a class loader first references another class. Every subclass of class ClassLoader must define this method.

If the resolve flag is true, the method should call the resolveClass method on the resulting class object.

Class loaders should use a hashtable or other cache to avoid defining classes with the same name multiple times.

Exceptions
ClassNotFoundException if the class loader cannot find a definition for the class.

Syntax 2
protected abstract Class loadClass( String name, boolean resolve ) throws ClassNotFoundException
Parameters
name
the name of the desired Class.
resolve
true if the Class needs to be resolved.
Returns
the resulting Class, or null if it was not found.
Description
Resolves the specified name to a Class. The method loadClass() is called by the virtual machine. As an abstract method, loadClass() must be defined in a subclass of ClassLoader. By using a Hashtable, you can avoid loading the same Class more than once.

Exceptions
ClassNotFoundException if the class loader cannot find a definition for the class.
See Also
Hashtable


 ClassLoader.resolveClass

ClassLoader.resolveClass

Class Overview | Class Members | This Package | All Packages

Syntax
protected final void resolveClass( Class c )
Parameters
c
the Class instance to be resolved.
Description
Resolves the class so that an instance of the class can be created, or so that one of its methods can be called. This method should be called by loadClass if the resolve flag is true.

See Also
defineClass


 ClassLoader.setSigners

ClassLoader.setSigners

Class Overview | Class Members | This Package | All Packages

Syntax
protected final void setSigners( Class cl, Object signers[] )
Description
Sets the signers of a class. This is called after defining a class, by signature-aware class loading code.


 Class ClassNotFoundException

Class java.lang.ClassNotFoundException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.lang.ClassNotFoundException

public class ClassNotFoundException
extends Exception

Thrown when an application tries to load in a class through its string name using:

  • The forName method in class Class.
  • The findSystemClass method in class ClassLoader .
  • The loadClass method in class ClassLoader.

but no definition for the class with the specifed name could be found.

See Also:
forName, findSystemClass, loadClass


 ClassNotFoundException Members

ClassNotFoundException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
ClassNotFoundException() | Constructs a ClassNotFoundException with no detail message.
ClassNotFoundException(String) | Constructs a ClassNotFoundException with the specified detail message.


 ClassNotFoundException.ClassNotFoundException

ClassNotFoundException.ClassNotFoundException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public ClassNotFoundException()
Description
Constructs a ClassNotFoundException with no detail message.

Syntax 2
public ClassNotFoundException( String s )
Parameters
s
the detail message.
Description
Constructs a ClassNotFoundException with the specified detail message.


 Class CloneNotSupportedException

Class java.lang.CloneNotSupportedException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.lang.CloneNotSupportedException

public class CloneNotSupportedException
extends Exception

Thrown to indicate that the clone method in class Object has been called to clone an object, but that the object's class does not implement the Cloneable interface.

Applications that override the clone method can also throw this exception to indicate that an object could not or should not be cloned.

See Also:
Cloneable, clone


 CloneNotSupportedException Members

CloneNotSupportedException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
CloneNotSupportedException() | Constructs a CloneNotSupportedException with no detail message.
CloneNotSupportedException(String) | Constructs a CloneNotSupportedException with the specified detail message.


 CloneNotSupportedException.CloneNotSupportedException

CloneNotSupportedException.CloneNotSupportedException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public CloneNotSupportedException()
Description
Constructs a CloneNotSupportedException with no detail message.

Syntax 2
public CloneNotSupportedException( String s )
Parameters
s
the detail message.
Description
Constructs a CloneNotSupportedException with the specified detail message.


 Interface Cloneable

Interface java.lang.Cloneable

This Package | All Packages

public interface Cloneable

A class implements the Cloneable interface to indicate to the clone method in class Object that it is legal for that method to make a field-for-field copy of instances of that class.

Attempts to clone instances that do not implement the Cloneable interface result in the exception CloneNotSupportedException being thrown.

See Also:
CloneNotSupportedException


 Class Compiler

Class java.lang.Compiler

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Compiler

public final class Compiler
extends Object

The Compiler class is provided to support Java-to-native-code compilers and related services. By design, the Compiler class does nothing; it serves as a placeholder for a JIT compiler implementation.

When the Java Virtual Machine first starts, it determines if the system property java.compiler exists. (System properties are accessible through getProperty and , a method defined by the System class.) If so, it is assumed to be the name of a library (with a platform-dependent exact location and type); the loadLibrary method in class System is called to load that library. If this loading succeeds, the function named java_lang_Compiler_start() in that library is called.

If no compiler is available, these methods do nothing.

See Also:
getProperty, getProperty, loadLibrary


 Compiler Members

Compiler Members

Class Overview | This Package | All Packages

Methods
Name | Description
command(Object) | Examines the argument type and its fields and perform some documented operation.
compileClass(Class) | Compiles the specified class.
compileClasses(String) | Compiles all classes whose name matches the specified string.
disable() | Cause the Compiler to cease operation.
enable() | Cause the Compiler to resume operation.


 Compiler.command

Compiler.command

Class Overview | Class Members | This Package | All Packages

Syntax
public static native Object command( Object any )
Parameters
any
an argument.
Returns
a compiler-specific value, or null if no compiler is available.
Description
Examines the argument type and its fields and perform some documented operation. No specific operations are required.


 Compiler.compileClass

Compiler.compileClass

Class Overview | Class Members | This Package | All Packages

Syntax
public static native boolean compileClass( Class clazz )
Parameters
clazz
a class.
Returns
true if the compilation succeeded; false if the compilation failed or no compiler is available.
Description
Compiles the specified class.


 Compiler.compileClasses

Compiler.compileClasses

Class Overview | Class Members | This Package | All Packages

Syntax
public static native boolean compileClasses( String string )
Parameters
string
the name of the classes to compile.
Returns
true if the compilation succeeded; false if the compilation failed or no compiler is available.
Description
Compiles all classes whose name matches the specified string.


 Compiler.disable

Compiler.disable

Class Overview | Class Members | This Package | All Packages

Syntax
public static native void disable()
Description
Cause the Compiler to cease operation.


 Compiler.enable

Compiler.enable

Class Overview | Class Members | This Package | All Packages

Syntax
public static native void enable()
Description
Cause the Compiler to resume operation.


 Class Double

Class java.lang.Double

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Number
           |
           +----java.lang.Double

public final class Double
extends Number

The Double class wraps a value of the primitive type double in an object. An object of type Double contains a single field whose type is double.

In addition, this class provides several methods for converting a double to a String and a String to a double, as well as other constants and methods useful when dealing with a double.


 Double Members

Double Members

Class Overview | This Package | All Packages

Fields
Name | Description
MAX_VALUE | The largest positive value of type double.
MIN_VALUE | The smallest positive value of type double.
NaN | A NaN value of type double.
NEGATIVE_INFINITY | The negative infinity of type double.
POSITIVE_INFINITY | The positive infinity of type double.
TYPE | The Class object representing the primitive type double.

Constructors
Name | Description
Double(double) | Constructs a newly allocated Double object that represents the primitive double argument.
Double(String) | Constructs a newly allocated Double object that represents the floating- point value of type double represented by the string.

Methods
Name | Description
byteValue() | Returns the value of this Double as a byte (by casting to a byte).
doubleToLongBits(double) | Returns a representation of the specified floating-point value according to the IEEE 754 floating-point "double format" bit layout.
doubleValue() | Returns the double value of this Double.
equals(Object) | Compares this object against the specified object.
floatValue() | Returns the float value of this Double.
hashCode() | Returns a hashcode for this Double.
intValue() | Returns the integer value of this Double (by casting to an int).
isInfinite() | Returns true if this Double value is infinitely large in magnitude.
isInfinite(double) | Returns true if the specified number is infinitely large in magnitude.
isNaN() | Returns true if this Double value is the special Not-a-Number (NaN) value.
isNaN(double) | Returns true if the specified number is the special Not-a-Number (NaN) value.
longBitsToDouble(long) | Returns the double-float corresponding to a given bit represention.
longValue() | Returns the long value of this Double (by casting to a long).
shortValue() | Returns the value of this Double as a short (by casting to a short).
toString() | Returns a String representation of this Double object.
toString(double) | Creates a string representation of the double argument.
valueOf(String) | Returns a new Double value initialized to the value represented by the specified String.


 Double.MAX_VALUE

Double.MAX_VALUE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final double MAX_VALUE
Description
The largest positive value of type double.


 Double.MIN_VALUE

Double.MIN_VALUE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final double MIN_VALUE
Description
The smallest positive value of type double.


 Double.NaN

Double.NaN

Class Overview | Class Members | This Package | All Packages

Syntax
public static final double NaN
Description
A NaN value of type double.


 Double.NEGATIVE_INFINITY

Double.NEGATIVE_INFINITY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final double NEGATIVE_INFINITY
Description
The negative infinity of type double.


 Double.POSITIVE_INFINITY

Double.POSITIVE_INFINITY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final double POSITIVE_INFINITY
Description
The positive infinity of type double.


 Double.TYPE

Double.TYPE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Class TYPE
Description
The Class object representing the primitive type double.


 Double.Double

Double.Double

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Double( double value )
Parameters
value
the value to be represented by the Double.
Description
Constructs a newly allocated Double object that represents the primitive double argument.

Syntax 2
public Double( String s ) throws NumberFormatException
Parameters
s
a string to be converted to a Double.
Description
Constructs a newly allocated Double object that represents the floating- point value of type double represented by the string. The string is converted to a double value as if by the valueOf method.

Exceptions
NumberFormatException if the string does not contain a parsable number.
See Also
valueOf


 Double.byteValue

Double.byteValue

Class Overview | Class Members | This Package | All Packages

Syntax
public byte byteValue()
Description
Returns the value of this Double as a byte (by casting to a byte).

Overrides
byteValue in class Number


 Double.doubleToLongBits

Double.doubleToLongBits

Class Overview | Class Members | This Package | All Packages

Syntax
public static native long doubleToLongBits( double value )
Parameters
value
a double precision floating-point number.
Returns
the bits that represent the floating-point number.
Description
Returns a representation of the specified floating-point value according to the IEEE 754 floating-point "double format" bit layout.

Bit 63 represents the sign of the floating-point number. Bits 62-52 represent the exponent. Bits 51-0 represent the significand (sometimes called the mantissa) of the floating-point number.

If the argument is positive infinity, the result is 0x7ff0000000000000L.

If the argument is negative infinity, the result is 0xfff0000000000000L.

If the argument is NaN, the result is 0x7ff8000000000000L.


 Double.doubleValue

Double.doubleValue

Class Overview | Class Members | This Package | All Packages

Syntax
public double doubleValue()
Returns
the double value represented by this object.
Description
Returns the double value of this Double.

Overrides
doubleValue in class Number


 Double.equals

Double.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Parameters
obj
the object to compare with.
Returns
true if the objects are the same; false otherwise.
Description
Compares this object against the specified object. The result is true if and only if the argument is not null and is a Double object that represents a double that has the identical bit pattern to the bit pattern of the double represented by this object.

Note that in most cases, for two instances of class Double, d1 and d2, the value of d1.equals(d2) is true if and only if

    d1.doubleValue() == d2.doubleValue()

also has the value true. However, there are two exceptions:

  • If d1 and d2 both represent Double.NaN, then the equals method returns true, even though Double.NaN==Double.NaN has the value false.
  • If d1 represents +0.0 while d2 represents -0.0, or vice versa, the equal test has the value false, even though +0.0==-0.0 has the value true.

Overrides
equals in class Object


 Double.floatValue

Double.floatValue

Class Overview | Class Members | This Package | All Packages

Syntax
public float floatValue()
Returns
the double value represented by this object is converted to type float and the result of the conversion is returned.
Description
Returns the float value of this Double.

Overrides
floatValue in class Number


 Double.hashCode

Double.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int hashCode()
Returns
a hash code value for this object.
Description
Returns a hashcode for this Double.

Overrides
hashCode in class Object


 Double.intValue

Double.intValue

Class Overview | Class Members | This Package | All Packages

Syntax
public int intValue()
Returns
the double value represented by this object is converted to type int and the result of the conversion is returned.
Description
Returns the integer value of this Double (by casting to an int).

Overrides
intValue in class Number


 Double.isInfinite

Double.isInfinite

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isInfinite( double v )
Parameters
v
the value to be tested.
Returns
true if the value of the argument is positive infinity or negative infinity; false otherwise.
Description
Returns true if the specified number is infinitely large in magnitude.


 Double.isInfinite

Double.isInfinite

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isInfinite()
Returns
true if the value represented by this object is positive infinity or negative infinity; false otherwise.
Description
Returns true if this Double value is infinitely large in magnitude.


 Double.isNaN

Double.isNaN

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isNaN( double v )
Parameters
v
the value to be tested.
Returns
true if the value of the argument is NaN; false otherwise.
Description
Returns true if the specified number is the special Not-a-Number (NaN) value.


 Double.isNaN

Double.isNaN

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isNaN()
Returns
true if the value represented by this object is NaN; false otherwise.
Description
Returns true if this Double value is the special Not-a-Number (NaN) value.


 Double.longBitsToDouble

Double.longBitsToDouble

Class Overview | Class Members | This Package | All Packages

Syntax
public static native double longBitsToDouble( long bits )
Parameters
bits
any long integer.
Returns
the double floating-point value with the same bit pattern.
Description
Returns the double-float corresponding to a given bit represention. The argument is considered to be a representation of a floating-point value according to the IEEE 754 floating-point "double precision" bit layout. That floating-point value is returned as the result.

If the argument is 0x7f80000000000000L, the result is positive infinity.

If the argument is 0xff80000000000000L, the result is negative infinity.

If the argument is any value in the range 0x7ff0000000000001L through 0x7fffffffffffffffL or in the range 0xfff0000000000001L through 0xffffffffffffffffL, the result is NaN. All IEEE 754 NaN values are, in effect, lumped together by the Java language into a single value.


 Double.longValue

Double.longValue

Class Overview | Class Members | This Package | All Packages

Syntax
public long longValue()
Returns
the double value represented by this object is converted to type long and the result of the conversion is returned.
Description
Returns the long value of this Double (by casting to a long).

Overrides
longValue in class Number


 Double.shortValue

Double.shortValue

Class Overview | Class Members | This Package | All Packages

Syntax
public short shortValue()
Description
Returns the value of this Double as a short (by casting to a short).

Overrides
shortValue in class Number


 Double.toString

Double.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public static String toString( double d )
Parameters
d
the double to be converted.
Returns
a string representation of the argument.
Description
Creates a string representation of the double argument.

The values NaN, NEGATIVE_INFINITY, POSITIVE_INFINITY, -0.0, and +0.0 are represented by the strings "NaN", "-Infinity", "Infinity", "-0.0", and "0.0", respectively.

If d is in the range 10-3 <= |d| <=107, then it is converted to a string in the style [-]ddd.ddd. Otherwise, it is converted to a string in the style [-]m.ddddE±xx.

There is always a minimum of one digit after the decimal point. The number of digits is the minimum needed to uniquely distinguish the argument value from adjacent values of type double.


 Double.toString

Double.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a String representation of this object.
Description
Returns a String representation of this Double object. The primitive double value represented by this object is converted to a string exactly as if by the method toString of one argument.

Overrides
toString in class Object
See Also
toString


 Double.valueOf

Double.valueOf

Class Overview | Class Members | This Package | All Packages

Syntax
public static Double valueOf( String s ) throws NumberFormatException
Parameters
s
the string to be parsed.
Returns
a newly constructed Double initialized to the value represented by the string argument.
Description
Returns a new Double value initialized to the value represented by the specified String.

Exceptions
NumberFormatException if the string does not contain a parsable number.


 Class Error

Class java.lang.Error

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Error

public class Error
extends Throwable

An Error is a subclass of Throwable that indicates serious problems that a reasonable application should not try to catch. Most such errors are abnormal conditions. The ThreadDeath error, though a "normal" condition, is also a subclass of Error because most applications should not try to catch it.

A method is not required to declare in its throws clause any subclasses of Error that might be thrown during the execution of the method but not caught, since these errors are abnormal conditions that should never occur.

See Also:
ThreadDeath


 Error Members

Error Members

Class Overview | This Package | All Packages

Constructors
Name | Description
Error() | Constructs an Error with no specified detail message.
Error(String) | Constructs an Error with the specified detail message.


 Error.Error

Error.Error

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Error()
Description
Constructs an Error with no specified detail message.

Syntax 2
public Error( String s )
Parameters
s
the detail message.
Description
Constructs an Error with the specified detail message.


 Class Exception

Class java.lang.Exception

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception

public class Exception
extends Throwable

The class Exception and its subclasses are a form of Throwable that indicates conditions that a reasonable application might want to catch.

See Also:
Error


 Exception Members

Exception Members

Class Overview | This Package | All Packages

Constructors
Name | Description
Exception() | Constructs an Exception with no specified detail message.
Exception(String) | Constructs an Exception with the specified detail message.


 Exception.Exception

Exception.Exception

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Exception()
Description
Constructs an Exception with no specified detail message.

Syntax 2
public Exception( String s )
Parameters
s
the detail message.
Description
Constructs an Exception with the specified detail message.


 Class ExceptionInInitializerError

Class java.lang.ExceptionInInitializerError

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Error
                   |
                   +----java.lang.LinkageError
                           |
                           +----java.lang.ExceptionInInitializerError

public class ExceptionInInitializerError
extends LinkageError

Signals that an unexpected exception has occurred in a static initializer.


 ExceptionInInitializerError Members

ExceptionInInitializerError Members

Class Overview | This Package | All Packages

Constructors
Name | Description
ExceptionInInitializerError() | Constructs an ExceptionInInitializerError with no detail message.
ExceptionInInitializerError(String) | Constructs a ExceptionInInitializerError with the specified detail message.
ExceptionInInitializerError(Throwable) | Constructs a new ExceptionInInitializerError class initialized to the specific throwable

Methods
Name | Description
getException() | Returns the exception that occurred during a static initialization that caused this Error to be created.


 ExceptionInInitializerError.ExceptionInInitializerError

ExceptionInInitializerError.ExceptionInInitializerError

Class Overview | Class Members | This Package | All Packages

Syntax 1
public ExceptionInInitializerError()
Description
Constructs an ExceptionInInitializerError with no detail message. A detail message is a String that describes this particular exception.

Syntax 2
public ExceptionInInitializerError( Throwable thrown )
Parameters
thrown
The exception thrown
Description
Constructs a new ExceptionInInitializerError class initialized to the specific throwable

Syntax 3
public ExceptionInInitializerError( String s )
Parameters
s
the detail message
Description
Constructs a ExceptionInInitializerError with the specified detail message. A detail message is a String that describes this particular exception.


 ExceptionInInitializerError.getException

ExceptionInInitializerError.getException

Class Overview | Class Members | This Package | All Packages

Syntax
public Throwable getException()
Description
Returns the exception that occurred during a static initialization that caused this Error to be created.


 Class Float

Class java.lang.Float

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Number
           |
           +----java.lang.Float

public final class Float
extends Number

The Float class wraps a value of primitive type float in an object. An object of type Float contains a single field whose type is float.

In addition, this class provides several methods for converting a float to a String and a String to a float, as well as other constants and methods useful when dealing with a float.


 Float Members

Float Members

Class Overview | This Package | All Packages

Fields
Name | Description
MAX_VALUE | The largest positive value of type float.
MIN_VALUE | The smallest positive value of type float.
NaN | The NaN value of type float.
NEGATIVE_INFINITY | The negative infinity of type float.
POSITIVE_INFINITY | The positive infinity of type float.
TYPE | The Class object representing the primitive type float.

Constructors
Name | Description
Float(double) | Constructs a newly allocated Floatobject that represents the argument converted to type float.
Float(float) | Constructs a newly allocated Float object that represents the primitive float argument.
Float(String) | Constructs a newly allocated Float object that represents the floating- point value of type float represented by the string.

Methods
Name | Description
byteValue() | Returns the value of this Float as a byte (by casting to a byte).
doubleValue() | Returns the double value of this Float.
equals(Object) | Compares this object against some other object.
floatToIntBits(float) | Returns the bit represention of a single-float value.
floatValue() | Returns the float value of this Float object.
hashCode() | Returns a hashcode for this Float.
intBitsToFloat(int) | Returns the single-float corresponding to a given bit represention.
intValue() | Returns the integer value of this Float (by casting to an int).
isInfinite() | Returns true if this Float value is infinitely large in magnitude.
isInfinite(float) | Returns true if the specified number is infinitely large in magnitude.
isNaN() | Returns true if this Float value is Not-a-Number (NaN).
isNaN(float) | Returns true if the specified number is the special Not-a-Number (NaN) value.
longValue() | Returns the long value of this Float (by casting to a long).
shortValue() | Returns the value of this Float as a short (by casting to a short).
toString() | Returns a String representation of this Float object.
toString(float) | Returns a String representation for the specified float value.
valueOf(String) | Returns the floating point value represented by the specified String.


 Float.MAX_VALUE

Float.MAX_VALUE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final float MAX_VALUE
Description
The largest positive value of type float.


 Float.MIN_VALUE

Float.MIN_VALUE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final float MIN_VALUE
Description
The smallest positive value of type float.


 Float.NaN

Float.NaN

Class Overview | Class Members | This Package | All Packages

Syntax
public static final float NaN
Description
The NaN value of type float.


 Float.NEGATIVE_INFINITY

Float.NEGATIVE_INFINITY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final float NEGATIVE_INFINITY
Description
The negative infinity of type float.


 Float.POSITIVE_INFINITY

Float.POSITIVE_INFINITY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final float POSITIVE_INFINITY
Description
The positive infinity of type float.


 Float.TYPE

Float.TYPE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Class TYPE
Description
The Class object representing the primitive type float.


 Float.Float

Float.Float

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Float( float value )
Parameters
value
the value to be represented by the Float.
Description
Constructs a newly allocated Float object that represents the primitive float argument.

Syntax 2
public Float( double value )
Parameters
value
the value to be represented by the Float.
Description
Constructs a newly allocated Floatobject that represents the argument converted to type float.

Syntax 3
public Float( String s ) throws NumberFormatException
Parameters
s
a string to be converted to a Float.
Description
Constructs a newly allocated Float object that represents the floating- point value of type float represented by the string. The string is converted to a float value as if by the valueOf method.

Exceptions
NumberFormatException if the string does not contain a parsable number.
See Also
valueOf


 Float.byteValue

Float.byteValue

Class Overview | Class Members | This Package | All Packages

Syntax
public byte byteValue()
Description
Returns the value of this Float as a byte (by casting to a byte).

Overrides
byteValue in class Number


 Float.doubleValue

Float.doubleValue

Class Overview | Class Members | This Package | All Packages

Syntax
public double doubleValue()
Description
Returns the double value of this Float.

Overrides
doubleValue in class Number


 Float.equals

Float.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Returns
true if the objects are the same; false otherwise.
Description
Compares this object against some other object. The result is true if and only if the argument is not null and is a Float object that represents a float that has the identical bit pattern to the bit pattern of the float represented by this object.

Note that in most cases, for two instances of class Float, f1 and f2, the value of f1.equals(f2) is true if and only if

    f1.floatValue() == f2.floatValue()

also has the value true. However, there are two exceptions:

  • If f1 and f2 both represent Float.NaN, then the equals method returns true, even though Float.NaN==Float.NaN has the value false.
  • If f1 represents +0.0f while f2 represents -0.0f, or vice versa, the equal test has the value false, even though 0.0f==-0.0f has the value true.

Overrides
equals in class Object
See Also
floatToIntBits


 Float.floatToIntBits

Float.floatToIntBits

Class Overview | Class Members | This Package | All Packages

Syntax
public static native int floatToIntBits( float value )
Parameters
value
a floating-point number.
Returns
the bits that represent the floating-point number.
Description
Returns the bit represention of a single-float value. The result is a representation of the floating-point argument according to the IEEE 754 floating-point "single precision" bit layout.

Bit 31 represents the sign of the floating-point number. Bits 30-23 represent the exponent. Bits 22-0 represent the significand (sometimes called the mantissa) of the floating-point number.

If the argument is positive infinity, the result is 0x7f800000.

If the argument is negative infinity, the result is 0xff800000.

If the argument is NaN, the result is 0x7fc00000.


 Float.floatValue

Float.floatValue

Class Overview | Class Members | This Package | All Packages

Syntax
public float floatValue()
Returns
the float value represented by this object.
Description
Returns the float value of this Float object.

Overrides
floatValue in class Number


 Float.hashCode

Float.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int hashCode()
Returns
a hash code value for this object.
Description
Returns a hashcode for this Float.

Overrides
hashCode in class Object


 Float.intBitsToFloat

Float.intBitsToFloat

Class Overview | Class Members | This Package | All Packages

Syntax
public static native float intBitsToFloat( int bits )
Parameters
bits
an integer.
Returns
the single-format floating-point value with the same bit pattern.
Description
Returns the single-float corresponding to a given bit represention. The argument is considered to be a representation of a floating-point value according to the IEEE 754 floating-point "single precision" bit layout.

If the argument is 0x7f800000, the result is positive infinity.

If the argument is 0xff800000, the result is negative infinity.

If the argument is any value in the range 0x7f800001 through 0x7f8fffff or in the range 0xff800001 through 0xff8fffff, the result is NaN. All IEEE 754 NaN values are, in effect, lumped together by the Java language into a single value.


 Float.intValue

Float.intValue

Class Overview | Class Members | This Package | All Packages

Syntax
public int intValue()
Returns
the float value represented by this object converted to type int and the result of the conversion is returned.
Description
Returns the integer value of this Float (by casting to an int).

Overrides
intValue in class Number


 Float.isInfinite

Float.isInfinite

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isInfinite( float v )
Parameters
v
the value to be tested.
Returns
true if the argument is positive infinity or negative infinity; false otherwise.
Description
Returns true if the specified number is infinitely large in magnitude.


 Float.isInfinite

Float.isInfinite

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isInfinite()
Returns
true if the value represented by this object is positive infinity or negative infinity; false otherwise.
Description
Returns true if this Float value is infinitely large in magnitude.


 Float.isNaN

Float.isNaN

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isNaN( float v )
Parameters
v
the value to be tested.
Returns
true if the argument is NaN; false otherwise.
Description
Returns true if the specified number is the special Not-a-Number (NaN) value.


 Float.isNaN

Float.isNaN

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isNaN()
Returns
true if the value represented by this object is NaN; false otherwise.
Description
Returns true if this Float value is Not-a-Number (NaN).


 Float.longValue

Float.longValue

Class Overview | Class Members | This Package | All Packages

Syntax
public long longValue()
Returns
the float value represented by this object is converted to type long and the result of the conversion is returned.
Description
Returns the long value of this Float (by casting to a long).

Overrides
longValue in class Number


 Float.shortValue

Float.shortValue

Class Overview | Class Members | This Package | All Packages

Syntax
public short shortValue()
Description
Returns the value of this Float as a short (by casting to a short).

Overrides
shortValue in class Number


 Float.toString

Float.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public static String toString( float f )
Parameters
d
the float to be converted.
Returns
a string representation of the argument.
Description
Returns a String representation for the specified float value.

The values NaN, NEGATIVE_INFINITY, POSITIVE_INFINITY, -0.0, and +0.0 are represented by the strings "NaN", "-Infinity", "Infinity", "-0.0", and "0.0", respectively.

If d is in the range 10-3 <= |d| <= 107, then it is converted to a String in the style [-]ddd.ddd. Otherwise, it is converted to a string in the style [-]m.ddddE±xx.

There is always a minimum of 1 digit after the decimal point. The number of digits is the minimum needed to uniquely distinguish the argument value from adjacent values of type float.


 Float.toString

Float.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a String representation of this object.
Description
Returns a String representation of this Float object. The primitive float value represented by this object is converted to a String exactly as if by the method toString of one argument.

Overrides
toString in class Object
See Also
toString


 Float.valueOf

Float.valueOf

Class Overview | Class Members | This Package | All Packages

Syntax
public static Float valueOf( String s ) throws NumberFormatException
Parameters
s
the string to be parsed.
Returns
a newly constructed Float initialized to the value represented by the String argument.
Description
Returns the floating point value represented by the specified String.

Exceptions
NumberFormatException if the string does not contain a parsable number.


 Class IllegalAccessError

Class java.lang.IllegalAccessError

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Error
                   |
                   +----java.lang.LinkageError
                           |
                           +----java.lang.IncompatibleClassChangeError
                                   |
                                   +----java.lang.IllegalAccessError

public class IllegalAccessError
extends IncompatibleClassChangeError

Thrown if an application attempts to access or modify a field, or to call a method that it does not have access to.

Normally, this error is caught by the compiler; this error can only occur at run time if the definition of a class has incompatibly changed.


 IllegalAccessError Members

IllegalAccessError Members

Class Overview | This Package | All Packages

Constructors
Name | Description
IllegalAccessError() | Constructs an IllegalAccessError with no detail message.
IllegalAccessError(String) | Constructs an IllegalAccessError with the specified detail message.


 IllegalAccessError.IllegalAccessError

IllegalAccessError.IllegalAccessError

Class Overview | Class Members | This Package | All Packages

Syntax 1
public IllegalAccessError()
Description
Constructs an IllegalAccessError with no detail message.

Syntax 2
public IllegalAccessError( String s )
Parameters
s
the detail message.
Description
Constructs an IllegalAccessError with the specified detail message.


 Class IllegalAccessException

Class java.lang.IllegalAccessException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.lang.IllegalAccessException

public class IllegalAccessException
extends Exception

Thrown when an application tries to load in a class through its string name using:

  • The forName method in class Class.
  • The findSystemClass method in class ClassLoader.
  • The loadClass method in class ClassLoader.

but the currently executing method does not have access to the definition of the specified class, because the class is not public and in another package.

An instance of this class can also be thrown when an application tries to create an instance of a class using the newInstance method in class Class, but the current method does not have access to the appropriate zero-argument constructor.

See Also:
forName, newInstance, findSystemClass, loadClass


 IllegalAccessException Members

IllegalAccessException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
IllegalAccessException() | Constructs an IllegalAccessException without a detail message.
IllegalAccessException(String) | Constructs an IllegalAccessException with a detail message.


 IllegalAccessException.IllegalAccessException

IllegalAccessException.IllegalAccessException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public IllegalAccessException()
Description
Constructs an IllegalAccessException without a detail message.

Syntax 2
public IllegalAccessException( String s )
Parameters
s
the detail message.
Description
Constructs an IllegalAccessException with a detail message.


 Class IllegalArgumentException

Class java.lang.IllegalArgumentException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.lang.RuntimeException
                           |
                           +----java.lang.IllegalArgumentException

public class IllegalArgumentException
extends RuntimeException

Thrown to indicate that a method has been passed an illegal or inappropriate argument.

See Also:
setPriority


 IllegalArgumentException Members

IllegalArgumentException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
IllegalArgumentException() | Constructs an IllegalArgumentException with no detail message.
IllegalArgumentException(String) | Constructs an IllegalArgumentException with the specified detail message.


 IllegalArgumentException.IllegalArgumentException

IllegalArgumentException.IllegalArgumentException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public IllegalArgumentException()
Description
Constructs an IllegalArgumentException with no detail message.

Syntax 2
public IllegalArgumentException( String s )
Parameters
s
the detail message.
Description
Constructs an IllegalArgumentException with the specified detail message.


 Class IllegalMonitorStateException

Class java.lang.IllegalMonitorStateException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.lang.RuntimeException
                           |
                           +----java.lang.IllegalMonitorStateException

public class IllegalMonitorStateException
extends RuntimeException

Thrown to indicate that a thread has attempted to wait on an object's monitor or to notify other threads waiting on an object's monitor without owning the specified monitor.

See Also:
notify, notifyAll, wait, wait, wait


 IllegalMonitorStateException Members

IllegalMonitorStateException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
IllegalMonitorStateException() | Constructs an IllegalMonitorStateException with no detail message.
IllegalMonitorStateException(String) | Constructs an IllegalMonitorStateException with the specified detail message.


 IllegalMonitorStateException.IllegalMonitorStateException

IllegalMonitorStateException.IllegalMonitorStateException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public IllegalMonitorStateException()
Description
Constructs an IllegalMonitorStateException with no detail message.

Syntax 2
public IllegalMonitorStateException( String s )
Parameters
s
the detail message.
Description
Constructs an IllegalMonitorStateException with the specified detail message.


 Class IllegalStateException

Class java.lang.IllegalStateException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.lang.RuntimeException
                           |
                           +----java.lang.IllegalStateException

public class IllegalStateException
extends RuntimeException

Signals that a method has been invoked at an illegal or inappropriate time. In other words, the Java environment or Java application is not in an appropriate state for the requested operation.


 IllegalStateException Members

IllegalStateException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
IllegalStateException() | Constructs an IllegalStateException with no detail message.
IllegalStateException(String) | Constructs an IllegalStateException with the specified detail message.


 IllegalStateException.IllegalStateException

IllegalStateException.IllegalStateException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public IllegalStateException()
Description
Constructs an IllegalStateException with no detail message. A detail message is a String that describes this particular exception.

Syntax 2
public IllegalStateException( String s )
Parameters
s
the String that contains a detailed message
Description
Constructs an IllegalStateException with the specified detail message. A detail message is a String that describes this particular exception.


 Class IllegalThreadStateException

Class java.lang.IllegalThreadStateException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.lang.RuntimeException
                           |
                           +----java.lang.IllegalArgumentException
                                   |
                                   +----java.lang.IllegalThreadStateException

public class IllegalThreadStateException
extends IllegalArgumentException

Thrown to indicate that a thread is not in an appropriate state for the requested operation. See, for example, the suspend and resume methods in class Thread.

See Also:
resume, suspend


 IllegalThreadStateException Members

IllegalThreadStateException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
IllegalThreadStateException() | Constructs an IllegalThreadStateException with no detail message.
IllegalThreadStateException(String) | Constructs an IllegalThreadStateException with the specified detail message.


 IllegalThreadStateException.IllegalThreadStateException

IllegalThreadStateException.IllegalThreadStateException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public IllegalThreadStateException()
Description
Constructs an IllegalThreadStateException with no detail message.

Syntax 2
public IllegalThreadStateException( String s )
Parameters
s
the detail message.
Description
Constructs an IllegalThreadStateException with the specified detail message.


 Class IncompatibleClassChangeError

Class java.lang.IncompatibleClassChangeError

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Error
                   |
                   +----java.lang.LinkageError
                           |
                           +----java.lang.IncompatibleClassChangeError

public class IncompatibleClassChangeError
extends LinkageError

Thrown when an incompatible class change has occurred to some class definition. The definition of some class, on which the currently executing method depends, has since changed.


 IncompatibleClassChangeError Members

IncompatibleClassChangeError Members

Class Overview | This Package | All Packages

Constructors
Name | Description
IncompatibleClassChangeError() | Constructs an IncompatibleClassChangeError with no detail message.
IncompatibleClassChangeError(String) | Constructs an IncompatibleClassChangeError with the specified detail message.


 IncompatibleClassChangeError.IncompatibleClassChangeError

IncompatibleClassChangeError.IncompatibleClassChangeError

Class Overview | Class Members | This Package | All Packages

Syntax 1
public IncompatibleClassChangeError()
Description
Constructs an IncompatibleClassChangeError with no detail message.

Syntax 2
public IncompatibleClassChangeError( String s )
Parameters
s
the detail message.
Description
Constructs an IncompatibleClassChangeError with the specified detail message.


 Class IndexOutOfBoundsException

Class java.lang.IndexOutOfBoundsException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.lang.RuntimeException
                           |
                           +----java.lang.IndexOutOfBoundsException

public class IndexOutOfBoundsException
extends RuntimeException

Thrown to indicate that an index of some sort (such as to an array, to a string, or to a vector) is out of range.

Applications can subclass this class to indicate similar exceptions.


 IndexOutOfBoundsException Members

IndexOutOfBoundsException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
IndexOutOfBoundsException() | Constructs an IndexOutOfBoundsException with no detail message.
IndexOutOfBoundsException(String) | Constructs an IndexOutOfBoundsException with the specified detail message.


 IndexOutOfBoundsException.IndexOutOfBoundsException

IndexOutOfBoundsException.IndexOutOfBoundsException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public IndexOutOfBoundsException()
Description
Constructs an IndexOutOfBoundsException with no detail message.

Syntax 2
public IndexOutOfBoundsException( String s )
Parameters
s
the detail message.
Description
Constructs an IndexOutOfBoundsException with the specified detail message.


 Class InstantiationError

Class java.lang.InstantiationError

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Error
                   |
                   +----java.lang.LinkageError
                           |
                           +----java.lang.IncompatibleClassChangeError
                                   |
                                   +----java.lang.InstantiationError

public class InstantiationError
extends IncompatibleClassChangeError

Thrown when an application tries to use the Java new construct to instantiate an abstract class or an interface.

Normally, this error is caught by the compiler; this error can only occur at run time if the definition of a class has incompatibly changed.


 InstantiationError Members

InstantiationError Members

Class Overview | This Package | All Packages

Constructors
Name | Description
InstantiationError() | Constructs an InstantiationError with no detail message.
InstantiationError(String) | Constructs an InstantiationError with the specified detail message.


 InstantiationError.InstantiationError

InstantiationError.InstantiationError

Class Overview | Class Members | This Package | All Packages

Syntax 1
public InstantiationError()
Description
Constructs an InstantiationError with no detail message.

Syntax 2
public InstantiationError( String s )
Parameters
s
the detail message.
Description
Constructs an InstantiationError with the specified detail message.


 Class InstantiationException

Class java.lang.InstantiationException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.lang.InstantiationException

public class InstantiationException
extends Exception

Thrown when an application tries to create an instance of a class using the newInstance method in class Class, but the specified class object cannot be instantiated because it is an interface or is an abstract class.

See Also:
newInstance


 InstantiationException Members

InstantiationException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
InstantiationException() | Constructs an InstantiationException with no detail message.
InstantiationException(String) | Constructs an InstantiationException with the specified detail message.


 InstantiationException.InstantiationException

InstantiationException.InstantiationException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public InstantiationException()
Description
Constructs an InstantiationException with no detail message.

Syntax 2
public InstantiationException( String s )
Parameters
s
the detail message.
Description
Constructs an InstantiationException with the specified detail message.


 Class Integer

Class java.lang.Integer

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Number
           |
           +----java.lang.Integer

public final class Integer
extends Number

The Integer class wraps a value of the primitive type int in an object. An object of type Integer contains a single field whose type is int.

In addition, this class provides several methods for converting an int to a String and a String to an int, as well as other constants and methods useful when dealing with an int.


 Integer Members

Integer Members

Class Overview | This Package | All Packages

Fields
Name | Description
MAX_VALUE | The largest value of type int.
MIN_VALUE | The smallest value of type int.
TYPE | The Class object representing the primitive type int.

Constructors
Name | Description
Integer(int) | Constructs a newly allocated Integer object that represents the primitive int argument.
Integer(String) | Constructs a newly allocated Integer object that represents the value represented by the string.

Methods
Name | Description
byteValue() | Returns the value of this Integer as a byte.
decode(String) | Decodes a string into an Integer.
doubleValue() | Returns the value of this Integer as a double.
equals(Object) | Compares this object to the specified object.
floatValue() | Returns the value of this Integer as a float.
getInteger(String) | Determines the integer value of the system property with the specified name.
getInteger(String, int) | Determines the integer value of the system property with the specified name.
getInteger(String, Integer) | Determines the integer value of the system property with the specified name.
hashCode() | Returns a hashcode for this Integer.
intValue() | Returns the value of this Integer as an int.
longValue() | Returns the value of this Integer as a long.
parseInt(String) | Parses the string argument as a signed decimal integer.
parseInt(String, int) | Parses the string argument as a signed integer in the radix specified by the second argument.
shortValue() | Returns the value of this Integer as a short.
toBinaryString(int) | Creates a string representation of the integer argument as an unsigned integer in base 2.
toHexString(int) | Creates a string representation of the integer argument as an unsigned integer in base 16.
toOctalString(int) | Creates a string representation of the integer argument as an unsigned integer in base 8.
toString() | Returns a String object representing this Integer's value.
toString(int) | Returns a new String object representing the specified integer.
toString(int, int) | Creates a string representation of the first argument in the radix specified by the second argument.
valueOf(String) | Returns a new Integer object initialized to the value of the specified String.
valueOf(String, int) | Returns a new Integer object initialized to the value of the specified String.


 Integer.MAX_VALUE

Integer.MAX_VALUE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int MAX_VALUE
Description
The largest value of type int.


 Integer.MIN_VALUE

Integer.MIN_VALUE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int MIN_VALUE
Description
The smallest value of type int.


 Integer.TYPE

Integer.TYPE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Class TYPE
Description
The Class object representing the primitive type int.


 Integer.Integer

Integer.Integer

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Integer( int value )
Parameters
value
the value to be represented by the Integer.
Description
Constructs a newly allocated Integer object that represents the primitive int argument.

Syntax 2
public Integer( String s ) throws NumberFormatException
Parameters
s
the String to be converted to an Integer.
Description
Constructs a newly allocated Integer object that represents the value represented by the string. The string is converted to an int value as if by the valueOf method.

Exceptions
NumberFormatException if the String does not contain a parsable integer.
See Also
valueOf


 Integer.byteValue

Integer.byteValue

Class Overview | Class Members | This Package | All Packages

Syntax
public byte byteValue()
Description
Returns the value of this Integer as a byte.

Overrides
byteValue in class Number


 Integer.decode

Integer.decode

Class Overview | Class Members | This Package | All Packages

Syntax
public static Integer decode( String nm ) throws NumberFormatException
Parameters
nm
the string to decode
Description
Decodes a string into an Integer. Deals with decimal, hexadecimal, and octal numbers.


 Integer.doubleValue

Integer.doubleValue

Class Overview | Class Members | This Package | All Packages

Syntax
public double doubleValue()
Returns
the int value represented by this object is converted to type double and the result of the conversion is returned.
Description
Returns the value of this Integer as a double.

Overrides
doubleValue in class Number


 Integer.equals

Integer.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Parameters
obj
the object to compare with.
Returns
true if the objects are the same; false otherwise.
Description
Compares this object to the specified object. The result is true if and only if the argument is not null and is an Integer object that contains the same int value as this object.

Overrides
equals in class Object


 Integer.floatValue

Integer.floatValue

Class Overview | Class Members | This Package | All Packages

Syntax
public float floatValue()
Returns
the int value represented by this object is converted to type float and the result of the conversion is returned.
Description
Returns the value of this Integer as a float.

Overrides
floatValue in class Number


 Integer.getInteger

Integer.getInteger

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static Integer getInteger( String nm )
Parameters
nm
property name.
Returns
the Integer value of the property.
Description
Determines the integer value of the system property with the specified name.

The first argument is treated as the name of a system property. System properties are accessible through getProperty and , a method defined by the System class. The string value of this property is then interpreted as an integer value and an Integer object representing this value is returned. Details of possible numeric formats can be found with the definition of getProperty.

If there is no property with the specified name, or if the property does not have the correct numeric format, then null is returned.

See Also
getProperty, getProperty

Syntax 2
public static Integer getInteger( String nm, int val )
Parameters
nm
property name.
val
default value.
Returns
the Integer value of the property.
Description
Determines the integer value of the system property with the specified name.

The first argument is treated as the name of a system property. System properties are accessible through getProperty and , a method defined by the System class. The string value of this property is then interpreted as an integer value and an Integer object representing this value is returned. Details of possible numeric formats can be found with the definition of getProperty.

If there is no property with the specified name, or if the property does not have the correct numeric format, then an Integer object that represents the value of the second argument is returned.

See Also
getProperty, getProperty

Syntax 3
public static Integer getInteger( String nm, Integer val )
Parameters
nm
property name.
val
default value.
Returns
the Integer value of the property.
Description
Determines the integer value of the system property with the specified name.

The first argument is treated as the name of a system property. System properties are accessible through getProperty and , a method defined by the System class. The string value of this property is then interpreted as an integer value and an Integer object representing this value is returned.

If the property value begins with "0x" or "#", not followed by a minus sign, the rest of it is parsed as a hexadecimal integer exactly as for the method Integer.valueOf with radix 16.

If the property value begins with "0" then it is parsed as an octal integer exactly as for the method Integer.valueOf with radix 8.

Otherwise the property value is parsed as a decimal integer exactly as for the method Integer.valueOf with radix 10.

The second argument is the default value. If there is no property of the specified name, or if the property does not have the correct numeric format, then the second argument is returned.

See Also
getProperty, getProperty


 Integer.hashCode

Integer.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int hashCode()
Returns
a hash code value for this object.
Description
Returns a hashcode for this Integer.

Overrides
hashCode in class Object


 Integer.intValue

Integer.intValue

Class Overview | Class Members | This Package | All Packages

Syntax
public int intValue()
Returns
the int value represented by this object.
Description
Returns the value of this Integer as an int.

Overrides
intValue in class Number


 Integer.longValue

Integer.longValue

Class Overview | Class Members | This Package | All Packages

Syntax
public long longValue()
Returns
the int value represented by this object that is converted to type long and the result of the conversion is returned.
Description
Returns the value of this Integer as a long.

Overrides
longValue in class Number


 Integer.parseInt

Integer.parseInt

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static int parseInt( String s, int radix ) throws NumberFormatException
Parameters
s
the String containing the integer.
radix
the radix to be used.
Returns
the integer represented by the string argument in the specified radix.
Description
Parses the string argument as a signed integer in the radix specified by the second argument. The characters in the string must all be digits of the specified radix (as determined by whether Character.digit returns a nonnegative value), except that the first character may be an ASCII minus sign '-' to indicate a negative value. The resulting integer value is returned.

Exceptions
NumberFormatException if the string does not contain a parsable integer.

Syntax 2
public static int parseInt( String s ) throws NumberFormatException
Parameters
s
a string.
Returns
the integer represented by the argument in decimal.
Description
Parses the string argument as a signed decimal integer. The characters in the string must all be decimal digits, except that the first character may be an ASCII minus sign '-' to indicate a negative value.

Exceptions
NumberFormatException if the string does not contain a parsable integer.


 Integer.shortValue

Integer.shortValue

Class Overview | Class Members | This Package | All Packages

Syntax
public short shortValue()
Description
Returns the value of this Integer as a short.

Overrides
shortValue in class Number


 Integer.toBinaryString

Integer.toBinaryString

Class Overview | Class Members | This Package | All Packages

Syntax
public static String toBinaryString( int i )
Parameters
i
an integer.
Returns
the string representation of the unsigned integer value represented by the argument in binary (base 2).
Description
Creates a string representation of the integer argument as an unsigned integer in base 2.

The unsigned integer value is the argument plus 232if the argument is negative; otherwise it is equal to the argument. This value is converted to a string of ASCII digits in binary (base 2) with no extra leading 0s.


 Integer.toHexString

Integer.toHexString

Class Overview | Class Members | This Package | All Packages

Syntax
public static String toHexString( int i )
Parameters
i
an integer.
Returns
the string representation of the unsigned integer value represented by the argument in hexadecimal (base 16).
Description
Creates a string representation of the integer argument as an unsigned integer in base 16.

The unsigned integer value is the argument plus 232 if the argument is negative; otherwise, it is equal to the argument. This value is converted to a string of ASCII digits in hexadecimal (base 16) with no extra leading 0s.


 Integer.toOctalString

Integer.toOctalString

Class Overview | Class Members | This Package | All Packages

Syntax
public static String toOctalString( int i )
Parameters
i
an integer
Returns
the string representation of the unsigned integer value represented by the argument in octal (base&mnsp;8).
Description
Creates a string representation of the integer argument as an unsigned integer in base 8.

The unsigned integer value is the argument plus 232 if the argument is negative; otherwise, it is equal to the argument. This value is converted to a string of ASCII digits in octal (base 8) with no extra leading 0s.


 Integer.toString

Integer.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public static String toString( int i, int radix )
Parameters
i
an integer.
radix
the radix.
Returns
a string representation of the argument in the specified radix.
Description
Creates a string representation of the first argument in the radix specified by the second argument.

If the radix is smaller than Character.MIN_RADIX or larger than Character.MAX_RADIX, then the radix 10 is used instead.

If the first argument is negative, the first element of the result is the ASCII minus character '-'. If the first argument is not negative, no sign character appears in the result. The following ASCII characters are used as digits:

    0123456789abcdefghijklmnopqrstuvwxyz

See Also
MAX_RADIX, MIN_RADIX


 Integer.toString

Integer.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public static String toString( int i )
Parameters
i
an integer to be converted.
Returns
a string representation of the argument in base 10.
Description
Returns a new String object representing the specified integer. The radix is assumed to be 10.


 Integer.toString

Integer.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string representation of the value of this object in base 10.
Description
Returns a String object representing this Integer's value.

Overrides
toString in class Object


 Integer.valueOf

Integer.valueOf

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static Integer valueOf( String s, int radix ) throws NumberFormatException
Parameters
s
the string to be parsed.
Returns
a newly constructed Integer initialized to the value represented by the string argument in the specified radix.
Description
Returns a new Integer object initialized to the value of the specified String. Throws an exception if the String cannot be parsed as an int.

Exceptions
NumberFormatException if the String does not contain a parsable integer.

Syntax 2
public static Integer valueOf( String s ) throws NumberFormatException
Parameters
s
the string to be parsed.
Returns
a newly constructed Integer initialized to the value represented by the string argument.
Description
Returns a new Integer object initialized to the value of the specified String. Throws an exception if the String cannot be parsed as an int. The radix is assumed to be 10.

Exceptions
NumberFormatException if the string does not contain a parsable integer.


 Class InternalError

Class java.lang.InternalError

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Error
                   |
                   +----java.lang.VirtualMachineError
                           |
                           +----java.lang.InternalError

public class InternalError
extends VirtualMachineError

Thrown to indicate some unexpected internal error has occurred in the Java Virtual Machine.


 InternalError Members

InternalError Members

Class Overview | This Package | All Packages

Constructors
Name | Description
InternalError() | Constructs an InternalError with no detail message.
InternalError(String) | Constructs an InternalError with the specified detail message.


 InternalError.InternalError

InternalError.InternalError

Class Overview | Class Members | This Package | All Packages

Syntax 1
public InternalError()
Description
Constructs an InternalError with no detail message.

Syntax 2
public InternalError( String s )
Parameters
s
the detail message.
Description
Constructs an InternalError with the specified detail message.


 Class InterruptedException

Class java.lang.InterruptedException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.lang.InterruptedException

public class InterruptedException
extends Exception

Thrown when a thread is waiting, sleeping, or otherwise paused for a long time and another thread interrupts it using the interrupt method in class Thread.

See Also:
wait, wait, wait, sleep, interrupt, interrupted


 InterruptedException Members

InterruptedException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
InterruptedException() | Constructs an InterruptedException with no detail message.
InterruptedException(String) | Constructs an InterruptedException with the specified detail message.


 InterruptedException.InterruptedException

InterruptedException.InterruptedException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public InterruptedException()
Description
Constructs an InterruptedException with no detail message.

Syntax 2
public InterruptedException( String s )
Parameters
s
the detail message.
Description
Constructs an InterruptedException with the specified detail message.


 Class LinkageError

Class java.lang.LinkageError

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Error
                   |
                   +----java.lang.LinkageError

public class LinkageError
extends Error

Subclasses of LinkageError indicate that a class has some dependency on another class; however, the latter class has incompatibly changed after the compilation of the former class.


 LinkageError Members

LinkageError Members

Class Overview | This Package | All Packages

Constructors
Name | Description
LinkageError() | Constructs a LinkageError with no detail message.
LinkageError(String) | Constructs a LinkageError with the specified detail message.


 LinkageError.LinkageError

LinkageError.LinkageError

Class Overview | Class Members | This Package | All Packages

Syntax 1
public LinkageError()
Description
Constructs a LinkageError with no detail message.

Syntax 2
public LinkageError( String s )
Parameters
s
the detail message.
Description
Constructs a LinkageError with the specified detail message.


 Class Long

Class java.lang.Long

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Number
           |
           +----java.lang.Long

public final class Long
extends Number

The Long class wraps a value of the primitive type long in an object. An object of type Long contains a single field whose type is long.

In addition, this class provides several methods for converting a long to a String and a String to a long, as well as other constants and methods useful when dealing with a long.


 Long Members

Long Members

Class Overview | This Package | All Packages

Fields
Name | Description
MAX_VALUE | The largest value of type long.
MIN_VALUE | The smallest value of type long.
TYPE | The Class object representing the primitive type long.

Constructors
Name | Description
Long(long) | Constructs a newly allocated Long object that represents the primitive long argument.
Long(String) | Constructs a newly allocated Long object that represents the value represented by the string.

Methods
Name | Description
byteValue() | Returns the value of this Long as a byte.
doubleValue() | Returns the value of this Long as a double.
equals(Object) | Compares this object against the specified object.
floatValue() | Returns the value of this Long as a float.
getLong(String) | Determines the long value of the system property with the specified name.
getLong(String, Long) | Determines the long value of the system property with the specified name.
getLong(String, long) | Determines the long value of the system property with the specified name.
hashCode() | Computes a hashcode for this Long.
intValue() | Returns the value of this Long as an int.
longValue() | Returns the value of this Long as a long.
parseLong(String) | Parses the string argument as a signed decimal long.
parseLong(String, int) | Parses the string argument as a signed long in the radix specified by the second argument.
shortValue() | Returns the value of this Long as a short.
toBinaryString(long) | Creates a string representation of the long argument as an unsigned integer in base 2.
toHexString(long) | Creates a string representation of the long argument as an unsigned integer in base 16.
toOctalString(long) | Creates a string representation of the long argument as an unsigned integer in base 8.
toString() | Returns a String object representing this Long's value.
toString(long) | Returns a new String object representing the specified integer.
toString(long, int) | Creates a string representation of the first argument in the radix specified by the second argument.
valueOf(String) | Returns a new long object initialized to the value of the specified String.
valueOf(String, int) | Returns a new long object initialized to the value of the specified String.


 Long.MAX_VALUE

Long.MAX_VALUE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final long MAX_VALUE
Description
The largest value of type long.


 Long.MIN_VALUE

Long.MIN_VALUE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final long MIN_VALUE
Description
The smallest value of type long.


 Long.TYPE

Long.TYPE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Class TYPE
Description
The Class object representing the primitive type long.


 Long.Long

Long.Long

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Long( long value )
Parameters
value
the value to be represented by the Long.
Description
Constructs a newly allocated Long object that represents the primitive long argument.

Syntax 2
public Long( String s ) throws NumberFormatException
Parameters
s
the string to be converted to a Long.
Description
Constructs a newly allocated Long object that represents the value represented by the string. The string is converted to an long value as if by the valueOf method.

Exceptions
NumberFormatException if the String does not contain a parsable long integer.
See Also
valueOf


 Long.byteValue

Long.byteValue

Class Overview | Class Members | This Package | All Packages

Syntax
public byte byteValue()
Description
Returns the value of this Long as a byte.

Overrides
byteValue in class Number


 Long.doubleValue

Long.doubleValue

Class Overview | Class Members | This Package | All Packages

Syntax
public double doubleValue()
Returns
the long value represented by this object that is converted to type double and the result of the conversion is returned.
Description
Returns the value of this Long as a double.

Overrides
doubleValue in class Number


 Long.equals

Long.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Parameters
obj
the object to compare with.
Returns
true if the objects are the same; false otherwise.
Description
Compares this object against the specified object. The result is true if and only if the argument is not null and is a Long object that contains the same long value as this object.

Overrides
equals in class Object


 Long.floatValue

Long.floatValue

Class Overview | Class Members | This Package | All Packages

Syntax
public float floatValue()
Returns
the long value represented by this object is converted to type float and the result of the conversion is returned.
Description
Returns the value of this Long as a float.

Overrides
floatValue in class Number


 Long.getLong

Long.getLong

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static Long getLong( String nm )
Parameters
nm
property name.
Returns
the Long value of the property.
Description
Determines the long value of the system property with the specified name.

The first argument is treated as the name of a system property. System properties are accessible through getProperty and , a method defined by the System class. The string value of this property is then interpreted as a long value and a Long object representing this value is returned. Details of possible numeric formats can be found with the definition of getProperty.

If there is no property with the specified name, or if the property does not have the correct numeric format, then null is returned.

See Also
getProperty, getProperty

Syntax 2
public static Long getLong( String nm, long val )
Parameters
nm
property name.
val
default value.
Returns
the Long value of the property.
Description
Determines the long value of the system property with the specified name.

The first argument is treated as the name of a system property. System properties are accessible through getProperty and , a method defined by the System class. The string value of this property is then interpreted as a long value and a Long object representing this value is returned. Details of possible numeric formats can be found with the definition of getProperty.

If there is no property with the specified name, or if the property does not have the correct numeric format, then a Long object that represents the value of the second argument is returned.

See Also
getProperty, getProperty

Syntax 3
public static Long getLong( String nm, Long val )
Parameters
nm
the property name.
val
the default Long value.
Returns
the long value of the property.
Description
Determines the long value of the system property with the specified name.

The first argument is treated as the name of a system property. System properties are accessible through getProperty and , a method defined by the System class. The string value of this property is then interpreted as a long value and a Long object representing this value is returned.

If the property value begins with "0x" or "#", not followed by a minus sign, the rest of it is parsed as a hexadecimal integer exactly as for the method Long.valueOf with radix 16.

If the property value begins with "0", then it is parsed as an octal integer exactly as for the method Long.valueOf with radix 8.

Otherwise the property value is parsed as a decimal integer exactly as for the method Long.valueOf with radix 10.

Note that, in every case, neither L nor l is permitted to appear at the end of the string.

The second argument is the default value. If there is no property of the specified name, or if the property does not have the correct numeric format, then the second argument is returned.

See Also
valueOf, getProperty, getProperty


 Long.hashCode

Long.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int hashCode()
Returns
a hash code value for this object.
Description
Computes a hashcode for this Long.

Overrides
hashCode in class Object


 Long.intValue

Long.intValue

Class Overview | Class Members | This Package | All Packages

Syntax
public int intValue()
Returns
the long value represented by this object is converted to type int and the result of the conversion is returned.
Description
Returns the value of this Long as an int.

Overrides
intValue in class Number


 Long.longValue

Long.longValue

Class Overview | Class Members | This Package | All Packages

Syntax
public long longValue()
Returns
the long value represented by this object.
Description
Returns the value of this Long as a long.

Overrides
longValue in class Number


 Long.parseLong

Long.parseLong

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static long parseLong( String s, int radix ) throws NumberFormatException
Parameters
s
the String containing the long.
radix
the radix to be used.
Returns
the long represented by the string argument in the specified radix.
Description
Parses the string argument as a signed long in the radix specified by the second argument. The characters in the string must all be digits of the specified radix (as determined by whether Character.digit returns a nonnegative value), except that the first character may be an ASCII minus sign '-' to indicate a negative value. The resulting long value is returned.

Exceptions
NumberFormatException if the string does not contain a parsable integer.

Syntax 2
public static long parseLong( String s ) throws NumberFormatException
Parameters
s
a string.
Returns
the long represented by the argument in decimal.
Description
Parses the string argument as a signed decimal long. The characters in the string must all be decimal digits, except that the first character may be an ASCII minus sign '-' to indicate a negative value.

Exceptions
NumberFormatException if the string does not contain a parsable long.


 Long.shortValue

Long.shortValue

Class Overview | Class Members | This Package | All Packages

Syntax
public short shortValue()
Description
Returns the value of this Long as a short.

Overrides
shortValue in class Number


 Long.toBinaryString

Long.toBinaryString

Class Overview | Class Members | This Package | All Packages

Syntax
public static String toBinaryString( long i )
Parameters
i
a long.
Returns
the string representation of the unsigned long value represented by the argument in binary (base 2).
Description
Creates a string representation of the long argument as an unsigned integer in base 2.

The unsigned long value is the argument plus 264 if the argument is negative; otherwise, it is equal to the argument. This value is converted to a string of ASCII digits in binary (base 2) with no extra leading 0s.


 Long.toHexString

Long.toHexString

Class Overview | Class Members | This Package | All Packages

Syntax
public static String toHexString( long i )
Parameters
i
a long.
Returns
the string representation of the unsigned long value represented by the argument in hexadecimal (base 16).
Description
Creates a string representation of the long argument as an unsigned integer in base 16.

The unsigned long value is the argument plus 264 if the argument is negative; otherwise, it is equal to the argument. This value is converted to a string of ASCII digits in hexadecimal (base 16) with no extra leading 0s.


 Long.toOctalString

Long.toOctalString

Class Overview | Class Members | This Package | All Packages

Syntax
public static String toOctalString( long i )
Parameters
i
a long.
Returns
the string representation of the unsigned long value represented by the argument in octal (base 8).
Description
Creates a string representation of the long argument as an unsigned integer in base 8.

The unsigned long value is the argument plus 264 if the argument is negative; otherwise, it is equal to the argument. This value is converted to a string of ASCII digits in octal (base 8) with no extra leading 0s.


 Long.toString

Long.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public static String toString( long i, int radix )
Parameters
i
a long.
radix
the radix.
Returns
a string representation of the argument in the specified radix.
Description
Creates a string representation of the first argument in the radix specified by the second argument.

If the radix is smaller than Character.MIN_RADIX or larger than Character.MAX_RADIX, then the radix 10 is used instead.

If the first argument is negative, the first element of the result is the ASCII minus sign '-'. If the first argument is not negative, no sign character appears in the result. The following ASCII characters are used as digits:

    0123456789abcdefghijklmnopqrstuvwxyz

See Also
MAX_RADIX, MIN_RADIX


 Long.toString

Long.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public static String toString( long i )
Parameters
i
a long to be converted.
Returns
a string representation of the argument in base 10.
Description
Returns a new String object representing the specified integer. The radix is assumed to be 10.


 Long.toString

Long.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string representation of this object in base 10.
Description
Returns a String object representing this Long's value.

Overrides
toString in class Object


 Long.valueOf

Long.valueOf

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static Long valueOf( String s, int radix ) throws NumberFormatException
Parameters
s
the String containing the long.
radix
the radix to be used.
Returns
a newly constructed Long initialized to the value represented by the string argument in the specified radix.
Description
Returns a new long object initialized to the value of the specified String. Throws an exception if the String cannot be parsed as a long.

Exceptions
NumberFormatException If the String does not contain a parsable long.

Syntax 2
public static Long valueOf( String s ) throws NumberFormatException
Parameters
s
the string to be parsed.
Returns
a newly constructed Long initialized to the value represented by the string argument.
Description
Returns a new long object initialized to the value of the specified String. Throws an exception if the String cannot be parsed as a long. The radix is assumed to be 10.

Exceptions
NumberFormatException If the String does not contain a parsable long.


 Class Math

Class java.lang.Math

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Math

public final class Math
extends Object

The class Math contains methods for performing basic numeric operations such as the elementary exponential, logarithm, square root, and trigonometric functions.

To help ensure portability of Java programs, the definitions of many of the numeric functions in this package require that they produce the same results as certain published algorithms. These algorithms are available from the well-known network library netlib as the package "Freely Distributable Math Library" (fdlibm). These algorithms, which are written in the C programming language, are then to be understood as executed with all floating-point operations following the rules of Java floating-point arithmetic.

The network library may be found on the World Wide Web at

    http://netlib.att.com/

then perform a keyword search for "fdlibm".

The Java math library is defined with respect to the version of fdlibm dated January 4, 1995. Where fdlibm provides more than one definition for a function (such as acos), use the "IEEE 754 core function" version (residing in a file whose name begins with the letter e).


 Math Members

Math Members

Class Overview | This Package | All Packages

Fields
Name | Description
E | The double value that is closer than any other to e, the base of the natural logarithms.
PI | The double value that is closer than any other to pi, the ratio of the circumference of a circle to its diameter.

Methods
Name | Description
abs(double) | Returns the absolute value of a double value.
abs(float) | Returns the absolute value of a float value.
abs(int) | Returns the absolute value of an int value.
abs(long) | Returns the absolute value of a long value.
acos(double) | Returns the arc cosine of an angle, in the range of 0.0 through pi.
asin(double) | Returns the arc sine of an angle, in the range of -pi/2 through pi/2.
atan(double) | Returns the arc tangent of an angle, in the range of -pi/2 through pi/2.
atan2(double, double) | Converts rectangular coordinates (b, a) to polar (r, theta).
ceil(double) | Returns the smallest (closest to negative infinity) double value that is not less than the argument and is equal to a mathematical integer.
cos(double) | Returns the trigonometric cosine of an angle.
exp(double) | Returns the exponential number e (i.e., 2.718...) raised to the power of a double value.
floor(double) | Returns the largest (closest to positive infinity) double value that is not greater than the argument and is equal to a mathematical integer.
IEEEremainder(double, double) | Computes the remainder operation on two arguments as prescribed by the IEEE 754 standard.
log(double) | Returns the natural logarithm (base e) of a double value.
max(double, double) | Returns the greater of two double values.
max(float, float) | Returns the greater of two float values.
max(int, int) | Returns the greater of two int values.
max(long, long) | Returns the greater of two long values.
min(double, double) | Returns the smaller of two double values.
min(float, float) | Returns the smaller of two float values.
min(int, int) | Returns the smaller of two int values.
min(long, long) | Returns the smaller of two long values.
pow(double, double) | Returns of value of the first argument raised to the power of the second argument.
random() | Returns a random number between 0.0 and 1.0.
rint(double) | returns the closest integer to the argument.
round(double) | Returns the closest long to the argument.
round(float) | Returns the closest int to the argument.
sin(double) | Returns the trigonometric sine of an angle.
sqrt(double) | Returns the square root of a double value.
tan(double) | Returns the trigonometric tangent of an angle.


 Math.E

Math.E

Class Overview | Class Members | This Package | All Packages

Syntax
public static final double E
Description
The double value that is closer than any other to e, the base of the natural logarithms.


 Math.PI

Math.PI

Class Overview | Class Members | This Package | All Packages

Syntax
public static final double PI
Description
The double value that is closer than any other to pi, the ratio of the circumference of a circle to its diameter.


 Math.abs

Math.abs

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static int abs( int a )
Parameters
a
an int value.
Returns
the absolute value of the argument.
Description
Returns the absolute value of an int value. If the argument is not negative, the argument is returned. If the argument is negative, the negation of the argument is returned.

Note that if the argument is equal to the value of Integer.MIN_VALUE, the most negative representable int value, the result is that same value, which is negative.

See Also
MIN_VALUE

Syntax 2
public static long abs( long a )
Parameters
a
a long value.
Returns
the absolute value of the argument.
Description
Returns the absolute value of a long value. If the argument is not negative, the argument is returned. If the argument is negative, the negation of the argument is returned.

Note that if the argument is equal to the value of Long.MIN_VALUE, the most negative representable long value, the result is that same value, which is negative.

See Also
MIN_VALUE

Syntax 3
public static float abs( float a )
Parameters
a
a float value.
Returns
the absolute value of the argument.
Description
Returns the absolute value of a float value. If the argument is not negative, the argument is returned. If the argument is negative, the negation of the argument is returned.

Syntax 4
public static double abs( double a )
Parameters
a
a double value.
Returns
the absolute value of the argument.
Description
Returns the absolute value of a double value. If the argument is not negative, the argument is returned. If the argument is negative, the negation of the argument is returned.


 Math.acos

Math.acos

Class Overview | Class Members | This Package | All Packages

Syntax
public static native double acos( double a )
Parameters
a
an angle, in radians.
Returns
the arc cosine of the argument.
Description
Returns the arc cosine of an angle, in the range of 0.0 through pi.


 Math.asin

Math.asin

Class Overview | Class Members | This Package | All Packages

Syntax
public static native double asin( double a )
Parameters
a
an angle, in radians.
Returns
the arc sine of the argument.
Description
Returns the arc sine of an angle, in the range of -pi/2 through pi/2.


 Math.atan

Math.atan

Class Overview | Class Members | This Package | All Packages

Syntax
public static native double atan( double a )
Parameters
a
an angle, in radians.
Returns
the arc tangent of the argument.
Description
Returns the arc tangent of an angle, in the range of -pi/2 through pi/2.


 Math.atan2

Math.atan2

Class Overview | Class Members | This Package | All Packages

Syntax
public static native double atan2( double a, double b )
Parameters
a
a double value.
b
a double value.
Returns
the theta component of the point (r, theta) in polar coordinates that corresponds to the point (b, a) in Cartesian coordinates.
Description
Converts rectangular coordinates (b, a) to polar (r, theta). This method computes the phase theta by computing an arc tangent of b/a in the range of -pi to pi.


 Math.ceil

Math.ceil

Class Overview | Class Members | This Package | All Packages

Syntax
public static native double ceil( double a )
Parameters
a
a double value.
Returns
the smallest (closest to negative infinity) double value that is not less than the argument and is equal to a mathematical integer.
Description
Returns the smallest (closest to negative infinity) double value that is not less than the argument and is equal to a mathematical integer.


 Math.cos

Math.cos

Class Overview | Class Members | This Package | All Packages

Syntax
public static native double cos( double a )
Parameters
a
an angle, in radians.
Returns
the cosine of the argument.
Description
Returns the trigonometric cosine of an angle.


 Math.exp

Math.exp

Class Overview | Class Members | This Package | All Packages

Syntax
public static native double exp( double a )
Parameters
a
a double value.
Returns
the value ea, where e is the base of the natural logarithms.
Description
Returns the exponential number e (i.e., 2.718...) raised to the power of a double value.


 Math.floor

Math.floor

Class Overview | Class Members | This Package | All Packages

Syntax
public static native double floor( double a )
Parameters
a
a double value.
a
an assigned value.
Returns
the largest (closest to positive infinity) double value that is not greater than the argument and is equal to a mathematical integer.
Description
Returns the largest (closest to positive infinity) double value that is not greater than the argument and is equal to a mathematical integer.


 Math.IEEEremainder

Math.IEEEremainder

Class Overview | Class Members | This Package | All Packages

Syntax
public static native double IEEEremainder( double f1, double f2 )
Parameters
f1
the dividend.
f2
the divisor.
Returns
the remainder when f1 is divided by f2.
Description
Computes the remainder operation on two arguments as prescribed by the IEEE 754 standard. The remainder value is mathematically equal to f1 - f2 × n, where n is the mathematical integer closest to the exact mathematical value of the quotient f1/f2, and if two mathematical integers are equally close to f1/f2, then n is the integer that is even. If the remainder is zero, its sign is the same as the sign of the first argument.


 Math.log

Math.log

Class Overview | Class Members | This Package | All Packages

Syntax
public static native double log( double a )
Parameters
a
a number greater than 0.0.
Returns
the value ln a, the natural logarithm of a.
Description
Returns the natural logarithm (base e) of a double value.


 Math.max

Math.max

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static int max( int a, int b )
Parameters
a
an int value.
b
an int value.
Returns
the larger of a and b.
Description
Returns the greater of two int values.

Syntax 2
public static long max( long a, long b )
Parameters
a
a long value.
b
a long value.
Returns
the larger of a and b.
Description
Returns the greater of two long values.

Syntax 3
public static float max( float a, float b )
Parameters
a
a float value.
b
a float value.
Returns
the larger of a and b.
Description
Returns the greater of two float values. If either value is NaN, then the result is NaN. Unlike the the numerical comparison operators, this method considers negative zero to be strictly smaller than positive zero.

Syntax 4
public static double max( double a, double b )
Parameters
a
a double value.
b
a double value.
Returns
the larger of a and b.
Description
Returns the greater of two double values. If either value is NaN, then the result is NaN. Unlike the the numerical comparison operators, this method considers negative zero to be strictly smaller than positive zero.


 Math.min

Math.min

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static int min( int a, int b )
Parameters
a
an int value.
b
an int value.
Returns
the smaller of a and b.
Description
Returns the smaller of two int values.

Syntax 2
public static long min( long a, long b )
Parameters
a
a long value.
b
a long value.
Returns
the smaller of a and b.
Description
Returns the smaller of two long values.

Syntax 3
public static float min( float a, float b )
Parameters
a
a float value.
b
a float value.
Returns
the smaller of a and b.
Description
Returns the smaller of two float values. If either value is NaN, then the result is NaN. Unlike the the numerical comparison operators, this method considers negative zero to be strictly smaller than positive zero.

Syntax 4
public static double min( double a, double b )
Parameters
a
a double value.
b
a double value.
Returns
the smaller of a and b.
Description
Returns the smaller of two double values. If either value is NaN, then the result is NaN. Unlike the the numerical comparison operators, this method considers negative zero to be strictly smaller than positive zero.


 Math.pow

Math.pow

Class Overview | Class Members | This Package | All Packages

Syntax
public static native double pow( double a, double b )
Parameters
a
a double value.
b
a double value.
Returns
the value ab.
Description
Returns of value of the first argument raised to the power of the second argument.

If (a == 0.0), then b must be greater than 0.0; otherwise an exception is thrown. An exception also will occur if (a <= 0.0) and b is not equal to a whole number.

Exceptions
ArithmeticException if (a == 0.0) and (b <= 0.0), or if (a <= 0.0) and b is not equal to a whole number.


 Math.random

Math.random

Class Overview | Class Members | This Package | All Packages

Syntax
public static synchronized double random()
Returns
a pseudorandom double between 0.0 and 1.0.
Description
Returns a random number between 0.0 and 1.0. Random number generators are often referred to as pseudorandom number generators because the numbers produced tend to repeat themselves after a period of time.

See Also
nextDouble


 Math.rint

Math.rint

Class Overview | Class Members | This Package | All Packages

Syntax
public static native double rint( double a )
Parameters
a
a double value.
Returns
the closest double value to a that is equal to a mathematical integer. If two double values that are mathematical integers are equally close to the value of the argument, the result is the integer value that is even.
Description
returns the closest integer to the argument.


 Math.round

Math.round

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static int round( float a )
Parameters
a
a float value.
Returns
the value of the argument rounded to the nearest int value.
Description
Returns the closest int to the argument.

If the argument is negative infinity or any value less than or equal to the value of Integer.MIN_VALUE, the result is equal to the value of Integer.MIN_VALUE.

If the argument is positive infinity or any value greater than or equal to the value of Integer.MAX_VALUE, the result is equal to the value of Integer.MAX_VALUE.

See Also
MAX_VALUE, MIN_VALUE

Syntax 2
public static long round( double a )
Parameters
a
a double value.
Returns
the value of the argument rounded to the nearest long value.
Description
Returns the closest long to the argument.

If the argument is negative infinity or any value less than or equal to the value of Long.MIN_VALUE, the result is equal to the value of Long.MIN_VALUE.

If the argument is positive infinity or any value greater than or equal to the value of Long.MAX_VALUE, the result is equal to the value of Long.MAX_VALUE.

See Also
MAX_VALUE, MIN_VALUE


 Math.sin

Math.sin

Class Overview | Class Members | This Package | All Packages

Syntax
public static native double sin( double a )
Parameters
a
an angle, in radians.
Returns
the sine of the argument.
Description
Returns the trigonometric sine of an angle.


 Math.sqrt

Math.sqrt

Class Overview | Class Members | This Package | All Packages

Syntax
public static native double sqrt( double a )
Parameters
a
a double value.
Returns
the square root of a. If the argument is NaN or less than zero, the result is NaN.
Description
Returns the square root of a double value.


 Math.tan

Math.tan

Class Overview | Class Members | This Package | All Packages

Syntax
public static native double tan( double a )
Parameters
a
an angle, in radians.
Returns
the tangent of the argument.
Description
Returns the trigonometric tangent of an angle.


 Class NegativeArraySizeException

Class java.lang.NegativeArraySizeException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.lang.RuntimeException
                           |
                           +----java.lang.NegativeArraySizeException

public class NegativeArraySizeException
extends RuntimeException

Thrown if an application tries to create an array with negative size.


 NegativeArraySizeException Members

NegativeArraySizeException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
NegativeArraySizeException() | Constructs a NegativeArraySizeException with no detail message.
NegativeArraySizeException(String) | Constructs a NegativeArraySizeException with the specified detail message.


 NegativeArraySizeException.NegativeArraySizeException

NegativeArraySizeException.NegativeArraySizeException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public NegativeArraySizeException()
Description
Constructs a NegativeArraySizeException with no detail message.

Syntax 2
public NegativeArraySizeException( String s )
Parameters
s
the detail message.
Description
Constructs a NegativeArraySizeException with the specified detail message.


 Class NoClassDefFoundError

Class java.lang.NoClassDefFoundError

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Error
                   |
                   +----java.lang.LinkageError
                           |
                           +----java.lang.NoClassDefFoundError

public class NoClassDefFoundError
extends LinkageError

Thrown if the Java Virtual Machine or a classloader tries to load in the definition of a class (as part of a normal method call or as part of creating a new instance using the new expression) and no definition of the class could be found.

The searched-for class definition existed when the currently executing class was compiled, but the definition can no longer be found.


 NoClassDefFoundError Members

NoClassDefFoundError Members

Class Overview | This Package | All Packages

Constructors
Name | Description
NoClassDefFoundError() | Constructs a NoClassDefFoundError with no detail message.
NoClassDefFoundError(String) | Constructs a NoClassDefFoundError with the specified detail message.


 NoClassDefFoundError.NoClassDefFoundError

NoClassDefFoundError.NoClassDefFoundError

Class Overview | Class Members | This Package | All Packages

Syntax 1
public NoClassDefFoundError()
Description
Constructs a NoClassDefFoundError with no detail message.

Syntax 2
public NoClassDefFoundError( String s )
Parameters
s
the detail message.
Description
Constructs a NoClassDefFoundError with the specified detail message.


 Class NoSuchFieldError

Class java.lang.NoSuchFieldError

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Error
                   |
                   +----java.lang.LinkageError
                           |
                           +----java.lang.IncompatibleClassChangeError
                                   |
                                   +----java.lang.NoSuchFieldError

public class NoSuchFieldError
extends IncompatibleClassChangeError

Thrown if an application tries to access or modify a specified field of an object, and that object no longer has that field.

Normally, this error is caught by the compiler; this error can only occur at run time if the definition of a class has incompatibly changed.


 NoSuchFieldError Members

NoSuchFieldError Members

Class Overview | This Package | All Packages

Constructors
Name | Description
NoSuchFieldError() | Constructs a NoSuchFieldException with no detail message.
NoSuchFieldError(String) | Constructs a NoSuchFieldException with the specified detail message.


 NoSuchFieldError.NoSuchFieldError

NoSuchFieldError.NoSuchFieldError

Class Overview | Class Members | This Package | All Packages

Syntax 1
public NoSuchFieldError()
Description
Constructs a NoSuchFieldException with no detail message.

Syntax 2
public NoSuchFieldError( String s )
Parameters
s
the detail message.
Description
Constructs a NoSuchFieldException with the specified detail message.


 Class NoSuchFieldException

Class java.lang.NoSuchFieldException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.lang.NoSuchFieldException

public class NoSuchFieldException
extends Exception

Signals that the class doesn't have a field of a specified name.


 NoSuchFieldException Members

NoSuchFieldException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
NoSuchFieldException() | Constructor.
NoSuchFieldException(String) | Constructor with a detail message.


 NoSuchFieldException.NoSuchFieldException

NoSuchFieldException.NoSuchFieldException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public NoSuchFieldException()
Description
Constructor.

Syntax 2
public NoSuchFieldException( String s )
Description
Constructor with a detail message.


 Class NoSuchMethodError

Class java.lang.NoSuchMethodError

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Error
                   |
                   +----java.lang.LinkageError
                           |
                           +----java.lang.IncompatibleClassChangeError
                                   |
                                   +----java.lang.NoSuchMethodError

public class NoSuchMethodError
extends IncompatibleClassChangeError

Thrown if an application tries to call a specified method of a class (either static or instance), and that class no longer has a definition of that method.

Normally, this error is caught by the compiler; this error can only occur at run time if the definition of a class has incompatibly changed.


 NoSuchMethodError Members

NoSuchMethodError Members

Class Overview | This Package | All Packages

Constructors
Name | Description
NoSuchMethodError() |
NoSuchMethodError(String) | Constructs a NoSuchMethodException with the specified detail message.


 NoSuchMethodError.NoSuchMethodError

NoSuchMethodError.NoSuchMethodError

Class Overview | Class Members | This Package | All Packages

Syntax 1
public NoSuchMethodError()

Syntax 2
public NoSuchMethodError( String s )
Parameters
s
the detail message.
Description
Constructs a NoSuchMethodException with the specified detail message.


 Class NoSuchMethodException

Class java.lang.NoSuchMethodException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.lang.NoSuchMethodException

public class NoSuchMethodException
extends Exception

Thrown when a particular method cannot be found.


 NoSuchMethodException Members

NoSuchMethodException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
NoSuchMethodException() | Constructs a NoSuchMethodException without a detail message.
NoSuchMethodException(String) | Constructs a NoSuchMethodException with a detail message.


 NoSuchMethodException.NoSuchMethodException

NoSuchMethodException.NoSuchMethodException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public NoSuchMethodException()
Description
Constructs a NoSuchMethodException without a detail message.

Syntax 2
public NoSuchMethodException( String s )
Parameters
s
the detail message.
Description
Constructs a NoSuchMethodException with a detail message.


 Class NullPointerException

Class java.lang.NullPointerException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.lang.RuntimeException
                           |
                           +----java.lang.NullPointerException

public class NullPointerException
extends RuntimeException

Thrown when an application attempts to use null in a case where an object is required. These include:

  • Calling the instance method of a null object.
  • Accessing or modifying the field of a null object.
  • Taking the length of null as if it were an array.
  • Accessing or modifying the slots of null as if it were an array.
  • Throwing null as if it were a Throwable value.

Applications should throw instances of this class to indicate other illegal uses of the null object.


 NullPointerException Members

NullPointerException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
NullPointerException() | Constructs a NullPointerException with no detail message.
NullPointerException(String) | Constructs a NullPointerException with the specified detail message.


 NullPointerException.NullPointerException

NullPointerException.NullPointerException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public NullPointerException()
Description
Constructs a NullPointerException with no detail message.

Syntax 2
public NullPointerException( String s )
Parameters
s
the detail message.
Description
Constructs a NullPointerException with the specified detail message.


 Class Number

Class java.lang.Number

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Number

public abstract class Number
extends Object
implements Serializable

The abstract class Number is the superclass of classes Byte, Double, Float, Integer, Long, and Short.

Subclasses of Number must provide methods to convert the represented numeric value to byte, double, float, int, long, and short.

See Also:
Byte, Double, Float, Integer, Long, Short


 Number Members

Number Members

Class Overview | This Package | All Packages

Constructors
Name | Description
Number() |

Methods
Name | Description
byteValue() | Returns the value of the specified number as a byte.
doubleValue() | Returns the value of the specified number as a double.
floatValue() | Returns the value of the specified number as a float.
intValue() | Returns the value of the specified number as an int.
longValue() | Returns the value of the specified number as a long.
shortValue() | Returns the value of the specified number as a short.


 Number.Number

Number.Number

Class Overview | Class Members | This Package | All Packages

Syntax
public Number()


 Number.byteValue

Number.byteValue

Class Overview | Class Members | This Package | All Packages

Syntax
public byte byteValue()
Returns
the numeric value represented by this object after conversion to type byte.
Description
Returns the value of the specified number as a byte. This may involve rounding or truncation.


 Number.doubleValue

Number.doubleValue

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract double doubleValue()
Returns
the numeric value represented by this object after conversion to type double.
Description
Returns the value of the specified number as a double. This may involve rounding.


 Number.floatValue

Number.floatValue

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract float floatValue()
Returns
the numeric value represented by this object after conversion to type float.
Description
Returns the value of the specified number as a float. This may involve rounding.


 Number.intValue

Number.intValue

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract int intValue()
Returns
the numeric value represented by this object after conversion to type int.
Description
Returns the value of the specified number as an int. This may involve rounding.


 Number.longValue

Number.longValue

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract long longValue()
Returns
the numeric value represented by this object after conversion to type long.
Description
Returns the value of the specified number as a long. This may involve rounding.


 Number.shortValue

Number.shortValue

Class Overview | Class Members | This Package | All Packages

Syntax
public short shortValue()
Returns
the numeric value represented by this object after conversion to type short.
Description
Returns the value of the specified number as a short. This may involve rounding or truncation.


 Class NumberFormatException

Class java.lang.NumberFormatException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.lang.RuntimeException
                           |
                           +----java.lang.IllegalArgumentException
                                   |
                                   +----java.lang.NumberFormatException

public class NumberFormatException
extends IllegalArgumentException

Thrown to indicate that the application has attempted to convert a string to one of the numeric types, but that the string does not have the appropriate format.

See Also:
toString


 NumberFormatException Members

NumberFormatException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
NumberFormatException() | Constructs a NumberFormatException with no detail message.
NumberFormatException(String) | Constructs a NumberFormatException with the specified detail message.


 NumberFormatException.NumberFormatException

NumberFormatException.NumberFormatException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public NumberFormatException()
Description
Constructs a NumberFormatException with no detail message.

Syntax 2
public NumberFormatException( String s )
Parameters
s
the detail message.
Description
Constructs a NumberFormatException with the specified detail message.


 Class Object

Class java.lang.Object

Class Members | This Package | All Packages
java.lang.Object

public class Object

Class Object is the root of the class hierarchy. Every class has Object as a superclass. All objects, including arrays, implement the methods of this class.

See Also:
Class


 Object Members

Object Members

Class Overview | This Package | All Packages

Constructors
Name | Description
Object() |

Methods
Name | Description
clone() | Creates a new object of the same class as this object.
equals(Object) | Compares two Objects for equality.
finalize() | Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
getClass() | Returns the runtime class of an object.
hashCode() | Returns a hash code value for the object.
notify() | Wakes up a single thread that is waiting on this object's monitor.
notifyAll() | Wakes up all threads that are waiting on this object's monitor.
toString() | Returns a string representation of the object.
wait() | Waits to be notified by another thread of a change in this object.
wait(long) | Waits to be notified by another thread of a change in this object.
wait(long, int) | Waits to be notified by another thread of a change in this object.


 Object.Object

Object.Object

Class Overview | Class Members | This Package | All Packages

Syntax
public Object()


 Object.clone

Object.clone

Class Overview | Class Members | This Package | All Packages

Syntax
protected native Object clone() throws CloneNotSupportedException
Returns
a clone of this instance.
Description
Creates a new object of the same class as this object. It then initializes each of the new object's fields by assigning it the same value as the corresponding field in this object. No constructor is called.

The clone method of class Object will only clone an object whose class indicates that it is willing for its instances to be cloned. A class indicates that its instances can be cloned by declaring that it implements the Cloneable interface.

Exceptions
CloneNotSupportedException if the object's class does not support the Cloneable interface. Subclasses that override the clone method can also throw this exception to indicate that an instance cannot be cloned.
Exceptions
OutOfMemoryError if there is not enough memory.
See Also
Cloneable


 Object.equals

Object.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Parameters
obj
the reference object with which to compare.
Returns
true if this object is the same as the obj argument; false otherwise.
Description
Compares two Objects for equality.

The equals method implements an equivalence relation:

  • It is reflexive: for any reference value x, x.equals(x) should return true.
  • It is symmetric: for any reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
  • It is transitive: for any reference values x,
     y, and z, if x.equals(y)
     returns  true and y.equals(z) returns
     true, then x.equals(z) should return
     true.
  • It is consistent: for any reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false.
  • For any reference value x, x.equals(null) should return false.

The equals method for class Object implements the most discriminating possible equivalence relation on objects; that is, for any reference values x and y, this method returns true if and only if x and y refer to the same object (x==y has the value true).

See Also
hashCode, Hashtable


 Object.finalize

Object.finalize

Class Overview | Class Members | This Package | All Packages

Syntax
protected void finalize() throws Throwable
Description
Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. A subclass overrides the finalize method to dispose of system resources or to perform other cleanup.

Any exception thrown by the finalize method causes the finalization of this object to be halted, but is otherwise ignored.

The finalize method in Object does nothing.

Exceptions
Throwable [Need description!]


 Object.getClass

Object.getClass

Class Overview | Class Members | This Package | All Packages

Syntax
public final native Class getClass()
Returns
the object of type Class that represents the runtime class of the object.
Description
Returns the runtime class of an object.


 Object.hashCode

Object.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public native int hashCode()
Returns
a hash code value for this object.
Description
Returns a hash code value for the object. This method is supported for the benefit of hashtables such as those provided by java.util.Hashtable.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals method, then calling the hashCode method on each of the two objects must produce the same integer result.

See Also
equals, Hashtable


 Object.notify

Object.notify

Class Overview | Class Members | This Package | All Packages

Syntax
public final native void notify()
Description
Wakes up a single thread that is waiting on this object's monitor. A thread waits on an object's monitor by calling one of the wait methods.

This method should only be called by a thread that is the owner of this object's monitor. A thread becomes the owner of the object's monitor in one of three ways:

  • By executing a synchronized instance method of that object.
  • By executing the body of a synchronized statement that synchronizes on the object.
  • For objects of type Class, by executing a synchronized static method of that class.

Only one thread at a time can own an object's monitor.

Exceptions
IllegalMonitorStateException if the current thread is not the owner of this object's monitor.
See Also
notifyAll, wait


 Object.notifyAll

Object.notifyAll

Class Overview | Class Members | This Package | All Packages

Syntax
public final native void notifyAll()
Description
Wakes up all threads that are waiting on this object's monitor. A thread waits on an object's monitor by calling one of the wait methods.

This method should only be called by a thread that is the owner of this object's monitor. See the notify method for a description of the ways in which a thread can become the owner of a monitor.

Exceptions
IllegalMonitorStateException if the current thread is not the owner of this object's monitor.
See Also
notify, wait


 Object.toString

Object.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string representation of the object.
Description
Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommendedthat all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object.


 Object.wait

Object.wait

Class Overview | Class Members | This Package | All Packages

Syntax 1
public final native void wait( long timeout ) throws InterruptedException
Parameters
timeout
the maximum time to wait in milliseconds.
Description
Waits to be notified by another thread of a change in this object.

The current thread must own this object's monitor. The thread releases ownership of this monitor and waits until either of the following two conditions has occurred:

  • Another thread notifies threads waiting on this object's monitor to wake up either through a call to the notify method or the notifyAll method.
  • The timeout period, specified by the timeout argument in milliseconds, has elapsed.

The thread then waits until it can re-obtain ownership of the monitor and resumes execution.

This method should only be called by a thread that is the owner of this object's monitor. See the notify method for a description of the ways in which a thread can become the owner of a monitor.

Exceptions
IllegalArgumentException if the value of timeout is negative.
Exceptions
IllegalMonitorStateException if the current thread is not the owner of the object's monitor.
Exceptions
InterruptedException if another thread has interrupted this thread.
See Also
notify, notifyAll

Syntax 2
public final void wait( long timeout, int nanos ) throws InterruptedException
Parameters
timeout
the maximum time to wait in milliseconds.
nano
additional time, in nanoseconds range 0-999999.
Description
Waits to be notified by another thread of a change in this object.

This method is similar to the wait method of one argument, but it allows finer control over the amount of time to wait for a notification before giving up.

The current thread must own this object's monitor. The thread releases ownership of this monitor and waits until either of the following two conditions has occurred:

  • Another thread notifies threads waiting on this object's monitor to wake up either through a call to the notify method or the notifyAll method.
  • The timeout period, specified by timeout milliseconds plus nanos nanoseconds arguments, has elapsed.

The thread then waits until it can re-obtain ownership of the monitor and resumes execution

This method should only be called by a thread that is the owner of this object's monitor. See the notify method for a description of the ways in which a thread can become the owner of a monitor.

Exceptions
IllegalArgumentException if the value of timeout is negative or the value of nanos is not in the range 0-999999.
Exceptions
IllegalMonitorStateException if the current thread is not the owner of this object's monitor.
Exceptions
InterruptedException if another thread has interrupted this thread.

Syntax 3
public final void wait() throws InterruptedException
Description
Waits to be notified by another thread of a change in this object.

The current thread must own this object's monitor. The thread releases ownership of this monitor and waits until another thread notifies threads waiting on this object's monitor to wake up either through a call to the notify method or the notifyAll method. The thread then waits until it can re-obtain ownership of the monitor and resumes execution.

This method should only be called by a thread that is the owner of this object's monitor. See the notify method for a description of the ways in which a thread can become the owner of a monitor.

Exceptions
IllegalMonitorStateException if the current thread is not the owner of the object's monitor.
Exceptions
InterruptedException if another thread has interrupted this thread.
See Also
notify, notifyAll


 Class OutOfMemoryError

Class java.lang.OutOfMemoryError

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Error
                   |
                   +----java.lang.VirtualMachineError
                           |
                           +----java.lang.OutOfMemoryError

public class OutOfMemoryError
extends VirtualMachineError

Thrown when the Java Virtual Machine cannot allocate an object because it is out of memory, and no more memory could be made available by the garbage collector.


 OutOfMemoryError Members

OutOfMemoryError Members

Class Overview | This Package | All Packages

Constructors
Name | Description
OutOfMemoryError() | Constructs an OutOfMemoryError with no detail message.
OutOfMemoryError(String) | Constructs an OutOfMemoryError with the specified detail message.


 OutOfMemoryError.OutOfMemoryError

OutOfMemoryError.OutOfMemoryError

Class Overview | Class Members | This Package | All Packages

Syntax 1
public OutOfMemoryError()
Description
Constructs an OutOfMemoryError with no detail message.

Syntax 2
public OutOfMemoryError( String s )
Parameters
s
the detail message.
Description
Constructs an OutOfMemoryError with the specified detail message.


 Class Process

Class java.lang.Process

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Process

public abstract class Process
extends Object

The exec methods return an instance of a subclass of Process that can be used to control the process and obtain information about it.

The subprocess is not killed when there are no more references to the Process object, but rather the subprocess continues executing asynchronously.

See Also:
exec, exec, exec, exec


 Process Members

Process Members

Class Overview | This Package | All Packages

Constructors
Name | Description
Process() |

Methods
Name | Description
destroy() | Kills the subprocess.
exitValue() | Returns the exit value for the subprocess.
getErrorStream() | Gets the error stream of the subprocess.
getInputStream() | Gets the input stream of the subprocess.
getOutputStream() | Gets the output stream of the subprocess.
waitFor() | Waits for the subprocess to complete.


 Process.Process

Process.Process

Class Overview | Class Members | This Package | All Packages

Syntax
public Process()


 Process.destroy

Process.destroy

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void destroy()
Description
Kills the subprocess.


 Process.exitValue

Process.exitValue

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract int exitValue()
Returns
the exit value of the subprocess.
Description
Returns the exit value for the subprocess.

Exceptions
IllegalThreadStateException if the subprocess has not yet terminated.


 Process.getErrorStream

Process.getErrorStream

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract InputStream getErrorStream()
Returns
the input stream connected to the error stream of the subprocess.
Description
Gets the error stream of the subprocess. This stream is usually unbuffered.


 Process.getInputStream

Process.getInputStream

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract InputStream getInputStream()
Returns
the input stream connected to the normal output of the subprocess.
Description
Gets the input stream of the subprocess. This stream is usually buffered.


 Process.getOutputStream

Process.getOutputStream

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract OutputStream getOutputStream()
Returns
the output stream connected to the normal input of the subprocess.
Description
Gets the output stream of the subprocess. This stream is usually buffered.


 Process.waitFor

Process.waitFor

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract int waitFor() throws InterruptedException
Returns
the exit value of the process.
Description
Waits for the subprocess to complete. This method returns immediately if the subprocess has already terminated. If the subprocess has not yet terminated, the calling thread will be blocked until the subprocess exits.

Exceptions
InterruptedException if the waitFor was interrupted.


 Interface Runnable

Interface java.lang.Runnable

Interface Members | This Package | All Packages

public interface Runnable

The Runnable interface should be implemented by any class whose instances are intended to be executed by a thread. The class must define a method of no arguments called run.

This interface is designed to provide a common protocol for objects that wish to execute code while they are active. For example, Runnable is implemented by class Thread. Being active simply means that a thread has been started and has not yet been stopped.

In addition, Runnable provides the means for a class to be active while not subclassing Thread. A class that implements Runnable can run without subclassing Thread by instantiating a ,code>Thread instance and passing itself in as the target. In most cases, the Runnable interface should be used if you are only planning to override the run() method and no other Thread methods. This is important because classes should not be subclassed unless the programmer intends on modifying or enhancing the fundamental behavior of the class.

See Also:
Thread


 Runnable Members

Runnable Members

Interface Overview | This Package | All Packages

Methods
Name | Description
run() | When an object implementing interface Runnable is used to create a thread, starting the thread causes the object's run method to be called in that separately executing thread.


 Runnable.run

Runnable.run

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void run()
Description
When an object implementing interface Runnable is used to create a thread, starting the thread causes the object's run method to be called in that separately executing thread.

See Also
run


 Class Runtime

Class java.lang.Runtime

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Runtime

public class Runtime
extends Object


 Runtime Members

Runtime Members

Class Overview | This Package | All Packages

Methods
Name | Description
exec(String) | Executes the specified string command in a separate process.
exec(String, String[]) | Executes the specified string command in a separate process with the specified environment.
exec(String[]) | Executes the specified command and arguments in a separate process.
exec(String[], String[]) | Executes the specified command and arguments in a separate process with the specified environment.
exit(int) | Terminates the currently running Java Virtual Machine.
freeMemory() | Returns the amount of free memory in the system.
gc() | Runs the garbage collector.
getLocalizedInputStream(InputStream) | Creates a localized version of an input stream. Deprecated.
getLocalizedOutputStream(OutputStream) | Creates a localized version of an output stream. Deprecated.
getRuntime() | Returns the runtime object associated with the current Java application.
load(String) | Loads the specified filename as a dynamic library.
loadLibrary(String) | Loads the dynamic library with the specified library name.
runFinalization() | Runs the finalization methods of any objects pending finalization.
runFinalizersOnExit(boolean) | Enable or disable finalization on exit; doing so specifies that the finalizers of all objects that have finalizers that have not yet been automatically invoked are to be run before the Java runtime exits.
totalMemory() | Returns the total amount of memory in the Java Virtual Machine.
traceInstructions(boolean) | Enables/Disables tracing of instructions.
traceMethodCalls(boolean) | Enables/Disables tracing of method calls.


 Runtime.exec

Runtime.exec

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Process exec( String command ) throws IOException
Parameters
command
a specified system command.
Returns
a Process object for managing the subprocess.
Description
Executes the specified string command in a separate process.

The command argument is parsed into tokens and then executed as a command in a separate process. This method has exactly the same effect as exec(command, null).

Exceptions
SecurityException if the current thread cannot create a subprocess.
See Also
exec

Syntax 2
public Process exec( String command, String envp[] ) throws IOException
Parameters
command
a specified system command.
envp
array containing environment in format name=value
Returns
a Process object for managing the subprocess.
Description
Executes the specified string command in a separate process with the specified environment.

This method breaks the command string into tokens and creates a new array cmdarray containing the tokens; it then performs the call exec(cmdarray, envp).

Exceptions
SecurityException if the current thread cannot create a subprocess.
See Also
exec

Syntax 3
public Process exec( String cmdarray[] ) throws IOException
Parameters
cmdarray
array containing the command to call and its arguments.
Returns
a Process object for managing the subprocess.
Description
Executes the specified command and arguments in a separate process.

The command specified by the tokens in cmdarray is executed as a command in a separate process. This has exactly the same effect as exec(cmdarray, null).

Exceptions
SecurityException if the current thread cannot create a subprocess.
See Also
exec

Syntax 4
public Process exec( String cmdarray[], String envp[] ) throws IOException
Parameters
cmdarray
array containing the command to call and its arguments.
envp
array containing environment in format name=value.
Returns
a Process object for managing the subprocess.
Description
Executes the specified command and arguments in a separate process with the specified environment.

If there is a security manager, its checkExec method is called with the first component of the array cmdarray as its argument. This may result in a security exception.

Given an array of strings cmdarray, representing the tokens of a command line, and an array of strings envp, representing an "environment" that defines system properties, this method creates a new process in which to execute the specified command.

Exceptions
SecurityException if the current thread cannot create a subprocess.
See Also
SecurityException, checkExec


 Runtime.exit

Runtime.exit

Class Overview | Class Members | This Package | All Packages

Syntax
public void exit( int status )
Parameters
status
exit status.
Description
Terminates the currently running Java Virtual Machine. This method never returns normally.

If there is a security manager, its checkExit method is called with the status as its argument. This may result in a security exception.

The argument serves as a status code; by convention, a nonzero status code indicates abnormal termination.

Exceptions
SecurityException if the current thread cannot exit with the specified status.
See Also
SecurityException, checkExit


 Runtime.freeMemory

Runtime.freeMemory

Class Overview | Class Members | This Package | All Packages

Syntax
public native long freeMemory()
Returns
an approximation to the total amount of memory currently available for future allocated objects, measured in bytes.
Description
Returns the amount of free memory in the system. The value returned by this method is always less than the value returned by the totalMemory method. Calling the gc method may result in increasing the value returned by freeMemory.


 Runtime.gc

Runtime.gc

Class Overview | Class Members | This Package | All Packages

Syntax
public native void gc()
Description
Runs the garbage collector. Calling this method suggests that the Java Virtual Machine expend effort toward recycling unused objects in order to make the memory they currently occupy available for quick reuse. When control returns from the method call, the Java Virtual Machine has made its best effort to recycle all unused objects.

The name gc stands for "garbage collector". The Java Virtual Machine performs this recycling process automatically as needed even if the gc method is not invoked explicitly.


 Runtime.getLocalizedInputStream

Runtime.getLocalizedInputStream

Class Overview | Class Members | This Package | All Packages

Syntax
public InputStream getLocalizedInputStream( InputStream in )
Returns
a localized input stream.
Description
Note: getLocalizedInputStream() is deprecated. As of JDK 1.1, the preferred way translate a byte stream in the local encoding into a character stream in Unicode is via the InputStreamReader and BufferedReader classes.

Creates a localized version of an input stream. This method takes an InputStream and returns an InputStream equivalent to the argument in all respects except that it is localized: as characters in the local character set are read from the stream, they are automatically converted from the local character set to Unicode.

If the argument is already a localized stream, it may be returned as the result.

See Also
InputStream, BufferedReader, InputStreamReader


 Runtime.getLocalizedOutputStream

Runtime.getLocalizedOutputStream

Class Overview | Class Members | This Package | All Packages

Syntax
public OutputStream getLocalizedOutputStream( OutputStream out )
Returns
a localized output stream.
Description
Note: getLocalizedOutputStream() is deprecated. As of JDK 1.1, the preferred way to translate a Unicode character stream into a byte stream in the local encoding is via the OutputStreamWriter, BufferedWriter, and PrintWriter classes.

Creates a localized version of an output stream. This method takes an OutputStream and returns an OutputStream equivalent to the argument in all respects except that it is localized: as Unicode characters are written to the stream, they are automatically converted to the local character set.

If the argument is already a localized stream, it may be returned as the result.

See Also
OutputStream, BufferedWriter, OutputStreamWriter, PrintWriter


 Runtime.getRuntime

Runtime.getRuntime

Class Overview | Class Members | This Package | All Packages

Syntax
public static Runtime getRuntime()
Returns
the Runtime object associated with the current Java application.
Description
Returns the runtime object associated with the current Java application.


 Runtime.load

Runtime.load

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void load( String filename )
Parameters
filename
the file to load.
Description
Loads the specified filename as a dynamic library. The filename argument must be a complete pathname. From java_g it will automagically insert "_g" before the ".so" (for example Runtime.getRuntime().load("/home/avh/lib/libX11.so");).

If there is a security manager, its checkLink method is called with the filename as its argument. This may result in a security exception.

Exceptions
SecurityException if the current thread cannot load the specified dynamic library.
Exceptions
UnsatisfiedLinkError if the file does not exist.
See Also
getRuntime, SecurityException, checkLink


 Runtime.loadLibrary

Runtime.loadLibrary

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void loadLibrary( String libname )
Parameters
libname
the name of the library.
Description
Loads the dynamic library with the specified library name. The mapping from a library name to a specific filename is done in a system-specific manner.

First, if there is a security manager, its checkLink method is called with the filename as its argument. This may result in a security exception.

If this method is called more than once with the same library name, the second and subsequent calls are ignored.

Exceptions
SecurityException if the current thread cannot load the specified dynamic library.
Exceptions
UnsatisfiedLinkError if the library does not exist.
See Also
SecurityException, checkLink


 Runtime.runFinalization

Runtime.runFinalization

Class Overview | Class Members | This Package | All Packages

Syntax
public native void runFinalization()
Description
Runs the finalization methods of any objects pending finalization. Calling this method suggests that the Java Virtual Machine expend effort toward running the finalize methods of objects that have been found to be discarded but whose finalize methods have not yet been run. When control returns from the method call, the Java Virtual Machine has made a best effort to complete all outstanding finalizations.

The Java Virtual Machine performs the finalization process automatically as needed if the runFinalization method is not invoked explicitly.

See Also
finalize


 Runtime.runFinalizersOnExit

Runtime.runFinalizersOnExit

Class Overview | Class Members | This Package | All Packages

Syntax
public static void runFinalizersOnExit( boolean value )
Description
Enable or disable finalization on exit; doing so specifies that the finalizers of all objects that have finalizers that have not yet been automatically invoked are to be run before the Java runtime exits. By default, finalization on exit is disabled. An invocation of the runFinalizersOnExit method is permitted only if the caller is allowed to exit, and is otherwise rejected by the security manager.

See Also
gc, exit


 Runtime.totalMemory

Runtime.totalMemory

Class Overview | Class Members | This Package | All Packages

Syntax
public native long totalMemory()
Returns
the total amount of memory currently available for allocating objects, measured in bytes.
Description
Returns the total amount of memory in the Java Virtual Machine.


 Runtime.traceInstructions

Runtime.traceInstructions

Class Overview | Class Members | This Package | All Packages

Syntax
public native void traceInstructions( boolean on )
Parameters
on
true to enable instruction tracing; false to disable this feature.
Description
Enables/Disables tracing of instructions. If the boolean argument is true, this method asks the Java Virtual Machine to print out a detailed trace of each instruction in the Java Virtual Machine as it is executed. The virtual machine may ignore this request if it does not support this feature. The destination of the trace output is system dependent.

If the boolean argument is false, this method causes the Java Virtual Machine to stop performing the detailed instruction trace it is performing.


 Runtime.traceMethodCalls

Runtime.traceMethodCalls

Class Overview | Class Members | This Package | All Packages

Syntax
public native void traceMethodCalls( boolean on )
Parameters
on
true to enable instruction tracing; false to disable this feature.
Description
Enables/Disables tracing of method calls. If the boolean argument is true, this method asks the Java Virtual Machine to print out a detailed trace of each method in the Java Virtual Machine as it is called. The virtual machine may ignore this request if it does not support this feature. The destination of the trace output is system dependent.

If the boolean argument is false, this method causes the Java Virtual Machine to stop performing the detailed method trace it is performing.


 Class RuntimeException

Class java.lang.RuntimeException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.lang.RuntimeException

public class RuntimeException
extends Exception

RuntimeException is the superclass of those exceptions that can be thrown during the normal operation of the Java Virtual Machine.

A method is not required to declare in its throws clause any subclasses of RuntimeException that might be thrown during the execution of the method but not caught.


 RuntimeException Members

RuntimeException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
RuntimeException() | Constructs a RuntimeException with no detail message.
RuntimeException(String) | Constructs a RuntimeException with the specified detail message.


 RuntimeException.RuntimeException

RuntimeException.RuntimeException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public RuntimeException()
Description
Constructs a RuntimeException with no detail message.

Syntax 2
public RuntimeException( String s )
Parameters
s
the detail message.
Description
Constructs a RuntimeException with the specified detail message.


 Class SecurityException

Class java.lang.SecurityException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.lang.RuntimeException
                           |
                           +----java.lang.SecurityException

public class SecurityException
extends RuntimeException

Thrown by the security manager to indicate a security violation.

See Also:
SecurityManager


 SecurityException Members

SecurityException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
SecurityException() | Constructs a SecurityException with no detail message.
SecurityException(String) | Constructs a SecurityException with the specified detail message.


 SecurityException.SecurityException

SecurityException.SecurityException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public SecurityException()
Description
Constructs a SecurityException with no detail message.

Syntax 2
public SecurityException( String s )
Parameters
s
the detail message.
Description
Constructs a SecurityException with the specified detail message.


 Class SecurityManager

Class java.lang.SecurityManager

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.SecurityManager

public abstract class SecurityManager
extends Object

The security manager is an abstract class that allows applications to implement a security policy. It allows an application to determine, before performing a possibly unsafe or sensitive operation, what the operation is and whether the operation is being performed by a class created via a class loader rather than installed locally. Classes loaded via a class loader (especially if they have been downloaded over a network) may be less trustworthy than classes from files installed locally. The application can allow or disallow the operation.

The SecurityManager class contains many methods with names that begin with the word check. These methods are called by various methods in the Java libraries before those methods perform certain potentially sensitive operations. The invocation of such a check method typically looks like this:

     SecurityManager security = System.getSecurityManager();
     if (security != null) {
         security.checkXXX(argument,  . . . );
     }

The security manager is thereby given an opportunity to prevent completion of the operation by throwing an exception. A security manager routine simply returns if the operation is permitted, but throws a SecurityException if the operation is not permitted. The only exception to this convention is checkTopLevelWindow, which returns a boolean value.

The current security manager is set by the setSecurityManager method in class System. The current security manager is obtained by the getSecurityManager method.

The default implementation of each of the check XXX methods is to assume that the caller does not have permission to perform the requested operation.

See Also:
ClassLoader, SecurityException, checkTopLevelWindow, getSecurityManager, setSecurityManager


 SecurityManager Members

SecurityManager Members

Class Overview | This Package | All Packages

Fields
Name | Description
inCheck | This field is true if there is a security check in progress; false otherwise.

Constructors
Name | Description
SecurityManager() | Constructs a new SecurityManager.

Methods
Name | Description
checkAccept(String, int) | Throws a SecurityException if the calling thread is not permitted to accept a socket connection from the specified host and port number.
checkAccess(Thread) | Throws a SecurityException if the calling thread is not allowed to modify the thread argument.
checkAccess(ThreadGroup) | Throws a SecurityException if the calling thread is not allowed to modify the thread group argument.
checkAwtEventQueueAccess() | Tests if a client can get access to the AWT event queue.
checkConnect(String, int) | Throws a SecurityException if the calling thread is not allowed to open a socket connection to the specified host and port number.
checkConnect(String, int, Object) | Throws a SecurityException if the specified security context is not allowed to open a socket connection to the specified host and port number.
checkCreateClassLoader() | Throws a SecurityException if the calling thread is not allowed to create a new class loader.
checkDelete(String) | Throws a SecurityException if the calling thread is not allowed to delete the specified file.
checkExec(String) | Throws a SecurityException if the calling thread is not allowed to create a subprocss.
checkExit(int) | Throws a SecurityException if the calling thread is not allowed to cause the Java Virtual Machine to halt with the specified status code.
checkLink(String) | Throws a SecurityException if the calling thread is not allowed to dynamic link the library code specified by the string argument file.
checkListen(int) | Throws a SecurityException if the calling thread is not allowed to wait for a connection request on the specified local port number.
checkMemberAccess(Class, int) | Tests if a client is allowed to access members.
checkMulticast(InetAddress) | Tests if current execution context is allowed to use (join/leave/send/receive) IP multicast.
checkMulticast(InetAddress, byte) | Tests to see if current execution context is allowed to use (join/leave/send/receive) IP multicast.
checkPackageAccess(String) | Throws a SecurityException if the calling thread is not allowed to access the package specified by the argument.
checkPackageDefinition(String) | Throws a SecurityException if the calling thread is not allowed to define classes in the package specified by the argument.
checkPrintJobAccess() | Tests if a client can initiate a print job request.
checkPropertiesAccess() | Throws a SecurityException if the calling thread is not allowed to access or modify the system properties.
checkPropertyAccess(String) | Throws a SecurityException if the calling thread is not allowed to access the system property with the specified key name.
checkRead(FileDescriptor) | Throws a SecurityException if the calling thread is not allowed to read from the specified file descriptor.
checkRead(String) | Throws a SecurityException if the calling thread is not allowed to read the file specified by the string argument.
checkRead(String, Object) | Throws a SecurityException if the specified security context is not allowed to read the file specified by the string argument.
checkSecurityAccess(String) | Tests access to certain operations for a security API action.
checkSetFactory() | Throws a SecurityException if the calling thread is not allowed to set the socket factory used by ServerSocket or Socket, or the stream handler factory used by URL.
checkSystemClipboardAccess() | Tests if a client can get access to the system clipboard.
checkTopLevelWindow(Object) | Returns false if the calling thread is not trusted to bring up the top-level window indicated by the window argument.
checkWrite(FileDescriptor) | Throws a SecurityException if the calling thread is not allowed to write to the specified file descriptor.
checkWrite(String) | Throws a SecurityException if the calling thread is not allowed to write to the file specified by the string argument.
classDepth(String) | Returns the stack depth of the specified class.
classLoaderDepth() | Returns the stack depth of the most recently executing method from a class defined using a class loader.
currentClassLoader() | Returns an object describing the most recent class loader executing on the stack.
currentLoadedClass() | Returns the current Class with a ClassLoader on the execution stack.
getClassContext() | Returns the current execution stack as an array of classes.
getInCheck() | Tests if there is a security check in progress.
getSecurityContext() | Creates an object that encapsulates the current execution environment.
getThreadGroup() | Returns the thread group into which to instantiate any new thread being created at the time this is being called.
inClass(String) | Tests if the specified String is in this Class.
inClassLoader() | Tests if the current ClassLoader is equal to null.


 SecurityManager.inCheck

SecurityManager.inCheck

Class Overview | Class Members | This Package | All Packages

Syntax
protected boolean inCheck
Description
This field is true if there is a security check in progress; false otherwise.


 SecurityManager.SecurityManager

SecurityManager.SecurityManager

Class Overview | Class Members | This Package | All Packages

Syntax
protected SecurityManager()
Description
Constructs a new SecurityManager. An application is not allowed to create a new security manager if there is already a current security manager.

Exceptions
SecurityException if a security manager already exists.
See Also
getSecurityManager


 SecurityManager.checkAccept

SecurityManager.checkAccept

Class Overview | Class Members | This Package | All Packages

Syntax
public void checkAccept( String host, int port )
Parameters
host
the host name of the socket connection.
port
the port number of the socket connection.
Description
Throws a SecurityException if the calling thread is not permitted to accept a socket connection from the specified host and port number.

This method is invoked for the current security manager by the accept method of class ServerSocket.

The checkAccept method for class SecurityManager always throws a SecurityException.

Exceptions
SecurityException if the caller does not have permission to accept the connection.
See Also
getSecurityManager, accept


 SecurityManager.checkAccess

SecurityManager.checkAccess

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void checkAccess( Thread g )
Parameters
g
the thread to be checked.
Description
Throws a SecurityException if the calling thread is not allowed to modify the thread argument.

This method is invoked for the current security manager by the stop, suspend, resume, setPriority, setName, and setDaemon methods of class Thread.

The checkAccess method for class SecurityManager always throws a SecurityException.

Exceptions
SecurityException if the caller does not have permission to modify the thread.
See Also
getSecurityManager, resume, setDaemon, setName, setPriority, stop, suspend

Syntax 2
public void checkAccess( ThreadGroup g )
Parameters
g
the thread group to be checked.
Description
Throws a SecurityException if the calling thread is not allowed to modify the thread group argument.

This method is invoked for the current security manager when a new child thread or child thread group is created, and by the setDaemon, setMaxPriority, stop, suspend, resume, and destroy methods of class ThreadGroup.

The checkAccess method for class SecurityManager always throws a SecurityException.

Exceptions
SecurityException if the caller does not have permission to modify the thread group.
See Also
getSecurityManager, destroy, resume, setDaemon, setMaxPriority, stop, suspend


 SecurityManager.checkAwtEventQueueAccess

SecurityManager.checkAwtEventQueueAccess

Class Overview | Class Members | This Package | All Packages

Syntax
public void checkAwtEventQueueAccess()
Description
Tests if a client can get access to the AWT event queue.


 SecurityManager.checkConnect

SecurityManager.checkConnect

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void checkConnect( String host, int port )
Parameters
host
the host name port to connect to.
port
the protocol port to connect to.
Description
Throws a SecurityException if the calling thread is not allowed to open a socket connection to the specified host and port number.

A port number of -1 indicates that the calling method is attempting to determine the IP address of the specified host name.

The checkConnect method for class SecurityManager always throws a SecurityException.

Exceptions
SecurityException if the caller does not have permission to open a socket connection to the specified host and port.

Syntax 2
public void checkConnect( String host, int port, Object context )
Parameters
host
the host name port to connect to.
port
the protocol port to connect to.
context
a system-dependent security context.
Description
Throws a SecurityException if the specified security context is not allowed to open a socket connection to the specified host and port number.

A port number of -1 indicates that the calling method is attempting to determine the IP address of the specified host name.

The checkConnect method for class SecurityManager always throws a SecurityException.

Exceptions
SecurityException if the specified security context does not have permission to open a socket connection to the specified host and port.
See Also
getSecurityContext


 SecurityManager.checkCreateClassLoader

SecurityManager.checkCreateClassLoader

Class Overview | Class Members | This Package | All Packages

Syntax
public void checkCreateClassLoader()
Description
Throws a SecurityException if the calling thread is not allowed to create a new class loader.

The checkCreateClassLoader method for class SecurityManager always throws a SecurityException.

Exceptions
SecurityException if the caller does not have permission to create a new class loader.
See Also
ClassLoader


 SecurityManager.checkDelete

SecurityManager.checkDelete

Class Overview | Class Members | This Package | All Packages

Syntax
public void checkDelete( String file )
Parameters
file
the system-dependent filename.
Description
Throws a SecurityException if the calling thread is not allowed to delete the specified file.

This method is invoked for the current security manager by the delete method of class File.

The checkDelete method for class SecurityManager always throws a SecurityException.

Exceptions
SecurityException if the caller does not have permission to delete the file.
See Also
delete, getSecurityManager


 SecurityManager.checkExec

SecurityManager.checkExec

Class Overview | Class Members | This Package | All Packages

Syntax
public void checkExec( String cmd )
Parameters
cmd
the specified system command.
Description
Throws a SecurityException if the calling thread is not allowed to create a subprocss.

This method is invoked for the current security manager by the exec methods of class Runtime.

The checkExec method for class SecurityManager always throws a SecurityException.

Exceptions
SecurityException if the caller does not have permission to create a subprocess.
See Also
exec, exec, exec, exec, getSecurityManager


 SecurityManager.checkExit

SecurityManager.checkExit

Class Overview | Class Members | This Package | All Packages

Syntax
public void checkExit( int status )
Parameters
status
the exit status.
Description
Throws a SecurityException if the calling thread is not allowed to cause the Java Virtual Machine to halt with the specified status code.

This method is invoked for the current security manager by the exit method of class Runtime. A status of 0 indicates success; other values indicate various errors.

The checkExit method for class SecurityManager always throws a SecurityException.

Exceptions
SecurityException if the caller does not have permission to halt the Java Virtual Machine with the specified status.
See Also
exit, getSecurityManager


 SecurityManager.checkLink

SecurityManager.checkLink

Class Overview | Class Members | This Package | All Packages

Syntax
public void checkLink( String lib )
Parameters
lib
the name of the library.
Description
Throws a SecurityException if the calling thread is not allowed to dynamic link the library code specified by the string argument file. The argument is either a simple library name or a complete filename.

This method is invoked for the current security manager by methods load and loadLibrary of class Runtime.

The checkLink method for class SecurityManager always throws a SecurityException.

Exceptions
SecurityException if the caller does not have permission to dynamically link the library.
See Also
load, loadLibrary, getSecurityManager


 SecurityManager.checkListen

SecurityManager.checkListen

Class Overview | Class Members | This Package | All Packages

Syntax
public void checkListen( int port )
Parameters
port
the local port.
Description
Throws a SecurityException if the calling thread is not allowed to wait for a connection request on the specified local port number.

The checkListen method for class SecurityManager always throws a SecurityException.

Exceptions
SecurityException if the caller does not have permission to listen on the specified port.


 SecurityManager.checkMemberAccess

SecurityManager.checkMemberAccess

Class Overview | Class Members | This Package | All Packages

Syntax
public void checkMemberAccess( Class clazz, int which )
Description
Tests if a client is allowed to access members. If access is denied, throw a SecurityException. The default policy is to deny all accesses.


 SecurityManager.checkMulticast

SecurityManager.checkMulticast

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void checkMulticast( InetAddress maddr )
Parameters
multicast
Internet group address to be used.
Description
Tests if current execution context is allowed to use (join/leave/send/receive) IP multicast.

Exceptions
SecurityException if a security error has occurred.

Syntax 2
public void checkMulticast( InetAddress maddr, byte ttl )
Parameters
multicast
Internet group address to be used.
ttl
value in use, if it is multicast send.
Description
Tests to see if current execution context is allowed to use (join/leave/send/receive) IP multicast.

Exceptions
SecurityException if a security error has occurred.


 SecurityManager.checkPackageAccess

SecurityManager.checkPackageAccess

Class Overview | Class Members | This Package | All Packages

Syntax
public void checkPackageAccess( String pkg )
Parameters
pkg
the package name.
Description
Throws a SecurityException if the calling thread is not allowed to access the package specified by the argument.

This method is used by the loadClass method of class loaders.

The checkPackageAccess method for class SecurityManager always throws a SecurityException.

Exceptions
SecurityException if the caller does not have permission to access the specified package.
See Also
loadClass


 SecurityManager.checkPackageDefinition

SecurityManager.checkPackageDefinition

Class Overview | Class Members | This Package | All Packages

Syntax
public void checkPackageDefinition( String pkg )
Parameters
pkg
the package name.
Description
Throws a SecurityException if the calling thread is not allowed to define classes in the package specified by the argument.

This method is used by the loadClass method of some class loaders.

The checkPackageDefinition method for class SecurityManager always throws a SecurityException.

Exceptions
SecurityException if the caller does not have permission to define classes in the specified package.
See Also
loadClass


 SecurityManager.checkPrintJobAccess

SecurityManager.checkPrintJobAccess

Class Overview | Class Members | This Package | All Packages

Syntax
public void checkPrintJobAccess()
Description
Tests if a client can initiate a print job request.


 SecurityManager.checkPropertiesAccess

SecurityManager.checkPropertiesAccess

Class Overview | Class Members | This Package | All Packages

Syntax
public void checkPropertiesAccess()
Description
Throws a SecurityException if the calling thread is not allowed to access or modify the system properties.

This method is used by the getProperties and setProperties methods of class System.

The checkPropertiesAccess method for class SecurityManager always throws a SecurityException.

Exceptions
SecurityException if the caller does not have permission to access or modify the system properties.
See Also
getProperties, setProperties


 SecurityManager.checkPropertyAccess

SecurityManager.checkPropertyAccess

Class Overview | Class Members | This Package | All Packages

Syntax
public void checkPropertyAccess( String key )
Parameters
key
a system property key.
Description
Throws a SecurityException if the calling thread is not allowed to access the system property with the specified key name.

This method is used by the getProperty method of class System.

The checkPropertiesAccess method for class SecurityManager always throws a SecurityException.

Exceptions
SecurityException if the caller does not have permission to access the specified system property.
See Also
getProperty


 SecurityManager.checkRead

SecurityManager.checkRead

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void checkRead( FileDescriptor fd )
Parameters
fd
the system-dependent file descriptor.
Description
Throws a SecurityException if the calling thread is not allowed to read from the specified file descriptor.

The checkRead method for class SecurityManager always throws a SecurityException.

Exceptions
SecurityException if the caller does not have permission to access the specified file descriptor.
See Also
FileDescriptor

Syntax 2
public void checkRead( String file )
Parameters
file
the system-dependent file name.
Description
Throws a SecurityException if the calling thread is not allowed to read the file specified by the string argument.

The checkRead method for class SecurityManager always throws a SecurityException.

Exceptions
SecurityException if the caller does not have permission to access the specified file.

Syntax 3
public void checkRead( String file, Object context )
Parameters
file
the system-dependent filename.
context
a system-dependent security context.
Description
Throws a SecurityException if the specified security context is not allowed to read the file specified by the string argument. The context must be a security context returned by a previous call to getSecurityContext.

The checkRead method for class SecurityManager always throws a SecurityException.

Exceptions
SecurityException if the specified security context does not have permission to read the specified file.
See Also
getSecurityContext


 SecurityManager.checkSecurityAccess

SecurityManager.checkSecurityAccess

Class Overview | Class Members | This Package | All Packages

Syntax
public void checkSecurityAccess( String action )
Description
Tests access to certain operations for a security API action.


 SecurityManager.checkSetFactory

SecurityManager.checkSetFactory

Class Overview | Class Members | This Package | All Packages

Syntax
public void checkSetFactory()
Description
Throws a SecurityException if the calling thread is not allowed to set the socket factory used by ServerSocket or Socket, or the stream handler factory used by URL.

The checkSetFactory method for class SecurityManager always throws a SecurityException.

Exceptions
SecurityException if the caller does not have permission to specify a socket factory or a stream handler factory.
See Also
setSocketFactory, setSocketImplFactory, setURLStreamHandlerFactory


 SecurityManager.checkSystemClipboardAccess

SecurityManager.checkSystemClipboardAccess

Class Overview | Class Members | This Package | All Packages

Syntax
public void checkSystemClipboardAccess()
Description
Tests if a client can get access to the system clipboard.


 SecurityManager.checkTopLevelWindow

SecurityManager.checkTopLevelWindow

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean checkTopLevelWindow( Object window )
Parameters
window
the new window that is being created.
Returns
true if the caller is trusted to put up top-level windows; false otherwise.
Description
Returns false if the calling thread is not trusted to bring up the top-level window indicated by the window argument. In this case, the caller can still decide to show the window, but the window should include some sort of visual warning. If the method returns true, then the window can be shown without any special restrictions.

See class Window for more information on trusted and untrusted windows.

The checkSetFactory method for class SecurityManager always returns false.

Exceptions
SecurityException if creation is disallowed entirely.
See Also
Window


 SecurityManager.checkWrite

SecurityManager.checkWrite

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void checkWrite( FileDescriptor fd )
Parameters
fd
the system-dependent file descriptor.
Description
Throws a SecurityException if the calling thread is not allowed to write to the specified file descriptor.

The checkWrite method for class SecurityManager always throws a SecurityException.

Exceptions
SecurityException if the caller does not have permission to access the specified file descriptor.
See Also
FileDescriptor

Syntax 2
public void checkWrite( String file )
Parameters
file
the system-dependent filename.
Description
Throws a SecurityException if the calling thread is not allowed to write to the file specified by the string argument.

The checkWrite method for class SecurityManager always throws a SecurityException.

Exceptions
SecurityException if the caller does not have permission to access the specified file.


 SecurityManager.classDepth

SecurityManager.classDepth

Class Overview | Class Members | This Package | All Packages

Syntax
protected native int classDepth( String name )
Parameters
name
the fully qualified name of the class to search for.
Returns
the depth on the stack frame of the first occurrence of a method from a class with the specified name; -1 if such a frame cannot be found.
Description
Returns the stack depth of the specified class.


 SecurityManager.classLoaderDepth

SecurityManager.classLoaderDepth

Class Overview | Class Members | This Package | All Packages

Syntax
protected native int classLoaderDepth()
Returns
the depth on the stack frame of the most recent occurrence of a method from a class defined using a class loader; returns -1 if there is no occurrence of a method from a class defined using a class loader.
Description
Returns the stack depth of the most recently executing method from a class defined using a class loader.


 SecurityManager.currentClassLoader

SecurityManager.currentClassLoader

Class Overview | Class Members | This Package | All Packages

Syntax
protected native ClassLoader currentClassLoader()
Returns
the class loader of the most recent occurrence on the stack of a method from a class defined using a class loader; returns null if there is no occurrence on the stack of a method from a class defined using a class loader.
Description
Returns an object describing the most recent class loader executing on the stack.


 SecurityManager.currentLoadedClass

SecurityManager.currentLoadedClass

Class Overview | Class Members | This Package | All Packages

Syntax
protected Class currentLoadedClass()
Description
Returns the current Class with a ClassLoader on the execution stack.


 SecurityManager.getClassContext

SecurityManager.getClassContext

Class Overview | Class Members | This Package | All Packages

Syntax
protected native Class[] getClassContext()
Returns
the execution stack.
Description
Returns the current execution stack as an array of classes.

The length of the array is the number of methods on the execution stack. The element at index 0 is the class of the currently executing method, the element at index 1 is the class of that method's caller, and so on.


 SecurityManager.getInCheck

SecurityManager.getInCheck

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean getInCheck()
Returns
the value of the inCheck field. This field should contain true if a security check is in progress; false otherwise.
Description
Tests if there is a security check in progress.

See Also
inCheck


 SecurityManager.getSecurityContext

SecurityManager.getSecurityContext

Class Overview | Class Members | This Package | All Packages

Syntax
public Object getSecurityContext()
Returns
an implementation-dependent object that encapsulates sufficient information about the current execution environment to perform some security checks later.
Description
Creates an object that encapsulates the current execution environment. The result of this method is used by the three-argument checkConnect method and by the two-argument checkRead method.

These methods are needed because a trusted method may be called on to read a file or open a socket on behalf of another method. The trusted method needs to determine if the other (possibly untrusted) method would be allowed to perform the operation on its own.

See Also
checkConnect, checkRead


 SecurityManager.getThreadGroup

SecurityManager.getThreadGroup

Class Overview | Class Members | This Package | All Packages

Syntax
public ThreadGroup getThreadGroup()
Description
Returns the thread group into which to instantiate any new thread being created at the time this is being called. By default, it returns the thread group of the current thread. This should be overriden by specific security manager to return the appropriate thread group.


 SecurityManager.inClass

SecurityManager.inClass

Class Overview | Class Members | This Package | All Packages

Syntax
protected boolean inClass( String name )
Parameters
name
the fully qualified name of the class.
Returns
true if a method from a class with the specified name is on the execution stack; false otherwise.
Description
Tests if the specified String is in this Class.


 SecurityManager.inClassLoader

SecurityManager.inClassLoader

Class Overview | Class Members | This Package | All Packages

Syntax
protected boolean inClassLoader()
Returns
true if a method from a class defined using a class loader is on the execution stack.
Description
Tests if the current ClassLoader is equal to null.


 Class Short

Class java.lang.Short

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Number
           |
           +----java.lang.Short

public final class Short
extends Number

The Short class is the standard wrapper for short values.

See Also:
Number


 Short Members

Short Members

Class Overview | This Package | All Packages

Fields
Name | Description
MAX_VALUE | The maximum value a Short can have.
MIN_VALUE | The minimum value a Short can have.
TYPE | The Class object representing the primitive type short.

Constructors
Name | Description
Short(short) | Constructs a Short object initialized to the specified short value.
Short(String) | Constructs a Short object initialized to the value specified by the String parameter.

Methods
Name | Description
byteValue() | Returns the value of this Short as a byte.
decode(String) | Decodes a String into a Short.
doubleValue() | Returns the value of this Short as a double.
equals(Object) | Compares this object to the specified object.
floatValue() | Returns the value of this Short as a float.
hashCode() | Returns a hashcode for this Short.
intValue() | Returns the value of this Short as an int.
longValue() | Returns the value of this Short as a long.
parseShort(String) | Assuming the specified String represents a short, returns that short's value.
parseShort(String, int) | Assuming the specified String represents a short, returns that short's value.
shortValue() | Returns the value of this Short as a short.
toString() | Returns a String object representing this Short's value.
toString(short) | Returns a new String object representing the specified Short.
valueOf(String) | Assuming the specified String represents a short, returns a new Short object initialized to that value.
valueOf(String, int) | Assuming the specified String represents a short, returns a new Short object initialized to that value.


 Short.MAX_VALUE

Short.MAX_VALUE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final short MAX_VALUE
Description
The maximum value a Short can have.


 Short.MIN_VALUE

Short.MIN_VALUE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final short MIN_VALUE
Description
The minimum value a Short can have.


 Short.TYPE

Short.TYPE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Class TYPE
Description
The Class object representing the primitive type short.


 Short.Short

Short.Short

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Short( short value )
Parameters
value
the initial value of the Short
Description
Constructs a Short object initialized to the specified short value.

Syntax 2
public Short( String s ) throws NumberFormatException
Parameters
s
the String to be converted to a Short
Description
Constructs a Short object initialized to the value specified by the String parameter. The radix is assumed to be 10.

Exceptions
NumberFormatException If the String does not contain a parsable short.


 Short.byteValue

Short.byteValue

Class Overview | Class Members | This Package | All Packages

Syntax
public byte byteValue()
Description
Returns the value of this Short as a byte.

Overrides
byteValue in class Number


 Short.decode

Short.decode

Class Overview | Class Members | This Package | All Packages

Syntax
public static Short decode( String nm ) throws NumberFormatException
Parameters
nm
the string to decode
Description
Decodes a String into a Short. The String may represent decimal, hexadecimal, and octal numbers.


 Short.doubleValue

Short.doubleValue

Class Overview | Class Members | This Package | All Packages

Syntax
public double doubleValue()
Description
Returns the value of this Short as a double.

Overrides
doubleValue in class Number


 Short.equals

Short.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Parameters
obj
the object to compare with
Returns
true if the objects are the same; false otherwise.
Description
Compares this object to the specified object.

Overrides
equals in class Object


 Short.floatValue

Short.floatValue

Class Overview | Class Members | This Package | All Packages

Syntax
public float floatValue()
Description
Returns the value of this Short as a float.

Overrides
floatValue in class Number


 Short.hashCode

Short.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int hashCode()
Description
Returns a hashcode for this Short.

Overrides
hashCode in class Object


 Short.intValue

Short.intValue

Class Overview | Class Members | This Package | All Packages

Syntax
public int intValue()
Description
Returns the value of this Short as an int.

Overrides
intValue in class Number


 Short.longValue

Short.longValue

Class Overview | Class Members | This Package | All Packages

Syntax
public long longValue()
Description
Returns the value of this Short as a long.

Overrides
longValue in class Number


 Short.parseShort

Short.parseShort

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static short parseShort( String s ) throws NumberFormatException
Parameters
s
the String containing the short
Description
Assuming the specified String represents a short, returns that short's value. Throws an exception if the String cannot be parsed as a short. The radix is assumed to be 10.

Exceptions
NumberFormatException If the string does not contain a parsable short.

Syntax 2
public static short parseShort( String s, int radix ) throws NumberFormatException
Parameters
s
the String containing the short
radix
the radix to be used
Description
Assuming the specified String represents a short, returns that short's value. Throws an exception if the String cannot be parsed as a short.

Exceptions
NumberFormatException If the String does not contain a parsable short.


 Short.shortValue

Short.shortValue

Class Overview | Class Members | This Package | All Packages

Syntax
public short shortValue()
Description
Returns the value of this Short as a short.

Overrides
shortValue in class Number


 Short.toString

Short.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public static String toString( short s )
Parameters
s
the short to be converted
Description
Returns a new String object representing the specified Short. The radix is assumed to be 10.


 Short.toString

Short.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Description
Returns a String object representing this Short's value.

Overrides
toString in class Object


 Short.valueOf

Short.valueOf

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static Short valueOf( String s, int radix ) throws NumberFormatException
Parameters
s
the String containing the integer
radix
the radix to be used
Description
Assuming the specified String represents a short, returns a new Short object initialized to that value. Throws an exception if the String cannot be parsed as a short.

Exceptions
NumberFormatException If the String does not contain a parsable short.

Syntax 2
public static Short valueOf( String s ) throws NumberFormatException
Parameters
s
the String containing the integer
Description
Assuming the specified String represents a short, returns a new Short object initialized to that value. Throws an exception if the String cannot be parsed as a short.

Exceptions
NumberFormatException If the String does not contain a parsable short.


 Class StackOverflowError

Class java.lang.StackOverflowError

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Error
                   |
                   +----java.lang.VirtualMachineError
                           |
                           +----java.lang.StackOverflowError

public class StackOverflowError
extends VirtualMachineError

Thrown when a stack overflow occurs because an application recurses too deeply.


 StackOverflowError Members

StackOverflowError Members

Class Overview | This Package | All Packages

Constructors
Name | Description
StackOverflowError() | Constructs a StackOverflowError with no detail message.
StackOverflowError(String) | Constructs a StackOverflowError with the specified detail message.


 StackOverflowError.StackOverflowError

StackOverflowError.StackOverflowError

Class Overview | Class Members | This Package | All Packages

Syntax 1
public StackOverflowError()
Description
Constructs a StackOverflowError with no detail message.

Syntax 2
public StackOverflowError( String s )
Parameters
s
the detail message.
Description
Constructs a StackOverflowError with the specified detail message.


 Class String

Class java.lang.String

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.String

public final class String
extends Object
implements Serializable

The String class represents character strings. All string literals in Java programs, such as "abc", are implemented as instances of this class.

Strings are constant; their values cannot be changed after they are created. String buffers support mutable strings. Because String objects are immutable they can be shared. For example:

     String str = "abc";

is equivalent to:

     char data[] = {'a', 'b', 'c'};
     String str = new String(data);

Here are some more examples of how strings can be used:

     System.out.println("abc");
     String cde = "cde";
     System.out.println("abc" + cde);
     String c = "abc".substring(2,3);
     String d = cde.substring(1, 2);

The class String includes methods for examining individual characters of the sequence, for comparing strings, for searching strings, for extracting substrings, and for creating a copy of a string with all characters translated to uppercase or to lowercase.

The Java language provides special support for the string concatentation operator ( + ), and for conversion of other objects to strings. String concatenation is implemented through the StringBuffer class and its append method. String conversions are implemented through the method toString, defined by Object and inherited by all classes in Java. For additional information on string concatenation and conversion, see Gosling, Joy, and Steele, The Java Language Specification.

See Also:
toString, StringBuffer, append, append, append, append, append, append, append, append, append, append


 String Members

String Members

Class Overview | This Package | All Packages

Constructors
Name | Description
String() | Allocates a new String containing no characters.
String(byte[]) | Construct a new String by converting the specified array of bytes using the platform's default character encoding.
String(byte[], int) | Allocates a new String containing characters constructed from an array of 8-bit integer values. Deprecated.
String(byte[], int, int) | Construct a new String by converting the specified subarray of bytes using the platform's default character encoding.
String(byte[], int, int, int) | Allocates a new String constructed from a subarray of an array of 8-bit integer values. Deprecated.
String(byte[], int, int, String) | Construct a new String by converting the specified subarray of bytes using the specified character encoding.
String(byte[], String) | Construct a new String by converting the specified array of bytes using the specified character encoding.
String(char[]) | Allocates a new String so that it represents the sequence of characters currently contained in the character array argument.
String(char[], int, int) | Allocates a new String that contains characters from a subarray of the character array argument.
String(String) | Allocates a new string that contains the same sequence of characters as the string argument.
String(StringBuffer) | Allocates a new string that contains the sequence of characters currently contained in the string buffer argument.

Methods
Name | Description
charAt(int) | Returns the character at the specified index.
compareTo(String) | Compares two strings lexicographically.
concat(String) | Concatenates the specified string to the end of this string.
copyValueOf(char[]) | Returns a String that is equivalent to the specified character array.
copyValueOf(char[], int, int) | Returns a String that is equivalent to the specified character array.
endsWith(String) | Tests if this string ends with the specified suffix.
equals(Object) | Compares this string to the specified object.
equalsIgnoreCase(String) | Compares this String to another object.
getBytes() | Convert this String into bytes according to the platform's default character encoding, storing the result into a new byte array.
getBytes(int, int, byte[], int) | Copies characters from this string into the destination byte array. Deprecated.
getBytes(String) | Convert this String into bytes according to the specified character encoding, storing the result into a new byte array.
getChars(int, int, char[], int) | Copies characters from this string into the destination character array.
hashCode() | Returns a hashcode for this string.
indexOf(int) | Returns the index within this string of the first occurrence of the specified character.
indexOf(int, int) | Returns the index within this string of the first occurrence of the specified character, starting the search at the specified index.
indexOf(String) | Returns the index within this string of the first occurrence of the specified substring.
indexOf(String, int) | Returns the index within this string of the first occurrence of the specified substring, starting at the specified index.
intern() | Returns a canonical representation for the string object.
lastIndexOf(int) | Returns the index within this string of the last occurrence of the specified character.
lastIndexOf(int, int) | Returns the index within this string of the last occurrence of the specified character, searching backward starting at the specified index.
lastIndexOf(String) | Returns the index within this string of the rightmost occurrence of the specified substring.
lastIndexOf(String, int) | Returns the index within this string of the last occurrence of the specified substring.
length() | Returns the length of this string.
regionMatches(boolean, int, String, int, int) | Tests if two string regions are equal.
regionMatches(int, String, int, int) | Tests if two string regions are equal.
replace(char, char) | Returns a new string resulting from replacing all occurrences of oldChar in this string with newChar.
startsWith(String) | Tests if this string starts with the specified prefix.
startsWith(String, int) | Tests if this string starts with the specified prefix.
substring(int) | Returns a new string that is a substring of this string.
substring(int, int) | Returns a new string that is a substring of this string.
toCharArray() | Converts this string to a new character array.
toLowerCase() | Converts this String to lowercase.
toLowerCase(Locale) | Converts all of the characters in this String to lower case using the rules of the given locale.
toString() | This object (which is already a string!) is itself returned.
toUpperCase() | Converts this string to uppercase.
toUpperCase(Locale) | Converts all of the characters in this String to upper case using the rules of the given locale.
trim() | Removes white space from both ends of this string.
valueOf(boolean) | Returns the string representation of the boolean argument.
valueOf(char) | Returns the string representation of the char * argument.
valueOf(char[]) | Returns the string representation of the char array argument.
valueOf(char[], int, int) | Returns the string representation of a specific subarray of the char array argument.
valueOf(double) | Returns the string representation of the double argument.
valueOf(float) | Returns the string representation of the float argument.
valueOf(int) | Returns the string representation of the int argument.
valueOf(long) | Returns the string representation of the long argument.
valueOf(Object) | Returns the string representation of the Object argument.


 String.String

String.String

Class Overview | Class Members | This Package | All Packages

Syntax 1
public String()
Description
Allocates a new String containing no characters.

Syntax 2
public String( String value )
Parameters
value
a String.
Description
Allocates a new string that contains the same sequence of characters as the string argument.

Syntax 3
public String( char value[] )
Parameters
value
the initial value of the string.
Description
Allocates a new String so that it represents the sequence of characters currently contained in the character array argument.

Syntax 4
public String( char value[], int offset, int count )
Parameters
value
array that is the source of characters.
offset
the initial offset.
count
the length.
Description
Allocates a new String that contains characters from a subarray of the character array argument. The offset argument is the index of the first character of the subarray and the count argument specifies the length of the subarray.

Exceptions
StringIndexOutOfBoundsException if the offset and count arguments index characters outside the bounds of the value array.

Syntax 5
public String( byte ascii[], int hibyte, int offset, int count )
Parameters
ascii
the bytes to be converted to characters.
hibyte
the top 8 bits of each 16-bit Unicode character.
offset
the initial offset.
count
the length.
Description
Note: String() is deprecated. This method does not properly convert bytes into characters. As of JDK 1.1, the preferred way to do this is via the String constructors that take a character-encoding name or that use the platform's default encoding.

Allocates a new String constructed from a subarray of an array of 8-bit integer values.

The offset argument is the index of the first byte of the subarray, and the count argument specifies the length of the subarray.

Each byte in the subarray is converted to a char as specified in the method above.

Exceptions
StringIndexOutOfBoundsException if the offset or count argument is invalid.
See Also
String, String, String, String, String

Syntax 6
public String( byte ascii[], int hibyte )
Parameters
ascii
the bytes to be converted to characters.
hibyte
the top 8 bits of each 16-bit Unicode character.
Description
Note: String() is deprecated. This method does not properly convert bytes into characters. As of JDK 1.1, the preferred way to do this is via the String constructors that take a character-encoding name or that use the platform's default encoding.

Allocates a new String containing characters constructed from an array of 8-bit integer values. Each character cin the resulting string is constructed from the corresponding component b in the byte array such that:

     c == (char)(((hibyte & 0xff) << 8)
                         | (b & 0xff))

See Also
String, String, String, String

Syntax 7
public String( byte bytes[], int offset, int length, String enc ) throws UnsupportedEncodingException
Parameters
bytes
The bytes to be converted into characters
offset
Index of the first byte to convert
length
Number of bytes to convert
enc
The name of a character encoding
Description
Construct a new String by converting the specified subarray of bytes using the specified character encoding. The length of the new String is a function of the encoding, and hence may not be equal to the length of the subarray.

Exceptions
UnsupportedEncodingException If the named encoding is not supported

Syntax 8
public String( byte bytes[], String enc ) throws UnsupportedEncodingException
Parameters
bytes
The bytes to be converted into characters
enc
A character-encoding name
Description
Construct a new String by converting the specified array of bytes using the specified character encoding. The length of the new String is a function of the encoding, and hence may not be equal to the length of the byte array.

Exceptions
UnsupportedEncodingException If the named encoding is not supported

Syntax 9
public String( byte bytes[], int offset, int length )
Parameters
bytes
The bytes to be converted into characters
offset
Index of the first byte to convert
length
Number of bytes to convert
Description
Construct a new String by converting the specified subarray of bytes using the platform's default character encoding. The length of the new String is a function of the encoding, and hence may not be equal to the length of the subarray.

Syntax 10
public String( byte bytes[] )
Parameters
bytes
The bytes to be converted into characters
Description
Construct a new String by converting the specified array of bytes using the platform's default character encoding. The length of the new String is a function of the encoding, and hence may not be equal to the length of the byte array.

Syntax 11
public String( StringBuffer buffer )
Parameters
buffer
a StringBuffer.
Description
Allocates a new string that contains the sequence of characters currently contained in the string buffer argument.


 String.charAt

String.charAt

Class Overview | Class Members | This Package | All Packages

Syntax
public char charAt( int index )
Parameters
index
the index of the character.
Returns
the character at the specified index of this string. The first character is at index 0.
Description
Returns the character at the specified index. An index ranges from 0 to length() - 1.

Exceptions
StringIndexOutOfBoundsException if the index is out of range.


 String.compareTo

String.compareTo

Class Overview | Class Members | This Package | All Packages

Syntax
public int compareTo( String anotherString )
Parameters
anotherString
the String to be compared.
Returns
the value 0 if the argument string is equal to this string; a value less than 0 if this string is lexicographically less than the string argument; and a value greater than 0 if this string is lexicographically greater than the string argument.
Description
Compares two strings lexicographically. The comparison is based on the Unicode value of each character in the strings.


 String.concat

String.concat

Class Overview | Class Members | This Package | All Packages

Syntax
public String concat( String str )
Parameters
str
the String that is concatenated to the end of this String.
Returns
a string that represents the concatenation of this object's characters followed by the string argument's characters.
Description
Concatenates the specified string to the end of this string.

If the length of the argument string is 0, then this object is returned.


 String.copyValueOf

String.copyValueOf

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static String copyValueOf( char data[], int offset, int count )
Parameters
data
the character array.
offset
initial offset of the subarray.
count
length of the subarray.
Returns
a String that contains the characters of the specified subarray of the character array.
Description
Returns a String that is equivalent to the specified character array. It creates a new array and copies the characters into it.

Syntax 2
public static String copyValueOf( char data[] )
Parameters
data
the character array.
Returns
a String that contains the characters of the character array.
Description
Returns a String that is equivalent to the specified character array. It creates a new array and copies the characters into it.


 String.endsWith

String.endsWith

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean endsWith( String suffix )
Parameters
suffix
the suffix.
Returns
true if the character sequence represented by the argument is a suffix of the character sequence represented by this object; false otherwise.
Description
Tests if this string ends with the specified suffix.


 String.equals

String.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object anObject )
Parameters
anObject
the object to compare this String against.
Returns
true if the String are equal; false otherwise.
Description
Compares this string to the specified object. The result is true if and only if the argument is not null and is a String object that represents the same sequence of characters as this object.

Overrides
equals in class Object
See Also
compareTo, equalsIgnoreCase


 String.equalsIgnoreCase

String.equalsIgnoreCase

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equalsIgnoreCase( String anotherString )
Parameters
anotherString
the String to compare this String against.
Returns
true if the Strings are equal, ignoring case; false otherwise.
Description
Compares this String to another object. The result is true if and only if the argument is not null and is a String object that represents the same sequence of characters as this object, where case is ignored.

Two characters are considered the same, ignoring case, if at least one of the following is true:

  • The two characters are the same (as compared by the == operator).
  • Applying the method Character.toUppercase to each character produces the same result.
  • Applying the method Character.toLowercase to each character produces the same result.

Two sequences of characters are the same, ignoring case, if the sequences have the same length and corresponding characters are the same, ignoring case.

See Also
toLowerCase, toUpperCase


 String.getBytes

String.getBytes

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void getBytes( int srcBegin, int srcEnd, byte dst[], int dstBegin )
Parameters
srcBegin
index of the first character in the string to copy.
srcEnd
index after the last character in the string to copy.
dst
the destination array.
dstBegin
the start offset in the destination array.
Description
Note: getBytes() is deprecated. This method does not properly convert characters into bytes. As of JDK 1.1, the preferred way to do this is via the getBytes(String enc) method, which takes a character-encoding name, or the getBytes() method, which uses the platform's default encoding.

Copies characters from this string into the destination byte array. Each byte receives the 8 low-order bits of the corresponding character.

The first character to be copied is at index srcBegin; the last character to be copied is at index srcEnd-1. The total number of characters to be copied is srcEnd-srcBegin. The characters, converted to bytes, are copied into the subarray of dst starting at index dstBegin and ending at index:

     dstbegin + (srcEnd-srcBegin) - 1

Exceptions
StringIndexOutOfBoundsException if srcBegin or srcEnd is out of range, or if srcBegin is greater than srcEnd.

Syntax 2
public byte[] getBytes( String enc ) throws UnsupportedEncodingException
Parameters
enc
A character-encoding name
Returns
The resultant byte array
Description
Convert this String into bytes according to the specified character encoding, storing the result into a new byte array.

Exceptions
UnsupportedEncodingException If the named encoding is not supported

Syntax 3
public byte[] getBytes()
Returns
the resultant byte array.
Description
Convert this String into bytes according to the platform's default character encoding, storing the result into a new byte array.


 String.getChars

String.getChars

Class Overview | Class Members | This Package | All Packages

Syntax
public void getChars( int srcBegin, int srcEnd, char dst[], int dstBegin )
Parameters
srcBegin
index of the first character in the string to copy.
srcEnd
index after the last character in the string to copy.
dst
the destination array.
dstBegin
the start offset in the destination array.
Description
Copies characters from this string into the destination character array.

The first character to be copied is at index srcBegin; the last character to be copied is at index srcEnd-1 (thus the total number of characters to be copied is srcEnd-srcBegin). The characters are copied into the subarray of dst starting at index dstBegin and ending at index:

     dstbegin + (srcEnd-srcBegin) - 1

Exceptions
StringIndexOutOfBoundsException If srcBegin or srcEnd is out of range, or if srcBegin is greater than the srcEnd.


 String.hashCode

String.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int hashCode()
Returns
a hash code value for this object.
Description
Returns a hashcode for this string.

Overrides
hashCode in class Object


 String.indexOf

String.indexOf

Class Overview | Class Members | This Package | All Packages

Syntax 1
public int indexOf( int ch )
Parameters
ch
a character.
Returns
the index of the first occurrence of the character in the character sequence represented by this object, or -1 if the character does not occur.
Description
Returns the index within this string of the first occurrence of the specified character.

Syntax 2
public int indexOf( int ch, int fromIndex )
Parameters
ch
a character.
fromIndex
the index to start the search from.
Returns
the index of the first occurrence of the character in the character sequence represented by this object that is greater than or equal to fromIndex, or -1 if the character does not occur.
Description
Returns the index within this string of the first occurrence of the specified character, starting the search at the specified index.


 String.indexOf

String.indexOf

Class Overview | Class Members | This Package | All Packages

Syntax 1
public int indexOf( String str )
Parameters
str
any string.
Returns
if the string argument occurs as a substring within this object, then the index of the first character of the first such substring is returned; if it does not occur as a substring, -1 is returned.
Description
Returns the index within this string of the first occurrence of the specified substring.

Syntax 2
public int indexOf( String str, int fromIndex )
Parameters
str
the substring to search for.
fromIndex
the index to start the search from.
Returns
If the string argument occurs as a substring within this object at a starting index no smaller than fromIndex, then the index of the first character of the first such substring is returned. If it does not occur as a substring starting at fromIndex or beyond, -1 is returned.
Description
Returns the index within this string of the first occurrence of the specified substring, starting at the specified index.


 String.intern

String.intern

Class Overview | Class Members | This Package | All Packages

Syntax
public native String intern()
Returns
a string that has the same contents as this string, but is guaranteed to be from a pool of unique strings.
Description
Returns a canonical representation for the string object.

If s and t are strings such that s.equals(t), it is guaranteed that
s.intern() == t.intern().


 String.lastIndexOf

String.lastIndexOf

Class Overview | Class Members | This Package | All Packages

Syntax 1
public int lastIndexOf( int ch )
Parameters
ch
a character.
Returns
the index of the last occurrence of the character in the character sequence represented by this object, or -1 if the character does not occur.
Description
Returns the index within this string of the last occurrence of the specified character. The String is searched backwards starting at the last character.

Syntax 2
public int lastIndexOf( int ch, int fromIndex )
Parameters
ch
a character.
fromIndex
the index to start the search from.
Returns
the index of the last occurrence of the character in the character sequence represented by this object that is less than or equal to fromIndex, or -1 if the character does not occur before that point.
Description
Returns the index within this string of the last occurrence of the specified character, searching backward starting at the specified index.


 String.lastIndexOf

String.lastIndexOf

Class Overview | Class Members | This Package | All Packages

Syntax 1
public int lastIndexOf( String str )
Parameters
str
the substring to search for.
Returns
if the string argument occurs one or more times as a substring within this object, then the index of the first character of the last such substring is returned. If it does not occur as a substring, -1 is returned.
Description
Returns the index within this string of the rightmost occurrence of the specified substring. The rightmost empty string "" is considered to occur at the index value this.length().

Syntax 2
public int lastIndexOf( String str, int fromIndex )
Parameters
str
the substring to search for.
fromIndex
the index to start the search from.
Returns
If the string argument occurs one or more times as a substring within this object at a starting index no greater than fromIndex, then the index of the first character of the last such substring is returned. If it does not occur as a substring starting at fromIndex or earlier, -1 is returned.
Description
Returns the index within this string of the last occurrence of the specified substring. The returned index indicates the start of the substring, and it must be equal to or less than fromIndex.


 String.length

String.length

Class Overview | Class Members | This Package | All Packages

Syntax
public int length()
Returns
the length of the sequence of characters represented by this object.
Description
Returns the length of this string. The length is equal to the number of 16-bit Unicode characters in the string.


 String.regionMatches

String.regionMatches

Class Overview | Class Members | This Package | All Packages

Syntax 1
public boolean regionMatches( int toffset, String other, int ooffset, int len )
Parameters
toffset
the starting offset of the subregion in this string.
other
the string argument.
ooffset
the starting offset of the subregion in the string argument.
len
the number of characters to compare.
Returns
true if the specified subregion of this string exactly matches the specified subregion of the string argument; false otherwise.
Description
Tests if two string regions are equal.

If toffset or ooffset is negative, or if toffset+length is greater than the length of this string, or if ooffset+length is greater than the length of the string argument, then this method returns false.

Syntax 2
public boolean regionMatches( boolean ignoreCase, int toffset, String other, int ooffset, int len )
Parameters
ignoreCase
if true, ignore case when comparing characters.
toffset
the starting offset of the subregion in this string.
other
the string argument.
ooffset
the starting offset of the subregion in the string argument.
len
the number of characters to compare.
Returns
true if the specified subregion of this string matches the specified subregion of the string argument; false otherwise. Whether the matching is exact or case insensitive depends on the ignoreCase argument.
Description
Tests if two string regions are equal.

If toffset or ooffset is negative, or if toffset+length is greater than the length of this string, or if ooffset+length is greater than the length of the string argument, then this method returns false.


 String.replace

String.replace

Class Overview | Class Members | This Package | All Packages

Syntax
public String replace( char oldChar, char newChar )
Parameters
oldChar
the old character.
newChar
the new character.
Returns
a string derived from this string by replacing every occurrence of oldChar with newChar.
Description
Returns a new string resulting from replacing all occurrences of oldChar in this string with newChar.

If the character oldChar does not occur in the character sequence represented by this object, then this string is returned.


 String.startsWith

String.startsWith

Class Overview | Class Members | This Package | All Packages

Syntax 1
public boolean startsWith( String prefix, int toffset )
Parameters
prefix
the prefix.
toffset
where to begin looking in the string.
Returns
true if the character sequence represented by the argument is a prefix of the substring of this object starting at index toffset; false otherwise.
Description
Tests if this string starts with the specified prefix.

Syntax 2
public boolean startsWith( String prefix )
Parameters
prefix
the prefix.
Returns
true if the character sequence represented by the argument is a prefix of the character sequence represented by this string; false otherwise.
Description
Tests if this string starts with the specified prefix.


 String.substring

String.substring

Class Overview | Class Members | This Package | All Packages

Syntax 1
public String substring( int beginIndex )
Parameters
beginIndex
the beginning index, inclusive.
Returns
the specified substring.
Description
Returns a new string that is a substring of this string. The substring begins at the specified index and extends to the end of this string.

Exceptions
StringIndexOutOfBoundsException if the beginIndex is out of range.

Syntax 2
public String substring( int beginIndex, int endIndex )
Parameters
beginIndex
the beginning index, inclusive.
endIndex
the ending index, exclusive.
Returns
the specified substring.
Description
Returns a new string that is a substring of this string. The substring begins at the specified beginIndex and extends to the character at index endIndex - 1.

Exceptions
StringIndexOutOfBoundsException if the beginIndex or the endIndex is out of range.


 String.toCharArray

String.toCharArray

Class Overview | Class Members | This Package | All Packages

Syntax
public char[] toCharArray()
Returns
a newly allocated character array whose length is the length of this string and whose contents are initialized to contain the character sequence represented by this string.
Description
Converts this string to a new character array.


 String.toLowerCase

String.toLowerCase

Class Overview | Class Members | This Package | All Packages

Syntax 1
public String toLowerCase( Locale locale )
Parameters
locale
use the case transformation rules for this locale
Returns
the String, converted to lowercase.
Description
Converts all of the characters in this String to lower case using the rules of the given locale.

See Also
toLowerCase, toUpperCase

Syntax 2
public String toLowerCase()
Returns
the string, converted to lowercase.
Description
Converts this String to lowercase.

If no character in the string has a different lowercase version, based on calling the toLowerCase method defined by Character, then the original string is returned.

Otherwise, a new string is allocated, whose length is identical to this string, and such that each character that has a different lowercase version is mapped to this lowercase equivalent.

See Also
toLowerCase, toUpperCase


 String.toString

String.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
the string itself.
Description
This object (which is already a string!) is itself returned.

Overrides
toString in class Object


 String.toUpperCase

String.toUpperCase

Class Overview | Class Members | This Package | All Packages

Syntax 1
public String toUpperCase( Locale locale )
Parameters
locale
use the case transformation rules for this locale
Returns
the String, converted to uppercase.
Description
Converts all of the characters in this String to upper case using the rules of the given locale.

See Also
toUpperCase, toLowerCase

Syntax 2
public String toUpperCase()
Returns
the string, converted to uppercase.
Description
Converts this string to uppercase.

If no character in this string has a different uppercase version, based on calling the toUpperCase method defined by Character, then the original string is returned.

Otherwise, a new string is allocated, whose length is identical to this string, and such that each character that has a different uppercase version is mapped to this uppercase equivalent.

See Also
toUpperCase, toLowerCase


 String.trim

String.trim

Class Overview | Class Members | This Package | All Packages

Syntax
public String trim()
Returns
this string, with white space removed from the front and end.
Description
Removes white space from both ends of this string.

All characters that have codes less than or equal to '\u0020' (the space character) are considered to be white space.


 String.valueOf

String.valueOf

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static String valueOf( Object obj )
Parameters
obj
an Object.
Returns
if the argument is null, then a string equal to "null"; otherwise, the value of obj.toString() is returned.
Description
Returns the string representation of the Object argument.

See Also
toString

Syntax 2
public static String valueOf( char data[] )
Parameters
data
a char array.
Returns
a newly allocated string representing the same sequence of characters contained in the character array argument.
Description
Returns the string representation of the char array argument.

Syntax 3
public static String valueOf( char data[], int offset, int count )
Parameters
data
the character array.
offset
the initial offset into the value of the String.
count
the length of the value of the String.
Returns
a newly allocated string representing the sequence of characters contained in the subarray of the character array argument.
Description
Returns the string representation of a specific subarray of the char array argument.

The offset argument is the index of the first character of the subarray. The count argument specifies the length of the subarray.


 String.valueOf

String.valueOf

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static String valueOf( boolean b )
Parameters
b
a boolean.
Returns
if the argument is true, a string equal to "true" is returned; otherwise, a string equal to "false" is returned.
Description
Returns the string representation of the boolean argument.

Syntax 2
public static String valueOf( char c )
Parameters
c
a char.
Returns
a newly allocated string of length 1 containing as its single character the argument c.
Description
Returns the string representation of the char * argument.

Syntax 3
public static String valueOf( int i )
Parameters
i
an int.
Returns
a newly allocated string containing a string representation of the int argument.
Description
Returns the string representation of the int argument.

The representation is exactly the one returned by the Integer.toString method of one argument.

See Also
toString

Syntax 4
public static String valueOf( long l )
Parameters
l
a long.
Returns
a newly allocated string containing a string representation of the long argument.
Description
Returns the string representation of the long argument.

The representation is exactly the one returned by the Long.toString method of one argument.

See Also
toString

Syntax 5
public static String valueOf( float f )
Parameters
f
a float.
Returns
a newly allocated string containing a string representation of the float argument.
Description
Returns the string representation of the float argument.

The representation is exactly the one returned by the Float.toString method of one argument.

See Also
toString

Syntax 6
public static String valueOf( double d )
Parameters
d
a double.
Returns
a newly allocated string containing a string representation of the double argument.
Description
Returns the string representation of the double argument.

The representation is exactly the one returned by the Double.toString method of one argument.

See Also
toString


 Class StringBuffer

Class java.lang.StringBuffer

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.StringBuffer

public final class StringBuffer
extends Object
implements Serializable

A string buffer implements a mutable sequence of characters.

String buffers are safe for use by multiple threads. The methods are synchronized where necessary so that all the operations on any particular instance behave as if they occur in some serial order.

String buffers are used by the compiler to implement the binary string concatenation operator +. For example, the code:

     x = "a" + 4 + "c"

is compiled to the equivalent of:

     x = new StringBuffer().append("a").append(4).append("c")
                           .toString()

The principal operations on a StringBuffer are the append and insert methods, which are overloaded so as to accept data of any type. Each effectively converts a given datum to a string and then appends or inserts the characters of that string to the string buffer. The append method always adds these characters at the end of the buffer; the insert method adds the characters at a specified point.

For example, if z refers to a string buffer object whose current contents are "start", then the method call z.append("le") would cause the string buffer to contain "startle", whereas z.insert(4, "le") would alter the string buffer to contain "starlet".

Every string buffer has a capacity. As long as the length of the character sequence contained in the string buffer does not exceed the capacity, it is not necessary to allocate a new internal buffer array. If the internal buffer overflows, it is automatically made larger.

See Also:
ByteArrayOutputStream, String


 StringBuffer Members

StringBuffer Members

Class Overview | This Package | All Packages

Constructors
Name | Description
StringBuffer() | Constructs a string buffer with no characters in it and an initial capacity of 16 characters.
StringBuffer(int) | Constructs a string buffer with no characters in it and an initial capacity specified by the length argument.
StringBuffer(String) | Constructs a string buffer so that it represents the same sequence of characters as the string argument.

Methods
Name | Description
append(boolean) | Appends the string representation of the boolean argument to the string buffer.
append(char) | Appends the string representation of the char argument to this string buffer.
append(char[]) | Appends the string representation of the char array argument to this string buffer.
append(char[], int, int) | Appends the string representation of a subarray of the char array argument to this string buffer.
append(double) | Appends the string representation of the double argument to this string buffer.
append(float) | Appends the string representation of the float argument to this string buffer.
append(int) | Appends the string representation of the int argument to this string buffer.
append(long) | Appends the string representation of the long argument to this string buffer.
append(Object) | Appends the string representation of the Object argument to this string buffer.
append(String) | Appends the string to this string buffer.
capacity() | Returns the current capacity of the String buffer.
charAt(int) | Returns the character at a specific index in this string buffer.
ensureCapacity(int) | Ensures that the capacity of the buffer is at least equal to the specified minimum.
getChars(int, int, char[], int) | Characters are copied from this string buffer into the destination character array dst.
insert(int, boolean) | Inserts the string representation of the boolean argument into this string buffer.
insert(int, char) | Inserts the string representation of the char argument into this string buffer.
insert(int, char[]) | Inserts the string representation of the char array argument into this string buffer.
insert(int, double) | Inserts the string representation of the double argument into this string buffer.
insert(int, float) | Inserts the string representation of the float argument into this string buffer.
insert(int, int) | Inserts the string representation of the second int argument into this string buffer.
insert(int, long) | Inserts the string representation of the long argument into this string buffer.
insert(int, Object) | Inserts the string representation of the Object argument into this string buffer.
insert(int, String) | Inserts the string into this string buffer.
length() | Returns the length (character count) of this string buffer.
reverse() | The character sequence contained in this string buffer is replaced by the reverse of the sequence.
setCharAt(int, char) | The character at the specified index of this string buffer is set to ch.
setLength(int) | Sets the length of this String buffer.
toString() | Converts to a string representing the data in this string buffer.


 StringBuffer.StringBuffer

StringBuffer.StringBuffer

Class Overview | Class Members | This Package | All Packages

Syntax 1
public StringBuffer()
Description
Constructs a string buffer with no characters in it and an initial capacity of 16 characters.

Syntax 2
public StringBuffer( int length )
Parameters
length
the initial capacity.
Description
Constructs a string buffer with no characters in it and an initial capacity specified by the length argument.

Exceptions
NegativeArraySizeException if the length argument is less than 0.

Syntax 3
public StringBuffer( String str )
Parameters
str
the initial contents of the buffer.
Description
Constructs a string buffer so that it represents the same sequence of characters as the string argument. The initial capacity of the string buffer is 16 plus the length of the string argument.


 StringBuffer.append

StringBuffer.append

Class Overview | Class Members | This Package | All Packages

Syntax 1
public synchronized StringBuffer append( Object obj )
Parameters
obj
an Object.
Returns
this string buffer.
Description
Appends the string representation of the Object argument to this string buffer.

The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string buffer.

See Also
valueOf, append

Syntax 2
public synchronized StringBuffer append( String str )
Parameters
str
a string.
Returns
this string buffer.
Description
Appends the string to this string buffer.

The characters of the String argument are appended, in order, to the contents of this string buffer, increasing the length of this string buffer by the length of the argument.

Syntax 3
public synchronized StringBuffer append( char str[] )
Parameters
str
the characters to be appended.
Returns
this string buffer.
Description
Appends the string representation of the char array argument to this string buffer.

The characters of the array argument are appended, in order, to the contents of this string buffer. The length of this string buffer increases by the length of the argument.

Syntax 4
public synchronized StringBuffer append( char str[], int offset, int len )
Parameters
str
the characters to be appended.
offset
the index of the first character to append.
len
the number of characters to append.
Returns
this string buffer.
Description
Appends the string representation of a subarray of the char array argument to this string buffer.

Characters of the character array str, starting at index offset, are appended, in order, to the contents of this string buffer. The length of this string buffer increases by the value of len.

Syntax 5
public StringBuffer append( boolean b )
Parameters
b
a boolean.
Returns
this string buffer.
Description
Appends the string representation of the boolean argument to the string buffer.

The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string buffer.

See Also
valueOf, append

Syntax 6
public synchronized StringBuffer append( char c )
Parameters
ch
a char.
Returns
this string buffer.
Description
Appends the string representation of the char argument to this string buffer.

The argument is appended to the contents of this string buffer. The length of this string buffer increases by 1.

Syntax 7
public StringBuffer append( int i )
Parameters
i
an int.
Returns
this string buffer.
Description
Appends the string representation of the int argument to this string buffer.

The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string buffer.

See Also
valueOf, append

Syntax 8
public StringBuffer append( long l )
Parameters
l
a long.
Returns
this string buffer.
Description
Appends the string representation of the long argument to this string buffer.

The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string buffer.

See Also
valueOf, append

Syntax 9
public StringBuffer append( float f )
Parameters
f
a float.
Returns
this string buffer.
Description
Appends the string representation of the float argument to this string buffer.

The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string buffer.

See Also
valueOf, append

Syntax 10
public StringBuffer append( double d )
Parameters
d
a double.
Returns
this string buffer.
Description
Appends the string representation of the double argument to this string buffer.

The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string buffer.

See Also
valueOf, append


 StringBuffer.capacity

StringBuffer.capacity

Class Overview | Class Members | This Package | All Packages

Syntax
public int capacity()
Returns
the current capacity of this string buffer.
Description
Returns the current capacity of the String buffer. The capacity is the amount of storage available for newly inserted characters; beyond which an allocation will occur.


 StringBuffer.charAt

StringBuffer.charAt

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized char charAt( int index )
Parameters
index
the index of the desired character.
Returns
the character at the specified index of this string buffer.
Description
Returns the character at a specific index in this string buffer.

The first character of a string buffer is at index 0, the next at index 1, and so on, for array indexing.

The index argument must be greater than or equal to 0, and less than the length of this string buffer.

Exceptions
StringIndexOutOfBoundsException if the index is invalid.
See Also
length


 StringBuffer.ensureCapacity

StringBuffer.ensureCapacity

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void ensureCapacity( int minimumCapacity )
Parameters
minimumCapacity
the minimum desired capacity.
Description
Ensures that the capacity of the buffer is at least equal to the specified minimum. If the current capacity of this string buffer is less than the argument, then a new internal buffer is allocated with greater capacity. The new capacity is the larger of:
  • The minimumCapacity argument.
  • Twice the old capacity, plus 2.
If the minimumCapacity argument is nonpositive, this method takes no action and simply returns.


 StringBuffer.getChars

StringBuffer.getChars

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void getChars( int srcBegin, int srcEnd, char dst[], int dstBegin )
Parameters
srcBegin
start copying at this offset in the string buffer.
srcEnd
stop copying at this offset in the string buffer.
dst
the array to copy the data into.
dstBegin
offset into dst.
Description
Characters are copied from this string buffer into the destination character array dst. The first character to be copied is at index srcBegin; the last character to be copied is at index srcEnd-1. The total number of characters to be copied is srcEnd-srcBegin. The characters are copied into the subarray of dst starting at index dstBegin and ending at index:

     dstbegin + (srcEnd-srcBegin) - 1

Exceptions
StringIndexOutOfBoundsException if there is an invalid index into the buffer.


 StringBuffer.insert

StringBuffer.insert

Class Overview | Class Members | This Package | All Packages

Syntax 1
public synchronized StringBuffer insert( int offset, Object obj )
Parameters
offset
the offset.
b
an Object.
Returns
this string buffer.
Description
Inserts the string representation of the Object argument into this string buffer.

The second argument is converted to a string as if by the method String.valueOf, and the characters of that string are then inserted into this string buffer at the indicated offset.

The offset argument must be greater than or equal to 0, and less than or equal to the length of this string buffer.

Exceptions
StringIndexOutOfBoundsException if the offset is invalid.
See Also
valueOf, insert, length

Syntax 2
public synchronized StringBuffer insert( int offset, String str )
Parameters
offset
the offset.
str
a string.
Returns
this string buffer.
Description
Inserts the string into this string buffer.

The characters of the String argument are inserted, in order, into this string buffer at the indicated offset. The length of this string buffer is increased by the length of the argument.

The offset argument must be greater than or equal to 0, and less than or equal to the length of this string buffer.

Exceptions
StringIndexOutOfBoundsException if the offset is invalid.
See Also
length

Syntax 3
public synchronized StringBuffer insert( int offset, char str[] )
Parameters
offset
the offset.
ch
a character array.
Returns
this string buffer.
Description
Inserts the string representation of the char array argument into this string buffer.

The characters of the array argument are inserted into the contents of this string buffer at the position indicated by offset. The length of this string buffer increases by the length of the argument.

Exceptions
StringIndexOutOfBoundsException if the offset is invalid.

Syntax 4
public StringBuffer insert( int offset, boolean b )
Parameters
offset
the offset.
b
a boolean.
Returns
this string buffer.
Description
Inserts the string representation of the boolean argument into this string buffer.

The second argument is converted to a string as if by the method String.valueOf, and the characters of that string are then inserted into this string buffer at the indicated offset.

The offset argument must be greater than or equal to 0, and less than or equal to the length of this string buffer.

Exceptions
StringIndexOutOfBoundsException if the offset is invalid.
See Also
valueOf, insert, length

Syntax 5
public synchronized StringBuffer insert( int offset, char c )
Parameters
offset
the offset.
ch
a char.
Returns
this string buffer.
Description
Inserts the string representation of the char argument into this string buffer.

The second argument is inserted into the contents of this string buffer at the position indicated by offset. The length of this string buffer increases by one.

The offset argument must be greater than or equal to 0, and less than or equal to the length of this string buffer.

Exceptions
StringIndexOutOfBoundsException if the offset is invalid.
See Also
length

Syntax 6
public StringBuffer insert( int offset, int i )
Parameters
offset
the offset.
b
an int.
Returns
this string buffer.
Description
Inserts the string representation of the second int argument into this string buffer.

The second argument is converted to a string as if by the method String.valueOf, and the characters of that string are then inserted into this string buffer at the indicated offset.

The offset argument must be greater than or equal to 0, and less than or equal to the length of this string buffer.

Exceptions
StringIndexOutOfBoundsException if the offset is invalid.
See Also
valueOf, insert, length

Syntax 7
public StringBuffer insert( int offset, long l )
Parameters
offset
the offset.
b
a long.
Returns
this string buffer.
Description
Inserts the string representation of the long argument into this string buffer.

The second argument is converted to a string as if by the method String.valueOf, and the characters of that string are then inserted into this string buffer at the indicated offset.

The offset argument must be greater than or equal to 0, and less than or equal to the length of this string buffer.

Exceptions
StringIndexOutOfBoundsException if the offset is invalid.
See Also
valueOf, insert, length

Syntax 8
public StringBuffer insert( int offset, float f )
Parameters
offset
the offset.
b
a float.
Returns
this string buffer.
Description
Inserts the string representation of the float argument into this string buffer.

The second argument is converted to a string as if by the method String.valueOf, and the characters of that string are then inserted into this string buffer at the indicated offset.

The offset argument must be greater than or equal to 0, and less than or equal to the length of this string buffer.

Exceptions
StringIndexOutOfBoundsException if the offset is invalid.
See Also
valueOf, insert, length

Syntax 9
public StringBuffer insert( int offset, double d )
Parameters
offset
the offset.
b
a double.
Returns
this string buffer.
Description
Inserts the string representation of the double argument into this string buffer.

The second argument is converted to a string as if by the method String.valueOf, and the characters of that string are then inserted into this string buffer at the indicated offset.

The offset argument must be greater than or equal to 0, and less than or equal to the length of this string buffer.

Exceptions
StringIndexOutOfBoundsException if the offset is invalid.
See Also
valueOf, insert, length


 StringBuffer.length

StringBuffer.length

Class Overview | Class Members | This Package | All Packages

Syntax
public int length()
Returns
the number of characters in this string buffer.
Description
Returns the length (character count) of this string buffer.


 StringBuffer.reverse

StringBuffer.reverse

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized StringBuffer reverse()
Returns
this string buffer.
Description
The character sequence contained in this string buffer is replaced by the reverse of the sequence.


 StringBuffer.setCharAt

StringBuffer.setCharAt

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setCharAt( int index, char ch )
Parameters
index
the index of the character to modify.
ch
the new character.
Description
The character at the specified index of this string buffer is set to ch.

The offset argument must be greater than or equal to 0, and less than the length of this string buffer.

Exceptions
StringIndexOutOfBoundsException if the index is invalid.
See Also
length


 StringBuffer.setLength

StringBuffer.setLength

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setLength( int newLength )
Parameters
newLength
the new length of the buffer.
Description
Sets the length of this String buffer. If the newLength argument is less than the current length of the string buffer, the string buffer is truncated to contain exactly the number of characters given by the newLength argument.

If the newLength argument is greater than or equal to the current length, sufficient null characters ('\u0000') are appended to the string buffer so that length becomes the newLength argument.

The newLength argument must be greater than or equal to 0.

Exceptions
StringIndexOutOfBoundsException if the newLength argument is invalid.
See Also
length


 StringBuffer.toString

StringBuffer.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string representation of the string buffer.
Description
Converts to a string representing the data in this string buffer. A new String object is allocated and initialized to contain the character sequence currently represented by this string buffer. This String is then returned. Subsequent changes to the string buffer do not affect the contents of the String.

Overrides
toString in class Object


 Class StringIndexOutOfBoundsException

Class java.lang.StringIndexOutOfBoundsException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.lang.RuntimeException
                           |
                           +----java.lang.IndexOutOfBoundsException
                                   |
                                   +----java.lang.StringIndexOutOfBoundsException

public class StringIndexOutOfBoundsException
extends IndexOutOfBoundsException

Thrown by the charAt method in class String and by other String methods to indicate that an index is either negative or greater than or equal to the size of the string.

See Also:
charAt


 StringIndexOutOfBoundsException Members

StringIndexOutOfBoundsException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
StringIndexOutOfBoundsException() | Constructs a StringIndexOutOfBoundsException with no detail message.
StringIndexOutOfBoundsException(int) | Constructs a new StringIndexOutOfBoundsException class with an argument indicating the illegal index.
StringIndexOutOfBoundsException(String) | Constructs a StringIndexOutOfBoundsException with the specified detail message.


 StringIndexOutOfBoundsException.StringIndexOutOfBoundsException

StringIndexOutOfBoundsException.StringIndexOutOfBoundsException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public StringIndexOutOfBoundsException()
Description
Constructs a StringIndexOutOfBoundsException with no detail message.

Syntax 2
public StringIndexOutOfBoundsException( String s )
Parameters
s
the detail message.
Description
Constructs a StringIndexOutOfBoundsException with the specified detail message.

Syntax 3
public StringIndexOutOfBoundsException( int index )
Parameters
index
the illegal index.
Description
Constructs a new StringIndexOutOfBoundsException class with an argument indicating the illegal index.


 Class System

Class java.lang.System

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.System

public final class System
extends Object

The System class contains several useful class fields and methods. It cannot be instantiated.

Among the facilities provided by the System class are standard input, standard output, and error output streams; access to externally defined "properties"; a means of loading files and libraries; and a utility method for quickly copying a portion of an array.


 System Members

System Members

Class Overview | This Package | All Packages

Fields
Name | Description
err | The "standard" error output stream.
in | The "standard" input stream.
out | The "standard" output stream.

Methods
Name | Description
arraycopy(Object, int, Object, int, int) | Copies an array from the specified source array, beginning at the specified position, to the specified position of the destination array.
currentTimeMillis() | Returns the current time in milliseconds.
exit(int) | Terminates the currently running Java Virtual Machine.
gc() | Runs the garbage collector.
getenv(String) | Gets an environment variable. Deprecated.
getProperties() | Determines the current system properties.
getProperty(String) | Gets the system property indicated by the specified key.
getProperty(String, String) | Gets the system property indicated by the specified key.
getSecurityManager() | Gets the system security interface.
identityHashCode(Object) | Returns the same hashcode for the given object as would be returned by the default method hashCode(), whether or not the given object's class overrides hashCode().
load(String) | Loads the specified filename as a dynamic library.
loadLibrary(String) | Loads the system library specified by the libname argument.
runFinalization() | Runs the finalization methods of any objects pending finalization.
runFinalizersOnExit(boolean) | Enable or disable finalization on exit; doing so specifies that the finalizers of all objects that have finalizers that have not yet been automatically invoked are to be run before the Java runtime exits.
setErr(PrintStream) | Reassigns the "standard" error output stream.
setIn(InputStream) | Reassigns the "standard" input stream.
setOut(PrintStream) | Reassigns the "standard" output stream.
setProperties(Properties) | Sets the system properties to the Properties argument.
setSecurityManager(SecurityManager) | Sets the System security.


 System.err

System.err

Class Overview | Class Members | This Package | All Packages

Syntax
public static final PrintStream err
Description
The "standard" error output stream. This stream is already open and ready to accept output data.

Typically this stream corresponds to display output or another output destination specified by the host environment or user. By convention, this output stream is used to display error messages or other information that should come to the immediate attention of a user even if the principal output stream, the value of the variable out, has been redirected to a file or other destination that is typically not continuously monitored.


 System.in

System.in

Class Overview | Class Members | This Package | All Packages

Syntax
public static final InputStream in
Description
The "standard" input stream. This stream is already open and ready to supply input data. Typically this stream corresponds to keyboard input or another input source specified by the host environment or user.


 System.out

System.out

Class Overview | Class Members | This Package | All Packages

Syntax
public static final PrintStream out
Description
The "standard" output stream. This stream is already open and ready to accept output data. Typically this stream corresponds to display output or another output destination specified by the host environment or user.

For simple stand-alone Java applications, a typical way to write a line of output data is:

    System.out.println(data)

See the println methods in class PrintStream.

See Also
println, println, println, println, println, println, println, println, println, println


 System.arraycopy

System.arraycopy

Class Overview | Class Members | This Package | All Packages

Syntax
public static native void arraycopy( Object src, int src_position, Object dst, int dst_position, int length )
Parameters
src:
the source array.
srcpos
start position in the source array.
dest
the destination array.
destpos
start position in the destination data.
length
the number of array elements to be copied.
Description
Copies an array from the specified source array, beginning at the specified position, to the specified position of the destination array. A subsequence of array components are copied from the source array referenced by src to the destination array referenced by dst. The number of components copied is equal to the length argument. The components at positions srcOffset through srcOffset+length-1 in the source array are copied into positions dstOffset through dstOffset+length-1, respectively, of the destination array.

If the src and dst arguments refer to the same array object, then the copying is performed as if the components at positions srcOffset through srcOffset+length-1 were first copied to a temporary array with length components and then the contents of the temporary array were copied into positions dstOffset through dstOffset+length-1 of the argument array.

If any of the following is true, an ArrayStoreException is thrown and the destination is not modified:

  • The src argument refers to an object that is not an array.
  • The dst argument refers to an object that is not an array.
  • The src argument and dst argument refer to arrays whose component types are different primitive types.
  • The src argument refers to an array with a primitive component type and the dst argument refers to an array with a reference component type.
  • The src argument refers to an array with a reference component type and the dst argument refers to an array with a primitive component type.

Otherwise, if any of the following is true, an ArrayIndexOutOfBoundsException is thrown and the destination is not modified:

  • The srcOffset argument is negative.
  • The dstOffset argument is negative.
  • The length argument is negative.
  • srcOffset+length is greater than src.length, the length of the source array.
  • dstOffset+length is greater than dst.length, the length of the destination array.

Otherwise, if any actual component of the source array from position srcOffset through srcOffset+length-1 cannot be converted to the component type of the destination array by assignment conversion, an ArrayStoreException is thrown. In this case, let k be the smallest nonnegative integer less than length such that src[srcOffset+k] cannot be converted to the component type of the destination array; when the exception is thrown, source array components from positions srcOffset through srcOffset+k-1 will already have been copied to destination array positions dstOffset through dstOffset+k-1 and no other positions of the destination array will have been modified.

Exceptions
ArrayIndexOutOfBoundsException if copying would cause access of data outside array bounds.
Exceptions
ArrayStoreException if an element in the src array could not be stored into the dest array because of a type mismatch.


 System.currentTimeMillis

System.currentTimeMillis

Class Overview | Class Members | This Package | All Packages

Syntax
public static native long currentTimeMillis()
Returns
the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC.
Description
Returns the current time in milliseconds.

See the description of the class Date for a discussion of slight discrepancies that may arise between "computer time" and coordinated universal time (UTC).

See Also
Date


 System.exit

System.exit

Class Overview | Class Members | This Package | All Packages

Syntax
public static void exit( int status )
Parameters
status
exit status.
Description
Terminates the currently running Java Virtual Machine. The argument serves as a status code; by convention, a nonzero status code indicates abnormal termination.

This method calls the exit method in class Runtime. This method never returns normally.

Exceptions
SecurityException if the current thread cannot exit with the specified status.
See Also
exit


 System.gc

System.gc

Class Overview | Class Members | This Package | All Packages

Syntax
public static void gc()
Description
Runs the garbage collector.

Calling the gc method suggests that the Java Virtual Machine expend effort toward recycling unused objects in order to make the memory they currently occupy available for quick reuse. When control returns from the method call, the Java Virtual Machine has made a best effort to reclaim space from all unused objects.

See Also
gc


 System.getenv

System.getenv

Class Overview | Class Members | This Package | All Packages

Syntax
public static String getenv( String name )
Parameters
the
name of the environment variable.
Returns
the value of the variable, or null if the variable is not defined.
Description
Note: getenv() is deprecated.

Gets an environment variable. An environment variable is a system dependent external variable that has a string value.


 System.getProperties

System.getProperties

Class Overview | Class Members | This Package | All Packages

Syntax
public static Properties getProperties()
Description
Determines the current system properties.

If there is a security manager, its checkPropertiesAccess method is called with no arguments. This may result in a security exception.

The current set of system properties is returned as a Properties object. If there is no current set of system properties, a set of system properties is first created and initialized.

This set of system properties always includes values for the following keys:
Key | Description of Associated Value
java.version | Java version number
java.vendor | Java vendor-specific string
java.vendor.url | Java vendor URL
java.home | Java installation directory
java.class.version | Java class format version number
java.class.path | Java class path
os.name | Operating system name
os.arch | Operating system architecture
os.version | Operating system version
file.separator | File separator ("/" on UNIX)
path.separator | Path separator (":" on UNIX)
line.separator | Line separator ("\n" on UNIX)
user.name | User's account name
user.home | User's home directory
user.dir | User's current working directory

Exceptions
SecurityException if the current thread cannot access the system properties.
See Also
SecurityException, checkPropertiesAccess, Properties


 System.getProperty

System.getProperty

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static String getProperty( String key )
Parameters
key
the name of the system property.
Returns
the string value of the system property, or null if there is no property with that key.
Description
Gets the system property indicated by the specified key.

First, if there is a security manager, its checkPropertyAccess method is called with the key as its argument. This may result in a system exception.

If there is no current set of system properties, a set of system properties is first created and initialized in the same manner as for the getProperties method.

Exceptions
SecurityException if the current thread cannot access the system properties or the specified property.
See Also
SecurityException, checkPropertyAccess, getProperties

Syntax 2
public static String getProperty( String key, String def )
Parameters
key
the name of the system property.
def
a default value.
Returns
the string value of the system property, or the default value if there is no property with that key.
Description
Gets the system property indicated by the specified key.

First, if there is a security manager, its checkPropertyAccess method is called with the key as its argument.

If there is no current set of system properties, a set of system properties is first created and initialized in the same manner as for the getProperties method.

Exceptions
SecurityException if the current thread cannot access the system properties or the specified property.
See Also
checkPropertyAccess, getProperties


 System.getSecurityManager

System.getSecurityManager

Class Overview | Class Members | This Package | All Packages

Syntax
public static SecurityManager getSecurityManager()
Returns
if a security manager has already been established for the current application, then that security manager is returned; otherwise, null is returned.
Description
Gets the system security interface.


 System.identityHashCode

System.identityHashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public static native int identityHashCode( Object x )
Description
Returns the same hashcode for the given object as would be returned by the default method hashCode(), whether or not the given object's class overrides hashCode(). The hashcode for the null reference is zero.


 System.load

System.load

Class Overview | Class Members | This Package | All Packages

Syntax
public static void load( String filename )
Parameters
filename
the file to load.
Description
Loads the specified filename as a dynamic library. The filename argument must be a complete pathname.

This method calls the load method in class Runtime.

Exceptions
SecurityException if the current thread cannot load the specified dynamic library.
Exceptions
UnsatisfiedLinkError if the file does not exist.
See Also
load


 System.loadLibrary

System.loadLibrary

Class Overview | Class Members | This Package | All Packages

Syntax
public static void loadLibrary( String libname )
Parameters
libname
the name of the library.
Description
Loads the system library specified by the libname argument. The manner in which a library name is mapped to the actual system library is system dependent.

Exceptions
SecurityException if the current thread cannot load the specified dynamic library.
Exceptions
UnsatisfiedLinkError if the library does not exist.
See Also
loadLibrary


 System.runFinalization

System.runFinalization

Class Overview | Class Members | This Package | All Packages

Syntax
public static void runFinalization()
Description
Runs the finalization methods of any objects pending finalization.

Calling this method suggests that the Java Virtual Machine expend effort toward running the finalize methods of objects that have been found to be discarded but whose finalize methods have not yet been run. When control returns from the method call, the Java Virtual Machine has made a best effort to complete all outstanding finalizations.

See Also
runFinalization


 System.runFinalizersOnExit

System.runFinalizersOnExit

Class Overview | Class Members | This Package | All Packages

Syntax
public static void runFinalizersOnExit( boolean value )
Description
Enable or disable finalization on exit; doing so specifies that the finalizers of all objects that have finalizers that have not yet been automatically invoked are to be run before the Java runtime exits. By default, finalization on exit is disabled.

See Also
exit, gc


 System.setErr

System.setErr

Class Overview | Class Members | This Package | All Packages

Syntax
public static void setErr( PrintStream err )
Description
Reassigns the "standard" error output stream.


 System.setIn

System.setIn

Class Overview | Class Members | This Package | All Packages

Syntax
public static void setIn( InputStream in )
Description
Reassigns the "standard" input stream.


 System.setOut

System.setOut

Class Overview | Class Members | This Package | All Packages

Syntax
public static void setOut( PrintStream out )
Description
Reassigns the "standard" output stream.


 System.setProperties

System.setProperties

Class Overview | Class Members | This Package | All Packages

Syntax
public static void setProperties( Properties props )
Parameters
props
the new system properties.
Description
Sets the system properties to the Properties argument.

First, if there is a security manager, its checkPropertiesAccess method is called with no arguments. This may result in a security exception.

The argument becomes the current set of system properties for use by the getProperty method. If the argument is null, then the current set of system properties is forgotten.

Exceptions
SecurityException if the current thread cannot set the system properties.
See Also
SecurityException, checkPropertiesAccess


 System.setSecurityManager

System.setSecurityManager

Class Overview | Class Members | This Package | All Packages

Syntax
public static void setSecurityManager( SecurityManager s )
Parameters
s
the security manager.
Description
Sets the System security. If a security manager has already been established for the currently running Java application, a SecurityException is thrown. Otherwise, the argument is established as the current security manager. If the argument is null and no security manager has been established, then no action is taken and the method simply returns.

Exceptions
SecurityException if the security manager has already been set.


 Class Thread

Class java.lang.Thread

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Thread

public class Thread
extends Object
implements Runnable

A thread is a thread of execution in a program. The Java Virtual Machine allows an application to have multiple threads of execution running concurrently.

Every thread has a priority. Threads with higher priority are executed in preference to threads with lower priority. Each thread may or may not also be marked as a daemon. When code running in some thread creates a new Thread object, the new thread has its priority initially set equal to the priority of the creating thread, and is a daemon thread if and only if the creating thread is a daemon.

When a Java Virtual Machine starts up, there is usually a single non-daemon thread (which typically calls the method named main of some designated class). The Java Virtual Machine continues to execute threads until either of the following occurs:

  • The exit method of class Runtime has been called and the security manager has permitted the exit operation to take place.
  • All threads that are not daemon threads have died, either by returning from the call to the run method or by performing the stop method.

There are two ways to create a new thread of execution. One is to declare a class to be a subclass of Thread. This subclass should override the run method of class Thread. An instance of the subclass can then be allocated and started. For example, a thread that computes primes larger than a stated value could be written as follows:

     class PrimeThread extends Thread {
         long minPrime;
         PrimeThread(long minPrime) {
             this.minPrime = minPrime;
         }
         public void run() {
             // compute primes larger than minPrime
              . . .
         }
     }

The following code would then create a thread and start it running:

     PrimeThread p = new PrimeThread(143);
     p.start();

The other way to create a thread is to declare a class that implements the Runnable interface. That class then implements the run method. An instance of the class can then be allocated, passed as an argument when creating Thread, and started. The same example in this other style looks like the following:

     class PrimeRun implements Runnable {
         long minPrime;
         PrimeRun(long minPrime) {
             this.minPrime = minPrime;
         }
         public void run() {
             // compute primes larger than minPrime
              . . .
         }
     }

The following code would then create a thread and start it running:

     PrimeRun p = new PrimeRun(143);
     new Thread(p).start();

Every thread has a name for identification purposes. More than one thread may have the same name. If a name is not specified when a thread is created, a new name is generated for it.

See Also:
Runnable, exit, run, stop


 Thread Members

Thread Members

Class Overview | This Package | All Packages

Fields
Name | Description
MAX_PRIORITY | The maximum priority that a thread can have.
MIN_PRIORITY | The minimum priority that a thread can have.
NORM_PRIORITY | The default priority that is assigned to a thread.

Constructors
Name | Description
Thread() | Allocates a new Thread object.
Thread(Runnable) | Allocates a new Thread object.
Thread(Runnable, String) | Allocates a new Thread object.
Thread(String) | Allocates a new Thread object.
Thread(ThreadGroup, Runnable) | Allocates a new Thread object.
Thread(ThreadGroup, Runnable, String) | Allocates a new Thread object so that it has target as its run object, has the specified name as its name, and belongs to the thread group referred to by group.
Thread(ThreadGroup, String) | Allocates a new Thread object.

Methods
Name | Description
activeCount() | Returns the current number of active threads in this thread group.
checkAccess() | Determines if the currently running thread has permission to modify this thread.
countStackFrames() | Counts the number of stack frames in this thread.
currentThread() | Returns a reference to the currently executing thread object.
destroy() | Destroys this thread, without any cleanup.
dumpStack() | Prints a stack trace of the current thread.
enumerate(Thread[]) | Copies into the specified array every active thread in this thread group and its subgroups.
getName() | Returns this thread's name.
getPriority() | Returns this thread's priority.
getThreadGroup() | Returns this thread's thread group.
interrupt() | Interrupts this thread.
interrupted() | Tests if the current thread has been interrupted.
isAlive() | Tests if this thread is alive.
isDaemon() | Tests if this thread is a daemon thread.
isInterrupted() | Tests if the current thread has been interrupted.
join() | Waits for this thread to die.
join(long) | Waits at most millis milliseconds for this thread to die.
join(long, int) | Waits at most millis milliseconds plus nanos nanoseconds for this thread to die.
resume() | Resumes a suspended thread.
run() | If this thread was constructed using a separate Runnable run object, then that Runnable object's run method is called; otherwise, this method does nothing and returns.
setDaemon(boolean) | Marks this thread as either a daemon thread or a user thread.
setName(String) | Changes the name of this thread to be equal to the argument name.
setPriority(int) | Changes the priority of this thread.
sleep(long) | Causes the currently executing thread to sleep (temporarily cease execution) for the specified number of milliseconds.
sleep(long, int) | Causes the currently executing thread to sleep (cease execution) for the specified number of milliseconds plus the specified number of nanoseconds.
start() | Causes this thread to begin execution; the Java Virtual Machine calls the run method of this thread.
stop() | Forces the thread to stop executing.
stop(Throwable) | Forces the thread to stop executing.
suspend() | Suspends this thread.
toString() | Returns a string representation of this thread, including the thread's name, priority, and thread group.
yield() | Causes the currently executing thread object to temporarily pause and allow other threads to execute.


 Thread.MAX_PRIORITY

Thread.MAX_PRIORITY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int MAX_PRIORITY
Description
The maximum priority that a thread can have.


 Thread.MIN_PRIORITY

Thread.MIN_PRIORITY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int MIN_PRIORITY
Description
The minimum priority that a thread can have.


 Thread.NORM_PRIORITY

Thread.NORM_PRIORITY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int NORM_PRIORITY
Description
The default priority that is assigned to a thread.


 Thread.Thread

Thread.Thread

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Thread()
Description
Allocates a new Thread object. This constructor has the same effect as Thread(null, null, gname), where gname is a newly generated name. Automatically generated names are of the form "Thread-"+n, where n is an integer.

Threads created this way must have overridden their run() method to actually do anything. An example illustrating this method being used follows:

     import java.lang.*;
     class plain01 implements Runnable {
         String name;
         plain01() {
             name = null;
         }
         plain01(String s) {
             name = s;
         }
         public void run() {
             if (name == null)
                 System.out.println("A new thread created");
             else
                 System.out.println("A new thread with name " + name +
                                    " created");
         }
     }
     class threadtest01 {
         public static void main(String args[] ) {
             int failed = 0 ;
             Thread t1 = new Thread();
             if (t1 != null)
                 System.out.println("new Thread() succeed");
             else {
                 System.out.println("new Thread() failed");
                 failed++;
             }
         }
     }

See Also
Thread

Syntax 2
public Thread( Runnable target )
Parameters
target
the object whose run method is called.
Description
Allocates a new Thread object. This constructor has the same effect as Thread(null, target, gname), where gname is a newly generated name. Automatically generated names are of the form "Thread-"+n, where n is an integer.

See Also
Thread

Syntax 3
public Thread( ThreadGroup group, Runnable target )
Parameters
group
the thread group.
target
the object whose run method is called.
Description
Allocates a new Thread object. This constructor has the same effect as Thread(group, target, gname), where gname is a newly generated name. Automatically generated names are of the form "Thread-"+n, where n is an integer.

Exceptions
SecurityException if the current thread cannot create a thread in the specified thread group.
See Also
Thread

Syntax 4
public Thread( String name )
Parameters
name
the name of the new thread.
Description
Allocates a new Thread object. This constructor has the same effect as Thread(null, null, name).

See Also
Thread

Syntax 5
public Thread( ThreadGroup group, String name )
Parameters
group
the thread group.
name
the name of the new thread.
Description
Allocates a new Thread object. This constructor has the same effect as Thread(group, null, name)

Exceptions
SecurityException if the current thread cannot create a thread in the specified thread group.
See Also
Thread

Syntax 6
public Thread( Runnable target, String name )
Parameters
target
the object whose run method is called.
name
the name of the new thread.
Description
Allocates a new Thread object. This constructor has the same effect as Thread(null, target, name).

See Also
Thread

Syntax 7
public Thread( ThreadGroup group, Runnable target, String name )
Parameters
group
the thread group.
target
the object whose run method is called.
name
the name of the new thread.
Description
Allocates a new Thread object so that it has target as its run object, has the specified name as its name, and belongs to the thread group referred to by group.

If group is not null, the checkAccess method of that thread group is called with no arguments; this may result in throwing a SecurityException; if group is null, the new process belongs to the same group as the thread that is creating the new thread.

If the target argument is not null, the run method of the target is called when this thread is started. If the target argument is null, this thread's run method is called when this thread is started.

The priority of the newly created thread is set equal to the priority of the thread creating it, that is, the currently running thread. The method setPriority may be used to change the priority to a new value.

The newly created thread is initially marked as being a daemon thread if and only if the thread creating it is currently marked as a daemon thread. The method setDaemon may be used to change whether or not a thread is a daemon.

Exceptions
SecurityException if the current thread cannot create a thread in the specified thread group.
See Also
run, run, setDaemon, setPriority, checkAccess


 Thread.activeCount

Thread.activeCount

Class Overview | Class Members | This Package | All Packages

Syntax
public static int activeCount()
Returns
the current number of threads in this thread's thread group.
Description
Returns the current number of active threads in this thread group.


 Thread.checkAccess

Thread.checkAccess

Class Overview | Class Members | This Package | All Packages

Syntax
public void checkAccess()
Description
Determines if the currently running thread has permission to modify this thread.

If there is a security manager, its checkAccess method is called with this thread as its argument. This may result in throwing a SecurityException.

Exceptions
SecurityException if the current thread is not allowed to access this thread.
See Also
checkAccess


 Thread.countStackFrames

Thread.countStackFrames

Class Overview | Class Members | This Package | All Packages

Syntax
public native int countStackFrames()
Returns
the number of stack frames in this thread.
Description
Counts the number of stack frames in this thread. The thread must be suspended.

Exceptions
IllegalThreadStateException if this thread is not suspended.


 Thread.currentThread

Thread.currentThread

Class Overview | Class Members | This Package | All Packages

Syntax
public static native Thread currentThread()
Returns
the currently executing thread.
Description
Returns a reference to the currently executing thread object.


 Thread.destroy

Thread.destroy

Class Overview | Class Members | This Package | All Packages

Syntax
public void destroy()
Description
Destroys this thread, without any cleanup. Any monitors it has locked remain locked. (This method is not implemented in Java 1.0.2.)


 Thread.dumpStack

Thread.dumpStack

Class Overview | Class Members | This Package | All Packages

Syntax
public static void dumpStack()
Description
Prints a stack trace of the current thread. This method is used only for debugging.

See Also
printStackTrace


 Thread.enumerate

Thread.enumerate

Class Overview | Class Members | This Package | All Packages

Syntax
public static int enumerate( Thread tarray[] )
Returns
the number of threads put into the array.
Description
Copies into the specified array every active thread in this thread group and its subgroups. This method simply calls the enumerate method of this thread's thread group with the array argument.

See Also
enumerate


 Thread.getName

Thread.getName

Class Overview | Class Members | This Package | All Packages

Syntax
public final String getName()
Returns
this thread's name.
Description
Returns this thread's name.

See Also
setName


 Thread.getPriority

Thread.getPriority

Class Overview | Class Members | This Package | All Packages

Syntax
public final int getPriority()
Returns
this thread's name.
Description
Returns this thread's priority.

See Also
setPriority


 Thread.getThreadGroup

Thread.getThreadGroup

Class Overview | Class Members | This Package | All Packages

Syntax
public final ThreadGroup getThreadGroup()
Returns
this thread's thread group.
Description
Returns this thread's thread group.


 Thread.interrupt

Thread.interrupt

Class Overview | Class Members | This Package | All Packages

Syntax
public void interrupt()
Description
Interrupts this thread.


 Thread.interrupted

Thread.interrupted

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean interrupted()
Returns
true if the current thread has been interrupted; false otherwise.
Description
Tests if the current thread has been interrupted. Note that interrupted is a static method, while isInterrupted is called on the current Thread instance.

See Also
isInterrupted


 Thread.isAlive

Thread.isAlive

Class Overview | Class Members | This Package | All Packages

Syntax
public final native boolean isAlive()
Returns
true if this thread is alive; false otherwise.
Description
Tests if this thread is alive. A thread is alive if it has been started and has not yet died.


 Thread.isDaemon

Thread.isDaemon

Class Overview | Class Members | This Package | All Packages

Syntax
public final boolean isDaemon()
Returns
true if this thread is a daemon thread; false otherwise.
Description
Tests if this thread is a daemon thread.

See Also
setDaemon


 Thread.isInterrupted

Thread.isInterrupted

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isInterrupted()
Returns
true if this thread has been interrupted; false otherwise.
Description
Tests if the current thread has been interrupted. Note that isInterrupted is called on the current Thread instance; by contrast, interrupted is a static method.

See Also
interrupted


 Thread.join

Thread.join

Class Overview | Class Members | This Package | All Packages

Syntax 1
public final synchronized void join( long millis ) throws InterruptedException
Parameters
millis
the time to wait in milliseconds.
Description
Waits at most millis milliseconds for this thread to die. A timeout of 0 means to wait forever.

Exceptions
InterruptedException if another thread has interrupted the current thread.

Syntax 2
public final synchronized void join( long millis, int nanos ) throws InterruptedException
Parameters
millis
the time to wait in milliseconds.
nanos
0-999999 additional nanoseconds to wait.
Description
Waits at most millis milliseconds plus nanos nanoseconds for this thread to die.

Exceptions
IllegalArgumentException if the value of millis is negative the value of nanos is not in the range 0-999999.
Exceptions
InterruptedException if another thread has interrupted the current thread.

Syntax 3
public final void join() throws InterruptedException
Description
Waits for this thread to die.

Exceptions
InterruptedException if another thread has interrupted the current thread.


 Thread.resume

Thread.resume

Class Overview | Class Members | This Package | All Packages

Syntax
public final void resume()
Description
Resumes a suspended thread.

First, the checkAccess method of this thread is called with no arguments. This may result in throwing a SecurityException(in the current thread).

If the thread is alive but suspended, it is resumed and is permitted to make progress in its execution.

Exceptions
SecurityException if the current thread cannot modify this thread.
See Also
checkAccess, isAlive


 Thread.run

Thread.run

Class Overview | Class Members | This Package | All Packages

Syntax
public void run()
Description
If this thread was constructed using a separate Runnable run object, then that Runnable object's run method is called; otherwise, this method does nothing and returns.

Subclasses of Thread should override this method.

See Also
start, stop, Thread, run


 Thread.setDaemon

Thread.setDaemon

Class Overview | Class Members | This Package | All Packages

Syntax
public final void setDaemon( boolean on )
Parameters
on
if true, marks this thread as a daemon thread.
Description
Marks this thread as either a daemon thread or a user thread. The Java Virtual Machine exits when the only threads running are all daemon threads.

This method must be called before the thread is started.

Exceptions
IllegalThreadStateException if this thread is active.
See Also
isDaemon


 Thread.setName

Thread.setName

Class Overview | Class Members | This Package | All Packages

Syntax
public final void setName( String name )
Parameters
name
the new name for this thread.
Description
Changes the name of this thread to be equal to the argument name.

First the checkAccess method of this thread is called with no arguments. This may result in throwing a SecurityException.

Exceptions
SecurityException if the current thread cannot modify this thread.
See Also
checkAccess, getName


 Thread.setPriority

Thread.setPriority

Class Overview | Class Members | This Package | All Packages

Syntax
public final void setPriority( int newPriority )
Description
Changes the priority of this thread.

First the checkAccess method of this thread is called with no arguments. This may result in throwing a SecurityException.

Otherwise, the priority of this thread is set to the smaller of the specified newPriority and the maximum permitted priority of the thread's thread group.

Exceptions
IllegalArgumentException If the priority is not in the range MIN_PRIORITY to MAX_PRIORITY.
Exceptions
SecurityException if the current thread cannot modify this thread.
See Also
checkAccess, getPriority, getThreadGroup, MAX_PRIORITY, MIN_PRIORITY, getMaxPriority


 Thread.sleep

Thread.sleep

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static native void sleep( long millis ) throws InterruptedException
Parameters
millis
the length of time to sleep in milliseconds.
Description
Causes the currently executing thread to sleep (temporarily cease execution) for the specified number of milliseconds. The thread does not lose ownership of any monitors.

Exceptions
InterruptedException if another thread has interrupted this thread.
See Also
notify

Syntax 2
public static void sleep( long millis, int nanos ) throws InterruptedException
Parameters
millis
the length of time to sleep in milliseconds.
nanos
0-999999 additional nanoseconds to sleep.
Description
Causes the currently executing thread to sleep (cease execution) for the specified number of milliseconds plus the specified number of nanoseconds. The thread does not lose ownership of any monitors.

Exceptions
IllegalArgumentException if the value of millis is negative or the value of nanos is not in the range 0-999999.
Exceptions
InterruptedException if another thread has interrupted this thread.
See Also
notify


 Thread.start

Thread.start

Class Overview | Class Members | This Package | All Packages

Syntax
public native synchronized void start()
Description
Causes this thread to begin execution; the Java Virtual Machine calls the run method of this thread.

The result is that two threads are running concurrently: the current thread (which returns from the call to the start method) and the other thread (which executes its run method).

Exceptions
IllegalThreadStateException if the thread was already started.
See Also
run, stop


 Thread.stop

Thread.stop

Class Overview | Class Members | This Package | All Packages

Syntax 1
public final void stop()
Description
Forces the thread to stop executing.

First, the checkAccess method of this thread is called with no arguments. This may result in throwing a SecurityException (in the current thread).

The thread represented by this thread is forced to stop whatever it is doing abnormally and to throw a newly created ThreadDeath object as an exception.

It is permitted to stop a thread that has not yet been started. If the thread is eventually started, it immediately terminates.

An application should not normally try to catch ThreadDeath unless it must do some extraordinary cleanup operation (note that the throwing of ThreadDeath causes finally clauses of try statements to be executed before the thread officially dies). If a catch clause catches a ThreadDeath object, it is important to rethrow the object so that the thread actually dies.

The top-level error handler that reacts to otherwise uncaught exceptions does not print out a message or otherwise notify the application if the uncaught exception is an instance of ThreadDeath.

Exceptions
SecurityException if the current thread cannot modify this thread.
See Also
checkAccess, run, start, ThreadDeath, uncaughtException

Syntax 2
public final synchronized void stop( Throwable o )
Parameters
obj
the Throwable object to be thrown.
Description
Forces the thread to stop executing.

First, the checkAccess method of this thread is called with no arguments. This may result in throwing a SecurityException (in the current thread).

If the argument obj is null, a NullPointerException is thrown (in the current thread).

The thread represented by this thread is forced to complete whatever it is doing abnormally and to throw the Throwable object obj as an exception. This is an unusual action to take; normally, the stop method that takes no arguments should be used.

It is permitted to stop a thread that has not yet been started. If the thread is eventually started, it immediately terminates.

Exceptions
SecurityException if the current thread cannot modify this thread.
See Also
checkAccess, run, start, stop


 Thread.suspend

Thread.suspend

Class Overview | Class Members | This Package | All Packages

Syntax
public final void suspend()
Description
Suspends this thread.

First, the checkAccess method of this thread is called with no arguments. This may result in throwing a SecurityException (in the current thread).

If the thread is alive, it is suspended and makes no further progress unless and until it is resumed.

Exceptions
SecurityException if the current thread cannot modify this thread.
See Also
checkAccess, isAlive


 Thread.toString

Thread.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string representation of this thread.
Description
Returns a string representation of this thread, including the thread's name, priority, and thread group.

Overrides
toString in class Object


 Thread.yield

Thread.yield

Class Overview | Class Members | This Package | All Packages

Syntax
public static native void yield()
Description
Causes the currently executing thread object to temporarily pause and allow other threads to execute.


 Class ThreadDeath

Class java.lang.ThreadDeath

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Error
                   |
                   +----java.lang.ThreadDeath

public class ThreadDeath
extends Error

An instance of ThreadDeath is thrown in the victim thread when the stop method with zero arguments in class Thread is called.

An application should catch instances of this class only if it must clean up after being terminated asynchronously. If ThreadDeath is caught by a method, it is important that it be rethrown so that the thread actually dies.

The top-level error handler does not print out a message if ThreadDeath is never caught.

The class ThreadDeath is specifically a subclass of Error rather than Exception, even though it is a "normal occurrence", because many applications catch all occurrences of Exception and then discard the exception.

See Also:
stop


 ThreadDeath Members

ThreadDeath Members

Class Overview | This Package | All Packages

Constructors
Name | Description
ThreadDeath() |


 ThreadDeath.ThreadDeath

ThreadDeath.ThreadDeath

Class Overview | Class Members | This Package | All Packages

Syntax
public ThreadDeath()


 Class ThreadGroup

Class java.lang.ThreadGroup

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.ThreadGroup

public class ThreadGroup
extends Object

A thread group represents a set of threads. In addition, a thread group can also include other thread groups. The thread groups form a tree in which every thread group except the initial thread group has a parent.

A thread is allowed to access information about its own thread group, but not to access information about its thread group's parent thread group or any other thread groups.


 ThreadGroup Members

ThreadGroup Members

Class Overview | This Package | All Packages

Constructors
Name | Description
ThreadGroup(String) | Constructs a new thread group.
ThreadGroup(ThreadGroup, String) | Creates a new thread group.

Methods
Name | Description
activeCount() | Returns an estimate of the number of active threads in this thread group.
activeGroupCount() | Returns an estimate of the number of active groups in this thread group.
allowThreadSuspension(boolean) | Used by VM to control lowmem implicit suspension.
checkAccess() | Determines if the currently running thread has permission to modify this thread group.
destroy() | Destroys this thread group and all of its subgroups.
enumerate(Thread[]) | Copies into the specified array every active thread in this thread group and its subgroups.
enumerate(Thread[], boolean) | Copies into the specified array every active thread in this thread group.
enumerate(ThreadGroup[]) | Copies into the specified array references to every active subgroup in this thread group.
enumerate(ThreadGroup[], boolean) | Copies into the specified array references to every active subgroup in this thread group.
getMaxPriority() | Returns the maximum priority of this thread group.
getName() | Returns the name of this thread group.
getParent() | Returns the parent of this thread group.
isDaemon() | Tests if this thread group is a daemon thread group.
isDestroyed() | Tests if this thread group has been destroyed.
list() | Prints information about this thread group to the standard output.
parentOf(ThreadGroup) | Tests if this thread group is either the thread group argument or one of its ancestor thread groups.
resume() | Resumes all processes in this thread group.
setDaemon(boolean) | Changes the daemon status of this thread group.
setMaxPriority(int) | Sets the maximum priority of the group.
stop() | Stops all processes in this thread group.
suspend() | Suspends all processes in this thread group.
toString() | Returns a string representation of this Thread group.
uncaughtException(Thread, Throwable) | Called by the Java Virtual Machine when a thread in this thread group stops because of an uncaught exception.


 ThreadGroup.ThreadGroup

ThreadGroup.ThreadGroup

Class Overview | Class Members | This Package | All Packages

Syntax 1
public ThreadGroup( String name )
Parameters
name
the name of the new thread group.
Description
Constructs a new thread group. The parent of this new group is the thread group of the currently running thread.

Syntax 2
public ThreadGroup( ThreadGroup parent, String name )
Parameters
parent
the parent thread group.
name
the name of the new thread group.
Description
Creates a new thread group. The parent of this new group is the specified thread group.

The checkAccess method of the parent thread group is called with no arguments; this may result in a security exception.

Exceptions
NullPointerException if the thread group argument is null.
Exceptions
SecurityException if the current thread cannot create a thread in the specified thread group.
See Also
SecurityException, checkAccess


 ThreadGroup.activeCount

ThreadGroup.activeCount

Class Overview | Class Members | This Package | All Packages

Syntax
public int activeCount()
Returns
the number of active threads in this thread group and in any other thread group that has this thread group as an ancestor.
Description
Returns an estimate of the number of active threads in this thread group.


 ThreadGroup.activeGroupCount

ThreadGroup.activeGroupCount

Class Overview | Class Members | This Package | All Packages

Syntax
public int activeGroupCount()
Returns
the number of active thread groups with this thread group as an ancestor.
Description
Returns an estimate of the number of active groups in this thread group.


 ThreadGroup.allowThreadSuspension

ThreadGroup.allowThreadSuspension

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean allowThreadSuspension( boolean b )
Description
Used by VM to control lowmem implicit suspension.


 ThreadGroup.checkAccess

ThreadGroup.checkAccess

Class Overview | Class Members | This Package | All Packages

Syntax
public final void checkAccess()
Description
Determines if the currently running thread has permission to modify this thread group.

If there is a security manager, its checkAccess method is called with this thread group as its argument. This may result in throwing a SecurityException.

Exceptions
SecurityException if the current thread is not allowed to access this thread group.
See Also
checkAccess


 ThreadGroup.destroy

ThreadGroup.destroy

Class Overview | Class Members | This Package | All Packages

Syntax
public final void destroy()
Description
Destroys this thread group and all of its subgroups. This thread group must be empty, indicating that all threads that had been in this thread group have since stopped.

Exceptions
IllegalThreadStateException if the thread group is not empty or if the thread group has already been destroyed.
Exceptions
SecurityException if the current thread cannot modify this thread group.


 ThreadGroup.enumerate

ThreadGroup.enumerate

Class Overview | Class Members | This Package | All Packages

Syntax 1
public int enumerate( Thread list[] )
Parameters
list
an array into which to place the list of threads.
Returns
the number of threads put into the array.
Description
Copies into the specified array every active thread in this thread group and its subgroups.

An application should use the activeCount method to get an estimate of how big the array should be. If the array is too short to hold all the threads, the extra threads are silently ignored.

See Also
activeCount

Syntax 2
public int enumerate( Thread list[], boolean recurse )
Parameters
list
an array into which to place the list of threads.
recurse
a flag indicating whether also to include threads in thread groups that are subgroups of this thread group.
Returns
the number of threads placed into the array.
Description
Copies into the specified array every active thread in this thread group. If the recurse flag is true, references to every active thread in this thread's subgroups are also included. If the array is too short to hold all the threads, the extra threads are silently ignored.

An application should use the activeCount method to get an estimate of how big the array should be.

See Also
activeCount


 ThreadGroup.enumerate

ThreadGroup.enumerate

Class Overview | Class Members | This Package | All Packages

Syntax
public int enumerate( ThreadGroup list[] )
Parameters
list
an array into which to place the list of thread groups.
Returns
the number of thread groups put into the array.
Description
Copies into the specified array references to every active subgroup in this thread group.

An application should use the activeGroupCount method to get an estimate of how big the array should be. If the array is too short to hold all the thread groups, the extra thread groups are silently ignored.

See Also
activeGroupCount


 ThreadGroup.enumerate

ThreadGroup.enumerate

Class Overview | Class Members | This Package | All Packages

Syntax
public int enumerate( ThreadGroup list[], boolean recurse )
Parameters
list
an array into which to place the list of threads.
recurse
a flag indicating whether to recursively enumerate all included thread groups.
Returns
the number of thread groups put into the array.
Description
Copies into the specified array references to every active subgroup in this thread group. If the recurse flag is true, references to all active subgroups of the subgroups and so forth are also included.

An application should use the activeGroupCount method to get an estimate of how big the array should be.

See Also
activeGroupCount


 ThreadGroup.getMaxPriority

ThreadGroup.getMaxPriority

Class Overview | Class Members | This Package | All Packages

Syntax
public final int getMaxPriority()
Returns
the maximum priority that a thread in this thread group can have.
Description
Returns the maximum priority of this thread group. Threads that are part of this group cannot have a higher priority than the maximum priority.


 ThreadGroup.getName

ThreadGroup.getName

Class Overview | Class Members | This Package | All Packages

Syntax
public final String getName()
Returns
the name of this thread group.
Description
Returns the name of this thread group.


 ThreadGroup.getParent

ThreadGroup.getParent

Class Overview | Class Members | This Package | All Packages

Syntax
public final ThreadGroup getParent()
Returns
the parent of this thread group. The top-level thread group is the only thread group whose parent is null.
Description
Returns the parent of this thread group.


 ThreadGroup.isDaemon

ThreadGroup.isDaemon

Class Overview | Class Members | This Package | All Packages

Syntax
public final boolean isDaemon()
Returns
true if this thread group is a daemon thread group; false otherwise.
Description
Tests if this thread group is a daemon thread group. A daemon thread group is automatically destroyed when its last thread is stopped or its last thread group is destroyed.


 ThreadGroup.isDestroyed

ThreadGroup.isDestroyed

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized boolean isDestroyed()
Description
Tests if this thread group has been destroyed.


 ThreadGroup.list

ThreadGroup.list

Class Overview | Class Members | This Package | All Packages

Syntax
public void list()
Description
Prints information about this thread group to the standard output. This method is useful only for debugging.


 ThreadGroup.parentOf

ThreadGroup.parentOf

Class Overview | Class Members | This Package | All Packages

Syntax
public final boolean parentOf( ThreadGroup g )
Parameters
g
a thread group.
Returns
true if this thread group is the thread group argument or one of its ancestor thread groups; false otherwise.
Description
Tests if this thread group is either the thread group argument or one of its ancestor thread groups.


 ThreadGroup.resume

ThreadGroup.resume

Class Overview | Class Members | This Package | All Packages

Syntax
public final void resume()
Description
Resumes all processes in this thread group.

First, the checkAccess method of this thread group is called with no arguments; this may result in a security exception.

This method then calls the resume method on all the threads in this thread group and in all of its sub groups.

Exceptions
SecurityException if the current thread is not allowed to access this thread group or any of the threads in the thread group.
See Also
SecurityException, resume, checkAccess


 ThreadGroup.setDaemon

ThreadGroup.setDaemon

Class Overview | Class Members | This Package | All Packages

Syntax
public final void setDaemon( boolean daemon )
Parameters
daemon
if true, marks this thread group as a daemon thread group; otherwise, marks this thread group as normal.
Description
Changes the daemon status of this thread group.

First, the checkAccess method of this thread group is called with no arguments; this may result in a security exception.

A daemon thread group is automatically destroyed when its last thread is stopped or its last thread group is destroyed.

Exceptions
SecurityException if the current thread cannot modify this thread.
See Also
SecurityException, checkAccess


 ThreadGroup.setMaxPriority

ThreadGroup.setMaxPriority

Class Overview | Class Members | This Package | All Packages

Syntax
public final void setMaxPriority( int pri )
Parameters
pri
the new priority of the thread group.
Description
Sets the maximum priority of the group.

First, the checkAccess method of this thread group is called with no arguments; this may result in a security exception.

Threads in the thread group that already have a higher priority are not affected.

Exceptions
SecurityException if the current thread cannot modify this thread group.
See Also
SecurityException, checkAccess


 ThreadGroup.stop

ThreadGroup.stop

Class Overview | Class Members | This Package | All Packages

Syntax
public final void stop()
Description
Stops all processes in this thread group.

First, the checkAccess method of this thread group is called with no arguments; this may result in a security exception.

This method then calls the stop method on all the threads in this thread group and in all of its subgroups.

Exceptions
SecurityException if the current thread is not allowed to access this thread group or any of the threads in the thread group.
See Also
SecurityException, stop, checkAccess


 ThreadGroup.suspend

ThreadGroup.suspend

Class Overview | Class Members | This Package | All Packages

Syntax
public final void suspend()
Description
Suspends all processes in this thread group.

First, the checkAccess method of this thread group is called with no arguments; this may result in a security exception.

This method then calls the suspend method on all the threads in this thread group and in all of its subgroups.

Exceptions
SecurityException if the current thread is not allowed to access this thread group or any of the threads in the thread group.
See Also
SecurityException, suspend, checkAccess


 ThreadGroup.toString

ThreadGroup.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string representation of this thread group.
Description
Returns a string representation of this Thread group.

Overrides
toString in class Object


 ThreadGroup.uncaughtException

ThreadGroup.uncaughtException

Class Overview | Class Members | This Package | All Packages

Syntax
public void uncaughtException( Thread t, Throwable e )
Parameters
t
the thread that is about to exit.
e
the uncaught exception.
Description
Called by the Java Virtual Machine when a thread in this thread group stops because of an uncaught exception.

The uncaughtException method of ThreadGroup does the following:

  • If this thread group has a parent thread group, the uncaughtException method of that parent is called with the same two arguments.
  • Otherwise, this method determines if the Throwable argument is an instance of ThreadDeath. If so, nothing special is done. Otherwise, the Throwable's printStackTrace method is called to print a stack backtrace to the standard error stream.

Applications can override this method in subclasses of ThreadGroup to provide alternative handling of uncaught exceptions.

See Also
err, ThreadDeath, printStackTrace


 Class Throwable

Class java.lang.Throwable

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable

public class Throwable
extends Object
implements Serializable

The Throwable class is the superclass of all errors and exceptions in the Java language. Only objects that are instances of this class (or of one of its subclasses) are thrown by the Java Virtual Machine or can be thrown by the Java throw statement. Similarly, only this class or one of its subclasses can be the argument type in a catch clause.

A Throwable class contains a snapshot of the execution stack of its thread at the time it was created. It can also contain a message string that gives more information about the error.

Here is one example of catching an exception:

     try {
         int a[] = new int[2];
         a[4];
     } catch (ArrayIndexOutOfBoundsException e) {
         System.out.println("exception: " + e.getMessage());
         e.printStackTrace();
     }


 Throwable Members

Throwable Members

Class Overview | This Package | All Packages

Constructors
Name | Description
Throwable() | Constructs a new Throwable with no detail message.
Throwable(String) | Constructs a new Throwable with the specified detail message.

Methods
Name | Description
fillInStackTrace() | Fills in the execution stack trace.
getLocalizedMessage() | Creates a localized description of this Throwable.
getMessage() | Returns the detail message of this throwable object.
printStackTrace() | Prints this Throwable and its backtrace to the standard error stream.
printStackTrace(PrintStream) | Prints this Throwable and its backtrace to the specified print stream.
printStackTrace(PrintWriter) | Prints this Throwable and its backtrace to the specified print writer.
toString() | Returns a short description of this throwable object.


 Throwable.Throwable

Throwable.Throwable

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Throwable()
Description
Constructs a new Throwable with no detail message. The stack trace is automatically filled in.

Syntax 2
public Throwable( String message )
Parameters
message
the detail message.
Description
Constructs a new Throwable with the specified detail message. The stack trace is automatically filled in.


 Throwable.fillInStackTrace

Throwable.fillInStackTrace

Class Overview | Class Members | This Package | All Packages

Syntax
public native Throwable fillInStackTrace()
Returns
this Throwable object.
Description
Fills in the execution stack trace. This method is useful when an application is re-throwing an error or exception. For example:

     try {
         a = b / c;
     } catch(ArithmeticThrowable e) {
         a = Number.MAX_VALUE;
         throw e.fillInStackTrace();
     }

See Also
printStackTrace


 Throwable.getLocalizedMessage

Throwable.getLocalizedMessage

Class Overview | Class Members | This Package | All Packages

Syntax
public String getLocalizedMessage()
Description
Creates a localized description of this Throwable. Subclasses may override this method in order to produce a locale-specific message. For subclasses that do not override this method, the default implementation returns the same result as getMessage().


 Throwable.getMessage

Throwable.getMessage

Class Overview | Class Members | This Package | All Packages

Syntax
public String getMessage()
Returns
the detail message of this Throwable, or null if this Throwable does not have a detail message.
Description
Returns the detail message of this throwable object.


 Throwable.printStackTrace

Throwable.printStackTrace

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void printStackTrace()
Description
Prints this Throwable and its backtrace to the standard error stream.

See Also
err

Syntax 2
public void printStackTrace( PrintStream s )
Description
Prints this Throwable and its backtrace to the specified print stream.

Syntax 3
public void printStackTrace( PrintWriter s )
Description
Prints this Throwable and its backtrace to the specified print writer.


 Throwable.toString

Throwable.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string representation of this Throwable.
Description
Returns a short description of this throwable object.

Overrides
toString in class Object


 Class UnknownError

Class java.lang.UnknownError

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Error
                   |
                   +----java.lang.VirtualMachineError
                           |
                           +----java.lang.UnknownError

public class UnknownError
extends VirtualMachineError

Thrown when an unknown but serious exception has occurred in the Java Virtual Machine.


 UnknownError Members

UnknownError Members

Class Overview | This Package | All Packages

Constructors
Name | Description
UnknownError() | Constructs an UnknownError with no detail message.
UnknownError(String) | Constructs an UnknownError with the specified detail message.


 UnknownError.UnknownError

UnknownError.UnknownError

Class Overview | Class Members | This Package | All Packages

Syntax 1
public UnknownError()
Description
Constructs an UnknownError with no detail message.

Syntax 2
public UnknownError( String s )
Parameters
s
the detail message.
Description
Constructs an UnknownError with the specified detail message.


 Class UnsatisfiedLinkError

Class java.lang.UnsatisfiedLinkError

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Error
                   |
                   +----java.lang.LinkageError
                           |
                           +----java.lang.UnsatisfiedLinkError

public class UnsatisfiedLinkError
extends LinkageError

Thrown if the Java Virtual Machine cannot find an appropriate native-language definition of a method declared native.

See Also:
Runtime


 UnsatisfiedLinkError Members

UnsatisfiedLinkError Members

Class Overview | This Package | All Packages

Constructors
Name | Description
UnsatisfiedLinkError() | Constructs an UnsatisfiedLinkError with no detail message.
UnsatisfiedLinkError(String) | Constructs an UnsatisfiedLinkError with the specified detail message.


 UnsatisfiedLinkError.UnsatisfiedLinkError

UnsatisfiedLinkError.UnsatisfiedLinkError

Class Overview | Class Members | This Package | All Packages

Syntax 1
public UnsatisfiedLinkError()
Description
Constructs an UnsatisfiedLinkError with no detail message.

Syntax 2
public UnsatisfiedLinkError( String s )
Parameters
s
the detail message.
Description
Constructs an UnsatisfiedLinkError with the specified detail message.


 Class VerifyError

Class java.lang.VerifyError

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Error
                   |
                   +----java.lang.LinkageError
                           |
                           +----java.lang.VerifyError

public class VerifyError
extends LinkageError

Thrown when the "verifier" detects that a class file, though well formed, contains some sort of internal inconsistency or security problem.


 VerifyError Members

VerifyError Members

Class Overview | This Package | All Packages

Constructors
Name | Description
VerifyError() | Constructs an VerifyError with no detail message.
VerifyError(String) | Constructs an VerifyError with the specified detail message.


 VerifyError.VerifyError

VerifyError.VerifyError

Class Overview | Class Members | This Package | All Packages

Syntax 1
public VerifyError()
Description
Constructs an VerifyError with no detail message.

Syntax 2
public VerifyError( String s )
Parameters
s
the detail message.
Description
Constructs an VerifyError with the specified detail message.


 Class VirtualMachineError

Class java.lang.VirtualMachineError

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Error
                   |
                   +----java.lang.VirtualMachineError

public abstract class VirtualMachineError
extends Error

Thrown to indicate that the Java Virtual Machine is broken or has run out of resources necessary for it to continue operating.


 VirtualMachineError Members

VirtualMachineError Members

Class Overview | This Package | All Packages

Constructors
Name | Description
VirtualMachineError() | Constructs a VirtualMachineError with no detail message.
VirtualMachineError(String) | Constructs a VirtualMachineError with the specified detail message.


 VirtualMachineError.VirtualMachineError

VirtualMachineError.VirtualMachineError

Class Overview | Class Members | This Package | All Packages

Syntax 1
public VirtualMachineError()
Description
Constructs a VirtualMachineError with no detail message.

Syntax 2
public VirtualMachineError( String s )
Parameters
s
the detail message.
Description
Constructs a VirtualMachineError with the specified detail message.


 Class Void

Class java.lang.Void

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Void

public final class Void
extends Object

The Void class is an uninstantiable placeholder class to hold a reference to the Class object representing the primitive Java type void.


 Void Members

Void Members

Class Overview | This Package | All Packages

Fields
Name | Description
TYPE | The Class object representing the primitive Java type void.


 Void.TYPE

Void.TYPE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Class TYPE
Description
The Class object representing the primitive Java type void.


 Package java.lang.reflect

Package java.lang.reflect

All Packages

Interfaces

  • Member

    • Classes

  • Array
  • Constructor
  • Field
  • Method
  • Modifier

    • Exceptions

  • InvocationTargetException


 Class Array

Class java.lang.reflect.Array

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.reflect.Array

public final class Array
extends Object

The Array class provides static methods to dynamically create and access Java arrays.

Array permits widening conversions to occur during a get or set operation, but throws an IllegalArgumentException if a narrowing conversion would occur.


 Array Members

Array Members

Class Overview | This Package | All Packages

Methods
Name | Description
get(Object, int) | Returns the value of the indexed component in the specified array object.
getBoolean(Object, int) | Returns the value of the indexed component in the specified array object, as a boolean.
getByte(Object, int) | Returns the value of the indexed component in the specified array object, as a byte.
getChar(Object, int) | Returns the value of the indexed component in the specified array object, as a char.
getDouble(Object, int) | Returns the value of the indexed component in the specified array object, as a double.
getFloat(Object, int) | Returns the value of the indexed component in the specified array object, as a float.
getInt(Object, int) | Returns the value of the indexed component in the specified array object, as an int.
getLength(Object) | Returns the length of the specified array object, as an int.
getLong(Object, int) | Returns the value of the indexed component in the specified array object, as a long.
getShort(Object, int) | Returns the value of the indexed component in the specified array object, as a short.
newInstance(Class, int) | Creates a new array with the specified component type and length.
newInstance(Class, int[]) | Creates a new array with the specified component type and dimensions.
set(Object, int, Object) | Sets the value of the indexed component of the specified array object to the specified new value.
setBoolean(Object, int, boolean) | Sets the value of the indexed component of the specified array object to the specified boolean value.
setByte(Object, int, byte) | Sets the value of the indexed component of the specified array object to the specified boolean value.
setChar(Object, int, char) | Sets the value of the indexed component of the specified array object to the specified byte value.
setDouble(Object, int, double) | Sets the value of the indexed component of the specified array object to the specified double value.
setFloat(Object, int, float) | Sets the value of the indexed component of the specified array object to the specified float value.
setInt(Object, int, int) | Sets the value of the indexed component of the specified array object to the specified int value.
setLong(Object, int, long) | Sets the value of the indexed component of the specified array object to the specified long value.
setShort(Object, int, short) | Sets the value of the indexed component of the specified array object to the specified short value.


 Array.get

Array.get

Class Overview | Class Members | This Package | All Packages

Syntax
public static native Object get( Object array, int index ) throws IllegalArgumentException, ArrayIndexOutOfBoundsException
Parameters
array
the array
index
the index
Returns
the (possibly wrapped) value of the indexed component in the specified array
Description
Returns the value of the indexed component in the specified array object. The value is automatically wrapped in an object if it has a primitive type.

Exceptions
NullPointerException If the specified object is null
Exceptions
IllegalArgumentException If the specified object is not an array
Exceptions
ArrayIndexOutOfBoundsException If the specified index argument is negative, or if it is greater than or equal to the length of the specified array


 Array.getBoolean

Array.getBoolean

Class Overview | Class Members | This Package | All Packages

Syntax
public static native boolean getBoolean( Object array, int index ) throws IllegalArgumentException, ArrayIndexOutOfBoundsException
Parameters
array
the array
index
the index
Returns
the value of the indexed component in the specified array
Description
Returns the value of the indexed component in the specified array object, as a boolean.

Exceptions
NullPointerException If the specified object is null
Exceptions
IllegalArgumentException If the specified object is not an array, or if the indexed element cannot be converted to the return type by an identity or widening conversion
Exceptions
ArrayIndexOutOfBoundsException If the specified index argument is negative, or if it is greater than or equal to the length of the specified array
See Also
get


 Array.getByte

Array.getByte

Class Overview | Class Members | This Package | All Packages

Syntax
public static native byte getByte( Object array, int index ) throws IllegalArgumentException, ArrayIndexOutOfBoundsException
Parameters
array
the array
index
the index
Returns
the value of the indexed component in the specified array
Description
Returns the value of the indexed component in the specified array object, as a byte.

Exceptions
NullPointerException If the specified object is null
Exceptions
IllegalArgumentException If the specified object is not an array, or if the indexed element cannot be converted to the return type by an identity or widening conversion
Exceptions
ArrayIndexOutOfBoundsException If the specified index argument is negative, or if it is greater than or equal to the length of the specified array
See Also
get


 Array.getChar

Array.getChar

Class Overview | Class Members | This Package | All Packages

Syntax
public static native char getChar( Object array, int index ) throws IllegalArgumentException, ArrayIndexOutOfBoundsException
Parameters
array
the array
index
the index
Returns
the value of the indexed component in the specified array
Description
Returns the value of the indexed component in the specified array object, as a char.

Exceptions
NullPointerException If the specified object is null
Exceptions
IllegalArgumentException If the specified object is not an array, or if the indexed element cannot be converted to the return type by an identity or widening conversion
Exceptions
ArrayIndexOutOfBoundsException If the specified index argument is negative, or if it is greater than or equal to the length of the specified array
See Also
get


 Array.getDouble

Array.getDouble

Class Overview | Class Members | This Package | All Packages

Syntax
public static native double getDouble( Object array, int index ) throws IllegalArgumentException, ArrayIndexOutOfBoundsException
Parameters
array
the array
index
the index
Returns
the value of the indexed component in the specified array
Description
Returns the value of the indexed component in the specified array object, as a double.

Exceptions
NullPointerException If the specified object is null
Exceptions
IllegalArgumentException If the specified object is not an array, or if the indexed element cannot be converted to the return type by an identity or widening conversion
Exceptions
ArrayIndexOutOfBoundsException If the specified index argument is negative, or if it is greater than or equal to the length of the specified array
See Also
get


 Array.getFloat

Array.getFloat

Class Overview | Class Members | This Package | All Packages

Syntax
public static native float getFloat( Object array, int index ) throws IllegalArgumentException, ArrayIndexOutOfBoundsException
Parameters
array
the array
index
the index
Returns
the value of the indexed component in the specified array
Description
Returns the value of the indexed component in the specified array object, as a float.

Exceptions
NullPointerException If the specified object is null
Exceptions
IllegalArgumentException If the specified object is not an array, or if the indexed element cannot be converted to the return type by an identity or widening conversion
Exceptions
ArrayIndexOutOfBoundsException If the specified index argument is negative, or if it is greater than or equal to the length of the specified array
See Also
get


 Array.getInt

Array.getInt

Class Overview | Class Members | This Package | All Packages

Syntax
public static native int getInt( Object array, int index ) throws IllegalArgumentException, ArrayIndexOutOfBoundsException
Parameters
array
the array
index
the index
Returns
the value of the indexed component in the specified array
Description
Returns the value of the indexed component in the specified array object, as an int.

Exceptions
NullPointerException If the specified object is null
Exceptions
IllegalArgumentException If the specified object is not an array, or if the indexed element cannot be converted to the return type by an identity or widening conversion
Exceptions
ArrayIndexOutOfBoundsException If the specified index argument is negative, or if it is greater than or equal to the length of the specified array
See Also
get


 Array.getLength

Array.getLength

Class Overview | Class Members | This Package | All Packages

Syntax
public static native int getLength( Object array ) throws IllegalArgumentException
Parameters
array
the array
Returns
the length of the array
Description
Returns the length of the specified array object, as an int.

Exceptions
IllegalArgumentException if the object argument is not an array


 Array.getLong

Array.getLong

Class Overview | Class Members | This Package | All Packages

Syntax
public static native long getLong( Object array, int index ) throws IllegalArgumentException, ArrayIndexOutOfBoundsException
Parameters
array
the array
index
the index
Returns
the value of the indexed component in the specified array
Description
Returns the value of the indexed component in the specified array object, as a long.

Exceptions
NullPointerException If the specified object is null
Exceptions
IllegalArgumentException If the specified object is not an array, or if the indexed element cannot be converted to the return type by an identity or widening conversion
Exceptions
ArrayIndexOutOfBoundsException If the specified index argument is negative, or if it is greater than or equal to the length of the specified array
See Also
get


 Array.getShort

Array.getShort

Class Overview | Class Members | This Package | All Packages

Syntax
public static native short getShort( Object array, int index ) throws IllegalArgumentException, ArrayIndexOutOfBoundsException
Parameters
array
the array
index
the index
Returns
the value of the indexed component in the specified array
Description
Returns the value of the indexed component in the specified array object, as a short.

Exceptions
NullPointerException If the specified object is null
Exceptions
IllegalArgumentException If the specified object is not an array, or if the indexed element cannot be converted to the return type by an identity or widening conversion
Exceptions
ArrayIndexOutOfBoundsException If the specified index argument is negative, or if it is greater than or equal to the length of the specified array
See Also
get


 Array.newInstance

Array.newInstance

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static Object newInstance( Class componentType, int length ) throws NegativeArraySizeException
Parameters
componentType
the Class object representing the component type of the new array
length
the length of the new array
Returns
the new array
Description
Creates a new array with the specified component type and length. The effect is that of the equivalent array creation expression:
    new componentType[length]

Exceptions
NullPointerException if the specified componentType parameter is null
Exceptions
NegativeArraySizeException if the specified length is negative

Syntax 2
public static Object newInstance( Class componentType, int dimensions[] ) throws IllegalArgumentException, NegativeArraySizeException
Parameters
componentType
the Class object representing the component type of the new array
dimensions
an array of ints representing the dimensions of the new array
Returns
the new array
Description
Creates a new array with the specified component type and dimensions.

The effect is that of the equivalent array creation expression:

    new componentType[dimensions[0]][dimensions[1]]...

Exceptions
NullPointerException if the specified componentType argument is null
Exceptions
IllegalArgumentException if the specified dimensions argument is a zero-dimensional array, or if the number of requested dimensions exceeds the limit on the number of array dimensions supported by the implementation (typically 255).
Exceptions
NegativeArraySizeException if any of the components in the specified dimension argument is negative.


 Array.set

Array.set

Class Overview | Class Members | This Package | All Packages

Syntax
public static native void set( Object array, int index, Object value ) throws IllegalArgumentException, ArrayIndexOutOfBoundsException
Parameters
array
the array
index
the index into the array
value
the new value of the indexed component
Description
Sets the value of the indexed component of the specified array object to the specified new value. The new value is first automatically unwrapped if the array has a primitive component type.

Exceptions
NullPointerException If the specified object argument is null, or if the array component type is primitive and the specified value is null
Exceptions
IllegalArgumentException If the specified object argument is not an array, or if the array component type is primitive and the specified value cannot be converted to the primitive type by a combination of unwrapping and identity or widening conversions
Exceptions
ArrayIndexOutOfBoundsException If the specified index argument is negative, or if it is greater than or equal to the length of the specified array


 Array.setBoolean

Array.setBoolean

Class Overview | Class Members | This Package | All Packages

Syntax
public static native void setBoolean( Object array, int index, boolean z ) throws IllegalArgumentException, ArrayIndexOutOfBoundsException
Parameters
array
the array
index
the index into the array
value
the new value of the indexed component
Description
Sets the value of the indexed component of the specified array object to the specified boolean value.

Exceptions
NullPointerException If the specified object argument is null
Exceptions
IllegalArgumentException If the specified object argument is not an array, or if the the specified value cannot be converted to the underlying array's component type by an identity or a primitive widening widening conversion
Exceptions
ArrayIndexOutOfBoundsException If the specified index argument is negative, or if it is greater than or equal to the length of the specified array
See Also
set


 Array.setByte

Array.setByte

Class Overview | Class Members | This Package | All Packages

Syntax
public static native void setByte( Object array, int index, byte b ) throws IllegalArgumentException, ArrayIndexOutOfBoundsException
Parameters
array
the array
index
the index into the array
value
the new value of the indexed component
Description
Sets the value of the indexed component of the specified array object to the specified boolean value.

Exceptions
NullPointerException If the specified object argument is null
Exceptions
IllegalArgumentException If the specified object argument is not an array, or if the the specified value cannot be converted to the underlying array's component type by an identity or a primitive widening widening conversion
Exceptions
ArrayIndexOutOfBoundsException If the specified index argument is negative, or if it is greater than or equal to the length of the specified array
See Also
set


 Array.setChar

Array.setChar

Class Overview | Class Members | This Package | All Packages

Syntax
public static native void setChar( Object array, int index, char c ) throws IllegalArgumentException, ArrayIndexOutOfBoundsException
Parameters
array
the array
index
the index into the array
value
the new value of the indexed component
Description
Sets the value of the indexed component of the specified array object to the specified byte value.

Exceptions
NullPointerException If the specified object argument is null
Exceptions
IllegalArgumentException If the specified object argument is not an array, or if the the specified value cannot be converted to the underlying array's component type by an identity or a primitive widening widening conversion
Exceptions
ArrayIndexOutOfBoundsException If the specified index argument is negative, or if it is greater than or equal to the length of the specified array
See Also
set


 Array.setDouble

Array.setDouble

Class Overview | Class Members | This Package | All Packages

Syntax
public static native void setDouble( Object array, int index, double d ) throws IllegalArgumentException, ArrayIndexOutOfBoundsException
Parameters
array
the array
index
the index into the array
value
the new value of the indexed component
Description
Sets the value of the indexed component of the specified array object to the specified double value.

Exceptions
NullPointerException If the specified object argument is null
Exceptions
IllegalArgumentException If the specified object argument is not an array, or if the the specified value cannot be converted to the underlying array's component type by an identity or a primitive widening widening conversion
Exceptions
ArrayIndexOutOfBoundsException If the specified index argument is negative, or if it is greater than or equal to the length of the specified array
See Also
set


 Array.setFloat

Array.setFloat

Class Overview | Class Members | This Package | All Packages

Syntax
public static native void setFloat( Object array, int index, float f ) throws IllegalArgumentException, ArrayIndexOutOfBoundsException
Parameters
array
the array
index
the index into the array
value
the new value of the indexed component
Description
Sets the value of the indexed component of the specified array object to the specified float value.

Exceptions
NullPointerException If the specified object argument is null
Exceptions
IllegalArgumentException If the specified object argument is not an array, or if the the specified value cannot be converted to the underlying array's component type by an identity or a primitive widening widening conversion
Exceptions
ArrayIndexOutOfBoundsException If the specified index argument is negative, or if it is greater than or equal to the length of the specified array
See Also
set


 Array.setInt

Array.setInt

Class Overview | Class Members | This Package | All Packages

Syntax
public static native void setInt( Object array, int index, int i ) throws IllegalArgumentException, ArrayIndexOutOfBoundsException
Parameters
array
the array
index
the index into the array
value
the new value of the indexed component
Description
Sets the value of the indexed component of the specified array object to the specified int value.

Exceptions
NullPointerException If the specified object argument is null
Exceptions
IllegalArgumentException If the specified object argument is not an array, or if the the specified value cannot be converted to the underlying array's component type by an identity or a primitive widening widening conversion
Exceptions
ArrayIndexOutOfBoundsException If the specified index argument is negative, or if it is greater than or equal to the length of the specified array
See Also
set


 Array.setLong

Array.setLong

Class Overview | Class Members | This Package | All Packages

Syntax
public static native void setLong( Object array, int index, long l ) throws IllegalArgumentException, ArrayIndexOutOfBoundsException
Parameters
array
the array
index
the index into the array
value
the new value of the indexed component
Description
Sets the value of the indexed component of the specified array object to the specified long value.

Exceptions
NullPointerException If the specified object argument is null
Exceptions
IllegalArgumentException If the specified object argument is not an array, or if the the specified value cannot be converted to the underlying array's component type by an identity or a primitive widening widening conversion
Exceptions
ArrayIndexOutOfBoundsException If the specified index argument is negative, or if it is greater than or equal to the length of the specified array
See Also
set


 Array.setShort

Array.setShort

Class Overview | Class Members | This Package | All Packages

Syntax
public static native void setShort( Object array, int index, short s ) throws IllegalArgumentException, ArrayIndexOutOfBoundsException
Parameters
array
the array
index
the index into the array
value
the new value of the indexed component
Description
Sets the value of the indexed component of the specified array object to the specified short value.

Exceptions
NullPointerException If the specified object argument is null
Exceptions
IllegalArgumentException If the specified object argument is not an array, or if the the specified value cannot be converted to the underlying array's component type by an identity or a primitive widening widening conversion
Exceptions
ArrayIndexOutOfBoundsException If the specified index argument is negative, or if it is greater than or equal to the length of the specified array
See Also
set


 Class Constructor

Class java.lang.reflect.Constructor

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.reflect.Constructor

public final class Constructor
extends Object
implements Member

Constructor provides information about, and access to, a single constructor for a class.

Constructor permits widening conversions to occur when matching the actual parameters to newInstance() with the underlying constructor's formal parameters, but throws an IllegalArgumentException if a narrowing conversion would occur.

See Also:
Member, Class, getConstructors, getConstructor, getDeclaredConstructors


 Constructor Members

Constructor Members

Class Overview | This Package | All Packages

Methods
Name | Description
equals(Object) | Compares this Constructor against the specified object.
getDeclaringClass() | Returns the Class object representing the class that declares the constructor represented by this Constructor object.
getExceptionTypes() | Returns an array of Class objects that represent the types of the checked exceptions thrown by the underlying constructor represented by this Constructor object.
getModifiers() | Returns the Java language modifiers for the constructor represented by this Constructor object, as an integer.
getName() | Returns the name of this constructor, as a string.
getParameterTypes() | Returns an array of Class objects that represent the formal parameter types, in declaration order, of the constructor represented by this Constructor object.
hashCode() | Returns a hashcode for this Constructor.
newInstance(Object[]) | Uses the constructor represented by this Constructor object to create and initialize a new instance of the constructor's declaring class, with the specified initialization parameters.
toString() | Return a string describing this Constructor.


 Constructor.equals

Constructor.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Description
Compares this Constructor against the specified object. Returns true if the objects are the same. Two Constructors are the same if they were declared by the same class and have the same formal parameter types.

Overrides
equals in class Object


 Constructor.getDeclaringClass

Constructor.getDeclaringClass

Class Overview | Class Members | This Package | All Packages

Syntax
public Class getDeclaringClass()
Description
Returns the Class object representing the class that declares the constructor represented by this Constructor object.


 Constructor.getExceptionTypes

Constructor.getExceptionTypes

Class Overview | Class Members | This Package | All Packages

Syntax
public Class[] getExceptionTypes()
Description
Returns an array of Class objects that represent the types of the checked exceptions thrown by the underlying constructor represented by this Constructor object. Returns an array of length 0 if the constructor throws no checked exceptions.


 Constructor.getModifiers

Constructor.getModifiers

Class Overview | Class Members | This Package | All Packages

Syntax
public native int getModifiers()
Description
Returns the Java language modifiers for the constructor represented by this Constructor object, as an integer. The Modifier class should be used to decode the modifiers.

See Also
Modifier


 Constructor.getName

Constructor.getName

Class Overview | Class Members | This Package | All Packages

Syntax
public String getName()
Description
Returns the name of this constructor, as a string. This is always the same as the name of the constructor's declaring class.


 Constructor.getParameterTypes

Constructor.getParameterTypes

Class Overview | Class Members | This Package | All Packages

Syntax
public Class[] getParameterTypes()
Description
Returns an array of Class objects that represent the formal parameter types, in declaration order, of the constructor represented by this Constructor object. Returns an array of length 0 if the underlying constructor takes no parameters.


 Constructor.hashCode

Constructor.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int hashCode()
Description
Returns a hashcode for this Constructor. The hashcode is the same as the hashcode for the underlying constructor's declaring class name.

Overrides
hashCode in class Object


 Constructor.newInstance

Constructor.newInstance

Class Overview | Class Members | This Package | All Packages

Syntax
public native Object newInstance( Object initargs[] ) throws InstantiationException, IllegalAccessException, IllegalArgumentException, InvocationTargetException
Description
Uses the constructor represented by this Constructor object to create and initialize a new instance of the constructor's declaring class, with the specified initialization parameters. Individual parameters are automatically unwrapped to match primitive formal parameters, and both primitive and reference parameters are subject to widening conversions as necessary. Returns the newly created and initialized object.

Creation proceeds with the following steps, in order:

If the class that declares the underlying constructor represents an abstract class, the creation throws an InstantiationException.

If this Constructor object enforces Java language access control and the underlying constructor is inaccessible, the creation throws an IllegalAccessException.

If the number of actual parameters supplied via initargs is different from the number of formal parameters required by the underlying constructor, the creation throws an IllegalArgumentException.

A new instance of the constructor's declaring class is created, and its fields are initialized to their default initial values.

For each actual parameter in the supplied initargs array:

If the corresponding formal parameter has a primitive type, an unwrapping conversion is attempted to convert the object value to a value of the primitive type. If this attempt fails, the creation throws an IllegalArgumentException.

If, after possible unwrapping, the parameter value cannot be converted to the corresponding formal parameter type by an identity or widening conversion, the creation throws an IllegalArgumentException.

Control transfers to the underlying constructor to initialize the new instance. If the constructor completes abruptly by throwing an exception, the exception is placed in an InvocationTargetException and thrown in turn to the caller of newInstance.

If the constructor completes normally, returns the newly created and initialized instance.

Exceptions
IllegalAccessException if the underlying constructor is inaccessible.
Exceptions
IllegalArgumentException if the number of actual and formal parameters differ, or if an unwrapping conversion fails.
Exceptions
InstantiationException if the class that declares the underlying constructor represents an abstract class.
Exceptions
InvocationTargetException if the underlying constructor throws an exception.


 Constructor.toString

Constructor.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Description
Return a string describing this Constructor. The string is formatted as the constructor access modifiers, if any, followed by the fully-qualified name of the declaring class, followed by a parenthesized, comma-separated list of the constructor's formal parameter types. For example:
    public java.util.Hashtable(int,float)

The only possible modifiers for constructors are the access modifiers public, protected or private. Only one of these may appear, or none if the constructor has default (package) access.

Overrides
toString in class Object


 Class Field

Class java.lang.reflect.Field

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.reflect.Field

public final class Field
extends Object
implements Member

A Field provides information about, and dynamic access to, a single field of a class or an interface. The reflected field may be a class (static) field or an instance field.

A Field permits widening conversions to occur during a get or set access operation, but throws an IllegalArgumentException if a narrowing conversion would occur.

See Also:
Member, Class, getFields, getField, getDeclaredFields, getDeclaredField


 Field Members

Field Members

Class Overview | This Package | All Packages

Methods
Name | Description
equals(Object) | Compares this Field against the specified object.
get(Object) | Returns the value of the field represented by this Field, on the specified object.
getBoolean(Object) | Get the value of a field as a boolean on specified object.
getByte(Object) | Get the value of a field as a byte on specified object.
getChar(Object) | Get the value of a field as a char on specified object.
getDeclaringClass() | Returns the Class object representing the class or interface that declares the field represented by this Field object.
getDouble(Object) | Get the value of a field as a double on specified object.
getFloat(Object) | Get the value of a field as a float on specified object.
getInt(Object) | Get the value of a field as a int on specified object.
getLong(Object) | Get the value of a field as a long on specified object.
getModifiers() | Returns the Java language modifiers for the field represented by this Field object, as an integer.
getName() | Returns the name of the field represented by this Field object.
getShort(Object) | Get the value of a field as a short on specified object.
getType() | Returns a Class object that identifies the declared type for the field represented by this Field object.
hashCode() | Returns a hashcode for this Field.
set(Object, Object) | Sets the field represented by this Field object on the specified object argument to the specified new value.
setBoolean(Object, boolean) | Set the value of a field as a boolean on specified object.
setByte(Object, byte) | Set the value of a field as a byte on specified object.
setChar(Object, char) | Set the value of a field as a char on specified object.
setDouble(Object, double) | Set the value of a field as a double on specified object.
setFloat(Object, float) | Set the value of a field as a float on specified object.
setInt(Object, int) | Set the value of a field as an int on specified object.
setLong(Object, long) | Set the value of a field as a long on specified object.
setShort(Object, short) | Set the value of a field as a short on specified object.
toString() | Return a string describing this Field.


 Field.equals

Field.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Description
Compares this Field against the specified object. Returns true if the objects are the same. Two Fields are the same if they were declared by the same class and have the same name and type.

Overrides
equals in class Object


 Field.get

Field.get

Class Overview | Class Members | This Package | All Packages

Syntax
public native Object get( Object obj ) throws IllegalArgumentException, IllegalAccessException
Description
Returns the value of the field represented by this Field, on the specified object. The value is automatically wrapped in an object if it has a primitive type.

The underlying field's value is obtained as follows:

If the underlying field is a static field, the object argument is ignored; it may be null.

Otherwise, the underlying field is an instance field. If the specified object argument is null, the method throws a NullPointerException. If the specified object is not an instance of the class or interface declaring the underlying field, the method throws an IllegalArgumentException.

If this Field object enforces Java language access control, and the underlying field is inaccessible, the method throws an IllegalAccessException.

Otherwise, the value is retrieved from the underlying instance or static field. If the field has a primitive type, the value is wrapped in an object before being returned, otherwise it is returned as is.

Exceptions
IllegalAccessException if the underlying constructor is inaccessible.
Exceptions
IllegalArgumentException if the specified object is not an instance of the class or interface declaring the underlying field.
Exceptions
NullPointerException if the specified object is null.


 Field.getBoolean

Field.getBoolean

Class Overview | Class Members | This Package | All Packages

Syntax
public native boolean getBoolean( Object obj ) throws IllegalArgumentException, IllegalAccessException
Description
Get the value of a field as a boolean on specified object.

Exceptions
IllegalAccessException if the underlying constructor is inaccessible.
Exceptions
IllegalArgumentException if the field value cannot be converted to the return type by a widening conversion.
See Also
get


 Field.getByte

Field.getByte

Class Overview | Class Members | This Package | All Packages

Syntax
public native byte getByte( Object obj ) throws IllegalArgumentException, IllegalAccessException
Description
Get the value of a field as a byte on specified object.

Exceptions
IllegalAccessException if the underlying constructor is inaccessible.
Exceptions
IllegalArgumentException if the field value cannot be converted to the return type by a widening conversion.
See Also
get


 Field.getChar

Field.getChar

Class Overview | Class Members | This Package | All Packages

Syntax
public native char getChar( Object obj ) throws IllegalArgumentException, IllegalAccessException
Description
Get the value of a field as a char on specified object.

Exceptions
IllegalAccessException if the underlying constructor is inaccessible.
Exceptions
IllegalArgumentException if the field value cannot be converted to the return type by a widening conversion.
See Also
get


 Field.getDeclaringClass

Field.getDeclaringClass

Class Overview | Class Members | This Package | All Packages

Syntax
public Class getDeclaringClass()
Description
Returns the Class object representing the class or interface that declares the field represented by this Field object.


 Field.getDouble

Field.getDouble

Class Overview | Class Members | This Package | All Packages

Syntax
public native double getDouble( Object obj ) throws IllegalArgumentException, IllegalAccessException
Description
Get the value of a field as a double on specified object.

Exceptions
IllegalAccessException if the underlying constructor is inaccessible.
Exceptions
IllegalArgumentException if the field value cannot be converted to the return type by a widening conversion.
See Also
get


 Field.getFloat

Field.getFloat

Class Overview | Class Members | This Package | All Packages

Syntax
public native float getFloat( Object obj ) throws IllegalArgumentException, IllegalAccessException
Description
Get the value of a field as a float on specified object.

Exceptions
IllegalAccessException if the underlying constructor is inaccessible.
Exceptions
IllegalArgumentException if the field value cannot be converted to the return type by a widening conversion.
See Also
get


 Field.getInt

Field.getInt

Class Overview | Class Members | This Package | All Packages

Syntax
public native int getInt( Object obj ) throws IllegalArgumentException, IllegalAccessException
Description
Get the value of a field as a int on specified object.

Exceptions
IllegalAccessException if the underlying constructor is inaccessible.
Exceptions
IllegalArgumentException if the field value cannot be converted to the return type by a widening conversion.
See Also
get


 Field.getLong

Field.getLong

Class Overview | Class Members | This Package | All Packages

Syntax
public native long getLong( Object obj ) throws IllegalArgumentException, IllegalAccessException
Description
Get the value of a field as a long on specified object.

Exceptions
IllegalAccessException if the underlying constructor is inaccessible.
Exceptions
IllegalArgumentException if the field value cannot be converted to the return type by a widening conversion.
See Also
get


 Field.getModifiers

Field.getModifiers

Class Overview | Class Members | This Package | All Packages

Syntax
public native int getModifiers()
Description
Returns the Java language modifiers for the field represented by this Field object, as an integer. The Modifier class should be used to decode the modifiers.

See Also
Modifier


 Field.getName

Field.getName

Class Overview | Class Members | This Package | All Packages

Syntax
public String getName()
Description
Returns the name of the field represented by this Field object.


 Field.getShort

Field.getShort

Class Overview | Class Members | This Package | All Packages

Syntax
public native short getShort( Object obj ) throws IllegalArgumentException, IllegalAccessException
Description
Get the value of a field as a short on specified object.

Exceptions
IllegalAccessException if the underlying constructor is inaccessible.
Exceptions
IllegalArgumentException if the field value cannot be converted to the return type by a widening conversion.
See Also
get


 Field.getType

Field.getType

Class Overview | Class Members | This Package | All Packages

Syntax
public Class getType()
Description
Returns a Class object that identifies the declared type for the field represented by this Field object.


 Field.hashCode

Field.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int hashCode()
Description
Returns a hashcode for this Field. This is computed as the exclusive-or of the hashcodes for the underlying field's declaring class name and its name.

Overrides
hashCode in class Object


 Field.set

Field.set

Class Overview | Class Members | This Package | All Packages

Syntax
public native void set( Object obj, Object value ) throws IllegalArgumentException, IllegalAccessException
Description
Sets the field represented by this Field object on the specified object argument to the specified new value. The new value is automatically unwrapped if the underlying field has a primitive type.

The operation proceeds as follows:

If the underlying field is static, the object argument is ignored; it may be null.

Otherwise the underlying field is an instance field. If the specified object argument is null, the method throws a NullPointerException. If the specified object argument is not an instance of the class or interface declaring the underlying field, the method throws an IllegalArgumentException.

If this Field object enforces Java language access control, and the underlying field is inaccessible, the method throws an IllegalAccessException.

If the underlying field is final, the method throws an IllegalAccessException.

If the underlying field is of a primitive type, an unwrapping conversion is attempted to convert the new value to a value of a primitive type. If this attempt fails, the method throws an IllegalArgumentException.

If, after possible unwrapping, the new value cannot be converted to the type of the underlying field by an identity or widening conversion, the method throws an IllegalArgumentException.

The field is set to the possibly unwrapped and widened new value.

Exceptions
IllegalAccessException if the underlying constructor is inaccessible.
Exceptions
IllegalArgumentException if the specified object is not an instance of the class or interface declaring the underlying field, or if an unwrapping conversion fails.
Exceptions
NullPointerException if the specified object is null.


 Field.setBoolean

Field.setBoolean

Class Overview | Class Members | This Package | All Packages

Syntax
public native void setBoolean( Object obj, boolean z ) throws IllegalArgumentException, IllegalAccessException
Description
Set the value of a field as a boolean on specified object.

Exceptions
IllegalAccessException if the underlying constructor is inaccessible.
Exceptions
IllegalArgumentException if the specified object is not an instance of the class or interface declaring the underlying field, or if an unwrapping conversion fails.
See Also
set


 Field.setByte

Field.setByte

Class Overview | Class Members | This Package | All Packages

Syntax
public native void setByte( Object obj, byte b ) throws IllegalArgumentException, IllegalAccessException
Description
Set the value of a field as a byte on specified object.

Exceptions
IllegalAccessException if the underlying constructor is inaccessible.
Exceptions
IllegalArgumentException if the specified object is not an instance of the class or interface declaring the underlying field, or if an unwrapping conversion fails.
See Also
set


 Field.setChar

Field.setChar

Class Overview | Class Members | This Package | All Packages

Syntax
public native void setChar( Object obj, char c ) throws IllegalArgumentException, IllegalAccessException
Description
Set the value of a field as a char on specified object.

Exceptions
IllegalAccessException if the underlying constructor is inaccessible.
Exceptions
IllegalArgumentException if the specified object is not an instance of the class or interface declaring the underlying field, or if an unwrapping conversion fails.
See Also
set


 Field.setDouble

Field.setDouble

Class Overview | Class Members | This Package | All Packages

Syntax
public native void setDouble( Object obj, double d ) throws IllegalArgumentException, IllegalAccessException
Description
Set the value of a field as a double on specified object.

Exceptions
IllegalAccessException if the underlying constructor is inaccessible.
Exceptions
IllegalArgumentException if the specified object is not an instance of the class or interface declaring the underlying field, or if an unwrapping conversion fails.
See Also
set


 Field.setFloat

Field.setFloat

Class Overview | Class Members | This Package | All Packages

Syntax
public native void setFloat( Object obj, float f ) throws IllegalArgumentException, IllegalAccessException
Description
Set the value of a field as a float on specified object.

Exceptions
IllegalAccessException if the underlying constructor is inaccessible.
Exceptions
IllegalArgumentException if the specified object is not an instance of the class or interface declaring the underlying field, or if an unwrapping conversion fails.
See Also
set


 Field.setInt

Field.setInt

Class Overview | Class Members | This Package | All Packages

Syntax
public native void setInt( Object obj, int i ) throws IllegalArgumentException, IllegalAccessException
Description
Set the value of a field as an int on specified object.

Exceptions
IllegalAccessException if the underlying constructor is inaccessible.
Exceptions
IllegalArgumentException if the specified object is not an instance of the class or interface declaring the underlying field, or if an unwrapping conversion fails.
See Also
set


 Field.setLong

Field.setLong

Class Overview | Class Members | This Package | All Packages

Syntax
public native void setLong( Object obj, long l ) throws IllegalArgumentException, IllegalAccessException
Description
Set the value of a field as a long on specified object.

Exceptions
IllegalAccessException if the underlying constructor is inaccessible.
Exceptions
IllegalArgumentException if the specified object is not an instance of the class or interface declaring the underlying field, or if an unwrapping conversion fails.
See Also
set


 Field.setShort

Field.setShort

Class Overview | Class Members | This Package | All Packages

Syntax
public native void setShort( Object obj, short s ) throws IllegalArgumentException, IllegalAccessException
Description
Set the value of a field as a short on specified object.

Exceptions
IllegalAccessException if the underlying constructor is inaccessible.
Exceptions
IllegalArgumentException if the specified object is not an instance of the class or interface declaring the underlying field, or if an unwrapping conversion fails.
See Also
set


 Field.toString

Field.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Description
Return a string describing this Field. The format is the access modifiers for the field, if any, followed by the field type, followed by a space, followed by the fully-qualified name of the class declaring the field, followed by a period, followed by the name of the field. For example:
    public static final int java.lang.Thread.MIN_PRIORITY
    private int java.io.FileDescriptor.fd

The modifiers are placed in canonical order as specified by "The Java Language Specification". This is public, protected or private first, and then other modifiers in the following order: static, final, transient, volatile.

Overrides
toString in class Object


 Class InvocationTargetException

Class java.lang.reflect.InvocationTargetException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.lang.reflect.InvocationTargetException

public class InvocationTargetException
extends Exception

InvocationTargetException is a checked exception that wraps an exception thrown by an invoked method or constructor.

See Also:
Method, Constructor


 InvocationTargetException Members

InvocationTargetException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
InvocationTargetException() |
InvocationTargetException(Throwable) | Constructs a InvocationTargetException with a target exception.
InvocationTargetException(Throwable, String) | Constructs a InvocationTargetException with a target exception and a detail message.

Methods
Name | Description
getTargetException() | Get the thrown target exception.


 InvocationTargetException.InvocationTargetException

InvocationTargetException.InvocationTargetException

Class Overview | Class Members | This Package | All Packages

Syntax 1
protected InvocationTargetException()

Syntax 2
public InvocationTargetException( Throwable target )
Description
Constructs a InvocationTargetException with a target exception.

Syntax 3
public InvocationTargetException( Throwable target, String s )
Description
Constructs a InvocationTargetException with a target exception and a detail message.


 InvocationTargetException.getTargetException

InvocationTargetException.getTargetException

Class Overview | Class Members | This Package | All Packages

Syntax
public Throwable getTargetException()
Description
Get the thrown target exception.


 Interface Member

Interface java.lang.reflect.Member

Interface Members | This Package | All Packages

public interface Member

Member is an interface that reflects identifying information about a single member (a field or a method) or a constructor.

See Also:
Class, Field, Method, Constructor


 Member Members

Member Members

Interface Overview | This Package | All Packages

Fields
Name | Description
DECLARED | Identifies the set of declared members of a class or interface.
PUBLIC | Identifies the set of all public members of a class or interface, including inherited members.

Methods
Name | Description
getDeclaringClass() | Returns the Class object representing the class or interface that declares the member or constructor represented by this Member.
getModifiers() | Returns the Java language modifiers for the member or constructor represented by this Member, as an integer.
getName() | Returns the simple name of the underlying member or constructor represented by this Member.


 Member.DECLARED

Member.DECLARED

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int DECLARED
Description
Identifies the set of declared members of a class or interface. Inherited members are not included.

See Also
checkMemberAccess


 Member.PUBLIC

Member.PUBLIC

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int PUBLIC
Description
Identifies the set of all public members of a class or interface, including inherited members.

See Also
checkMemberAccess


 Member.getDeclaringClass

Member.getDeclaringClass

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Class getDeclaringClass()
Description
Returns the Class object representing the class or interface that declares the member or constructor represented by this Member.


 Member.getModifiers

Member.getModifiers

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getModifiers()
Description
Returns the Java language modifiers for the member or constructor represented by this Member, as an integer. The Modifier class should be used to decode the modifiers in the integer.

See Also
Modifier


 Member.getName

Member.getName

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getName()
Description
Returns the simple name of the underlying member or constructor represented by this Member.


 Class Method

Class java.lang.reflect.Method

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.reflect.Method

public final class Method
extends Object
implements Member

A Method provides information about, and access to, a single method on a class or interface. The reflected method may be a class method or an instance method (including an abstract method).

A Method permits widening conversions to occur when matching the actual parameters to invokewith the underlying method's formal parameters, but it throws an IllegalArgumentException if a narrowing conversion would occur.

See Also:
Member, Class, getMethods, getMethod, getDeclaredMethods, getDeclaredMethod


 Method Members

Method Members

Class Overview | This Package | All Packages

Methods
Name | Description
equals(Object) | Compares this Method against the specified object.
getDeclaringClass() | Returns the Class object representing the class or interface that declares the method represented by this Method object.
getExceptionTypes() | Returns an array of Class objects that represent the types of the checked exceptions thrown by the underlying method represented by this Method object.
getModifiers() | Returns the Java language modifiers for the method represented by this Method object, as an integer.
getName() | Returns the name of the method represented by this Method object, as a String.
getParameterTypes() | Returns an array of Class objects that represent the formal parameter types, in declaration order, of the method represented by this Method object.
getReturnType() | Returns a Class object that represents the formal return type of the method represented by this Method object.
hashCode() | Returns a hashcode for this Method.
invoke(Object, Object[]) | Invokes the underlying method represented by this Method object, on the specified object with the specified parameters.
toString() | Returns a string describing this Method.


 Method.equals

Method.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Description
Compares this Method against the specified object. Returns true if the objects are the same. Two Methods are the same if they were declared by the same class and have the same name and formal parameter types.

Overrides
equals in class Object


 Method.getDeclaringClass

Method.getDeclaringClass

Class Overview | Class Members | This Package | All Packages

Syntax
public Class getDeclaringClass()
Description
Returns the Class object representing the class or interface that declares the method represented by this Method object.


 Method.getExceptionTypes

Method.getExceptionTypes

Class Overview | Class Members | This Package | All Packages

Syntax
public Class[] getExceptionTypes()
Description
Returns an array of Class objects that represent the types of the checked exceptions thrown by the underlying method represented by this Method object. Returns an array of length 0 if the method throws no checked exceptions.


 Method.getModifiers

Method.getModifiers

Class Overview | Class Members | This Package | All Packages

Syntax
public native int getModifiers()
Description
Returns the Java language modifiers for the method represented by this Method object, as an integer. The Modifier class should be used to decode the modifiers.

See Also
Modifier


 Method.getName

Method.getName

Class Overview | Class Members | This Package | All Packages

Syntax
public String getName()
Description
Returns the name of the method represented by this Method object, as a String.


 Method.getParameterTypes

Method.getParameterTypes

Class Overview | Class Members | This Package | All Packages

Syntax
public Class[] getParameterTypes()
Description
Returns an array of Class objects that represent the formal parameter types, in declaration order, of the method represented by this Method object. Returns an array of length 0 if the underlying method takes no parameters.


 Method.getReturnType

Method.getReturnType

Class Overview | Class Members | This Package | All Packages

Syntax
public Class getReturnType()
Description
Returns a Class object that represents the formal return type of the method represented by this Method object.


 Method.hashCode

Method.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int hashCode()
Description
Returns a hashcode for this Method. The hashcode is computed as the exclusive-or of the hashcodes for the underlying method's declaring class name and the method's name.

Overrides
hashCode in class Object


 Method.invoke

Method.invoke

Class Overview | Class Members | This Package | All Packages

Syntax
public native Object invoke( Object obj, Object args[] ) throws IllegalAccessException, IllegalArgumentException, InvocationTargetException
Description
Invokes the underlying method represented by this Method object, on the specified object with the specified parameters. Individual parameters are automatically unwrapped to match primitive formal parameters, and both primitive and reference parameters are subject to widening conversions as necessary. The value returned by the underlying method is automatically wrapped in an object if it has a primitive type.

Method invocation proceeds with the following steps, in order:

If the underlying method is static, then the specified object argument is ignored. It may be null.

Otherwise, the method is an instance method. If the specified object argument is null, the invocation throws a NullPointerException. Otherwise, if the specified object argument is not an instance of the class or interface declaring the underlying method, the invocation throws an IllegalArgumentException.

If this Method object enforces Java language access control and the underlying method is inaccessible, the invocation throws an IllegalAccessException.

If the number of actual parameters supplied via args is different from the number of formal parameters required by the underlying method, the invocation throws an IllegalArgumentException.

For each actual parameter in the supplied args array:

If the corresponding formal parameter has a primitive type, an unwrapping conversion is attempted to convert the object value to a value of a primitive type. If this attempt fails, the invocation throws an IllegalArgumentException.

If, after possible unwrapping, the parameter value cannot be converted to the corresponding formal parameter type by an identity or widening conversion, the invocation throws an IllegalArgumentException.

If the underlying method is an instance method, it is invoked using dynamic method lookup as documented in The Java Language Specification, section 15.11.4.4; in particular, overriding based on the runtime type of the target object will occur.

If the underlying method is static, it is invoked as exactly the method on the declaring class.

Control transfers to the underlying method. If the method completes abruptly by throwing an exception, the exception is placed in an InvocationTargetException and thrown in turn to the caller of invoke.

If the method completes normally, the value it returns is returned to the caller of invoke; if the value has a primitive type, it is first appropriately wrapped in an object. If the underlying method return type is void, the invocation returns null.

Exceptions
IllegalAccessException if the underlying method is inaccessible.
Exceptions
IllegalArgumentException if the number of actual and formal parameters differ, or if an unwrapping conversion fails.
Exceptions
InvocationTargetException if the underlying method throws an exception.
Exceptions
NullPointerException if the specified object is null.


 Method.toString

Method.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Description
Returns a string describing this Method. The string is formatted as the method access modifiers, if any, followed by the method return type, followed by a space, followed by the class declaring the method, followed by a period, followed by the method name, followed by a parenthesized, comma-separated list of the method's formal parameter types. If the method throws checked exceptions, the parameter list is followed by a space, followed by the word throws followed by a comma-separated list of the thrown exception types. For example:
    public boolean java.lang.Object.equals(java.lang.Object)

The access modifiers are placed in canonical order as specified by "The Java Language Specification". This is public, protected or private first, and then other modifiers in the following order: abstract, static, final, synchronized native.

Overrides
toString in class Object


 Class Modifier

Class java.lang.reflect.Modifier

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.reflect.Modifier

public class Modifier
extends Object

The Modifier class provides static methods and constants to decode class and member access modifiers.

See Also:
getModifiers, getModifiers


 Modifier Members

Modifier Members

Class Overview | This Package | All Packages

Fields
Name | Description
ABSTRACT |
FINAL |
INTERFACE |
NATIVE |
PRIVATE |
PROTECTED |
PUBLIC |
STATIC |
SYNCHRONIZED |
TRANSIENT |
VOLATILE |

Constructors
Name | Description
Modifier() |

Methods
Name | Description
isAbstract(int) | Return true if the specifier integer includes the abstract modifier.
isFinal(int) | Return true if the specifier integer includes the final modifier.
isInterface(int) | Return true if the specifier integer includes the interface modifier.
isNative(int) | Return true if the specifier integer includes the native modifier.
isPrivate(int) | Return true if the specifier integer includes the private modifier.
isProtected(int) | Return true if the specifier integer includes the protected modifier.
isPublic(int) | Return true if the specified integer includes the public modifier.
isStatic(int) | Return true if the specifier integer includes the static modifier.
isSynchronized(int) | Return true if the specifier integer includes the final modifier.
isTransient(int) | Return true if the specifier integer includes the transient modifier.
isVolatile(int) | Return true if the specifier integer includes the volatile modifier.
toString(int) | Return a string describing the access modifier flags in the specified modifier.


 Modifier.ABSTRACT

Modifier.ABSTRACT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int ABSTRACT


 Modifier.FINAL

Modifier.FINAL

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int FINAL


 Modifier.INTERFACE

Modifier.INTERFACE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int INTERFACE


 Modifier.NATIVE

Modifier.NATIVE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int NATIVE


 Modifier.PRIVATE

Modifier.PRIVATE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int PRIVATE


 Modifier.PROTECTED

Modifier.PROTECTED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int PROTECTED


 Modifier.PUBLIC

Modifier.PUBLIC

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int PUBLIC


 Modifier.STATIC

Modifier.STATIC

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int STATIC


 Modifier.SYNCHRONIZED

Modifier.SYNCHRONIZED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SYNCHRONIZED


 Modifier.TRANSIENT

Modifier.TRANSIENT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int TRANSIENT


 Modifier.VOLATILE

Modifier.VOLATILE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VOLATILE


 Modifier.Modifier

Modifier.Modifier

Class Overview | Class Members | This Package | All Packages

Syntax
public Modifier()


 Modifier.isAbstract

Modifier.isAbstract

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isAbstract( int mod )
Description
Return true if the specifier integer includes the abstract modifier.


 Modifier.isFinal

Modifier.isFinal

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isFinal( int mod )
Description
Return true if the specifier integer includes the final modifier.


 Modifier.isInterface

Modifier.isInterface

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isInterface( int mod )
Description
Return true if the specifier integer includes the interface modifier.


 Modifier.isNative

Modifier.isNative

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isNative( int mod )
Description
Return true if the specifier integer includes the native modifier.


 Modifier.isPrivate

Modifier.isPrivate

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isPrivate( int mod )
Description
Return true if the specifier integer includes the private modifier.


 Modifier.isProtected

Modifier.isProtected

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isProtected( int mod )
Description
Return true if the specifier integer includes the protected modifier.


 Modifier.isPublic

Modifier.isPublic

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isPublic( int mod )
Description
Return true if the specified integer includes the public modifier.


 Modifier.isStatic

Modifier.isStatic

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isStatic( int mod )
Description
Return true if the specifier integer includes the static modifier.


 Modifier.isSynchronized

Modifier.isSynchronized

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isSynchronized( int mod )
Description
Return true if the specifier integer includes the final modifier.


 Modifier.isTransient

Modifier.isTransient

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isTransient( int mod )
Description
Return true if the specifier integer includes the transient modifier.


 Modifier.isVolatile

Modifier.isVolatile

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isVolatile( int mod )
Description
Return true if the specifier integer includes the volatile modifier.


 Modifier.toString

Modifier.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public static String toString( int mod )
Description
Return a string describing the access modifier flags in the specified modifier. For example:
    public final synchronized
    private transient volatile
The modifier names are return in canonical order, as specified by The Java Language Specification.


 Package java.math

Package java.math

All Packages

Classes

  • BigDecimal
  • BigInteger


 Class BigDecimal

Class java.math.BigDecimal

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Number
           |
           +----java.math.BigDecimal

public class BigDecimal
extends Number

Immutable, arbitrary-precision signed decimal numbers. A BigDecimal consists of an arbitrary precision integer value and a non-negative integer scale, which represents the number of decimal digits to the right of the decimal point. (The number represented by the BigDecimal is intVal/10**scale.) BigDecimals provide operations for basic arithmetic, scale manipulation, comparison, format conversion and hashing.

The BigDecimal class gives its user complete control over rounding behavior, forcing the user to explicitly specify a rounding behavior for operations capable of discarding precision (divide and setScale). Eight rounding modes are provided for this purpose. Two types of operations are provided for manipulating the scale of a BigDecimal: scaling/rounding operations and decimal point motion operations. Scaling/Rounding operations (SetScale) return a BigDecimal whose value is approximately (or exactly) equal to that of the operand, but whose scale is the specified value; that is, they increase or decrease the precision of the number with minimal effect on its value. Decimal point motion operations (movePointLeft and movePointRight) return a BigDecimal created from the operand by moving the decimal point a specified distance in the specified direction; that is, they change a number's value without affecting its precision.

See Also:
BigInteger


 BigDecimal Members

BigDecimal Members

Class Overview | This Package | All Packages

Fields
Name | Description
ROUND_CEILING | If the BigDecimal is positive, behave as for ROUND_UP; if negative, behave as for ROUND_DOWN.
ROUND_DOWN | Never increment the digit prior to a discarded fraction (i.e., truncate).
ROUND_FLOOR | If the BigDecimal is positive, behave as for ROUND_DOWN; if negative behave as for ROUND_UP.
ROUND_HALF_DOWN | Behave as for ROUND_UP if the discarded fraction is > .5; otherwise, behave as for ROUND_DOWN.
ROUND_HALF_EVEN | Behave as for ROUND_HALF_UP if the digit to the left of the discarded fraction is odd; behave as for ROUND_HALF_DOWN if it's even.
ROUND_HALF_UP | Behave as for ROUND_UP if the discarded fraction is >= .5; otherwise, behave as for ROUND_DOWN.
ROUND_UNNECESSARY | This "pseudo-rounding-mode" is actually an assertion that the requested operation has an exact result, hence no rounding is necessary.
ROUND_UP | Always increment the digit prior to a non-zero discarded fraction.

Constructors
Name | Description
BigDecimal(BigInteger) | Translates a BigInteger into a BigDecimal.
BigDecimal(BigInteger, int) | Translates a BigInteger and a scale into a BigDecimal.
BigDecimal(double) | Translates a double into a BigDecimal.
BigDecimal(String) | Constructs a BigDecimal from a string containing an optional minus sign followed by a sequence of zero or more decimal digits, optionally followed by a fraction, which consists of a decimal point followed by zero or more decimal digits.

Methods
Name | Description
abs() | Returns a BigDecimal whose value is the absolute value of this number, and whose scale is this.scale().
add(BigDecimal) | Returns a BigDecimal whose value is (this + val), and whose scale is MAX(this.scale(), val.scale).
compareTo(BigDecimal) | Returns -1, 0 or 1 as this number is less than, equal to, or greater than val.
divide(BigDecimal, int) | Returns a BigDecimal whose value is (this / val), and whose scale is this.scale().
divide(BigDecimal, int, int) | Returns a BigDecimal whose value is (this / val), and whose scale is as specified.
doubleValue() | Converts the number to a double.
equals(Object) | Returns true iff x is a BigDecimal whose value is equal to this number.
floatValue() | Converts this number to a float.
hashCode() | Computes a hash code for this object.
intValue() | Converts this number to an int.
longValue() | Converts this number to a long.
max(BigDecimal) | Returns the BigDecimal whose value is the greater of this and val.
min(BigDecimal) | Returns the BigDecimal whose value is the lesser of this and val.
movePointLeft(int) | Returns a BigDecimal which is equivalent to this one with the decimal point moved n places to the left.
movePointRight(int) | Moves the decimal point the specified number of places to the right.
multiply(BigDecimal) | Returns a BigDecimal whose value is (this * val), and whose scale is this.scale() + val.scale.
negate() | Returns a BigDecimal whose value is -1 * this, and whose scale is this.scale().
scale() | Returns the scale of this number.
setScale(int) | Returns a BigDecimal whose scale is the specified value, and whose value is exactly equal to this number's.
setScale(int, int) | Returns a BigDecimal whose scale is the specified value, and whose integer value is determined by multiplying or dividing this BigDecimal's integer value by the appropriate power of ten to maintain the overall value.
signum() | Returns the signum function of this number (i.e., -1, 0 or 1 as the value of this number is negative, zero or positive).
subtract(BigDecimal) | Returns a BigDecimal whose value is (this - val), and whose scale is MAX(this.scale(), val.scale).
toBigInteger() | Converts this number to a BigInteger.
toString() | Returns the string representation of this number.
valueOf(long) | Returns a BigDecimal with the given value and a scale of zero.
valueOf(long, int) | Returns a BigDecimal with a value of (val/10**scale).


 BigDecimal.ROUND_CEILING

BigDecimal.ROUND_CEILING

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int ROUND_CEILING
Description
If the BigDecimal is positive, behave as for ROUND_UP; if negative, behave as for ROUND_DOWN. Note that this rounding mode never decreases the value. (Rounds towards positive infinity.)


 BigDecimal.ROUND_DOWN

BigDecimal.ROUND_DOWN

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int ROUND_DOWN
Description
Never increment the digit prior to a discarded fraction (i.e., truncate). Note that this rounding mode never increases the magnitude. (Rounds towards zero.)


 BigDecimal.ROUND_FLOOR

BigDecimal.ROUND_FLOOR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int ROUND_FLOOR
Description
If the BigDecimal is positive, behave as for ROUND_DOWN; if negative behave as for ROUND_UP. Note that this rounding mode never increases the value. (Rounds towards negative infinity.)


 BigDecimal.ROUND_HALF_DOWN

BigDecimal.ROUND_HALF_DOWN

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int ROUND_HALF_DOWN
Description
Behave as for ROUND_UP if the discarded fraction is > .5; otherwise, behave as for ROUND_DOWN. (Rounds towards "nearest neighbor" unless both neighbors are equidistant, in which case rounds down.)


 BigDecimal.ROUND_HALF_EVEN

BigDecimal.ROUND_HALF_EVEN

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int ROUND_HALF_EVEN
Description
Behave as for ROUND_HALF_UP if the digit to the left of the discarded fraction is odd; behave as for ROUND_HALF_DOWN if it's even. (Rounds towards the "nearest neighbor" unless both neighbors are equidistant, in which case, rounds towards the even neighbor.)


 BigDecimal.ROUND_HALF_UP

BigDecimal.ROUND_HALF_UP

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int ROUND_HALF_UP
Description
Behave as for ROUND_UP if the discarded fraction is >= .5; otherwise, behave as for ROUND_DOWN. (Rounds towards "nearest neighbor" unless both neighbors are equidistant, in which case rounds up.)


 BigDecimal.ROUND_UNNECESSARY

BigDecimal.ROUND_UNNECESSARY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int ROUND_UNNECESSARY
Description
This "pseudo-rounding-mode" is actually an assertion that the requested operation has an exact result, hence no rounding is necessary. If this rounding mode is specified on an operation that yields an inexact result, an arithmetic exception is thrown.


 BigDecimal.ROUND_UP

BigDecimal.ROUND_UP

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int ROUND_UP
Description
Always increment the digit prior to a non-zero discarded fraction. Note that this rounding mode never decreases the magnitude. (Rounds away from zero.)


 BigDecimal.BigDecimal

BigDecimal.BigDecimal

Class Overview | Class Members | This Package | All Packages

Syntax 1
public BigDecimal( String val ) throws NumberFormatException
Description
Constructs a BigDecimal from a string containing an optional minus sign followed by a sequence of zero or more decimal digits, optionally followed by a fraction, which consists of a decimal point followed by zero or more decimal digits. The string must contain at least one digit in the integer or fractional part. The scale of the resulting BigDecimal will be the number of digits to the right of the decimal point in the string, or 0 if the string contains no decimal point. The character-to-digit mapping is provided by Character.digit. Any extraneous characters (including whitespace) will result in a NumberFormatException.

Syntax 2
public BigDecimal( double val ) throws NumberFormatException
Description
Translates a double into a BigDecimal. The scale of the BigDecimal is the smallest value such that (10**scale * val) is an integer. A double whose value is -infinity, +infinity or NaN will result in a NumberFormatException.

Syntax 3
public BigDecimal( BigInteger val )
Description
Translates a BigInteger into a BigDecimal. The scale of the BigDecimal is zero.

Syntax 4
public BigDecimal( BigInteger val, int scale ) throws NumberFormatException
Description
Translates a BigInteger and a scale into a BigDecimal. The value of the BigDecimal is (BigInteger/10**scale). A negative scale will result in a NumberFormatException.


 BigDecimal.abs

BigDecimal.abs

Class Overview | Class Members | This Package | All Packages

Syntax
public BigDecimal abs()
Description
Returns a BigDecimal whose value is the absolute value of this number, and whose scale is this.scale().


 BigDecimal.add

BigDecimal.add

Class Overview | Class Members | This Package | All Packages

Syntax
public BigDecimal add( BigDecimal val )
Description
Returns a BigDecimal whose value is (this + val), and whose scale is MAX(this.scale(), val.scale).


 BigDecimal.compareTo

BigDecimal.compareTo

Class Overview | Class Members | This Package | All Packages

Syntax
public int compareTo( BigDecimal val )
Description
Returns -1, 0 or 1 as this number is less than, equal to, or greater than val. Two BigDecimals that are equal in value but have a different scale (e.g., 2.0, 2.00) are considered equal by this method. This method is provided in preference to individual methods for each of the six boolean comparison operators (<, ==, >, >=, !=, <=). The suggested idiom for performing these comparisons is: (x.compareTo(y) 0), where is one of the six comparison operators.


 BigDecimal.divide

BigDecimal.divide

Class Overview | Class Members | This Package | All Packages

Syntax 1
public BigDecimal divide( BigDecimal val, int scale, int roundingMode ) throws ArithmeticException, IllegalArgumentException
Description
Returns a BigDecimal whose value is (this / val), and whose scale is as specified. If rounding must be performed to generate a result with the given scale, the specified rounding mode is applied. Throws an ArithmeticException if val == 0, scale < 0, or the rounding mode is ROUND_UNNECESSARY and the specified scale is insufficient to represent the result of the division exactly. Throws an IllegalArgumentException if roundingMode does not represent a valid rounding mode.

Syntax 2
public BigDecimal divide( BigDecimal val, int roundingMode ) throws ArithmeticException, IllegalArgumentException
Description
Returns a BigDecimal whose value is (this / val), and whose scale is this.scale(). If rounding must be performed to generate a result with the given scale, the specified rounding mode is applied. Throws an ArithmeticException if val == 0. Throws an IllegalArgumentException if roundingMode does not represent a valid rounding mode.


 BigDecimal.doubleValue

BigDecimal.doubleValue

Class Overview | Class Members | This Package | All Packages

Syntax
public double doubleValue()
Description
Converts the number to a double. Similar to the double-to-float narrowing primitive conversion defined in The Java Language Specification: if the number has too great a magnitude to represent as a double, it will be converted to infinity or negative infinity, as appropriate.

Overrides
doubleValue in class Number


 BigDecimal.equals

BigDecimal.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object x )
Description
Returns true iff x is a BigDecimal whose value is equal to this number. This method is provided so that BigDecimals can be used as hash keys. Unlike compareTo, this method considers two BigDecimals equal only if they are equal in value and scale.

Overrides
equals in class Object


 BigDecimal.floatValue

BigDecimal.floatValue

Class Overview | Class Members | This Package | All Packages

Syntax
public float floatValue()
Description
Converts this number to a float. Similar to the double-to-float narrowing primitive conversion defined in The Java Language Specification: if the number has too great a magnitude to represent as a float, it will be converted to infinity or negative infinity, as appropriate.

Overrides
floatValue in class Number


 BigDecimal.hashCode

BigDecimal.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int hashCode()
Description
Computes a hash code for this object. Note that two BigDecimals that are numerically equal but differ in scale (e.g., 2.0, 2.00) will not generally have the same hash code.

Overrides
hashCode in class Object


 BigDecimal.intValue

BigDecimal.intValue

Class Overview | Class Members | This Package | All Packages

Syntax
public int intValue()
Description
Converts this number to an int. Standard narrowing primitive conversion as per The Java Language Specification. In particular, note that any fractional part of this number will be truncated.

Overrides
intValue in class Number


 BigDecimal.longValue

BigDecimal.longValue

Class Overview | Class Members | This Package | All Packages

Syntax
public long longValue()
Description
Converts this number to a long. Standard narrowing primitive conversion as per The Java Language Specification. In particular, note that any fractional part of this number will be truncated.

Overrides
longValue in class Number


 BigDecimal.max

BigDecimal.max

Class Overview | Class Members | This Package | All Packages

Syntax
public BigDecimal max( BigDecimal val )
Description
Returns the BigDecimal whose value is the greater of this and val. If the values are equal (as defined by the compareTo operator), either may be returned.


 BigDecimal.min

BigDecimal.min

Class Overview | Class Members | This Package | All Packages

Syntax
public BigDecimal min( BigDecimal val )
Description
Returns the BigDecimal whose value is the lesser of this and val. If the values are equal (as defined by the compareTo operator), either may be returned.


 BigDecimal.movePointLeft

BigDecimal.movePointLeft

Class Overview | Class Members | This Package | All Packages

Syntax
public BigDecimal movePointLeft( int n )
Description
Returns a BigDecimal which is equivalent to this one with the decimal point moved n places to the left. If n is non-negative, the call merely adds n to the scale. If n is negative, the call is equivalent to movePointRight(-n). (The BigDecimal returned by this call has value (this * 10**-n) and scale MAX(this.scale()+n, 0).)


 BigDecimal.movePointRight

BigDecimal.movePointRight

Class Overview | Class Members | This Package | All Packages

Syntax
public BigDecimal movePointRight( int n )
Description
Moves the decimal point the specified number of places to the right. If this number's scale is >= n, the call merely subtracts n from the scale; otherwise, it sets the scale to zero, and multiplies the integer value by 10 ** (n - this.scale). If n is negative, the call is equivalent to movePointLeft(-n). (The BigDecimal returned by this call has value (this * 10**n) and scale MAX(this.scale()-n, 0).)


 BigDecimal.multiply

BigDecimal.multiply

Class Overview | Class Members | This Package | All Packages

Syntax
public BigDecimal multiply( BigDecimal val )
Description
Returns a BigDecimal whose value is (this * val), and whose scale is this.scale() + val.scale.


 BigDecimal.negate

BigDecimal.negate

Class Overview | Class Members | This Package | All Packages

Syntax
public BigDecimal negate()
Description
Returns a BigDecimal whose value is -1 * this, and whose scale is this.scale().


 BigDecimal.scale

BigDecimal.scale

Class Overview | Class Members | This Package | All Packages

Syntax
public int scale()
Description
Returns the scale of this number.


 BigDecimal.setScale

BigDecimal.setScale

Class Overview | Class Members | This Package | All Packages

Syntax 1
public BigDecimal setScale( int scale, int roundingMode ) throws ArithmeticException, IllegalArgumentException
Description
Returns a BigDecimal whose scale is the specified value, and whose integer value is determined by multiplying or dividing this BigDecimal's integer value by the appropriate power of ten to maintain the overall value. If the scale is reduced by the operation, the integer value must be divided (rather than multiplied), and precision may be lost; in this case, the specified rounding mode is applied to the division. Throws an ArithmeticException if scale is negative, or the rounding mode is ROUND_UNNECESSARY and it is impossible to perform the specified scaling operation without loss of precision. Throws an IllegalArgumentException if roundingMode does not represent a valid rounding mode.

Syntax 2
public BigDecimal setScale( int scale ) throws ArithmeticException, IllegalArgumentException
Description
Returns a BigDecimal whose scale is the specified value, and whose value is exactly equal to this number's. Throws an ArithmeticException if this is not possible. This call is typically used to increase the scale, in which case it is guaranteed that there exists a BigDecimal of the specified scale and the correct value. The call can also be used to reduce the scale if the caller knows that the number has sufficiently many zeros at the end of its fractional part (i.e., factors of ten in its integer value) to allow for the rescaling without loss of precision. Note that this call returns the same result as the two argument version of setScale, but saves the caller the trouble of specifying a rounding mode in cases where it is irrelevant.


 BigDecimal.signum

BigDecimal.signum

Class Overview | Class Members | This Package | All Packages

Syntax
public int signum()
Description
Returns the signum function of this number (i.e., -1, 0 or 1 as the value of this number is negative, zero or positive).


 BigDecimal.subtract

BigDecimal.subtract

Class Overview | Class Members | This Package | All Packages

Syntax
public BigDecimal subtract( BigDecimal val )
Description
Returns a BigDecimal whose value is (this - val), and whose scale is MAX(this.scale(), val.scale).


 BigDecimal.toBigInteger

BigDecimal.toBigInteger

Class Overview | Class Members | This Package | All Packages

Syntax
public BigInteger toBigInteger()
Description
Converts this number to a BigInteger. Standard narrowing primitive conversion as per The Java Language Specification. In particular, note that any fractional part of this number will be truncated.


 BigDecimal.toString

BigDecimal.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Description
Returns the string representation of this number. The digit-to- character mapping provided by Character.forDigit is used. The minus sign and decimal point are used to indicate sign and scale. (This representation is compatible with the (String, int) constructor.)

Overrides
toString in class Object


 BigDecimal.valueOf

BigDecimal.valueOf

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static BigDecimal valueOf( long val, int scale ) throws NumberFormatException
Description
Returns a BigDecimal with a value of (val/10**scale). This factory is provided in preference to a (long) constructor because it allows for reuse of frequently used BigDecimals (like 0 and 1), obviating the need for exported constants. A negative scale will result in a NumberFormatException.

Syntax 2
public static BigDecimal valueOf( long val )
Description
Returns a BigDecimal with the given value and a scale of zero. This factory is provided in preference to a (long) constructor because it allows for reuse of frequently used BigDecimals (like 0 and 1), obviating the need for exported constants.


 Class BigInteger

Class java.math.BigInteger

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Number
           |
           +----java.math.BigInteger

public class BigInteger
extends Number

Immutable arbitrary-precision integers. All operations behave as if BigIntegers were represented in two's-complement notation (like Java's primitive integer types). BigIntegers provide analogues to all of Java's primitive integer operators, and all relevant static methods from java.lang.Math. Additionally, BigIntegers provide operations for modular arithmetic, GCD calculation, primality testing, prime generation, single-bit manipulation, and a few other odds and ends.

Semantics of arithmetic operations exactly mimic those of java's integer arithmetic operators, as defined in The Java Language Specification. For example, division by zero throws an ArithmeticException, and division of a negative by a positive yields a negative (or zero) remainder. All of the details in the Spec concerning overflow are ignored, as BigIntegers are made as large as necessary to accommodate the results of an operation.

Semantics of shift operations extend those of Java's shift operators to allow for negative shift distances. A right-shift with a negative shift distance results in a left shift, and vice-versa. The unsigned right shift operator (>>>) is omitted, as this operation makes little sense in combination with the "infinite word size" abstraction provided by this class.

Semantics of bitwise logical operations are are exactly mimic those of Java's bitwise integer operators. The Binary operators (and, or, xor) implicitly perform sign extension on the shorter of the two operands prior to performing the operation.

Comparison operations perform signed integer comparisons, analogous to those performed by java's relational and equality operators.

Modular arithmetic operations are provided to compute residues, perform exponentiation, and compute multiplicative inverses. These methods always return a non-negative result, between 0 and (modulus - 1), inclusive.

Single-bit operations operate on a single bit of the two's-complement representation of their operand. If necessary, the operand is sign extended so that it contains the designated bit. None of the single-bit operations can produce a number with a different sign from the the BigInteger being operated on, as they affect only a single bit, and the "infinite word size" abstraction provided by this class ensures that there are infinitely many "virtual sign bits" preceding each BigInteger.

See Also:
BigDecimal


 BigInteger Members

BigInteger Members

Class Overview | This Package | All Packages

Constructors
Name | Description
BigInteger(byte[]) | Translates a byte array containing the two's-complement representation of a (signed) integer into a BigInteger.
BigInteger(int, byte[]) | Translates the sign-magnitude representation of an integer into a BigInteger.
BigInteger(int, int, Random) | Returns a randomly selected BigInteger with the specified bitLength that is probably prime.
BigInteger(int, Random) | Returns a random number uniformly distributed on [0, 2**numBits - 1] (assuming a fair source of random bits is provided in rndSrc).
BigInteger(String) | Translates a string containing an optional minus sign followed by a sequence of one or more decimal digits into a BigInteger.
BigInteger(String, int) | Translates a string containing an optional minus sign followed by a sequence of one or more digits in the specified radix into a BigInteger.

Methods
Name | Description
abs() | Returns a BigInteger whose value is the absolute value of this number.
add(BigInteger) | Returns a BigInteger whose value is (this + val).
and(BigInteger) | Returns a BigInteger whose value is (this & val).
andNot(BigInteger) | Returns a BigInteger whose value is (this & ~val).
bitCount() | Returns the number of bits in the two's complement representation of this number that differ from its sign bit.
bitLength() | Returns the number of bits in the minimal two's-complement representation of this number, *excluding* a sign bit, i.e., (ceil(log2(this < 0 ? -this : this + 1))).
clearBit(int) | Returns a BigInteger whose value is equivalent to this number with the designated bit cleared.
compareTo(BigInteger) | Returns -1, 0 or 1 as this number is less than, equal to, or greater than val.
divide(BigInteger) | Returns a BigInteger whose value is (this / val).
divideAndRemainder(BigInteger) | Returns an array of two BigIntegers.
doubleValue() | Converts the number to a double.
equals(Object) | Returns true iff x is a BigInteger whose value is equal to this number.
flipBit(int) | Returns a BigInteger whose value is equivalent to this number with the designated bit flipped.
floatValue() | Converts this number to a float.
gcd(BigInteger) | Returns a BigInteger whose value is the greatest common denominator of abs(this) and abs(val).
getLowestSetBit() | Returns the index of the rightmost (lowest-order) one bit in this number (i.e., the number of zero bits to the right of the rightmost one bit).
hashCode() | Computes a hash code for this object.
intValue() | Converts this number to an int.
isProbablePrime(int) | Returns true if this BigInteger is probably prime, false if it's definitely composite.
longValue() | Converts this number to a long.
max(BigInteger) | Returns the BigInteger whose value is the greater of this and val.
min(BigInteger) | Returns the BigInteger whose value is the lesser of this and val.
mod(BigInteger) | Returns a BigInteger whose value is this mod m.
modInverse(BigInteger) | Returns modular multiplicative inverse of this, mod m.
modPow(BigInteger, BigInteger) | Returns a BigInteger whose value is (this ** exponent) mod m.
multiply(BigInteger) | Returns a BigInteger whose value is (this * val).
negate() | Returns a BigInteger whose value is (-1 * this).
not() | Returns a BigInteger whose value is (~this).
or(BigInteger) | Returns a BigInteger whose value is (this | val).
pow(int) | Returns a BigInteger whose value is (this ** exponent).
remainder(BigInteger) | Returns a BigInteger whose value is (this % val).
setBit(int) | Returns a BigInteger whose value is equivalent to this number with the designated bit set.
shiftLeft(int) | Returns a BigInteger whose value is (this << n).
shiftRight(int) | Returns a BigInteger whose value is (this >> n).
signum() | Returns the signum function of this number (i.e., -1, 0 or 1 as the value of this number is negative, zero or positive).
subtract(BigInteger) | Returns a BigInteger whose value is (this - val).
testBit(int) | Returns true iff the designated bit is set.
toByteArray() | Returns the two's-complement representation of this number.
toString() | Returns the string representation of this number, radix 10.
toString(int) | Returns the string representation of this number in the given radix.
valueOf(long) | Returns a BigInteger with the specified value.
xor(BigInteger) | Returns a BigInteger whose value is (this ^ val).


 BigInteger.BigInteger

BigInteger.BigInteger

Class Overview | Class Members | This Package | All Packages

Syntax 1
public BigInteger( byte val[] ) throws NumberFormatException
Description
Translates a byte array containing the two's-complement representation of a (signed) integer into a BigInteger. The input array is assumed to be big-endian (i.e., the most significant byte is in the [0] position). (The most significant bit of the most significant byte is the sign bit.) The array must contain at least one byte or a NumberFormatException will be thrown.

Syntax 2
public BigInteger( int signum, byte magnitude[] ) throws NumberFormatException
Description
Translates the sign-magnitude representation of an integer into a BigInteger. The sign is represented as an integer signum value (-1 for negative, 0 for zero, 1 for positive). The magnitude is represented as a big-endian byte array (i.e., the most significant byte is in the [0] position). An invalid signum value or a 0 signum value coupled with a nonzero magnitude will result in a NumberFormatException. A zero length magnitude array is permissible, and will result in in a value of 0 (irrespective of the given signum value).

Syntax 3
public BigInteger( String val, int radix ) throws NumberFormatException
Description
Translates a string containing an optional minus sign followed by a sequence of one or more digits in the specified radix into a BigInteger. The character-to-digit mapping is provided by Character.digit. Any extraneous characters (including whitespace), or a radix outside the range from Character.MIN_RADIX(2) to Character.MAX_RADIX(36), inclusive, will result in a NumberFormatException.

Syntax 4
public BigInteger( String val ) throws NumberFormatException
Description
Translates a string containing an optional minus sign followed by a sequence of one or more decimal digits into a BigInteger. The character-to-digit mapping is provided by Character.digit. Any extraneous characters (including whitespace) will result in a NumberFormatException.

Syntax 5
public BigInteger( int numBits, Random rndSrc ) throws IllegalArgumentException
Description
Returns a random number uniformly distributed on [0, 2**numBits - 1] (assuming a fair source of random bits is provided in rndSrc). Note that this constructor always returns a non-negative BigInteger. Throws an IllegalArgumentException if numBits < 0.

Syntax 6
public BigInteger( int bitLength, int certainty, Random rnd )
Description
Returns a randomly selected BigInteger with the specified bitLength that is probably prime. The certainty parameter is a measure of the uncertainty that the caller is willing to tolerate: the probability that the number is prime will exceed 1 - 1/2**certainty. The execution time is proportional to the value of the certainty parameter. The given random number generator is used to select candidates to be tested for primality. Throws an ArithmeticException if bitLength < 2.


 BigInteger.abs

BigInteger.abs

Class Overview | Class Members | This Package | All Packages

Syntax
public BigInteger abs()
Description
Returns a BigInteger whose value is the absolute value of this number.


 BigInteger.add

BigInteger.add

Class Overview | Class Members | This Package | All Packages

Syntax
public BigInteger add( BigInteger val ) throws ArithmeticException
Description
Returns a BigInteger whose value is (this + val).


 BigInteger.and

BigInteger.and

Class Overview | Class Members | This Package | All Packages

Syntax
public BigInteger and( BigInteger val )
Description
Returns a BigInteger whose value is (this & val). (This method returns a negative number iff this and val are both negative.)


 BigInteger.andNot

BigInteger.andNot

Class Overview | Class Members | This Package | All Packages

Syntax
public BigInteger andNot( BigInteger val )
Description
Returns a BigInteger whose value is (this & ~val). This method, which is equivalent to and(val.not()), is provided as a convenience for masking operations. (This method returns a negative number iff this is negative and val is positive.)


 BigInteger.bitCount

BigInteger.bitCount

Class Overview | Class Members | This Package | All Packages

Syntax
public int bitCount()
Description
Returns the number of bits in the two's complement representation of this number that differ from its sign bit. This method is useful when implementing bit-vector style sets atop BigIntegers.


 BigInteger.bitLength

BigInteger.bitLength

Class Overview | Class Members | This Package | All Packages

Syntax
public int bitLength()
Description
Returns the number of bits in the minimal two's-complement representation of this number, *excluding* a sign bit, i.e., (ceil(log2(this < 0 ? -this : this + 1))). (For positive numbers, this is equivalent to the number of bits in the ordinary binary representation.)


 BigInteger.clearBit

BigInteger.clearBit

Class Overview | Class Members | This Package | All Packages

Syntax
public BigInteger clearBit( int n ) throws ArithmeticException
Description
Returns a BigInteger whose value is equivalent to this number with the designated bit cleared. (Computes (this & ~(1 << n)).) Throws an ArithmeticException if n < 0.


 BigInteger.compareTo

BigInteger.compareTo

Class Overview | Class Members | This Package | All Packages

Syntax
public int compareTo( BigInteger val )
Description
Returns -1, 0 or 1 as this number is less than, equal to, or greater than val. This method is provided in preference to individual methods for each of the six boolean comparison operators (<, ==, >, >=, !=, <=). The suggested idiom for performing these comparisons is: (x.compareTo(y) 0), where is one of the six comparison operators.


 BigInteger.divide

BigInteger.divide

Class Overview | Class Members | This Package | All Packages

Syntax
public BigInteger divide( BigInteger val ) throws ArithmeticException
Description
Returns a BigInteger whose value is (this / val). Throws an ArithmeticException if val == 0.


 BigInteger.divideAndRemainder

BigInteger.divideAndRemainder

Class Overview | Class Members | This Package | All Packages

Syntax
public BigInteger[] divideAndRemainder( BigInteger val ) throws ArithmeticException
Description
Returns an array of two BigIntegers. The first ([0]) element of the return value is the quotient (this / val), and the second ([1]) element is the remainder (this % val). Throws an ArithmeticException if val == 0.


 BigInteger.doubleValue

BigInteger.doubleValue

Class Overview | Class Members | This Package | All Packages

Syntax
public double doubleValue()
Description
Converts the number to a double. Similar to the double-to-float narrowing primitive conversion defined in The Java Language Specification: if the number has too great a magnitude to represent as a double, it will be converted to infinity or negative infinity, as appropriate.

Overrides
doubleValue in class Number


 BigInteger.equals

BigInteger.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object x )
Description
Returns true iff x is a BigInteger whose value is equal to this number. This method is provided so that BigIntegers can be used as hash keys.

Overrides
equals in class Object


 BigInteger.flipBit

BigInteger.flipBit

Class Overview | Class Members | This Package | All Packages

Syntax
public BigInteger flipBit( int n ) throws ArithmeticException
Description
Returns a BigInteger whose value is equivalent to this number with the designated bit flipped. (Computes (this ^ (1 << n)).) Throws an ArithmeticException if n < 0.


 BigInteger.floatValue

BigInteger.floatValue

Class Overview | Class Members | This Package | All Packages

Syntax
public float floatValue()
Description
Converts this number to a float. Similar to the double-to-float narrowing primitive conversion defined in The Java Language Specification: if the number has too great a magnitude to represent as a float, it will be converted to infinity or negative infinity, as appropriate.

Overrides
floatValue in class Number


 BigInteger.gcd

BigInteger.gcd

Class Overview | Class Members | This Package | All Packages

Syntax
public BigInteger gcd( BigInteger val )
Description
Returns a BigInteger whose value is the greatest common denominator of abs(this) and abs(val). Returns 0 if this == 0 && val == 0.


 BigInteger.getLowestSetBit

BigInteger.getLowestSetBit

Class Overview | Class Members | This Package | All Packages

Syntax
public int getLowestSetBit()
Description
Returns the index of the rightmost (lowest-order) one bit in this number (i.e., the number of zero bits to the right of the rightmost one bit). Returns -1 if this number contains no one bits. (Computes (this==0? -1 : log2(this & -this)).)


 BigInteger.hashCode

BigInteger.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int hashCode()
Description
Computes a hash code for this object.

Overrides
hashCode in class Object


 BigInteger.intValue

BigInteger.intValue

Class Overview | Class Members | This Package | All Packages

Syntax
public int intValue()
Description
Converts this number to an int. Standard narrowing primitive conversion as per The Java Language Specification.

Overrides
intValue in class Number


 BigInteger.isProbablePrime

BigInteger.isProbablePrime

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isProbablePrime( int certainty )
Description
Returns true if this BigInteger is probably prime, false if it's definitely composite. The certainty parameter is a measure of the uncertainty that the caller is willing to tolerate: the method returns true if the probability that this number is is prime exceeds 1 - 1/2**certainty. The execution time is proportional to the value of the certainty parameter.


 BigInteger.longValue

BigInteger.longValue

Class Overview | Class Members | This Package | All Packages

Syntax
public long longValue()
Description
Converts this number to a long. Standard narrowing primitive conversion as per The Java Language Specification.

Overrides
longValue in class Number


 BigInteger.max

BigInteger.max

Class Overview | Class Members | This Package | All Packages

Syntax
public BigInteger max( BigInteger val )
Description
Returns the BigInteger whose value is the greater of this and val. If the values are equal, either may be returned.


 BigInteger.min

BigInteger.min

Class Overview | Class Members | This Package | All Packages

Syntax
public BigInteger min( BigInteger val )
Description
Returns the BigInteger whose value is the lesser of this and val. If the values are equal, either may be returned.


 BigInteger.mod

BigInteger.mod

Class Overview | Class Members | This Package | All Packages

Syntax
public BigInteger mod( BigInteger m )
Description
Returns a BigInteger whose value is this mod m. Throws an ArithmeticException if m <= 0.


 BigInteger.modInverse

BigInteger.modInverse

Class Overview | Class Members | This Package | All Packages

Syntax
public BigInteger modInverse( BigInteger m ) throws ArithmeticException
Description
Returns modular multiplicative inverse of this, mod m. Throws an ArithmeticException if m <= 0 or this has no multiplicative inverse mod m (i.e., gcd(this, m) != 1).


 BigInteger.modPow

BigInteger.modPow

Class Overview | Class Members | This Package | All Packages

Syntax
public BigInteger modPow( BigInteger exponent, BigInteger m )
Description
Returns a BigInteger whose value is (this ** exponent) mod m. (If exponent == 1, the returned value is (this mod m). If exponent < 0, the returned value is the modular multiplicative inverse of (this ** -exponent).) Throws an ArithmeticException if m <= 0.


 BigInteger.multiply

BigInteger.multiply

Class Overview | Class Members | This Package | All Packages

Syntax
public BigInteger multiply( BigInteger val )
Description
Returns a BigInteger whose value is (this * val).


 BigInteger.negate

BigInteger.negate

Class Overview | Class Members | This Package | All Packages

Syntax
public BigInteger negate()
Description
Returns a BigInteger whose value is (-1 * this).


 BigInteger.not

BigInteger.not

Class Overview | Class Members | This Package | All Packages

Syntax
public BigInteger not()
Description
Returns a BigInteger whose value is (~this). (This method returns a negative value iff this number is non-negative.)


 BigInteger.or

BigInteger.or

Class Overview | Class Members | This Package | All Packages

Syntax
public BigInteger or( BigInteger val )
Description
Returns a BigInteger whose value is (this | val). (This method returns a negative number iff either this or val is negative.)


 BigInteger.pow

BigInteger.pow

Class Overview | Class Members | This Package | All Packages

Syntax
public BigInteger pow( int exponent ) throws ArithmeticException
Description
Returns a BigInteger whose value is (this ** exponent). Throws an ArithmeticException if exponent < 0 (as the operation would yield a non-integer value). Note that exponent is an integer rather than a BigInteger.


 BigInteger.remainder

BigInteger.remainder

Class Overview | Class Members | This Package | All Packages

Syntax
public BigInteger remainder( BigInteger val ) throws ArithmeticException
Description
Returns a BigInteger whose value is (this % val). Throws an ArithmeticException if val == 0.


 BigInteger.setBit

BigInteger.setBit

Class Overview | Class Members | This Package | All Packages

Syntax
public BigInteger setBit( int n ) throws ArithmeticException
Description
Returns a BigInteger whose value is equivalent to this number with the designated bit set. (Computes (this | (1 << n)).) Throws an ArithmeticException if n < 0.


 BigInteger.shiftLeft

BigInteger.shiftLeft

Class Overview | Class Members | This Package | All Packages

Syntax
public BigInteger shiftLeft( int n )
Description
Returns a BigInteger whose value is (this << n). (Computes floor(this * 2**n).)


 BigInteger.shiftRight

BigInteger.shiftRight

Class Overview | Class Members | This Package | All Packages

Syntax
public BigInteger shiftRight( int n )
Description
Returns a BigInteger whose value is (this >> n). Sign extension is performed. (Computes floor(this / 2**n).)


 BigInteger.signum

BigInteger.signum

Class Overview | Class Members | This Package | All Packages

Syntax
public int signum()
Description
Returns the signum function of this number (i.e., -1, 0 or 1 as the value of this number is negative, zero or positive).


 BigInteger.subtract

BigInteger.subtract

Class Overview | Class Members | This Package | All Packages

Syntax
public BigInteger subtract( BigInteger val )
Description
Returns a BigInteger whose value is (this - val).


 BigInteger.testBit

BigInteger.testBit

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean testBit( int n ) throws ArithmeticException
Description
Returns true iff the designated bit is set. (Computes ((this & (1 << n)) != 0).) Throws an ArithmeticException if n < 0.


 BigInteger.toByteArray

BigInteger.toByteArray

Class Overview | Class Members | This Package | All Packages

Syntax
public byte[] toByteArray()
Description
Returns the two's-complement representation of this number. The array is big-endian (i.e., the most significant byte is in the [0] position). The array contains the minimum number of bytes required to represent the number (ceil((this.bitLength() + 1)/8)). (This representation is compatible with the (byte[]) constructor.)


 BigInteger.toString

BigInteger.toString

Class Overview | Class Members | This Package | All Packages

Syntax 1
public String toString( int radix )
Description
Returns the string representation of this number in the given radix. If the radix is outside the range from Character.MIN_RADIX(2) to Character.MAX_RADIX(36) inclusive, it will default to 10 (as is the case for Integer.toString). The digit-to-character mapping provided by Character.forDigit is used, and a minus sign is prepended if appropriate. (This representation is compatible with the (String, int) constructor.)

Syntax 2
public String toString()
Description
Returns the string representation of this number, radix 10. The digit-to-character mapping provided by Character.forDigit is used, and a minus sign is prepended if appropriate. (This representation is compatible with the (String) constructor, and allows for string concatenation with Java's + operator.)

Overrides
toString in class Object


 BigInteger.valueOf

BigInteger.valueOf

Class Overview | Class Members | This Package | All Packages

Syntax
public static BigInteger valueOf( long val )
Description
Returns a BigInteger with the specified value. This factory is provided in preference to a (long) constructor because it allows for reuse of frequently used BigIntegers (like 0 and 1), obviating the need for exported constants.


 BigInteger.xor

BigInteger.xor

Class Overview | Class Members | This Package | All Packages

Syntax
public BigInteger xor( BigInteger val )
Description
Returns a BigInteger whose value is (this ^ val). (This method returns a negative number iff exactly one of this and val are negative.)


 Package java.net

Package java.net

All Packages

Interfaces

  • ContentHandlerFactory
  • FileNameMap
  • SocketImplFactory
  • URLStreamHandlerFactory

    • Classes

  • ContentHandler
  • DatagramPacket
  • DatagramSocket
  • DatagramSocketImpl
  • HttpURLConnection
  • InetAddress
  • MulticastSocket
  • ServerSocket
  • Socket
  • SocketImpl
  • URL
  • URLConnection
  • URLEncoder
  • URLStreamHandler

    • Exceptions

  • BindException
  • ConnectException
  • MalformedURLException
  • NoRouteToHostException
  • ProtocolException
  • SocketException
  • UnknownHostException
  • UnknownServiceException


 Class BindException

Class java.net.BindException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.io.IOException
                           |
                           +----java.net.SocketException
                                   |
                                   +----java.net.BindException

public class BindException
extends SocketException

Signals that an error occurred while attempting to bind a socket to a local address and port. Typically, the port is in use, or the requested local address could not be assigned.


 BindException Members

BindException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
BindException() | Construct a new BindException with no detailed message.
BindException(String) | Constructs a new BindException with the specified detail message as to why the bind error occurred.


 BindException.BindException

BindException.BindException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public BindException( String msg )
Parameters
msg
the detail message
Description
Constructs a new BindException with the specified detail message as to why the bind error occurred. A detail message is a String that gives a specific description of this error.

Syntax 2
public BindException()
Description
Construct a new BindException with no detailed message.


 Class ConnectException

Class java.net.ConnectException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.io.IOException
                           |
                           +----java.net.SocketException
                                   |
                                   +----java.net.ConnectException

public class ConnectException
extends SocketException

Signals that an error occurred while attempting to connect a socket to a remote address and port. Typically, the connection was refused remotely (e.g., no process is listening on the remote address/port).


 ConnectException Members

ConnectException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
ConnectException() | Construct a new ConnectException with no detailed message.
ConnectException(String) | Constructs a new ConnectException with the specified detail message as to why the connect error occurred.


 ConnectException.ConnectException

ConnectException.ConnectException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public ConnectException( String msg )
Parameters
msg
the detail message
Description
Constructs a new ConnectException with the specified detail message as to why the connect error occurred. A detail message is a String that gives a specific description of this error.

Syntax 2
public ConnectException()
Description
Construct a new ConnectException with no detailed message.


 Class ContentHandler

Class java.net.ContentHandler

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.net.ContentHandler

public abstract class ContentHandler
extends Object

The abstract class ContentHandler is the superclass of all classes that read an Object from a URLConnection.

An application does not generally call the getContent method in this class directly. Instead, an application calls the getContent method in class URL or in URLConnection. The application's content handler factory (an instance of a class that implements the interface ContentHandlerFactory set up by a call to setContentHandler) is called with a String giving the MIME type of the object being received on the socket. The factory returns an instance of a subclass of ContentHandler, and its getContent method is called to create the object.

See Also:
getContent, ContentHandlerFactory, getContent, URLConnection, getContent, setContentHandlerFactory


 ContentHandler Members

ContentHandler Members

Class Overview | This Package | All Packages

Constructors
Name | Description
ContentHandler() |

Methods
Name | Description
getContent(URLConnection) | Given a URL connect stream positioned at the beginning of the representation of an object, this method reads that stream and creates an object from it.


 ContentHandler.ContentHandler

ContentHandler.ContentHandler

Class Overview | Class Members | This Package | All Packages

Syntax
public ContentHandler()


 ContentHandler.getContent

ContentHandler.getContent

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract Object getContent( URLConnection urlc ) throws IOException
Parameters
urlc
a URL connection.
Returns
the object read by the ContentHandler.
Description
Given a URL connect stream positioned at the beginning of the representation of an object, this method reads that stream and creates an object from it.

Exceptions
IOException if an I/O error occurs while reading the object.


 Interface ContentHandlerFactory

Interface java.net.ContentHandlerFactory

Interface Members | This Package | All Packages

public interface ContentHandlerFactory

This interface defines a factory for content handlers. An implementation of this interface should map a MIME type into an instance of ContentHandler.

This interface is used by the URLStreamHandler class to create a ContentHandler for a MIME type.

See Also:
ContentHandler, URLStreamHandler


 ContentHandlerFactory Members

ContentHandlerFactory Members

Interface Overview | This Package | All Packages

Methods
Name | Description
createContentHandler(String) | Creates a new ContentHandler to read an object from a URLStreamHandler.


 ContentHandlerFactory.createContentHandler

ContentHandlerFactory.createContentHandler

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract ContentHandler createContentHandler( String mimetype )
Parameters
mimetype
the MIME type for which a content handler is desired.
Returns
a new ContentHandler to read an object from a URLStreamHandler.
Description
Creates a new ContentHandler to read an object from a URLStreamHandler.

See Also
ContentHandler, URLStreamHandler


 Class DatagramPacket

Class java.net.DatagramPacket

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.net.DatagramPacket

public final class DatagramPacket
extends Object

This class represents a datagram packet.

Datagram packets are used to implement a connectionless packet delivery service. Each message is routed from one machine to another based solely on information contained within that packet. Multiple packets sent from one machine to another might be routed differently, and might arrive in any order.


 DatagramPacket Members

DatagramPacket Members

Class Overview | This Package | All Packages

Constructors
Name | Description
DatagramPacket(byte[], int) | Constructs a DatagramPacket for receiving packets of length ilength.
DatagramPacket(byte[], int, InetAddress, int) | Constructs a datagram packet for sending packets of length ilength to the specified port number on the specified host.

Methods
Name | Description
getAddress() | Returns the IP address of the machine to which this datagram is being sent or from which the datagram was received.
getData() | Returns the data received or the data to be sent.
getLength() | Returns the length of the data to be sent or the length of the data received.
getPort() | Returns the port number on the remote host to which this datagram is being sent or from which the datagram was received.
setAddress(InetAddress) |
setData(byte[]) |
setLength(int) |
setPort(int) |


 DatagramPacket.DatagramPacket

DatagramPacket.DatagramPacket

Class Overview | Class Members | This Package | All Packages

Syntax 1
public DatagramPacket( byte ibuf[], int ilength )
Parameters
ibuf
buffer for holding the incoming datagram.
ilength
the number of bytes to read.
Description
Constructs a DatagramPacket for receiving packets of length ilength.

The length argument must be less than or equal to ibuf.length.

Syntax 2
public DatagramPacket( byte ibuf[], int ilength, InetAddress iaddr, int iport )
Parameters
ibuf
the packet data.
ilength
the packet length.
iaddr
the destination address.
iport
the destination port number.
Description
Constructs a datagram packet for sending packets of length ilength to the specified port number on the specified host. The length argument must be less than or equal to ibuf.length.

See Also
InetAddress


 DatagramPacket.getAddress

DatagramPacket.getAddress

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized InetAddress getAddress()
Returns
the IP address of the machine to which this datagram is being sent or from which the datagram was received.
Description
Returns the IP address of the machine to which this datagram is being sent or from which the datagram was received.

See Also
InetAddress


 DatagramPacket.getData

DatagramPacket.getData

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized byte[] getData()
Returns
the data received or the data to be sent.
Description
Returns the data received or the data to be sent.


 DatagramPacket.getLength

DatagramPacket.getLength

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized int getLength()
Returns
the length of the data to be sent or the length of the data received.
Description
Returns the length of the data to be sent or the length of the data received.


 DatagramPacket.getPort

DatagramPacket.getPort

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized int getPort()
Returns
the port number on the remote host to which this datagram is being sent or from which the datagram was received.
Description
Returns the port number on the remote host to which this datagram is being sent or from which the datagram was received.


 DatagramPacket.setAddress

DatagramPacket.setAddress

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setAddress( InetAddress iaddr )


 DatagramPacket.setData

DatagramPacket.setData

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setData( byte ibuf[] )


 DatagramPacket.setLength

DatagramPacket.setLength

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setLength( int ilength )


 DatagramPacket.setPort

DatagramPacket.setPort

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setPort( int iport )


 Class DatagramSocket

Class java.net.DatagramSocket

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.net.DatagramSocket

public class DatagramSocket
extends Object

This class represents a socket for sending and receiving datagram packets.

A datagram socket is the sending or receiving point for a connectionless packet delivery service. Each packet sent or received on a datagram socket is individually addressed and routed. Multiple packets sent from one machine to another may be routed differently, and may arrive in any order.

See Also:
DatagramPacket


 DatagramSocket Members

DatagramSocket Members

Class Overview | This Package | All Packages

Constructors
Name | Description
DatagramSocket() | Constructs a datagram socket and binds it to any available port on the local host machine.
DatagramSocket(int) | Constructs a datagram socket and binds it to the specified port on the local host machine.
DatagramSocket(int, InetAddress) | Creates a datagram socket, bound to the specified local address.

Methods
Name | Description
close() | Closes this datagram socket.
getLocalAddress() | Gets the local address to which the socket is bound.
getLocalPort() | Returns the port number on the local host to which this socket is bound.
getSoTimeout() | Retrive setting for SO_TIMEOUT.
receive(DatagramPacket) | Receives a datagram packet from this socket.
send(DatagramPacket) | Sends a datagram packet from this socket.
setSoTimeout(int) | Enable/disable SO_TIMEOUT with the specified timeout, in milliseconds.


 DatagramSocket.DatagramSocket

DatagramSocket.DatagramSocket

Class Overview | Class Members | This Package | All Packages

Syntax 1
public DatagramSocket() throws SocketException
Description
Constructs a datagram socket and binds it to any available port on the local host machine.

Exceptions
SocketException if the socket could not be opened, or the socket could not bind to the specified local port.

Syntax 2
public DatagramSocket( int port ) throws SocketException
Parameters
local
port to use.
Description
Constructs a datagram socket and binds it to the specified port on the local host machine.

Exceptions
SocketException if the socket could not be opened, or the socket could not bind to the specified local port.

Syntax 3
public DatagramSocket( int port, InetAddress laddr ) throws SocketException
Parameters
port
local port to use
laddr
local address to bind
Description
Creates a datagram socket, bound to the specified local address. The local port must be between 0 and 65535 inclusive.


 DatagramSocket.close

DatagramSocket.close

Class Overview | Class Members | This Package | All Packages

Syntax
public void close()
Description
Closes this datagram socket.


 DatagramSocket.getLocalAddress

DatagramSocket.getLocalAddress

Class Overview | Class Members | This Package | All Packages

Syntax
public InetAddress getLocalAddress()
Description
Gets the local address to which the socket is bound.


 DatagramSocket.getLocalPort

DatagramSocket.getLocalPort

Class Overview | Class Members | This Package | All Packages

Syntax
public int getLocalPort()
Returns
the port number on the local host to which this socket is bound.
Description
Returns the port number on the local host to which this socket is bound.


 DatagramSocket.getSoTimeout

DatagramSocket.getSoTimeout

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized int getSoTimeout() throws SocketException
Description
Retrive setting for SO_TIMEOUT. 0 returns implies that the option is disabled (i.e., timeout of infinity).


 DatagramSocket.receive

DatagramSocket.receive

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void receive( DatagramPacket p ) throws IOException
Parameters
p
the DatagramPacket into which to place the incoming data.
Description
Receives a datagram packet from this socket. When this method returns, the DatagramPacket's buffer is filled with the data received. The datagram packet also contains the sender's IP address, and the port number on the sender's machine.

This method blocks until a datagram is received. The length field of the datagram packet object contains the length of the received message. If the message is longer than the buffer length, the message is truncated.

Exceptions
IOException if an I/O error occurs.
See Also
DatagramPacket, DatagramSocket


 DatagramSocket.send

DatagramSocket.send

Class Overview | Class Members | This Package | All Packages

Syntax
public void send( DatagramPacket p ) throws IOException
Parameters
p
the DatagramPacket to be sent.
Description
Sends a datagram packet from this socket. The DatagramPacket includes information indicating the data to be sent, its length, the IP address of the remote host, and the port number on the remote host.

Exceptions
IOException if an I/O error occurs.
See Also
DatagramPacket


 DatagramSocket.setSoTimeout

DatagramSocket.setSoTimeout

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setSoTimeout( int timeout ) throws SocketException
Description
Enable/disable SO_TIMEOUT with the specified timeout, in milliseconds. With this option set to a non-zero timeout, a call to receive() for this DatagramSocket will block for only this amount of time. If the timeout expires, a java.io.InterruptedIOException is raised, though the ServerSocket is still valid. The option must be enabled prior to entering the blocking operation to have effect. The timeout must be > 0. A timeout of zero is interpreted as an infinite timeout.


 Class DatagramSocketImpl

Class java.net.DatagramSocketImpl

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.net.DatagramSocketImpl

public abstract class DatagramSocketImpl
extends Object
implements SocketOptions

Abstract datagram and multicast socket implementation base class.


 DatagramSocketImpl Members

DatagramSocketImpl Members

Class Overview | This Package | All Packages

Fields
Name | Description
fd | The file descriptor object
localPort |

Constructors
Name | Description
DatagramSocketImpl() |

Methods
Name | Description
bind(int, InetAddress) | Binds a datagram socket to a local port and address.
close() | Close the socket.
create() | Creates a datagram socket
getFileDescriptor() | Get the datagram socket file descriptor
getLocalPort() | Get the local port.
getTTL() | Retrieve the TTL (time-to-live) option.
join(InetAddress) | Join the multicast group.
leave(InetAddress) | Leave the multicast group.
peek(InetAddress) | Peek at the packet to see who it is from.
receive(DatagramPacket) | Receive the datagram packet.
send(DatagramPacket) | Sends a datagram packet.
setTTL(byte) | Set the TTL (time-to-live) option.


 DatagramSocketImpl.fd

DatagramSocketImpl.fd

Class Overview | Class Members | This Package | All Packages

Syntax
protected FileDescriptor fd
Description
The file descriptor object


 DatagramSocketImpl.localPort

DatagramSocketImpl.localPort

Class Overview | Class Members | This Package | All Packages

Syntax
protected int localPort


 DatagramSocketImpl.DatagramSocketImpl

DatagramSocketImpl.DatagramSocketImpl

Class Overview | Class Members | This Package | All Packages

Syntax
public DatagramSocketImpl()


 DatagramSocketImpl.bind

DatagramSocketImpl.bind

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract void bind( int lport, InetAddress laddr ) throws SocketException
Description
Binds a datagram socket to a local port and address.


 DatagramSocketImpl.close

DatagramSocketImpl.close

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract void close()
Description
Close the socket.


 DatagramSocketImpl.create

DatagramSocketImpl.create

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract void create() throws SocketException
Description
Creates a datagram socket


 DatagramSocketImpl.getFileDescriptor

DatagramSocketImpl.getFileDescriptor

Class Overview | Class Members | This Package | All Packages

Syntax
protected FileDescriptor getFileDescriptor()
Description
Get the datagram socket file descriptor


 DatagramSocketImpl.getLocalPort

DatagramSocketImpl.getLocalPort

Class Overview | Class Members | This Package | All Packages

Syntax
protected int getLocalPort()
Description
Get the local port.


 DatagramSocketImpl.getTTL

DatagramSocketImpl.getTTL

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract byte getTTL() throws IOException
Description
Retrieve the TTL (time-to-live) option.


 DatagramSocketImpl.join

DatagramSocketImpl.join

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract void join( InetAddress inetaddr ) throws IOException
Parameters
multicast
address to join.
Description
Join the multicast group.


 DatagramSocketImpl.leave

DatagramSocketImpl.leave

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract void leave( InetAddress inetaddr ) throws IOException
Parameters
multicast
address to leave.
Description
Leave the multicast group.


 DatagramSocketImpl.peek

DatagramSocketImpl.peek

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract int peek( InetAddress i ) throws IOException
Parameters
return
the address which the packet came from.
Description
Peek at the packet to see who it is from.


 DatagramSocketImpl.receive

DatagramSocketImpl.receive

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract void receive( DatagramPacket p ) throws IOException
Parameters
Packet
Received.
Description
Receive the datagram packet.


 DatagramSocketImpl.send

DatagramSocketImpl.send

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract void send( DatagramPacket p ) throws IOException
Parameters
packet
to be sent.
Description
Sends a datagram packet. The packet contains the data and the destination address to send the packet to.


 DatagramSocketImpl.setTTL

DatagramSocketImpl.setTTL

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract void setTTL( byte ttl ) throws IOException
Parameters
TTL
to be set.
Description
Set the TTL (time-to-live) option.


 Interface FileNameMap

Interface java.net.FileNameMap

Interface Members | This Package | All Packages

public interface FileNameMap

A simple interface which provides a mechanism to map between between a file name and a MIME type string.


 FileNameMap Members

FileNameMap Members

Interface Overview | This Package | All Packages

Methods
Name | Description
getContentTypeFor(String) |


 FileNameMap.getContentTypeFor

FileNameMap.getContentTypeFor

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getContentTypeFor( String fileName )


 Class HttpURLConnection

Class java.net.HttpURLConnection

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.net.URLConnection
           |
           +----java.net.HttpURLConnection

public abstract class HttpURLConnection
extends URLConnection

A URLConnection with support for HTTP-specific features. See the spec for details.


 HttpURLConnection Members

HttpURLConnection Members

Class Overview | This Package | All Packages

Fields
Name | Description
HTTP_ACCEPTED |
HTTP_BAD_GATEWAY |
HTTP_BAD_METHOD |
HTTP_BAD_REQUEST | 4XX: client error
HTTP_CLIENT_TIMEOUT |
HTTP_CONFLICT |
HTTP_CREATED |
HTTP_ENTITY_TOO_LARGE |
HTTP_FORBIDDEN |
HTTP_GATEWAY_TIMEOUT |
HTTP_GONE |
HTTP_INTERNAL_ERROR |
HTTP_LENGTH_REQUIRED |
HTTP_MOVED_PERM |
HTTP_MOVED_TEMP |
HTTP_MULT_CHOICE | 3XX: relocation/redirect
HTTP_NO_CONTENT |
HTTP_NOT_ACCEPTABLE |
HTTP_NOT_AUTHORITATIVE |
HTTP_NOT_FOUND |
HTTP_NOT_MODIFIED |
HTTP_OK | 2XX: generally "OK"
HTTP_PARTIAL |
HTTP_PAYMENT_REQUIRED |
HTTP_PRECON_FAILED |
HTTP_PROXY_AUTH |
HTTP_REQ_TOO_LONG |
HTTP_RESET |
HTTP_SEE_OTHER |
HTTP_SERVER_ERROR | 5XX: server error
HTTP_UNAUTHORIZED |
HTTP_UNAVAILABLE |
HTTP_UNSUPPORTED_TYPE |
HTTP_USE_PROXY |
HTTP_VERSION |
method |
responseCode |
responseMessage |

Constructors
Name | Description
HttpURLConnection(URL) | Constructor for the URLStreamHandler.

Methods
Name | Description
disconnect() | Close the connection to the server.
getFollowRedirects()
getRequestMethod() | Get the request method.
getResponseCode() | Gets HTTP response status.
getResponseMessage() | Gets the HTTP response message, if any, returned along with the response code from a server.
setFollowRedirects(boolean) | Sets whether HTTP redirects (requests with response code 3xx) should be automatically followed by this class.
setRequestMethod(String) Set the method for the URL request, one of:
  • GET
  • POST
  • HEAD
  • OPTIONS
  • PUT
  • DELETE
  • TRACE
are legal, subject to protocol restrictions.
usingProxy() | Indicates if the connection is going through a proxy.


 HttpURLConnection.HTTP_ACCEPTED

HttpURLConnection.HTTP_ACCEPTED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HTTP_ACCEPTED


 HttpURLConnection.HTTP_BAD_GATEWAY

HttpURLConnection.HTTP_BAD_GATEWAY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HTTP_BAD_GATEWAY


 HttpURLConnection.HTTP_BAD_METHOD

HttpURLConnection.HTTP_BAD_METHOD

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HTTP_BAD_METHOD


 HttpURLConnection.HTTP_BAD_REQUEST

HttpURLConnection.HTTP_BAD_REQUEST

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HTTP_BAD_REQUEST
Description
4XX: client error


 HttpURLConnection.HTTP_CLIENT_TIMEOUT

HttpURLConnection.HTTP_CLIENT_TIMEOUT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HTTP_CLIENT_TIMEOUT


 HttpURLConnection.HTTP_CONFLICT

HttpURLConnection.HTTP_CONFLICT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HTTP_CONFLICT


 HttpURLConnection.HTTP_CREATED

HttpURLConnection.HTTP_CREATED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HTTP_CREATED


 HttpURLConnection.HTTP_ENTITY_TOO_LARGE

HttpURLConnection.HTTP_ENTITY_TOO_LARGE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HTTP_ENTITY_TOO_LARGE


 HttpURLConnection.HTTP_FORBIDDEN

HttpURLConnection.HTTP_FORBIDDEN

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HTTP_FORBIDDEN


 HttpURLConnection.HTTP_GATEWAY_TIMEOUT

HttpURLConnection.HTTP_GATEWAY_TIMEOUT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HTTP_GATEWAY_TIMEOUT


 HttpURLConnection.HTTP_GONE

HttpURLConnection.HTTP_GONE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HTTP_GONE


 HttpURLConnection.HTTP_INTERNAL_ERROR

HttpURLConnection.HTTP_INTERNAL_ERROR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HTTP_INTERNAL_ERROR


 HttpURLConnection.HTTP_LENGTH_REQUIRED

HttpURLConnection.HTTP_LENGTH_REQUIRED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HTTP_LENGTH_REQUIRED


 HttpURLConnection.HTTP_MOVED_PERM

HttpURLConnection.HTTP_MOVED_PERM

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HTTP_MOVED_PERM


 HttpURLConnection.HTTP_MOVED_TEMP

HttpURLConnection.HTTP_MOVED_TEMP

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HTTP_MOVED_TEMP


 HttpURLConnection.HTTP_MULT_CHOICE

HttpURLConnection.HTTP_MULT_CHOICE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HTTP_MULT_CHOICE
Description
3XX: relocation/redirect


 HttpURLConnection.HTTP_NO_CONTENT

HttpURLConnection.HTTP_NO_CONTENT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HTTP_NO_CONTENT


 HttpURLConnection.HTTP_NOT_ACCEPTABLE

HttpURLConnection.HTTP_NOT_ACCEPTABLE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HTTP_NOT_ACCEPTABLE


 HttpURLConnection.HTTP_NOT_AUTHORITATIVE

HttpURLConnection.HTTP_NOT_AUTHORITATIVE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HTTP_NOT_AUTHORITATIVE


 HttpURLConnection.HTTP_NOT_FOUND

HttpURLConnection.HTTP_NOT_FOUND

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HTTP_NOT_FOUND


 HttpURLConnection.HTTP_NOT_MODIFIED

HttpURLConnection.HTTP_NOT_MODIFIED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HTTP_NOT_MODIFIED


 HttpURLConnection.HTTP_OK

HttpURLConnection.HTTP_OK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HTTP_OK
Description
2XX: generally "OK"


 HttpURLConnection.HTTP_PARTIAL

HttpURLConnection.HTTP_PARTIAL

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HTTP_PARTIAL


 HttpURLConnection.HTTP_PAYMENT_REQUIRED

HttpURLConnection.HTTP_PAYMENT_REQUIRED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HTTP_PAYMENT_REQUIRED


 HttpURLConnection.HTTP_PRECON_FAILED

HttpURLConnection.HTTP_PRECON_FAILED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HTTP_PRECON_FAILED


 HttpURLConnection.HTTP_PROXY_AUTH

HttpURLConnection.HTTP_PROXY_AUTH

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HTTP_PROXY_AUTH


 HttpURLConnection.HTTP_REQ_TOO_LONG

HttpURLConnection.HTTP_REQ_TOO_LONG

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HTTP_REQ_TOO_LONG


 HttpURLConnection.HTTP_RESET

HttpURLConnection.HTTP_RESET

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HTTP_RESET


 HttpURLConnection.HTTP_SEE_OTHER

HttpURLConnection.HTTP_SEE_OTHER

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HTTP_SEE_OTHER


 HttpURLConnection.HTTP_SERVER_ERROR

HttpURLConnection.HTTP_SERVER_ERROR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HTTP_SERVER_ERROR
Description
5XX: server error


 HttpURLConnection.HTTP_UNAUTHORIZED

HttpURLConnection.HTTP_UNAUTHORIZED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HTTP_UNAUTHORIZED


 HttpURLConnection.HTTP_UNAVAILABLE

HttpURLConnection.HTTP_UNAVAILABLE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HTTP_UNAVAILABLE


 HttpURLConnection.HTTP_UNSUPPORTED_TYPE

HttpURLConnection.HTTP_UNSUPPORTED_TYPE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HTTP_UNSUPPORTED_TYPE


 HttpURLConnection.HTTP_USE_PROXY

HttpURLConnection.HTTP_USE_PROXY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HTTP_USE_PROXY


 HttpURLConnection.HTTP_VERSION

HttpURLConnection.HTTP_VERSION

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HTTP_VERSION


 HttpURLConnection.method

HttpURLConnection.method

Class Overview | Class Members | This Package | All Packages

Syntax
protected String method


 HttpURLConnection.responseCode

HttpURLConnection.responseCode

Class Overview | Class Members | This Package | All Packages

Syntax
protected int responseCode


 HttpURLConnection.responseMessage

HttpURLConnection.responseMessage

Class Overview | Class Members | This Package | All Packages

Syntax
protected String responseMessage


 HttpURLConnection.HttpURLConnection

HttpURLConnection.HttpURLConnection

Class Overview | Class Members | This Package | All Packages

Syntax
protected HttpURLConnection( URL u )
Description
Constructor for the URLStreamHandler.


 HttpURLConnection.disconnect

HttpURLConnection.disconnect

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void disconnect()
Description
Close the connection to the server.


 HttpURLConnection.getFollowRedirects

HttpURLConnection.getFollowRedirects

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean getFollowRedirects()


 HttpURLConnection.getRequestMethod

HttpURLConnection.getRequestMethod

Class Overview | Class Members | This Package | All Packages

Syntax
public String getRequestMethod()
Description
Get the request method.


 HttpURLConnection.getResponseCode

HttpURLConnection.getResponseCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int getResponseCode() throws IOException
Description
Gets HTTP response status. From responses like:
 HTTP/1.0 200 OK
 HTTP/1.0 401 Unauthorized
Extracts the ints 200 and 401 respectively. Returns -1 if none can be discerned from the response (i.e., the response is not valid HTTP).


 HttpURLConnection.getResponseMessage

HttpURLConnection.getResponseMessage

Class Overview | Class Members | This Package | All Packages

Syntax
public String getResponseMessage() throws IOException
Description
Gets the HTTP response message, if any, returned along with the response code from a server. From responses like:
 HTTP/1.0 200 OK
 HTTP/1.0 404 Not Found
Extracts the Strings "OK" and "Not Found" respectively. Returns null if none could be discerned from the responses (the result was not valid HTTP).


 HttpURLConnection.setFollowRedirects

HttpURLConnection.setFollowRedirects

Class Overview | Class Members | This Package | All Packages

Syntax
public static void setFollowRedirects( boolean set )
Description
Sets whether HTTP redirects (requests with response code 3xx) should be automatically followed by this class. False by default. Applets cannot change this variable.


 HttpURLConnection.setRequestMethod

HttpURLConnection.setRequestMethod

Class Overview | Class Members | This Package | All Packages

Syntax
public void setRequestMethod( String method ) throws ProtocolException
Description
Set the method for the URL request, one of:
  • GET
  • POST
  • HEAD
  • OPTIONS
  • PUT
  • DELETE
  • TRACE
are legal, subject to protocol restrictions. The default method is GET.

Exceptions
ProtocolException if the method cannot be reset or if the requested method isn't valid for HTTP.


 HttpURLConnection.usingProxy

HttpURLConnection.usingProxy

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract boolean usingProxy()
Description
Indicates if the connection is going through a proxy.


 Class InetAddress

Class java.net.InetAddress

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.net.InetAddress

public final class InetAddress
extends Object
implements Serializable

This class represents an Internet Protocol (IP) address.

Applications should use the methods getLocalHost, getByName, or getAllByName to create a new InetAddress instance.

See Also:
getAllByName, getByName, getLocalHost


 InetAddress Members

InetAddress Members

Class Overview | This Package | All Packages

Methods
Name | Description
equals(Object) | Compares this object against the specified object.
getAddress() | Returns the raw IP address of this InetAddress object.
getAllByName(String) | Determines all the IP addresses of a host, given the host's name.
getByName(String) | Determines the IP address of a host, given the host's name.
getHostAddress() | Returns the IP address string "%d.%d.%d.%d"
getHostName() | Returns the hostname for this address.
getLocalHost() | Returns the local host.
hashCode() | Returns a hashcode for this IP address.
isMulticastAddress() | Utility routine to check if the InetAddress is a IP multicast address.
toString() | Converts this IP address to a String.


 InetAddress.equals

InetAddress.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Parameters
obj
the object to compare against.
Returns
true if the objects are the same; false otherwise.
Description
Compares this object against the specified object. The result is true if and only if the argument is not null and it represents the same IP address as this object.

Two instances of InetAddress represent the same IP address if the length of the byte arrays returned by getAddress is the same for both, and each of the array components is the same for the byte arrays.

Overrides
equals in class Object
See Also
getAddress


 InetAddress.getAddress

InetAddress.getAddress

Class Overview | Class Members | This Package | All Packages

Syntax
public byte[] getAddress()
Returns
the raw IP address of this object.
Description
Returns the raw IP address of this InetAddress object. The result is in network byte order: the highest order byte of the address is in getAddress()[0].


 InetAddress.getAllByName

InetAddress.getAllByName

Class Overview | Class Members | This Package | All Packages

Syntax
public static InetAddress[] getAllByName( String host ) throws UnknownHostException
Parameters
host
the name of the host.
Returns
an array of all the IP addresses for a given host name.
Description
Determines all the IP addresses of a host, given the host's name. The host name can either be a machine name, such as "java.sun.com", or a string representing its IP address, such as "206.26.48.100".

Exceptions
UnknownHostException if no IP address for the host could be found.


 InetAddress.getByName

InetAddress.getByName

Class Overview | Class Members | This Package | All Packages

Syntax
public static InetAddress getByName( String host ) throws UnknownHostException
Parameters
host
the specified host, or null for the local host.
Returns
an IP address for the given host name.
Description
Determines the IP address of a host, given the host's name. The host name can either be a machine name, such as "java.sun.com", or a string representing its IP address, such as "206.26.48.100".

Exceptions
UnknownHostException if no IP address for the host could be found.


 InetAddress.getHostAddress

InetAddress.getHostAddress

Class Overview | Class Members | This Package | All Packages

Syntax
public String getHostAddress()
Returns
raw IP address in a string format
Description
Returns the IP address string "%d.%d.%d.%d"


 InetAddress.getHostName

InetAddress.getHostName

Class Overview | Class Members | This Package | All Packages

Syntax
public String getHostName()
Returns
the host name for this IP address.
Description
Returns the hostname for this address. If the host is equal to null, then this address refers to any of the local machine's available network addresses.


 InetAddress.getLocalHost

InetAddress.getLocalHost

Class Overview | Class Members | This Package | All Packages

Syntax
public static InetAddress getLocalHost() throws UnknownHostException
Returns
the IP address of the local host.
Description
Returns the local host.

Exceptions
UnknownHostException if no IP address for the host could be found.


 InetAddress.hashCode

InetAddress.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int hashCode()
Returns
a hash code value for this IP address.
Description
Returns a hashcode for this IP address.

Overrides
hashCode in class Object


 InetAddress.isMulticastAddress

InetAddress.isMulticastAddress

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isMulticastAddress()
Description
Utility routine to check if the InetAddress is a IP multicast address. IP multicast address is a Class D address i.e first four bits of the address are 1110.


 InetAddress.toString

InetAddress.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string representation of this IP address.
Description
Converts this IP address to a String.

Overrides
toString in class Object


 Class MalformedURLException

Class java.net.MalformedURLException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.io.IOException
                           |
                           +----java.net.MalformedURLException

public class MalformedURLException
extends IOException

Thrown to indicate that a malformed URL has occurred. Either no legal protocol could be found in a specification string or the string could not be parsed.


 MalformedURLException Members

MalformedURLException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
MalformedURLException() | Constructs a MalformedURLException with no detail message.
MalformedURLException(String) | Constructs a MalformedURLException with the specified detail message.


 MalformedURLException.MalformedURLException

MalformedURLException.MalformedURLException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public MalformedURLException()
Description
Constructs a MalformedURLException with no detail message.

Syntax 2
public MalformedURLException( String msg )
Parameters
msg
the detail message.
Description
Constructs a MalformedURLException with the specified detail message.


 Class MulticastSocket

Class java.net.MulticastSocket

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.net.DatagramSocket
           |
           +----java.net.MulticastSocket

public class MulticastSocket
extends DatagramSocket

The multicast datagram socket class is useful for sending and receiving IP multicast packets. A MulticastSocket is a (UDP) DatagramSocket, with additional capabilities for joining "groups" of other multicast hosts on the internet.

A multicast group is specified by a class D IP address, those in the range 224.0.0.1 to 239.255.255.255, inclusive, and by a standard UDP port number. One would join a multicast group by first creating a MulticastSocket with the desired port, then invoking the joinGroup(InetAddress groupAddr) method:

 // join a Multicast group and send the group salutations
 ...
 byte[] msg = {'H', 'e', 'l', 'l', 'o'};
 InetAddress group = InetAddress.getByName("228.5.6.7");
 MulticastSocket s = new MulticastSocket(6789);
 s.joinGroup(group);
 DatagramPacket hi = new DatagramPacket(msg, msg.length,
                             group, 6789);
 s.send(hi);
 // get their responses!
 byte[] buf = new byte[1000];
 DatagramPacket recv = new DatagramPacket(buf, buf.length);
 s.receive(recv);
 ...
 // OK, I'm done talking - leave the group...
 s.leaveGroup(group);
When one sends a message to a multicast group, all subscribing recipients to that host and port receive the message (within the time-to-live range of the packet, see below). The socket needn't be a member of the multicast group to send messages to it.

When a socket subscribes to a multicast group/port, it receives datagrams sent by other hosts to the group/port, as do all other members of the group and port. A socket relinquishes membership in a group by the leaveGroup(InetAddress addr) method. Multiple MulticastSocket's may subscribe to a multicast group and port concurrently, and they will all receive group datagrams.

Currently applets are not allowed ot use multicast sockets.


 MulticastSocket Members

MulticastSocket Members

Class Overview | This Package | All Packages

Constructors
Name | Description
MulticastSocket() | Create a multicast socket.
MulticastSocket(int) | Create a multicast socket and bind it to a specific port.

Methods
Name | Description
getInterface() | Retrieve the address of the network interface used for multicast packets.
getTTL() | Get the default time-to-live for multicast packets sent out on the socket.
joinGroup(InetAddress) | Joins a multicast group.
leaveGroup(InetAddress) | Leave a multicast group.
send(DatagramPacket, byte) | Sends a datagram packet to the destination, with a TTL (time- to-live) other than the default for the socket.
setInterface(InetAddress) | Set the outgoing network interface for multicast packets on this socket, to other than the system default.
setTTL(byte) | Set the default time-to-live for multicast packets sent out on this socket.


 MulticastSocket.MulticastSocket

MulticastSocket.MulticastSocket

Class Overview | Class Members | This Package | All Packages

Syntax 1
public MulticastSocket() throws IOException
Description
Create a multicast socket.

Syntax 2
public MulticastSocket( int port ) throws IOException
Parameters
local
port to use
Description
Create a multicast socket and bind it to a specific port.


 MulticastSocket.getInterface

MulticastSocket.getInterface

Class Overview | Class Members | This Package | All Packages

Syntax
public InetAddress getInterface() throws SocketException
Description
Retrieve the address of the network interface used for multicast packets.


 MulticastSocket.getTTL

MulticastSocket.getTTL

Class Overview | Class Members | This Package | All Packages

Syntax
public byte getTTL() throws IOException
Description
Get the default time-to-live for multicast packets sent out on the socket.


 MulticastSocket.joinGroup

MulticastSocket.joinGroup

Class Overview | Class Members | This Package | All Packages

Syntax
public void joinGroup( InetAddress mcastaddr ) throws IOException
Parameters
mcastaddr
is the multicast address to join
Description
Joins a multicast group.

Exceptions
IOException is raised if there is an error joining or when address is not a multicast address.


 MulticastSocket.leaveGroup

MulticastSocket.leaveGroup

Class Overview | Class Members | This Package | All Packages

Syntax
public void leaveGroup( InetAddress mcastaddr ) throws IOException
Parameters
mcastaddr
is the multicast address to leave
Description
Leave a multicast group.

Exceptions
IOException is raised if there is an error leaving or when address is not a multicast address.


 MulticastSocket.send

MulticastSocket.send

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void send( DatagramPacket p, byte ttl ) throws IOException
Parameters
p
is the packet to be sent. The packet should contain the destination multicast ip address and the data to be sent. One does not need to be the member of the group to send packets to a destination multicast address.
ttl
optional time to live for multicast packet. default ttl is 1.
Description
Sends a datagram packet to the destination, with a TTL (time- to-live) other than the default for the socket. This method need only be used in instances where a particular TTL is desired; otherwise it is preferable to set a TTL once on the socket, and use that default TTL for all packets. This method does not alter the default TTL for the socket.

Exceptions
IOException is raised if an error occurs i.e error while setting ttl.
See Also
send, receive


 MulticastSocket.setInterface

MulticastSocket.setInterface

Class Overview | Class Members | This Package | All Packages

Syntax
public void setInterface( InetAddress inf ) throws SocketException
Description
Set the outgoing network interface for multicast packets on this socket, to other than the system default. Useful for multihomed hosts.


 MulticastSocket.setTTL

MulticastSocket.setTTL

Class Overview | Class Members | This Package | All Packages

Syntax
public void setTTL( byte ttl ) throws IOException
Parameters
ttl
the time-to-live
Description
Set the default time-to-live for multicast packets sent out on this socket. The TTL sets the IP time-to-live for DatagramPackets sent to a MulticastGroup, which specifies how many "hops" that the packet will be forwarded on the network before it expires.

The ttl is an unsigned 8-bit quantity, and so must be in the range 0 < ttl <= 0xFF .


 Class NoRouteToHostException

Class java.net.NoRouteToHostException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.io.IOException
                           |
                           +----java.net.SocketException
                                   |
                                   +----java.net.NoRouteToHostException

public class NoRouteToHostException
extends SocketException

Signals that an error occurred while attempting to connect a socket to a remote address and port. Typically, the remote host cannot be reached because of an intervening firewall, or if an intermediate router is down.


 NoRouteToHostException Members

NoRouteToHostException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
NoRouteToHostException() | Construct a new NoRouteToHostException with no detailed message.
NoRouteToHostException(String) | Constructs a new NoRouteToHostException with the specified detail message as to why the remote host cannot be reached.


 NoRouteToHostException.NoRouteToHostException

NoRouteToHostException.NoRouteToHostException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public NoRouteToHostException( String msg )
Parameters
msg
the detail message
Description
Constructs a new NoRouteToHostException with the specified detail message as to why the remote host cannot be reached. A detail message is a String that gives a specific description of this error.

Syntax 2
public NoRouteToHostException()
Description
Construct a new NoRouteToHostException with no detailed message.


 Class ProtocolException

Class java.net.ProtocolException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.io.IOException
                           |
                           +----java.net.ProtocolException

public class ProtocolException
extends IOException

Thrown to indicate that there is an error in the underlying protocol, such as a TCP error.


 ProtocolException Members

ProtocolException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
ProtocolException() | Constructs a new ProtocolException with no detail message.
ProtocolException(String) | Constructs a new ProtocolException with the specified detail message.


 ProtocolException.ProtocolException

ProtocolException.ProtocolException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public ProtocolException( String host )
Parameters
host
the detail message.
Description
Constructs a new ProtocolException with the specified detail message.

Syntax 2
public ProtocolException()
Description
Constructs a new ProtocolException with no detail message.


 Class ServerSocket

Class java.net.ServerSocket

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.net.ServerSocket

public class ServerSocket
extends Object

This class implements server sockets. A server socket waits for requests to come in over the network. It performs some operation based on that request, and then possibly returns a result to the requester.

The actual work of the server socket is performed by an instance of the SocketImpl class. An application can change the socket factory that creates the socket implementation to configure itself to create sockets appropriate to the local firewall.

See Also:
SocketImpl, setSocketFactory


 ServerSocket Members

ServerSocket Members

Class Overview | This Package | All Packages

Constructors
Name | Description
ServerSocket(int) | Creates a server socket on a specified port.
ServerSocket(int, int) | Creates a server socket and binds it to the specified local port number.
ServerSocket(int, int, InetAddress) | Create a server with the specified port, listen backlog, and local IP address to bind to.

Methods
Name | Description
accept() | Listens for a connection to be made to this socket and accepts it.
close() | Closes this socket.
getInetAddress() | Returns the local address of this server socket.
getLocalPort() | Returns the port on which this socket is listening.
getSoTimeout() | Retrive setting for SO_TIMEOUT.
implAccept(Socket) | Subclasses of ServerSocket use this method to override accept() to return their own subclass of socket.
setSocketFactory(SocketImplFactory) | Sets the server socket implementation factory for the application.
setSoTimeout(int) | Enable/disable SO_TIMEOUT with the specified timeout, in milliseconds.
toString() | Returns the implementation address and implementation port of this socket as a String.


 ServerSocket.ServerSocket

ServerSocket.ServerSocket

Class Overview | Class Members | This Package | All Packages

Syntax 1
public ServerSocket( int port ) throws IOException
Parameters
port
the port number, or 0 to use any free port.
Description
Creates a server socket on a specified port. A port of 0 creates a socket on any free port.

The maximum queue length for incoming connection indications (a request to connect) is set to 50. If a connection indication arrives when the queue is full, the connection is refused.

If the application has specified a server socket factory, that factory's createSocketImpl method is called to create the actual socket implementation. Otherwise a "plain" socket is created.

Exceptions
IOException if an I/O error occurs when opening the socket.
See Also
SocketImpl, createSocketImpl, setSocketFactory

Syntax 2
public ServerSocket( int port, int backlog ) throws IOException
Parameters
port
the specified port, or 0 to use any free port.
backlog
the maximum length of the queue.
Description
Creates a server socket and binds it to the specified local port number. A port number of 0 creates a socket on any free port.

The maximum queue length for incoming connection indications (a request to connect) is set to the count parameter. If a connection indication arrives when the queue is full, the connection is refused.

If the application has specified a server socket factory, that factory's createSocketImpl method is called to create the actual socket implementation. Otherwise a "plain" socket is created.

Exceptions
IOException if an I/O error occurs when opening the socket.
See Also
SocketImpl, createSocketImpl, setSocketFactory

Syntax 3
public ServerSocket( int port, int backlog, InetAddress bindAddr ) throws IOException
Parameters
port
the local TCP port
backlog
the listen backlog
bindAddr
the local InetAddress the server will bind to
Description
Create a server with the specified port, listen backlog, and local IP address to bind to. The bindAddr argument can be used on a multi-homed host for a ServerSocket that will only accept connect requests to one of its addresses. If bindAddr is null, it will default accepting connections on any/all local addresses. The port must be between 0 and 65535, inclusive.

See Also
SocketConstants, SocketOption, SocketImpl, 1


 ServerSocket.accept

ServerSocket.accept

Class Overview | Class Members | This Package | All Packages

Syntax
public Socket accept() throws IOException
Description
Listens for a connection to be made to this socket and accepts it. The method blocks until a connection is made.

Exceptions
IOException if an I/O error occurs when waiting for a connection.


 ServerSocket.close

ServerSocket.close

Class Overview | Class Members | This Package | All Packages

Syntax
public void close() throws IOException
Description
Closes this socket.

Exceptions
IOException if an I/O error occurs when closing the socket.


 ServerSocket.getInetAddress

ServerSocket.getInetAddress

Class Overview | Class Members | This Package | All Packages

Syntax
public InetAddress getInetAddress()
Returns
the address to which this socket is connected, or null if the socket is not yet connected.
Description
Returns the local address of this server socket.


 ServerSocket.getLocalPort

ServerSocket.getLocalPort

Class Overview | Class Members | This Package | All Packages

Syntax
public int getLocalPort()
Returns
the port number to which this socket is listening.
Description
Returns the port on which this socket is listening.


 ServerSocket.getSoTimeout

ServerSocket.getSoTimeout

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized int getSoTimeout() throws IOException
Description
Retrive setting for SO_TIMEOUT. 0 returns implies that the option is disabled (i.e., timeout of infinity).


 ServerSocket.implAccept

ServerSocket.implAccept

Class Overview | Class Members | This Package | All Packages

Syntax
protected final void implAccept( Socket s ) throws IOException
Description
Subclasses of ServerSocket use this method to override accept() to return their own subclass of socket. So a FooServerSocket will typically hand this method an empty FooSocket(). On return from implAccept the FooSocket will be connected to a client.


 ServerSocket.setSocketFactory

ServerSocket.setSocketFactory

Class Overview | Class Members | This Package | All Packages

Syntax
public static synchronized void setSocketFactory( SocketImplFactory fac ) throws IOException
Parameters
fac
the desired factory.
Description
Sets the server socket implementation factory for the application. The factory can be specified only once.

When an application creates a new server socket, the socket implementation factory's createSocketImpl method is called to create the actual socket implementation.

Exceptions
IOException if an I/O error occurs when setting the socket factory.
Exceptions
SocketException if the factory has already been defined.
See Also
createSocketImpl


 ServerSocket.setSoTimeout

ServerSocket.setSoTimeout

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setSoTimeout( int timeout ) throws SocketException
Description
Enable/disable SO_TIMEOUT with the specified timeout, in milliseconds. With this option set to a non-zero timeout, a call to accept() for this ServerSocket will block for only this amount of time. If the timeout expires, a java.io.InterruptedIOException is raised, though the ServerSocket is still valid. The option must be enabled prior to entering the blocking operation to have effect. The timeout must be > 0. A timeout of zero is interpreted as an infinite timeout.


 ServerSocket.toString

ServerSocket.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string representation of this socket.
Description
Returns the implementation address and implementation port of this socket as a String.

Overrides
toString in class Object


 Class Socket

Class java.net.Socket

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.net.Socket

public class Socket
extends Object

This class implements client sockets (also called just "sockets"). A socket is an endpoint for communication between two machines.

The actual work of the socket is performed by an instance of the SocketImpl class. An application, by changing the socket factory that creates the socket implementation, can configure itself to create sockets appropriate to the local firewall.

See Also:
setSocketImplFactory, SocketImpl


 Socket Members

Socket Members

Class Overview | This Package | All Packages

Constructors
Name | Description
Socket() | Creates an unconnected socket, with the system-default type of SocketImpl.
Socket(InetAddress, int) | Creates a stream socket and connects it to the specified port number at the specified IP address.
Socket(InetAddress, int, boolean) | Creates a socket and connects it to the specified port number at the specified IP address. Deprecated.
Socket(InetAddress, int, InetAddress, int) | Creates a socket and connects it to the specified remote address on the specified remote port.
Socket(SocketImpl) | Creates an unconnected Socket with a user-specified SocketImpl.
Socket(String, int) | Creates a stream socket and connects it to the specified port number on the named host.
Socket(String, int, boolean) | Creates a stream socket and connects it to the specified port number on the named host. Deprecated.
Socket(String, int, InetAddress, int) | Creates a socket and connects it to the specified remote host on the specified remote port.

Methods
Name | Description
close() | Closes this socket.
getInetAddress() | Returns the address to which the socket is connected.
getInputStream() | Returns an input stream for this socket.
getLocalAddress() | Gets the local address to which the socket is bound.
getLocalPort() | Returns the local port to which this socket is bound.
getOutputStream() | Returns an output stream for this socket.
getPort() | Returns the remote port to which this socket is connected.
getSoLinger() | Returns setting for SO_LINGER.
getSoTimeout() | Returns setting for SO_TIMEOUT.
getTcpNoDelay() | Tests if TCP_NODELAY is enabled.
setSocketImplFactory(SocketImplFactory) | Sets the client socket implementation factory for the application.
setSoLinger(boolean, int) | Enable/disable SO_LINGER with the specified linger time.
setSoTimeout(int) | Enable/disable SO_TIMEOUT with the specified timeout, in milliseconds.
setTcpNoDelay(boolean) | Enable/disable TCP_NODELAY (disable/enable Nagle's algorithm).
toString() | Converts this socket to a String.


 Socket.Socket

Socket.Socket

Class Overview | Class Members | This Package | All Packages

Syntax 1
protected Socket()
Description
Creates an unconnected socket, with the system-default type of SocketImpl.

Syntax 2
protected Socket( SocketImpl impl ) throws SocketException
Description
Creates an unconnected Socket with a user-specified SocketImpl.

The impl parameter is an instance of a SocketImpl the subclass wishes to use on the Socket.

Syntax 3
public Socket( String host, int port ) throws UnknownHostException, IOException
Parameters
host
the host name.
port
the port number.
Description
Creates a stream socket and connects it to the specified port number on the named host.

If the application has specified a server socket factory, that factory's createSocketImpl method is called to create the actual socket implementation. Otherwise a "plain" socket is created.

Exceptions
IOException if an I/O error occurs when creating the socket.
See Also
setSocketImplFactory, SocketImpl, createSocketImpl

Syntax 4
public Socket( InetAddress address, int port ) throws IOException
Parameters
address
the IP address.
port
the port number.
Description
Creates a stream socket and connects it to the specified port number at the specified IP address.

If the application has specified a socket factory, that factory's createSocketImpl method is called to create the actual socket implementation. Otherwise a "plain" socket is created.

Exceptions
IOException if an I/O error occurs when creating the socket.
See Also
setSocketImplFactory, SocketImpl, createSocketImpl

Syntax 5
public Socket( String host, int port, InetAddress localAddr, int localPort ) throws IOException
Parameters
host
the name of the remote host
port
the remote port
localAddr
the local address the socket is bound to
localPort
the local port the socket is bound to
Description
Creates a socket and connects it to the specified remote host on the specified remote port. The Socket will also bind() to the local address and port supplied.

Syntax 6
public Socket( InetAddress address, int port, InetAddress localAddr, int localPort ) throws IOException
Parameters
address
the remote address
port
the remote port
localAddr
the local address the socket is bound to
localPort
the local port the socket is bound to
Description
Creates a socket and connects it to the specified remote address on the specified remote port. The Socket will also bind() to the local address and port supplied.

Syntax 7
public Socket( String host, int port, boolean stream ) throws IOException
Parameters
host
the host name.
port
the port number.
stream
a boolean indicating whether this is a stream socket or a datagram socket.
Description
Note: Socket() is deprecated. Use DatagramSocket instead for UDP transport.

Creates a stream socket and connects it to the specified port number on the named host.

If the stream argument is true, this creates a stream socket. If the stream argument is false, it creates a datagram socket.

If the application has specified a server socket factory, that factory's createSocketImpl method is called to create the actual socket implementation. Otherwise a "plain" socket is created.

Exceptions
IOException if an I/O error occurs when creating the socket.
See Also
setSocketImplFactory, SocketImpl, createSocketImpl

Syntax 8
public Socket( InetAddress host, int port, boolean stream ) throws IOException
Parameters
address
the IP address.
port
the port number.
stream
if true, create a stream socket; otherwise, create a datagram socket.
Description
Note: Socket() is deprecated. Use DatagramSocket instead for UDP transport.

Creates a socket and connects it to the specified port number at the specified IP address.

If the stream argument is true, this creates a stream socket. If the stream argument is false, it creates a datagram socket.

If the application has specified a server socket factory, that factory's createSocketImpl method is called to create the actual socket implementation. Otherwise a "plain" socket is created.

Exceptions
IOException if an I/O error occurs when creating the socket.
See Also
setSocketImplFactory, SocketImpl, createSocketImpl


 Socket.close

Socket.close

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void close() throws IOException
Description
Closes this socket.

Exceptions
IOException if an I/O error occurs when closing this socket.


 Socket.getInetAddress

Socket.getInetAddress

Class Overview | Class Members | This Package | All Packages

Syntax
public InetAddress getInetAddress()
Returns
the remote IP address to which this socket is connected.
Description
Returns the address to which the socket is connected.


 Socket.getInputStream

Socket.getInputStream

Class Overview | Class Members | This Package | All Packages

Syntax
public InputStream getInputStream() throws IOException
Returns
an input stream for reading bytes from this socket.
Description
Returns an input stream for this socket.

Exceptions
IOException if an I/O error occurs when creating the input stream.


 Socket.getLocalAddress

Socket.getLocalAddress

Class Overview | Class Members | This Package | All Packages

Syntax
public InetAddress getLocalAddress()
Description
Gets the local address to which the socket is bound.


 Socket.getLocalPort

Socket.getLocalPort

Class Overview | Class Members | This Package | All Packages

Syntax
public int getLocalPort()
Returns
the local port number to which this socket is connected.
Description
Returns the local port to which this socket is bound.


 Socket.getOutputStream

Socket.getOutputStream

Class Overview | Class Members | This Package | All Packages

Syntax
public OutputStream getOutputStream() throws IOException
Returns
an output stream for writing bytes to this socket.
Description
Returns an output stream for this socket.

Exceptions
IOException if an I/O error occurs when creating the output stream.


 Socket.getPort

Socket.getPort

Class Overview | Class Members | This Package | All Packages

Syntax
public int getPort()
Returns
the remote port number to which this socket is connected.
Description
Returns the remote port to which this socket is connected.


 Socket.getSoLinger

Socket.getSoLinger

Class Overview | Class Members | This Package | All Packages

Syntax
public int getSoLinger() throws SocketException
Description
Returns setting for SO_LINGER. -1 returns implies that the option is disabled.


 Socket.getSoTimeout

Socket.getSoTimeout

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized int getSoTimeout() throws SocketException
Description
Returns setting for SO_TIMEOUT. 0 returns implies that the option is disabled (i.e., timeout of infinity).


 Socket.getTcpNoDelay

Socket.getTcpNoDelay

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean getTcpNoDelay() throws SocketException
Description
Tests if TCP_NODELAY is enabled.


 Socket.setSocketImplFactory

Socket.setSocketImplFactory

Class Overview | Class Members | This Package | All Packages

Syntax
public static synchronized void setSocketImplFactory( SocketImplFactory fac ) throws IOException
Parameters
fac
the desired factory.
Description
Sets the client socket implementation factory for the application. The factory can be specified only once.

When an application creates a new client socket, the socket implementation factory's createSocketImpl method is called to create the actual socket implementation.

Exceptions
IOException if an I/O error occurs when setting the socket factory.
Exceptions
SocketException if the factory is already defined.
See Also
createSocketImpl


 Socket.setSoLinger

Socket.setSoLinger

Class Overview | Class Members | This Package | All Packages

Syntax
public void setSoLinger( boolean on, int val ) throws SocketException
Description
Enable/disable SO_LINGER with the specified linger time.


 Socket.setSoTimeout

Socket.setSoTimeout

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setSoTimeout( int timeout ) throws SocketException
Description
Enable/disable SO_TIMEOUT with the specified timeout, in milliseconds. With this option set to a non-zero timeout, a read() call on the InputStream associated with this Socket will block for only this amount of time. If the timeout expires, a java.io.InterruptedIOException is raised, though the Socket is still valid. The option must be enabled prior to entering the blocking operation to have effect. The timeout must be > 0. A timeout of zero is interpreted as an infinite timeout.


 Socket.setTcpNoDelay

Socket.setTcpNoDelay

Class Overview | Class Members | This Package | All Packages

Syntax
public void setTcpNoDelay( boolean on ) throws SocketException
Description
Enable/disable TCP_NODELAY (disable/enable Nagle's algorithm).


 Socket.toString

Socket.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string representation of this socket.
Description
Converts this socket to a String.

Overrides
toString in class Object


 Class SocketException

Class java.net.SocketException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.io.IOException
                           |
                           +----java.net.SocketException

public class SocketException
extends IOException

Thrown to indicate that there is an error in the underlying protocol, such as a TCP error.


 SocketException Members

SocketException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
SocketException() | Constructs a new ProtocolException with no detail message.
SocketException(String) | Constructs a new ProtocolException with the specified detail message.


 SocketException.SocketException

SocketException.SocketException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public SocketException( String msg )
Parameters
host
the detail message.
Description
Constructs a new ProtocolException with the specified detail message.

Syntax 2
public SocketException()
Description
Constructs a new ProtocolException with no detail message.


 Class SocketImpl

Class java.net.SocketImpl

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.net.SocketImpl

public abstract class SocketImpl
extends Object
implements SocketOptions

The abstract class SocketImpl is a common superclass of all classes that actually implement sockets. It is used to create both client and server sockets.

A "plain" socket implements these methods exactly as described, without attempting to go through a firewall or proxy.


 SocketImpl Members

SocketImpl Members

Class Overview | This Package | All Packages

Fields
Name | Description
address | The IP address of the remote end of this socket.
fd | The file descriptor object for this socket.
localport | The local port number to which this socket is connected.
port | The port number on the remote host to which this socket is connected.

Constructors
Name | Description
SocketImpl() |

Methods
Name | Description
accept(SocketImpl) | Accepts a connection.
available() | Returns the number of bytes that can be read from this socket without blocking.
bind(InetAddress, int) | Binds this socket to the specified port number on the specified host.
close() | Closes this socket.
connect(InetAddress, int) | Connects this socket to the specified port number on the specified host.
connect(String, int) | Connects this socket to the specified port on the named host.
create(boolean) | Creates either a stream or a datagram socket.
getFileDescriptor() | Returns the value of this socket's fd field.
getInetAddress() | Returns the value of this socket's address field.
getInputStream() | Returns an input stream for this socket.
getLocalPort() | Returns the value of this socket's localport field.
getOutputStream() | Returns an output stream for this socket.
getPort() | Returns the value of this socket's port field.
listen(int) | Sets the maximum queue length for incoming connection indications (a request to connect) to the count argument.
toString() | Returns the address and port of this socket as a String.


 SocketImpl.address

SocketImpl.address

Class Overview | Class Members | This Package | All Packages

Syntax
protected InetAddress address
Description
The IP address of the remote end of this socket.


 SocketImpl.fd

SocketImpl.fd

Class Overview | Class Members | This Package | All Packages

Syntax
protected FileDescriptor fd
Description
The file descriptor object for this socket.


 SocketImpl.localport

SocketImpl.localport

Class Overview | Class Members | This Package | All Packages

Syntax
protected int localport
Description
The local port number to which this socket is connected.


 SocketImpl.port

SocketImpl.port

Class Overview | Class Members | This Package | All Packages

Syntax
protected int port
Description
The port number on the remote host to which this socket is connected.


 SocketImpl.SocketImpl

SocketImpl.SocketImpl

Class Overview | Class Members | This Package | All Packages

Syntax
public SocketImpl()


 SocketImpl.accept

SocketImpl.accept

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract void accept( SocketImpl s ) throws IOException
Parameters
s
the accepted connection.
Description
Accepts a connection.

Exceptions
IOException if an I/O error occurs when accepting the connection.


 SocketImpl.available

SocketImpl.available

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract int available() throws IOException
Returns
the number of bytes that can be read from this socket without blocking.
Description
Returns the number of bytes that can be read from this socket without blocking.

Exceptions
IOException if an I/O error occurs when determining the number of bytes available.


 SocketImpl.bind

SocketImpl.bind

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract void bind( InetAddress host, int port ) throws IOException
Parameters
host
the IP address of the remote host.
port
the port number.
Description
Binds this socket to the specified port number on the specified host.

Exceptions
IOException if an I/O error occurs when binding this socket.


 SocketImpl.close

SocketImpl.close

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract void close() throws IOException
Description
Closes this socket.

Exceptions
IOException if an I/O error occurs when closing this socket.


 SocketImpl.connect

SocketImpl.connect

Class Overview | Class Members | This Package | All Packages

Syntax 1
protected abstract void connect( String host, int port ) throws IOException
Parameters
host
the name of the remote host.
port
the port number.
Description
Connects this socket to the specified port on the named host.

Exceptions
IOException if an I/O error occurs when connecting to the remote host.

Syntax 2
protected abstract void connect( InetAddress address, int port ) throws IOException
Parameters
address
the IP address of the remote host.
port
the port number.
Description
Connects this socket to the specified port number on the specified host.

Exceptions
IOException if an I/O error occurs when attempting a connection.


 SocketImpl.create

SocketImpl.create

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract void create( boolean stream ) throws IOException
Parameters
stream
if true, create a stream socket; otherwise, create a datagram socket.
Description
Creates either a stream or a datagram socket.

Exceptions
IOException if an I/O error occurs while creating the socket.


 SocketImpl.getFileDescriptor

SocketImpl.getFileDescriptor

Class Overview | Class Members | This Package | All Packages

Syntax
protected FileDescriptor getFileDescriptor()
Returns
the value of this socket's fd field.
Description
Returns the value of this socket's fd field.

See Also
fd


 SocketImpl.getInetAddress

SocketImpl.getInetAddress

Class Overview | Class Members | This Package | All Packages

Syntax
protected InetAddress getInetAddress()
Returns
the value of this socket's address field.
Description
Returns the value of this socket's address field.

See Also
address


 SocketImpl.getInputStream

SocketImpl.getInputStream

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract InputStream getInputStream() throws IOException
Returns
a stream for reading from this socket.
Description
Returns an input stream for this socket.

Exceptions
IOException if an I/O error occurs when creating the input stream.


 SocketImpl.getLocalPort

SocketImpl.getLocalPort

Class Overview | Class Members | This Package | All Packages

Syntax
protected int getLocalPort()
Returns
the value of this socket's localport field.
Description
Returns the value of this socket's localport field.

See Also
localport


 SocketImpl.getOutputStream

SocketImpl.getOutputStream

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract OutputStream getOutputStream() throws IOException
Returns
an output stream for writing to this socket.
Description
Returns an output stream for this socket.

Exceptions
IOException if an I/O error occurs when creating the output stream.


 SocketImpl.getPort

SocketImpl.getPort

Class Overview | Class Members | This Package | All Packages

Syntax
protected int getPort()
Returns
the value of this socket's port field.
Description
Returns the value of this socket's port field.

See Also
port


 SocketImpl.listen

SocketImpl.listen

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract void listen( int backlog ) throws IOException
Parameters
backlog
the maximum length of the queue.
Description
Sets the maximum queue length for incoming connection indications (a request to connect) to the count argument. If a connection indication arrives when the queue is full, the connection is refused.

Exceptions
IOException if an I/O error occurs when creating the queue.


 SocketImpl.toString

SocketImpl.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string representation of this socket.
Description
Returns the address and port of this socket as a String.

Overrides
toString in class Object


 Interface SocketImplFactory

Interface java.net.SocketImplFactory

Interface Members | This Package | All Packages

public interface SocketImplFactory

This interface defines a factory for socket implementations. It is used by the classes Socket and ServerSocket to create actual socket implementations.

See Also:
Socket, ServerSocket


 SocketImplFactory Members

SocketImplFactory Members

Interface Overview | This Package | All Packages

Methods
Name | Description
createSocketImpl() | Creates a new SocketImpl instance.


 SocketImplFactory.createSocketImpl

SocketImplFactory.createSocketImpl

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract SocketImpl createSocketImpl()
Returns
a new instance of SocketImpl.
Description
Creates a new SocketImpl instance.

See Also
SocketImpl


 Class URL

Class java.net.URL

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.net.URL

public final class URL
extends Object
implements Serializable

Class URL represents a Uniform Resource Locator, a pointer to a "resource" on the World Wide Web. A resource can be something as simple as a file or a directory, or it can be a reference to a more complicated object, such as a query to a database or to a search engine. More information on the types of URLs and their formats can be found at:

    http://www.ncsa.uiuc.edu/demoweb/url-primer.html

In general, a URL can be broken into several parts. The previous example of a URL indicates that the protocol to use is http (HyperText Transport Protocol) and that the information resides on a host machine named www.ncsa.uiuc.edu. The information on that host machine is named demoweb/url-primer.html. The exact meaning of this name on the host machine is both protocol dependent and host dependent. The information normally resides in a file, but it could be generated on the fly. This component of the URL is called the file component, even though the information is not necessarily in a file.

A URL can optionally specify a "port", which is the port number to which the TCP connection is made on the remote host machine. If the port is not specified, the default port for the protocol is used instead. For example, the default port for http is 80. An alternative port could be specified as:

    http://www.ncsa.uiuc.edu:8080/demoweb/url-primer.html

A URL may have appended to it an "anchor", also known as a "ref" or a "reference". The anchor is indicated by the sharp sign character "#" followed by more characters. For example,

    http://java.sun.com/index.html#chapter1

This anchor is not technically part of the URL. Rather, it indicates that after the specified resource is retrieved, the application is specifically interested in that part of the document that has the tag chapter1 attached to it. The meaning of a tag is resource specific.

An application can also specify a "relative URL", which contains only enough information to reach the resource relative to another URL. Relative URLs are frequently used within HTML pages. For example, if the contents of the URL:

    http://java.sun.com/index.html
contained within it the relative URL:
    FAQ.html
it would be a shorthand for:
    http://java.sun.com/FAQ.html

The relative URL need not specify all the components of a URL. If the protocol, host name, or port number is missing, the value is inherited from the fully specified URL. The file component must be specified. The optional anchor is not inherited.


 URL Members

URL Members

Class Overview | This Package | All Packages

Constructors
Name | Description
URL(String) | Creates a URL object from the String representation.
URL(String, String, int, String) | Creates a URL object from the specified protocol, host, port number, and file.
URL(String, String, String) | Creates an absolute URL from the specified protocol name, host name, and file name.
URL(URL, String) | Creates a URL by parsing the specification spec within a specified context.

Methods
Name | Description
equals(Object) | Compares two URLs.
getContent() | Returns the contents of this URL.
getFile() | Returns the file name of this URL.
getHost() | Returns the host name of this URL, if applicable.
getPort() | Returns the port number of this URL.
getProtocol() | Returns the protocol name this URL.
getRef() | Returns the anchor (also known as the "reference") of this URL.
hashCode() | Creates an integer suitable for hash table indexing.
openConnection() | Returns a URLConnection object that represents a connection to the remote object referred to by the URL.
openStream() | Opens a connection to this URL and returns an InputStream for reading from that connection.
sameFile(URL) | Compares two URLs, excluding the "ref" fields.
set(String, String, int, String, String) | Sets the fields of the URL.
setURLStreamHandlerFactory(URLStreamHandlerFactory) | Sets an application's URLStreamHandlerFactory.
toExternalForm() | Constructs a string representation of this URL.
toString() | Constructs a string representation of this URL.


 URL.URL

URL.URL

Class Overview | Class Members | This Package | All Packages

Syntax 1
public URL( String protocol, String host, int port, String file ) throws MalformedURLException
Parameters
protocol
the name of the protocol.
host
the name of the host.
port
the port number.
file
the host file.
Description
Creates a URL object from the specified protocol, host, port number, and file. Specifying a port number of -1 indicates that the URL should use the default port for the protocol.

If this is the first URL object being created with the specified protocol, a stream protocol handler object, an instance of class URLStreamHandler, is created for that protocol:

  1. If the application has previously set up an instance of URLStreamHandlerFactory as the stream handler factory, then the createURLStreamHandler method of that instance is called with the protocol string as an argument to create the stream protocol handler.
  2. If no URLStreamHandlerFactory has yet been set up, or if the factory's createURLStreamHandler method returns null, then the constructor finds the value of the system property:
      java.handler.protol.pkgs
    If the value of that system property is not null, it is interpreted as a list of packages separated by a vertical slash character '|'. The constructor tries to load the class named:
      <package>.<protocol>.Handler
    where <package> is replaced by the name of the package and <protocol> is replaced by the name of the protocol. If this class does not exist, or if the class exists but it is not a subclass of URLStreamHandler, then the next package in the list is tried.
  3. If the previous step fails to find a protocol handler, then the constructor tries to load the class named:
      sun.net.www.protocol.<protocol>.Handler
    If this class does not exist, or if the class exists but it is not a subclass of URLStreamHandler, then a MalformedURLException is thrown.

Exceptions
MalformedURLException if an unknown protocol is specified.
See Also
getProperty, setURLStreamHandlerFactory, URLStreamHandler, createURLStreamHandler

Syntax 2
public URL( String protocol, String host, String file ) throws MalformedURLException
Parameters
protocol
the protocol to use.
host
the host to connect to.
file
the file on that host.
Description
Creates an absolute URL from the specified protocol name, host name, and file name. The default port for the specified protocol is used.

This method is equivalent to calling the four-argument constructor with the arguments being protocol, host, -1, and file.

Exceptions
MalformedURLException if an unknown protocol is specified.
See Also
URL

Syntax 3
public URL( String spec ) throws MalformedURLException
Parameters
spec
the String to parse as a URL.
Description
Creates a URL object from the String representation.

This constructor is equivalent to a call to the two-argument constructor with a null first argument.

Exceptions
MalformedURLException If the string specifies an unknown protocol.
See Also
URL

Syntax 4
public URL( URL context, String spec ) throws MalformedURLException
Parameters
context
the context in which to parse the specification.
spec
a String representation of a URL.
Description
Creates a URL by parsing the specification spec within a specified context. If the context argument is not null and the spec argument is a partial URL specification, then any of the strings missing components are inherited from the context argument.

The specification given by the String argument is parsed to determine if it specifies a protocol. If the String contains an ASCII colon ':' character before the first occurrence of an ASCII slash character '/', then the characters before the colon comprise the protocol.

  • If the spec argument does not specify a protocol:
    • If the context argument is not null, then the protocol is copied from the context argument.
    • If the context argument is null, then a MalformedURLException is thrown.
  • If the spec argument does specify a protocol:
    • If the context argument is null, or specifies a different protocol than the specification argument, the context argument is ignored.
    • If the context argument is not null and specifies the same protocol as the specification, the host, port number, and file are copied from the context argument into the newly created URL.

The constructor then searches for an appropriate stream protocol handler of type URLStreamHandler as outlined for:

    java.net.URL#URL(java.lang.String, java.lang.String, int, java.lang.String)
The stream protocol handler's parseURL method is called to parse the remaining fields of the specification that override any defaults set by the context argument.

Exceptions
MalformedURLException if no protocol is specified, or an unknown protocol is found.
See Also
URL, URLStreamHandler, parseURL


 URL.equals

URL.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Parameters
obj
the URL to compare against.
Returns
true if the objects are the same; false otherwise.
Description
Compares two URLs. The result is true if and only if the argument is not null and is a URL object that represents the same URL as this object. Two URL objects are equal if they have the same protocol and reference the same host, the same port number on the host, and the same file on the host. The anchors of the URL objects are not compared.

This method is equivalent to:

    (obj instanceof URL) && sameFile((URL)obj)

Overrides
equals in class Object


 URL.getContent

URL.getContent

Class Overview | Class Members | This Package | All Packages

Syntax
public final Object getContent() throws IOException
Returns
the contents of this URL.
Description
Returns the contents of this URL. This method is a shorthand for:
    openConnection().getContent()

Exceptions
IOException if an I/O exception occurs.
See Also
getContent


 URL.getFile

URL.getFile

Class Overview | Class Members | This Package | All Packages

Syntax
public String getFile()
Returns
the file name of this URL.
Description
Returns the file name of this URL.


 URL.getHost

URL.getHost

Class Overview | Class Members | This Package | All Packages

Syntax
public String getHost()
Returns
the host name of this URL.
Description
Returns the host name of this URL, if applicable. For "file" protocol, this is an empty string.


 URL.getPort

URL.getPort

Class Overview | Class Members | This Package | All Packages

Syntax
public int getPort()
Returns
the port number
Description
Returns the port number of this URL. Returns -1 if the port is not set.


 URL.getProtocol

URL.getProtocol

Class Overview | Class Members | This Package | All Packages

Syntax
public String getProtocol()
Returns
the protocol of this URL.
Description
Returns the protocol name this URL.


 URL.getRef

URL.getRef

Class Overview | Class Members | This Package | All Packages

Syntax
public String getRef()
Returns
the anchor (also known as the "reference") of this URL.
Description
Returns the anchor (also known as the "reference") of this URL.


 URL.hashCode

URL.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int hashCode()
Returns
a hash code for this URL.
Description
Creates an integer suitable for hash table indexing.

Overrides
hashCode in class Object


 URL.openConnection

URL.openConnection

Class Overview | Class Members | This Package | All Packages

Syntax
public URLConnection openConnection() throws IOException
Returns
a URLConnection to the URL.
Description
Returns a URLConnection object that represents a connection to the remote object referred to by the URL.

If there is not already an open connection, the connection is opened by calling the openConnection method of the protocol handler for this URL.

Exceptions
IOException if an I/O exception occurs.
See Also
URL, URLConnection, openConnection


 URL.openStream

URL.openStream

Class Overview | Class Members | This Package | All Packages

Syntax
public final InputStream openStream() throws IOException
Returns
an input stream for reading from the URL connection.
Description
Opens a connection to this URL and returns an InputStream for reading from that connection. This method is a shorthand for:
    openConnection().getInputStream()

Exceptions
IOException if an I/O exception occurs.


 URL.sameFile

URL.sameFile

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean sameFile( URL other )
Parameters
other
the URL to compare against.
Returns
true if they reference the same remote object; false otherwise.
Description
Compares two URLs, excluding the "ref" fields. Returns true if this URL and the other argument both refer to the same resource. The two URLs might not both contain the same anchor.


 URL.set

URL.set

Class Overview | Class Members | This Package | All Packages

Syntax
protected void set( String protocol, String host, int port, String file, String ref )
Parameters
protocol
the protocol to use
host
the host name to connecto to
port
the protocol port to connect to
file
the specified file name on that host
ref
the reference
Description
Sets the fields of the URL. This is not a public method so that only URLStreamHandlers can modify URL fields. URLs are otherwise constant. REMIND: this method will be moved to URLStreamHandler


 URL.setURLStreamHandlerFactory

URL.setURLStreamHandlerFactory

Class Overview | Class Members | This Package | All Packages

Syntax
public static synchronized void setURLStreamHandlerFactory( URLStreamHandlerFactory fac )
Parameters
fac
the desired factory.
Description
Sets an application's URLStreamHandlerFactory. This method can be called at most once by an application.

The URLStreamHandlerFactory instance is used to construct a stream protocol handler from a protocol name.

Exceptions
Error if the application has already set a factory.
See Also
URL, URLStreamHandlerFactory


 URL.toExternalForm

URL.toExternalForm

Class Overview | Class Members | This Package | All Packages

Syntax
public String toExternalForm()
Returns
a string representation of this object.
Description
Constructs a string representation of this URL. The string is created by calling the toExternalForm method of the stream protocol handler for this object.

See Also
URL, toExternalForm


 URL.toString

URL.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string representation of this object.
Description
Constructs a string representation of this URL. The string is created by calling the toExternalForm method of the stream protocol handler for this object.

Overrides
toString in class Object
See Also
URL, toExternalForm


 Class URLConnection

Class java.net.URLConnection

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.net.URLConnection

public abstract class URLConnection
extends Object

The abstract class URLConnection is the superclass of all classes that represent a communications link between the application and a URL. Instances of this class can be used both to read from and to write to the resource referenced by the URL. In general, creating a connection to a URL is a multistep process:

openConnection() | connect()
Manipulate parameters that affect the connection to the remote resource. | Interact with the resource; query header fields and contents.
---------------------------->
time
  1. The connection object is created by invoking the openConnection method on a URL.
  2. The setup parameters and general request properties are manipulated.
  3. The actual connection to the remote object is made, using the connect method.
  4. The remote object becomes available. The header fields and the contents of the remote object can be accessed.

The setup parameters are modified using the following methods:

  • setAllowUserInteraction
  • setDoInput
  • setDoOutput
  • setIfModifiedSince
  • setUseCaches

and the general request properties are modified using the method:

  • setRequestProperty

Default values for the AllowUserInteraction and UseCaches parameters can be set using the methods setDefaultAllowUserInteraction and setDefaultUseCaches. Default values for general request properties can be set using the setDefaultRequestProperty method.

Each of the above set methods has a corresponding get method to retrieve the value of the parameter or general request property. The specific parameters and general request properties that are applicable are protocol specific.

The following methods are used to access the header fields and the contents after the connection is made to the remote object:

  • getContent
  • getHeaderField
  • getInputStream
  • getOutputStream

Certain header fields are accessed frequently. The methods:

  • getContentEncoding
  • getContentLength
  • getContentType
  • getDate
  • getExpiration
  • getLastModifed

provide convenient access to these fields. The getContentType method is used by the getContent method to determine the type of the remote object; subclasses may find it convenient to override the getContentType method.

In the common case, all of the pre-connection parameters and general request properties can be ignored: the pre-connection parameters and request properties default to sensible values. For most clients of this interface, there are only two interesting methods: getInputStream and getObject, which are mirrored in the URL class by convenience methods.

More information on the request properties and header fields of an http connection can be found at:

    http://www.w3.org/hypertext/WWW/Protocols/HTTP1.0/draft-ietf-http-spec.html

See Also:
openConnection, connect, getContent, getContentEncoding, getContentLength, getContentType, getDate, getExpiration, getHeaderField, getHeaderField, getInputStream, getLastModified, getOutputStream, setAllowUserInteraction, setDefaultRequestProperty, setDefaultUseCaches, setDoInput, setDoOutput, setIfModifiedSince, setRequestProperty, setUseCaches


 URLConnection Members

URLConnection Members

Class Overview | This Package | All Packages

Fields
Name | Description
allowUserInteraction | If true, this URL is being examined in a context in which it makes sense to allow user interactions such as popping up an authentication dialog.
connected | If false, this connection object has not created a communications link to the specified URL.
doInput | This variable is set by the setDoInput method.
doOutput | This variable is set by the setDoOutput method.
fileNameMap |
ifModifiedSince | Some protocols support skipping the fetching of the object unless the object has been modified more recently than a certain time.
url | The URL represents the remote object on the World Wide Web to which this connection is opened.
useCaches | If true, the protocol is allowed to use caching whenever it can.

Constructors
Name | Description
URLConnection(URL) | Constructs a URL connection to the specified URL.

Methods
Name | Description
connect() | Opens a communications link to the resource referenced by this URL, if such a connection has not already been established.
getAllowUserInteraction() | Returns the value of the allowUserInteraction field for this object.
getContent() | Retrieves the contents of this URL connection.
getContentEncoding() | Returns the value of the content-encoding header field.
getContentLength() | Returns the value of the content-length header field.
getContentType() | Returns the value of the content-type header field.
getDate() | Returns the value of the date header field.
getDefaultAllowUserInteraction() | Returns the default value of the allowUserInteraction field.
getDefaultRequestProperty(String) | Returns the value of the default request property.
getDefaultUseCaches() | Returns the default value of a URLConnection's useCaches flag.
getDoInput() | Returns the value of this URLConnection's doInput flag.
getDoOutput() | Returns the value of this URLConnection's doOutput flag.
getExpiration() | Returns the value of the expires header field.
getHeaderField(int) | Returns the value for the nth header field.
getHeaderField(String) | Returns the name of the specified header field.
getHeaderFieldDate(String, long) | Returns the value of the named field parsed as date.
getHeaderFieldInt(String, int) | Returns the value of the named field parsed as a number.
getHeaderFieldKey(int) | Returns the key for the nth header field.
getIfModifiedSince() | Returns the value of this object's ifModifiedSince field.
getInputStream() | Returns an input stream that reads from this open connection.
getLastModified() | Returns the value of the last-modified header field.
getOutputStream() | Returns an output stream that writes to this connection.
getRequestProperty(String) | Returns the value of the named general request property for this connection.
getURL() | Returns the value of this URLConnection's URL field.
getUseCaches() | Returns the value of this URLConnection's useCaches field.
guessContentTypeFromName(String) | Tries to determine the content type of an object, based on the specified "file" component of a URL.
guessContentTypeFromStream(InputStream) | Tries to determine the type of an input stream based on the characters at the beginning of the input stream.
setAllowUserInteraction(boolean) | Set the value of the allowUserInteraction field of this URLConnection.
setContentHandlerFactory(ContentHandlerFactory) | Sets the ContentHandlerFactory of an application.
setDefaultAllowUserInteraction(boolean) | Sets the default value of the allowUserInteraction field for all future URLConnection objects to the specified value.
setDefaultRequestProperty(String, String) | Sets the default value of a general request property.
setDefaultUseCaches(boolean) | Sets the default value of the useCaches field to the specified value.
setDoInput(boolean) | Sets the value of the doInput field for this URLConnection to the specified value.
setDoOutput(boolean) | Sets the value of the doOutput field for this URLConnection to the specified value.
setIfModifiedSince(long) | Sets the value of the ifModifiedSince field of this URLConnection to the specified value.
setRequestProperty(String, String) | Sets the general request property.
setUseCaches(boolean) | Sets the value of the useCaches field of this URLConnection to the specified value.
toString() | Returns a String representation of this URL connection.


 URLConnection.allowUserInteraction

URLConnection.allowUserInteraction

Class Overview | Class Members | This Package | All Packages

Syntax
protected boolean allowUserInteraction
Description
If true, this URL is being examined in a context in which it makes sense to allow user interactions such as popping up an authentication dialog. If false, then no user interaction is allowed.

The value of this field can be set by the setAllowUserInteraction method. Its value is returned by the getAllowUserInteraction method. Its default value is the value of the argument in the last invocation of the setDefaultAllowUserInteraction method.

See Also
getAllowUserInteraction, setAllowUserInteraction, setDefaultAllowUserInteraction


 URLConnection.connected

URLConnection.connected

Class Overview | Class Members | This Package | All Packages

Syntax
protected boolean connected
Description
If false, this connection object has not created a communications link to the specified URL. If true, the communications link has been established.


 URLConnection.doInput

URLConnection.doInput

Class Overview | Class Members | This Package | All Packages

Syntax
protected boolean doInput
Description
This variable is set by the setDoInput method. Its value is returned by the getDoInput method.

A URL connection can be used for input and/or output. Setting the doInput flag to true indicates that the application intends to read data from the URL connection.

The default value of this field is true.

See Also
getDoInput, setDoInput


 URLConnection.doOutput

URLConnection.doOutput

Class Overview | Class Members | This Package | All Packages

Syntax
protected boolean doOutput
Description
This variable is set by the setDoOutput method. Its value is returned by the getDoInput method.

A URL connection can be used for input and/or output. Setting the doOutput flag to true indicates that the application intends to write data to the URL connection.

The default value of this field is false.

See Also
getDoOutput, setDoOutput


 URLConnection.fileNameMap

URLConnection.fileNameMap

Class Overview | Class Members | This Package | All Packages

Syntax
public static FileNameMap fileNameMap


 URLConnection.ifModifiedSince

URLConnection.ifModifiedSince

Class Overview | Class Members | This Package | All Packages

Syntax
protected long ifModifiedSince
Description
Some protocols support skipping the fetching of the object unless the object has been modified more recently than a certain time.

A nonzero value gives a time as the number of seconds since January 1, 1970, GMT. The object is fetched only if it has been modified more recently than that time.

This variable is set by the setIfModifiedSince method. Its value is returned by the getIfModifiedSince method.

The default value of this field is 0, indicating that the fetching must always occur.

See Also
getIfModifiedSince, setIfModifiedSince


 URLConnection.url

URLConnection.url

Class Overview | Class Members | This Package | All Packages

Syntax
protected URL url
Description
The URL represents the remote object on the World Wide Web to which this connection is opened.

The value of this field can be accessed by the getURL method.

The default value of this variable is the value of the URL argument in the URLConnection constructor.

See Also
getURL, url


 URLConnection.useCaches

URLConnection.useCaches

Class Overview | Class Members | This Package | All Packages

Syntax
protected boolean useCaches
Description
If true, the protocol is allowed to use caching whenever it can. If false, the protocol must always try to get a fresh copy of the object.

This field is set by the setUseCaches method. Its value is returned by the getUseCaches method.

Its default value is the value given in the last invocation of the setDefaultUseCaches method.

See Also
setUseCaches, getUseCaches, setDefaultUseCaches


 URLConnection.URLConnection

URLConnection.URLConnection

Class Overview | Class Members | This Package | All Packages

Syntax
protected URLConnection( URL url )
Parameters
url
the specified URL.
Description
Constructs a URL connection to the specified URL. A connection to the object referenced by the URL is not created.


 URLConnection.connect

URLConnection.connect

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void connect() throws IOException
Description
Opens a communications link to the resource referenced by this URL, if such a connection has not already been established.

If the connect method is called when the connection has already been opened (indicated by the connected field having the value true), the call is ignored.

URLConnection objects go through two phases: first they are created, then they are connected. After being created, and before being connected, various options can be specified (e.g., doInput and UseCaches). After connecting, it is an error to try to set them. Operations that depend on being connected, like getContentLength, will implicitly perform the connection, if necessary.

Exceptions
IOException if an I/O error occurs while opening the connection.
See Also
connected


 URLConnection.getAllowUserInteraction

URLConnection.getAllowUserInteraction

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean getAllowUserInteraction()
Returns
the value of the allowUserInteraction field for this object.
Description
Returns the value of the allowUserInteraction field for this object.

See Also
allowUserInteraction


 URLConnection.getContent

URLConnection.getContent

Class Overview | Class Members | This Package | All Packages

Syntax
public Object getContent() throws IOException
Returns
the object fetched. The instanceOf operation should be used to determine the specific kind of object returned.
Description
Retrieves the contents of this URL connection.

This method first determines the content type of the object by calling the getContentType method. If this is the first time that the application has seen that specific content type, a content handler for that content type is created:

  1. If the application has set up a content handler factory instance using the setContentHandlerFactory method, the createContentHandler method of that instance is called with the content type as an argument; the result is a content handler for that content type.
  2. If no content handler factory has yet been set up, or if the factory's createContentHandler method returns null, then the application loads the class named:
      sun.net.www.content.<contentType>
    where <contentType> is formed by taking the content-type string, replacing all slash characters with a period ('.'), and all other non-alphanumeric characters with the underscore character '_'. The alphanumeric characters are specifically the 26 uppercase ASCII letters 'A' through 'Z', the 26 lowercase ASCII letters 'a' through 'z', and the 10 ASCII digits '0' through '9'. If the specified class does not exist, or is not a subclass of ContentHandler, then an UnknownServiceException is thrown.

Exceptions
IOException if an I/O error occurs while getting the content.
Exceptions
UnknownServiceException if the protocol does not support the content type.
See Also
createContentHandler, getContentType, setContentHandlerFactory


 URLConnection.getContentEncoding

URLConnection.getContentEncoding

Class Overview | Class Members | This Package | All Packages

Syntax
public String getContentEncoding()
Returns
the content encoding of the resource that the URL references, or null if not known.
Description
Returns the value of the content-encoding header field.

See Also
getHeaderField


 URLConnection.getContentLength

URLConnection.getContentLength

Class Overview | Class Members | This Package | All Packages

Syntax
public int getContentLength()
Returns
the content length of the resource that this connection's URL references, or -1 if the content length is not known.
Description
Returns the value of the content-length header field.


 URLConnection.getContentType

URLConnection.getContentType

Class Overview | Class Members | This Package | All Packages

Syntax
public String getContentType()
Returns
the content type of the resource that the URL references, or null if not known.
Description
Returns the value of the content-type header field.

See Also
getHeaderField


 URLConnection.getDate

URLConnection.getDate

Class Overview | Class Members | This Package | All Packages

Syntax
public long getDate()
Returns
the sending date of the resource that the URL references, or 0 if not known. The value returned is the number of seconds since January 1, 1970 GMT.
Description
Returns the value of the date header field.

See Also
getHeaderField


 URLConnection.getDefaultAllowUserInteraction

URLConnection.getDefaultAllowUserInteraction

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean getDefaultAllowUserInteraction()
Returns
the default value of the allowUserInteraction field.
Description
Returns the default value of the allowUserInteraction field.

Ths default is "sticky", being a part of the static state of all URLConnections. This flag applies to the next, and all following URLConnections that are created.

See Also
allowUserInteraction


 URLConnection.getDefaultRequestProperty

URLConnection.getDefaultRequestProperty

Class Overview | Class Members | This Package | All Packages

Syntax
public static String getDefaultRequestProperty( String key )
Returns
the value of the default request property for the specified key.
Description
Returns the value of the default request property. Default request properties are set for every connection.

See Also
setDefaultRequestProperty


 URLConnection.getDefaultUseCaches

URLConnection.getDefaultUseCaches

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean getDefaultUseCaches()
Returns
the default value of a URLConnection's useCaches flag.
Description
Returns the default value of a URLConnection's useCaches flag.

Ths default is "sticky", being a part of the static state of all URLConnections. This flag applies to the next, and all following URLConnections that are created.

See Also
useCaches


 URLConnection.getDoInput

URLConnection.getDoInput

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean getDoInput()
Returns
the value of this URLConnection's doInput flag.
Description
Returns the value of this URLConnection's doInput flag.

See Also
doInput


 URLConnection.getDoOutput

URLConnection.getDoOutput

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean getDoOutput()
Returns
the value of this URLConnection's doOutput flag.
Description
Returns the value of this URLConnection's doOutput flag.

See Also
doOutput


 URLConnection.getExpiration

URLConnection.getExpiration

Class Overview | Class Members | This Package | All Packages

Syntax
public long getExpiration()
Returns
the expiration date of the resource that this URL references, or 0 if not known. The value is the number of seconds since January 1, 1970 GMT.
Description
Returns the value of the expires header field.

See Also
getHeaderField


 URLConnection.getHeaderField

URLConnection.getHeaderField

Class Overview | Class Members | This Package | All Packages

Syntax
public String getHeaderField( String name )
Parameters
name
the name of a header field.
Returns
the value of the named header field, or null if there is no such field in the header.
Description
Returns the name of the specified header field.


 URLConnection.getHeaderField

URLConnection.getHeaderField

Class Overview | Class Members | This Package | All Packages

Syntax
public String getHeaderField( int n )
Parameters
n
an index.
Returns
the value of the nth header field.
Description
Returns the value for the nth header field. It returns null if there are fewer than n fields.

This method can be used in conjunction with the getHeaderFieldKey method to iterate through all the headers in the message.

See Also
getHeaderFieldKey


 URLConnection.getHeaderFieldDate

URLConnection.getHeaderFieldDate

Class Overview | Class Members | This Package | All Packages

Syntax
public long getHeaderFieldDate( String name, long Default )
Parameters
name
the name of the header field.
Default
a default value.
Returns
the value of the field, parsed as a date. The value of the Default argument is returned if the field is missing or malformed.
Description
Returns the value of the named field parsed as date. The result is the number of seconds since January 1, 1970 GMT represented by the named field.

This form of getHeaderField exists because some connection types (e.g., http-ng) have pre-parsed headers. Classes for that connection type can override this method and short-circuit the parsing.


 URLConnection.getHeaderFieldInt

URLConnection.getHeaderFieldInt

Class Overview | Class Members | This Package | All Packages

Syntax
public int getHeaderFieldInt( String name, int Default )
Parameters
name
the name of the header field.
Default
the default value.
Returns
the value of the named field, parsed as an integer. The Default value is returned if the field is missing or malformed.
Description
Returns the value of the named field parsed as a number.

This form of getHeaderField exists because some connection types (e.g., http-ng) have pre-parsed headers. Classes for that connection type can override this method and short-circuit the parsing.


 URLConnection.getHeaderFieldKey

URLConnection.getHeaderFieldKey

Class Overview | Class Members | This Package | All Packages

Syntax
public String getHeaderFieldKey( int n )
Parameters
n
an index.
Returns
the key for the nth header field, or null if there are fewer than n fields.
Description
Returns the key for the nth header field.


 URLConnection.getIfModifiedSince

URLConnection.getIfModifiedSince

Class Overview | Class Members | This Package | All Packages

Syntax
public long getIfModifiedSince()
Returns
the value of this object's ifModifiedSince field.
Description
Returns the value of this object's ifModifiedSince field.

See Also
ifModifiedSince


 URLConnection.getInputStream

URLConnection.getInputStream

Class Overview | Class Members | This Package | All Packages

Syntax
public InputStream getInputStream() throws IOException
Returns
an input stream that reads from this open connection.
Description
Returns an input stream that reads from this open connection.

Exceptions
IOException if an I/O error occurs while creating the input stream.
Exceptions
UnknownServiceException if the protocol does not support input.


 URLConnection.getLastModified

URLConnection.getLastModified

Class Overview | Class Members | This Package | All Packages

Syntax
public long getLastModified()
Returns
the date the resource referenced by this URLConnection was last modified, or 0 if not known.
Description
Returns the value of the last-modified header field. The result is the number of seconds since January 1, 1970 GMT.

See Also
getHeaderField


 URLConnection.getOutputStream

URLConnection.getOutputStream

Class Overview | Class Members | This Package | All Packages

Syntax
public OutputStream getOutputStream() throws IOException
Returns
an output stream that writes to this connection.
Description
Returns an output stream that writes to this connection.

Exceptions
IOException if an I/O error occurs while creating the output stream.
Exceptions
UnknownServiceException if the protocol does not support output.


 URLConnection.getRequestProperty

URLConnection.getRequestProperty

Class Overview | Class Members | This Package | All Packages

Syntax
public String getRequestProperty( String key )
Returns
the value of the named general request property for this connection.
Description
Returns the value of the named general request property for this connection.


 URLConnection.getURL

URLConnection.getURL

Class Overview | Class Members | This Package | All Packages

Syntax
public URL getURL()
Returns
the value of this URLConnection's URL field.
Description
Returns the value of this URLConnection's URL field.

See Also
url


 URLConnection.getUseCaches

URLConnection.getUseCaches

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean getUseCaches()
Returns
the value of this URLConnection's useCaches field.
Description
Returns the value of this URLConnection's useCaches field.

See Also
useCaches


 URLConnection.guessContentTypeFromName

URLConnection.guessContentTypeFromName

Class Overview | Class Members | This Package | All Packages

Syntax
protected static String guessContentTypeFromName( String fname )
Parameters
fname
a filename.
Returns
a guess as to what the content type of the object is, based upon its file name.
Description
Tries to determine the content type of an object, based on the specified "file" component of a URL. This is a convenience method that can be used by subclasses that override the getContentType method.

See Also
getContentType


 URLConnection.guessContentTypeFromStream

URLConnection.guessContentTypeFromStream

Class Overview | Class Members | This Package | All Packages

Syntax
public static String guessContentTypeFromStream( InputStream is ) throws IOException
Parameters
is
an input stream that supports marks.
Returns
a guess at the content type, or null if none can be determined.
Description
Tries to determine the type of an input stream based on the characters at the beginning of the input stream. This method can be used by subclasses that override the getContentType method.

Ideally, this routine would not be needed. But many http servers return the incorrect content type; in addition, there are many nonstandard extensions. Direct inspection of the bytes to determine the content type is often more accurate than believing the content type claimed by the http server.

Exceptions
IOException if an I/O error occurs while reading the input stream.
See Also
mark, markSupported, getContentType


 URLConnection.setAllowUserInteraction

URLConnection.setAllowUserInteraction

Class Overview | Class Members | This Package | All Packages

Syntax
public void setAllowUserInteraction( boolean allowuserinteraction )
Parameters
allowuserinteraction
the new value.
Description
Set the value of the allowUserInteraction field of this URLConnection.

See Also
allowUserInteraction


 URLConnection.setContentHandlerFactory

URLConnection.setContentHandlerFactory

Class Overview | Class Members | This Package | All Packages

Syntax
public static synchronized void setContentHandlerFactory( ContentHandlerFactory fac )
Parameters
fac
the desired factory.
Description
Sets the ContentHandlerFactory of an application. It can be called at most once by an application.

The ContentHandlerFactory instance is used to construct a content handler from a content type

Exceptions
Error if the factory has already been defined.
See Also
ContentHandlerFactory, getContent


 URLConnection.setDefaultAllowUserInteraction

URLConnection.setDefaultAllowUserInteraction

Class Overview | Class Members | This Package | All Packages

Syntax
public static void setDefaultAllowUserInteraction( boolean defaultallowuserinteraction )
Parameters
defaultallowuserinteraction
the new value.
Description
Sets the default value of the allowUserInteraction field for all future URLConnection objects to the specified value.

See Also
allowUserInteraction


 URLConnection.setDefaultRequestProperty

URLConnection.setDefaultRequestProperty

Class Overview | Class Members | This Package | All Packages

Syntax
public static void setDefaultRequestProperty( String key, String value )
Parameters
key
the keyword by which the request is known (e.g., "accept").
value
the value associated with the key.
Description
Sets the default value of a general request property. When a URLConnection is created, it is initialized with these properties.


 URLConnection.setDefaultUseCaches

URLConnection.setDefaultUseCaches

Class Overview | Class Members | This Package | All Packages

Syntax
public void setDefaultUseCaches( boolean defaultusecaches )
Parameters
defaultusecaches
the new value.
Description
Sets the default value of the useCaches field to the specified value.

See Also
useCaches


 URLConnection.setDoInput

URLConnection.setDoInput

Class Overview | Class Members | This Package | All Packages

Syntax
public void setDoInput( boolean doinput )
Parameters
value
the new value.
Description
Sets the value of the doInput field for this URLConnection to the specified value.

A URL connection can be used for input and/or output. Set the DoInput flag to true if you intend to use the URL connection for input, false if not. The default is true unless DoOutput is explicitly set to true, in which case DoInput defaults to false.

See Also
doInput


 URLConnection.setDoOutput

URLConnection.setDoOutput

Class Overview | Class Members | This Package | All Packages

Syntax
public void setDoOutput( boolean dooutput )
Parameters
value
the new value.
Description
Sets the value of the doOutput field for this URLConnection to the specified value.

A URL connection can be used for input and/or output. Set the DoOutput flag to true if you intend to use the URL connection for output, false if not. The default is false.

See Also
doOutput


 URLConnection.setIfModifiedSince

URLConnection.setIfModifiedSince

Class Overview | Class Members | This Package | All Packages

Syntax
public void setIfModifiedSince( long ifmodifiedsince )
Parameters
value
the new value.
Description
Sets the value of the ifModifiedSince field of this URLConnection to the specified value.

See Also
ifModifiedSince


 URLConnection.setRequestProperty

URLConnection.setRequestProperty

Class Overview | Class Members | This Package | All Packages

Syntax
public void setRequestProperty( String key, String value )
Parameters
key
the keyword by which the request is known (e.g., "accept").
value
the value associated with it.
Description
Sets the general request property.


 URLConnection.setUseCaches

URLConnection.setUseCaches

Class Overview | Class Members | This Package | All Packages

Syntax
public void setUseCaches( boolean usecaches )
Description
Sets the value of the useCaches field of this URLConnection to the specified value.

Some protocols do caching of documents. Occasionally, it is important to be able to "tunnel through" and ignore the caches (e.g., the "reload" button in a browser). If the UseCaches flag on a connection is true, the connection is allowed to use whatever caches it can. If false, caches are to be ignored. The default value comes from DefaultUseCaches, which defaults to true.

See Also
useCaches


 URLConnection.toString

URLConnection.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string representation of this URLConnection.
Description
Returns a String representation of this URL connection.

Overrides
toString in class Object


 Class URLEncoder

Class java.net.URLEncoder

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.net.URLEncoder

public class URLEncoder
extends Object

The class contains a utility method for converting a String into a MIME format called "x-www-form-urlencoded" format.

To convert a String, each character is examined in turn:

  • The ASCII characters 'a' through 'z', 'A' through 'Z', and '0' through '9' remain the same.
  • The space character ' ' is converted into a plus sign '+'.
  • All other characters are converted into the 3-character string "%xy", where xy is the two-digit hexadecimal representation of the lower 8-bits of the character.


 URLEncoder Members

URLEncoder Members

Class Overview | This Package | All Packages

Methods
Name | Description
encode(String) | Translates a string into x-www-form-urlencoded format.


 URLEncoder.encode

URLEncoder.encode

Class Overview | Class Members | This Package | All Packages

Syntax
public static String encode( String s )
Parameters
s
String to be translated.
Returns
the translated String.
Description
Translates a string into x-www-form-urlencoded format.


 Class URLStreamHandler

Class java.net.URLStreamHandler

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.net.URLStreamHandler

public abstract class URLStreamHandler
extends Object

The abstract class URLStreamHandler is the common superclass for all stream protocol handlers. A stream protocol handler knows how to make a connection for a particular protocol type, such as http, ftp, or gopher.

In most cases, an instance of a URLStreamHandler subclass is not created directly by an application. Rather, the first time a protocol name is encountered when constructing a URL, the appropriate stream protocol handler is automatically loaded.

See Also:
URL


 URLStreamHandler Members

URLStreamHandler Members

Class Overview | This Package | All Packages

Constructors
Name | Description
URLStreamHandler() |

Methods
Name | Description
openConnection(URL) | Opens a connection to the object referenced by the URL argument.
parseURL(URL, String, int, int) | Parses the string representation of a URL into a URL object.
setURL(URL, String, String, int, String, String) | Sets the fields of the URL argument to the indicated values.
toExternalForm(URL) | Converts a URL of a specific protocol to a String.


 URLStreamHandler.URLStreamHandler

URLStreamHandler.URLStreamHandler

Class Overview | Class Members | This Package | All Packages

Syntax
public URLStreamHandler()


 URLStreamHandler.openConnection

URLStreamHandler.openConnection

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract URLConnection openConnection( URL u ) throws IOException
Parameters
u
the URL that this connects to.
Returns
a URLConnection object for the URL.
Description
Opens a connection to the object referenced by the URL argument. This method should be overridden by a subclass.

Exceptions
IOException if an I/O error occurs while opening the connection.


 URLStreamHandler.parseURL

URLStreamHandler.parseURL

Class Overview | Class Members | This Package | All Packages

Syntax
protected void parseURL( URL u, String spec, int start, int limit )
Parameters
u
the URL to receive the result of parsing the spec.
spec
the String representing the URL that must be parsed.
start
the character index at which to begin parsing. This is just past the ':' (if there is one) that specifies the determination of the protocol name.
limit
the character position to stop parsing at. This is the end of the string or the position of the "#" character, if present. All information after the sharp sign indicates an anchor.
Description
Parses the string representation of a URL into a URL object.

If there is any inherited context, then it has already been copied into the URL argument.

The parseURL method of URLStreamHandler parses the string representation as if it were an http specification. Most URL protocol families have a similar parsing. A stream protocol handler for a protocol that has a different syntax must override this routine.


 URLStreamHandler.setURL

URLStreamHandler.setURL

Class Overview | Class Members | This Package | All Packages

Syntax
protected void setURL( URL u, String protocol, String host, int port, String file, String ref )
Parameters
u
the URL to modify.
protocol
the protocol name.
host
the remote host value for the URL.
port
the port on the remote machine.
file
the file.
ref
the reference.
Description
Sets the fields of the URL argument to the indicated values. Only classes derived from URLStreamHandler are supposed to be able to call the set method on a URL.

See Also
set


 URLStreamHandler.toExternalForm

URLStreamHandler.toExternalForm

Class Overview | Class Members | This Package | All Packages

Syntax
protected String toExternalForm( URL u )
Parameters
u
the URL.
Returns
a string representation of the URL argument.
Description
Converts a URL of a specific protocol to a String.


 Interface URLStreamHandlerFactory

Interface java.net.URLStreamHandlerFactory

Interface Members | This Package | All Packages

public interface URLStreamHandlerFactory

This interface defines a factory for URL stream protocol handlers.

It is used by the URL class to create a URLStreamHandler for a specific protocol.

See Also:
URL, URLStreamHandler


 URLStreamHandlerFactory Members

URLStreamHandlerFactory Members

Interface Overview | This Package | All Packages

Methods
Name | Description
createURLStreamHandler(String) | Creates a new URLStreamHandler instance with the specified protocol.


 URLStreamHandlerFactory.createURLStreamHandler

URLStreamHandlerFactory.createURLStreamHandler

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract URLStreamHandler createURLStreamHandler( String protocol )
Parameters
protocol
the protocol ("ftp", "http", "nntp", etc.).
Returns
a URLStreamHandler for the specific protocol.
Description
Creates a new URLStreamHandler instance with the specified protocol.

See Also
URLStreamHandler


 Class UnknownHostException

Class java.net.UnknownHostException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.io.IOException
                           |
                           +----java.net.UnknownHostException

public class UnknownHostException
extends IOException

Thrown to indicate that the IP address of a host could not be determined.


 UnknownHostException Members

UnknownHostException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
UnknownHostException() | Constructs a new UnknownHostException with no detail message.
UnknownHostException(String) | Constructs a new UnknownHostException with the specified detail message.


 UnknownHostException.UnknownHostException

UnknownHostException.UnknownHostException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public UnknownHostException( String host )
Parameters
host
the detail message.
Description
Constructs a new UnknownHostException with the specified detail message.

Syntax 2
public UnknownHostException()
Description
Constructs a new UnknownHostException with no detail message.


 Class UnknownServiceException

Class java.net.UnknownServiceException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.io.IOException
                           |
                           +----java.net.UnknownServiceException

public class UnknownServiceException
extends IOException

Thrown to indicate that an unknown service exception has occurred. Either the MIME type returned by a URL connection does not make sense, or the application is attempting to write to a read-only URL connection.


 UnknownServiceException Members

UnknownServiceException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
UnknownServiceException() | Constructs a new UnknownServiceException with no detail message.
UnknownServiceException(String) | Constructs a new UnknownServiceException with the specified detail message.


 UnknownServiceException.UnknownServiceException

UnknownServiceException.UnknownServiceException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public UnknownServiceException()
Description
Constructs a new UnknownServiceException with no detail message.

Syntax 2
public UnknownServiceException( String msg )
Parameters
msg
the detail message.
Description
Constructs a new UnknownServiceException with the specified detail message.


 Package java.security

Package java.security

All Packages

Interfaces

  • Certificate
  • Key
  • Principal
  • PrivateKey
  • PublicKey

    • Classes

  • DigestInputStream
  • DigestOutputStream
  • Identity
  • IdentityScope
  • KeyPair
  • KeyPairGenerator
  • MessageDigest
  • Provider
  • SecureRandom
  • Security
  • Signature
  • Signer

    • Exceptions

  • DigestException
  • InvalidKeyException
  • InvalidParameterException
  • KeyException
  • KeyManagementException
  • NoSuchAlgorithmException
  • NoSuchProviderException
  • ProviderException
  • SignatureException


 Interface Certificate

Interface java.security.Certificate

Interface Members | This Package | All Packages

public interface Certificate

This is an interface of abstract methods for managing an identity certificate. An identity certificate is a guarantee by a principal that a public key is that of another principal. (A principal represents an entity such as an individual user or a group.)

In particular, this interface is intended to be a common abstraction for constructs that have different formats but important common uses. For example, different types of certificates, such as X.509 certificates and PGP certificates, share general certificate functionality (the need to encode and decode certificates) and some types of information, such as a public key, the principal whose key it is, and the guarantor guaranteeing that the public key is that of the specified principal. So an implementation of X.509 certificates and an implementation of PGP certificates can both utilize the Certificate interface, even though their formats and additional types and amounts of information stored are different.

Important: This interface is useful for cataloging and grouping objects sharing certain common uses. It does not have any semantics of its own. In particular, a Certificate object does not make any statement as to the validity of the binding. It is the duty of the application implementing this interface to verify the certificate and satisfy itself of its validity.


 Certificate Members

Certificate Members

Interface Overview | This Package | All Packages

Methods
Name | Description
decode(InputStream) | Decodes a certificate from an input stream.
encode(OutputStream) | Encodes the certificate to an output stream in a format that can be decoded by the decode method.
getFormat() | Returns the name of the coding format.
getGuarantor() | Returns the guarantor of the certificate, that is, the principal guaranteeing that the public key associated with this certificate is that of the principal associated with this certificate.
getPrincipal() | Returns the principal of the principal-key pair being guaranteed by the guarantor.
getPublicKey() | Returns the key of the principal-key pair being guaranteed by the guarantor.
toString(boolean) | Returns a string that represents the contents of the certificate.


 Certificate.decode

Certificate.decode

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void decode( InputStream stream ) throws KeyException, IOException
Parameters
stream
the input stream from which to fetch the data being decoded.
Description
Decodes a certificate from an input stream. The format should be that returned by getFormat and produced by encode.

Exceptions
KeyException if the certificate is not properly initialized, or data is missing, etc.
Exceptions
IOException if an exception occurs while trying to input the encoded certificate from the input stream.
See Also
encode, getFormat


 Certificate.encode

Certificate.encode

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void encode( OutputStream stream ) throws KeyException, IOException
Parameters
stream
the output stream to which to encode the certificate.
Description
Encodes the certificate to an output stream in a format that can be decoded by the decode method.

Exceptions
KeyException if the certificate is not properly initialized, or data is missing, etc.
Exceptions
IOException if a stream exception occurs while trying to output the encoded certificate to the output stream.
See Also
decode, getFormat


 Certificate.getFormat

Certificate.getFormat

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getFormat()
Returns
the name of the coding format.
Description
Returns the name of the coding format. This is used as a hint to find an appropriate parser. It could be "X.509", "PGP", etc. This is the format produced and understood by the encode and decode methods.


 Certificate.getGuarantor

Certificate.getGuarantor

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Principal getGuarantor()
Returns
the guarantor which guaranteed the principal-key binding.
Description
Returns the guarantor of the certificate, that is, the principal guaranteeing that the public key associated with this certificate is that of the principal associated with this certificate. For X.509 certificates, the guarantor will typically be a Certificate Authority (such as the United States Postal Service or Verisign, Inc.).


 Certificate.getPrincipal

Certificate.getPrincipal

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Principal getPrincipal()
Returns
the principal to which this certificate is bound.
Description
Returns the principal of the principal-key pair being guaranteed by the guarantor.


 Certificate.getPublicKey

Certificate.getPublicKey

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract PublicKey getPublicKey()
Returns
the public key that this certificate certifies belongs to a particular principal.
Description
Returns the key of the principal-key pair being guaranteed by the guarantor.


 Certificate.toString

Certificate.toString

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String toString( boolean detailed )
Parameters
detailed
whether or not to give detailed information about the certificate.
Description
Returns a string that represents the contents of the certificate.


 Class DigestException

Class java.security.DigestException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.security.DigestException

public class DigestException
extends Exception

This is the generic Message Digest exception.


 DigestException Members

DigestException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
DigestException() | Constructs a DigestException with no detail message.
DigestException(String) | Constructs a DigestException with the specified detail message.


 DigestException.DigestException

DigestException.DigestException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public DigestException()
Description
Constructs a DigestException with no detail message. (A detail message is a String that describes this particular exception.)

Syntax 2
public DigestException( String msg )
Parameters
msg
the detail message.
Description
Constructs a DigestException with the specified detail message. (A detail message is a String that describes this particular exception.)


 Class DigestInputStream

Class java.security.DigestInputStream

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.InputStream
           |
           +----java.io.FilterInputStream
                   |
                   +----java.security.DigestInputStream

public class DigestInputStream
extends FilterInputStream

A transparent stream that updates the associated message digest using the bits going through the stream.

To complete the message digest computation, call one of the digest methods on the associated message digest after your calls to one of this digest input stream's read methods.

It is possible to turn this stream on or off (see on). When it is on, a call to read results in an update on the message digest. But when it is off, the message digest is not updated. The default is for the stream to be on.

Note that digest objects can compute only one digest (see MessageDigest), so that in order to compute intermediate digests, a caller should retain a handle onto the digest object, and clone it for each digest to be computed, leaving the orginal digest untouched.

See Also:
MessageDigest, DigestOutputStream


 DigestInputStream Members

DigestInputStream Members

Class Overview | This Package | All Packages

Fields
Name | Description
digest | The message digest associated with this stream.

Constructors
Name | Description
DigestInputStream(InputStream, MessageDigest) | Creates a digest input stream, using the specified input stream and message digest.

Methods
Name | Description
getMessageDigest() | Returns the message digest associated with this stream.
on(boolean) | Turns the digest function on or off.
read() | Reads a byte, and updates the message digest (if the digest function is on).
read(byte[], int, int) | Reads into a byte array, and updates the message digest (if the digest function is on).
setMessageDigest(MessageDigest) | Associates the specified message digest with this stream.
toString() | Prints a string representation of this digest input stream and its associated message digest object.


 DigestInputStream.digest

DigestInputStream.digest

Class Overview | Class Members | This Package | All Packages

Syntax
protected MessageDigest digest
Description
The message digest associated with this stream.


 DigestInputStream.DigestInputStream

DigestInputStream.DigestInputStream

Class Overview | Class Members | This Package | All Packages

Syntax
public DigestInputStream( InputStream stream, MessageDigest digest )
Parameters
stream
the input stream.
digest
the message digest to associate with this stream.
Description
Creates a digest input stream, using the specified input stream and message digest.


 DigestInputStream.getMessageDigest

DigestInputStream.getMessageDigest

Class Overview | Class Members | This Package | All Packages

Syntax
public MessageDigest getMessageDigest()
Returns
the message digest associated with this stream.
Description
Returns the message digest associated with this stream.


 DigestInputStream.on

DigestInputStream.on

Class Overview | Class Members | This Package | All Packages

Syntax
public void on( boolean on )
Parameters
on
true to turn the digest function on, false to turn it off.
Description
Turns the digest function on or off. The default is on. When it is on, a call to read results in an update on the message digest. But when it is off, the message digest is not updated.


 DigestInputStream.read

DigestInputStream.read

Class Overview | Class Members | This Package | All Packages

Syntax 1
public int read() throws IOException
Returns
the byte read.
Description
Reads a byte, and updates the message digest (if the digest function is on). That is, this method reads a byte from the input stream, blocking until the byte is actually read. If the digest function is on (see on), this method will then call update on the message digest associated with this stream, passing it the byte read.

Exceptions
IOException if an I/O error occurs.
Overrides
read in class FilterInputStream
See Also
update

Syntax 2
public int read( byte b[], int off, int len ) throws IOException
Parameters
b
the array into which the data is read.
off
the starting offset into b of where the data should be placed.
len
the maximum number of bytes to be read from the input stream into b, starting at offset off.
Returns
the actual number of bytes read. This is less than len if the end of the stream is reached prior to reading len bytes. -1 is returned if no bytes were read because the end of the stream had already been reached when the call was made.
Description
Reads into a byte array, and updates the message digest (if the digest function is on). That is, this method reads up to len bytes from the input stream into the array b, starting at offset off. This method blocks until the data is actually read. If the digest function is on (see on), this method will then call update on the message digest associated with this stream, passing it the data.

Exceptions
IOException if an I/O error occurs.
Overrides
read in class FilterInputStream
See Also
update


 DigestInputStream.setMessageDigest

DigestInputStream.setMessageDigest

Class Overview | Class Members | This Package | All Packages

Syntax
public void setMessageDigest( MessageDigest digest )
Parameters
digest
the message digest to be associated with this stream.
Description
Associates the specified message digest with this stream.


 DigestInputStream.toString

DigestInputStream.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Description
Prints a string representation of this digest input stream and its associated message digest object.

Overrides
toString in class Object


 Class DigestOutputStream

Class java.security.DigestOutputStream

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.OutputStream
           |
           +----java.io.FilterOutputStream
                   |
                   +----java.security.DigestOutputStream

public class DigestOutputStream
extends FilterOutputStream

A transparent stream that updates the associated message digest using the bits going through the stream.

To complete the message digest computation, call one of the digest methods on the associated message digest after your calls to one of this digest ouput stream's write methods.

It is possible to turn this stream on or off (see on). When it is on, a call to write results in an update on the message digest. But when it is off, the message digest is not updated. The default is for the stream to be on.

See Also:
MessageDigest, DigestInputStream


 DigestOutputStream Members

DigestOutputStream Members

Class Overview | This Package | All Packages

Fields
Name | Description
digest | The message digest associated with this stream.

Constructors
Name | Description
DigestOutputStream(OutputStream, MessageDigest) | Creates a digest output stream, using the specified output stream and message digest.

Methods
Name | Description
getMessageDigest() | Returns the message digest associated with this stream.
on(boolean) | Turns the digest function on or off.
setMessageDigest(MessageDigest) | Associates the specified message digest with this stream.
toString() | Prints a string representation of this digest output stream and its associated message digest object.
write(byte[], int, int) | Updates the message digest (if the digest function is on) using the specified subarray, and in any case writes the subarray to the output stream.
write(int) | Updates the message digest (if the digest function is on) using the specified byte, and in any case writes the byte to the output stream.


 DigestOutputStream.digest

DigestOutputStream.digest

Class Overview | Class Members | This Package | All Packages

Syntax
protected MessageDigest digest
Description
The message digest associated with this stream.


 DigestOutputStream.DigestOutputStream

DigestOutputStream.DigestOutputStream

Class Overview | Class Members | This Package | All Packages

Syntax
public DigestOutputStream( OutputStream stream, MessageDigest digest )
Parameters
stream
the output stream.
digest
the message digest to associate with this stream.
Description
Creates a digest output stream, using the specified output stream and message digest.


 DigestOutputStream.getMessageDigest

DigestOutputStream.getMessageDigest

Class Overview | Class Members | This Package | All Packages

Syntax
public MessageDigest getMessageDigest()
Returns
the message digest associated with this stream.
Description
Returns the message digest associated with this stream.


 DigestOutputStream.on

DigestOutputStream.on

Class Overview | Class Members | This Package | All Packages

Syntax
public void on( boolean on )
Parameters
on
true to turn the digest function on, false to turn it off.
Description
Turns the digest function on or off. The default is on. When it is on, a call to write results in an update on the message digest. But when it is off, the message digest is not updated.


 DigestOutputStream.setMessageDigest

DigestOutputStream.setMessageDigest

Class Overview | Class Members | This Package | All Packages

Syntax
public void setMessageDigest( MessageDigest digest )
Parameters
digest
the message digest to be associated with this stream.
Description
Associates the specified message digest with this stream.


 DigestOutputStream.toString

DigestOutputStream.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Description
Prints a string representation of this digest output stream and its associated message digest object.

Overrides
toString in class Object


 DigestOutputStream.write

DigestOutputStream.write

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void write( int b ) throws IOException
Parameters
b
the byte to be used for updating and writing to the output stream.
Description
Updates the message digest (if the digest function is on) using the specified byte, and in any case writes the byte to the output stream. That is, if the digest function is on (see on), this method calls update on the message digest associated with this stream, passing it the byte b. This method then writes the byte to the output stream, blocking until the byte is actually written.

Exceptions
IOException if an I/O error occurs.
Overrides
write in class FilterOutputStream
See Also
update

Syntax 2
public void write( byte b[], int off, int len ) throws IOException
Parameters
b
the array containing the subarray to be used for updating and writing to the output stream.
off
the offset into b of the first byte to be updated and written.
len
the number of bytes of data to be updated and written from b, starting at offset off.
Description
Updates the message digest (if the digest function is on) using the specified subarray, and in any case writes the subarray to the output stream. That is, if the digest function is on (see on), this method calls update on the message digest associated with this stream, passing it the subarray specifications. This method then writes the subarray bytes to the output stream, blocking until the bytes are actually written.

Exceptions
IOException if an I/O error occurs.
Overrides
write in class FilterOutputStream
See Also
update


 Class Identity

Class java.security.Identity

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.security.Identity

public abstract class Identity
extends Object
implements Principal, Serializable

This class represents identities: real-world objects such as people, companies or organizations whose identities can be authenticated using their public keys. Identities may also be more abstract (or concrete) constructs, such as daemon threads or smart cards.

All Identity objects have a name and a public key. Names are immutable. Identities may also be scoped. That is, if an Identity is specified to have a particular scope, then the name and public key of the Identity are unique within that scope.

An Identity also has a set of certificates (all certifying its own public key). The Principal names specified in these certificates need not be the same, only the key.

An Identity can be subclassed, to include postal and email addresses, telephone numbers, images of faces and logos, and so on.

See Also:
IdentityScope, Signer, Principal


 Identity Members

Identity Members

Class Overview | This Package | All Packages

Constructors
Name | Description
Identity() | Constructor for serialization only.
Identity(String) | Constructs an identity with the specified name and no scope.
Identity(String, IdentityScope) | Constructs an identity with the specified name and scope.

Methods
Name | Description
addCertificate(Certificate) | Adds a certificate for this identity.
certificates() | Returns a copy of all the certificates for this identity.
equals(Object) | Tests for equality between the specified object and this identity.
getInfo() | Returns general information previously specified for this identity.
getName() | Returns this identity's name.
getPublicKey() | Returns this identity's public key.
getScope() | Returns this identity's scope.
hashCode() | Returns a hashcode for this identity.
identityEquals(Identity) | Tests for equality between the specified identity and this identity.
removeCertificate(Certificate) | Removes a certificate from this identity.
setInfo(String) | Specifies a general information string for this identity.
setPublicKey(PublicKey) | Sets this identity's public key.
toString() | Returns a short string describing this identity, telling its name and its scope (if any).
toString(boolean) | Returns a string representation of this identity, with optionally more details than that provided by the toString method without any arguments.


 Identity.Identity

Identity.Identity

Class Overview | Class Members | This Package | All Packages

Syntax 1
protected Identity()
Description
Constructor for serialization only.

Syntax 2
public Identity( String name, IdentityScope scope ) throws KeyManagementException
Parameters
name
the identity name.
scope
the scope of the identity.
Description
Constructs an identity with the specified name and scope.

Exceptions
KeyManagementException if there is already an identity with the same name in the scope.

Syntax 3
public Identity( String name )
Parameters
name
the identity name.
Description
Constructs an identity with the specified name and no scope.


 Identity.addCertificate

Identity.addCertificate

Class Overview | Class Members | This Package | All Packages

Syntax
public void addCertificate( Certificate certificate ) throws KeyManagementException
Parameters
certificate
the certificate to be added.
Description
Adds a certificate for this identity. If the identity has a public key, the public key in the certificate must be the same, and if the identity does not have a public key, the identity's public key is set to be that specified in the certificate.

Exceptions
KeyManagementException if the certificate is not valid, if the public key in the certificate being added conflicts with this identity's public key, or if another exception occurs.


 Identity.certificates

Identity.certificates

Class Overview | Class Members | This Package | All Packages

Syntax
public Certificate[] certificates()
Returns
a copy of all the certificates for this identity.
Description
Returns a copy of all the certificates for this identity.


 Identity.equals

Identity.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public final boolean equals( Object identity )
Parameters
identity
the object to test for equality with this identity.
Returns
true if the objects are considered equal, false otherwise.
Description
Tests for equality between the specified object and this identity. This first tests to see if the entities actually refer to the same object, in which case it returns true. Next, it checks to see if the entities have the same name and the same scope. If they do, the method returns true. Otherwise, it calls identityEquals, which subclasses should override.

Overrides
equals in class Object
See Also
identityEquals


 Identity.getInfo

Identity.getInfo

Class Overview | Class Members | This Package | All Packages

Syntax
public String getInfo()
Returns
general information about this identity.
Description
Returns general information previously specified for this identity.

See Also
setInfo


 Identity.getName

Identity.getName

Class Overview | Class Members | This Package | All Packages

Syntax
public final String getName()
Returns
the name of this identity.
Description
Returns this identity's name.


 Identity.getPublicKey

Identity.getPublicKey

Class Overview | Class Members | This Package | All Packages

Syntax
public PublicKey getPublicKey()
Returns
the public key for this identity.
Description
Returns this identity's public key.


 Identity.getScope

Identity.getScope

Class Overview | Class Members | This Package | All Packages

Syntax
public final IdentityScope getScope()
Returns
the scope of this identity.
Description
Returns this identity's scope.


 Identity.hashCode

Identity.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int hashCode()
Returns
a hashcode for this identity.
Description
Returns a hashcode for this identity.

Overrides
hashCode in class Object


 Identity.identityEquals

Identity.identityEquals

Class Overview | Class Members | This Package | All Packages

Syntax
protected boolean identityEquals( Identity identity )
Parameters
identity
the identity to test for equality with this identity.
Returns
true if the identities are considered equal, false otherwise.
Description
Tests for equality between the specified identity and this identity. This method should be overriden by subclasses to test for equality. The default behavior is to return true if the names and public keys are equal.

See Also
equals


 Identity.removeCertificate

Identity.removeCertificate

Class Overview | Class Members | This Package | All Packages

Syntax
public void removeCertificate( Certificate certificate ) throws KeyManagementException
Parameters
certificate
the certificate to be removed.
Description
Removes a certificate from this identity.

Exceptions
KeyManagementException if the certificate is missing, or if another exception occurs.


 Identity.setInfo

Identity.setInfo

Class Overview | Class Members | This Package | All Packages

Syntax
public void setInfo( String info )
Parameters
info
the information string.
Description
Specifies a general information string for this identity.

See Also
getInfo


 Identity.setPublicKey

Identity.setPublicKey

Class Overview | Class Members | This Package | All Packages

Syntax
public void setPublicKey( PublicKey key ) throws KeyManagementException
Parameters
key
the public key for this identity.
Description
Sets this identity's public key. The old key and all of this identity's certificates are removed by this operation.

Exceptions
KeyManagementException if another identity in the identity's scope has the same public key, or if another exception occurs.


 Identity.toString

Identity.toString

Class Overview | Class Members | This Package | All Packages

Syntax 1
public String toString()
Returns
information about this identity, such as its name and the name of its scope (if any).
Description
Returns a short string describing this identity, telling its name and its scope (if any).

Overrides
toString in class Object

Syntax 2
public String toString( boolean detailed )
Parameters
detailed
whether or not to provide detailed information.
Returns
information about this identity. If detailed is true, then this method returns more information than that provided by the toString method without any arguments.
Description
Returns a string representation of this identity, with optionally more details than that provided by the toString method without any arguments.

See Also
toString


 Class IdentityScope

Class java.security.IdentityScope

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.security.Identity
           |
           +----java.security.IdentityScope

public abstract class IdentityScope
extends Identity

This class represents a scope for identities. It is an Identity itself, and therefore has a name and can have a scope. It can also optionally have a public key and associated certificates.

An IdentityScope can contain Identity objects of all kinds, including Signers. All types of Identity objects can be retrieved, added, and removed using the same methods. Note that it is possible, and in fact expected, that different types of identity scopes will apply different policies for their various operations on the various types of Identities.

There is a one-to-one mapping between keys and identities, and there can only be one copy of one key per scope. For example, suppose Acme Software, Inc is a software publisher known to a user. Suppose it is an Identity, that is, it has a public key, and a set of associated certificates. It is named in the scope using the name "Acme Software". No other named Identity in the scope has the same public key. Of course, none has the same name as well.

See Also:
Identity, Signer, Principal, Key


 IdentityScope Members

IdentityScope Members

Class Overview | This Package | All Packages

Constructors
Name | Description
IdentityScope() | This constructor is used for serialization only and should not be used by subclasses.
IdentityScope(String) | Constructs a new identity scope with the specified name.
IdentityScope(String, IdentityScope) | Constructs a new identity scope with the specified name and scope.

Methods
Name | Description
addIdentity(Identity) | Adds an identity to this identity scope.
getIdentity(Principal) | Retrieves the identity whose name is the same as that of the specified principal.
getIdentity(PublicKey) | Retrieves the identity with the specified public key.
getIdentity(String) | Returns the identity in this scope with the specified name (if any).
getSystemScope() | Returns the system's identity scope.
identities() | Returns an enumeration of all identities in this identity scope.
removeIdentity(Identity) | Removes an identity from this identity scope.
setSystemScope(IdentityScope) | Sets the system's identity scope.
size() | Returns the number of identities within this identity scope.
toString() | Returns a string representation of this identity scope, including its name, its scope name, and the number of identities in this identity scope.


 IdentityScope.IdentityScope

IdentityScope.IdentityScope

Class Overview | Class Members | This Package | All Packages

Syntax 1
protected IdentityScope()
Description
This constructor is used for serialization only and should not be used by subclasses.

Syntax 2
public IdentityScope( String name )
Parameters
name
the scope name.
Description
Constructs a new identity scope with the specified name.

Syntax 3
public IdentityScope( String name, IdentityScope scope ) throws KeyManagementException
Parameters
name
the scope name.
scope
the scope for the new identity scope.
Description
Constructs a new identity scope with the specified name and scope.

Exceptions
KeyManagementException if there is already an identity with the same name in the scope.


 IdentityScope.addIdentity

IdentityScope.addIdentity

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void addIdentity( Identity identity ) throws KeyManagementException
Parameters
identity
the identity to be added.
Description
Adds an identity to this identity scope.

Exceptions
KeyManagementException if the identity is not valid, a name conflict occurs, another identity has the same public key as the identity being added, or another exception occurs.


 IdentityScope.getIdentity

IdentityScope.getIdentity

Class Overview | Class Members | This Package | All Packages

Syntax 1
public abstract Identity getIdentity( String name )
Parameters
name
the name of the identity to be retrieved.
Returns
the identity named name, or null if there are no identities named name in this scope.
Description
Returns the identity in this scope with the specified name (if any).

Syntax 2
public Identity getIdentity( Principal principal )
Parameters
principal
the principal corresponding to the identity to be retrieved.
Returns
the identity whose name is the same as that of the principal, or null if there are no identities of the same name in this scope.
Description
Retrieves the identity whose name is the same as that of the specified principal. (Note: Identity implements Principal.)

Syntax 3
public abstract Identity getIdentity( PublicKey key )
Parameters
key
the public key for the identity to be returned.
Returns
the identity with the given key, or null if there are no identities in this scope with that key.
Description
Retrieves the identity with the specified public key.


 IdentityScope.getSystemScope

IdentityScope.getSystemScope

Class Overview | Class Members | This Package | All Packages

Syntax
public static IdentityScope getSystemScope()
Returns
the system's identity scope.
Description
Returns the system's identity scope. See the "System Identity Scope" section in the Java Cryptography Architecture API Specification & Reference.


 IdentityScope.identities

IdentityScope.identities

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract Enumeration identities()
Returns
an enumeration of all identities in this identity scope.
Description
Returns an enumeration of all identities in this identity scope.


 IdentityScope.removeIdentity

IdentityScope.removeIdentity

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void removeIdentity( Identity identity ) throws KeyManagementException
Parameters
identity
the identity to be removed.
Description
Removes an identity from this identity scope.

Exceptions
KeyManagementException if the identity is missing, or another exception occurs.


 IdentityScope.setSystemScope

IdentityScope.setSystemScope

Class Overview | Class Members | This Package | All Packages

Syntax
protected static void setSystemScope( IdentityScope scope )
Parameters
scope
the scope to set.
Description
Sets the system's identity scope. See the "System Identity Scope" section in the Java Cryptography Architecture API Specification & Reference.


 IdentityScope.size

IdentityScope.size

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract int size()
Returns
the number of identities within this identity scope.
Description
Returns the number of identities within this identity scope.


 IdentityScope.toString

IdentityScope.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string representation of this identity scope.
Description
Returns a string representation of this identity scope, including its name, its scope name, and the number of identities in this identity scope.

Overrides
toString in class Identity


 Class InvalidKeyException

Class java.security.InvalidKeyException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.security.KeyException
                           |
                           +----java.security.InvalidKeyException

public class InvalidKeyException
extends KeyException

This is the exception for invalid Keys (invalid encoding, wrong length, uninitialized, etc).


 InvalidKeyException Members

InvalidKeyException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
InvalidKeyException() | Constructs an InvalidKeyException with no detail message.
InvalidKeyException(String) | Constructs an InvalidKeyException with the specified detail message.


 InvalidKeyException.InvalidKeyException

InvalidKeyException.InvalidKeyException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public InvalidKeyException()
Description
Constructs an InvalidKeyException with no detail message. A detail message is a String that describes this particular exception.

Syntax 2
public InvalidKeyException( String msg )
Parameters
msg
the detail message.
Description
Constructs an InvalidKeyException with the specified detail message. A detail message is a String that describes this particular exception.


 Class InvalidParameterException

Class java.security.InvalidParameterException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.lang.RuntimeException
                           |
                           +----java.lang.IllegalArgumentException
                                   |
                                   +----java.security.InvalidParameterException

public class InvalidParameterException
extends IllegalArgumentException

This exception is thrown when an invalid parameter is passed to a method.


 InvalidParameterException Members

InvalidParameterException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
InvalidParameterException() | Constructs an InvalidParameterException with no detail message.
InvalidParameterException(String) | Constructs an InvalidParameterException with the specified detail message.


 InvalidParameterException.InvalidParameterException

InvalidParameterException.InvalidParameterException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public InvalidParameterException()
Description
Constructs an InvalidParameterException with no detail message. A detail message is a String that describes this particular exception.

Syntax 2
public InvalidParameterException( String msg )
Parameters
msg
the detail message.
Description
Constructs an InvalidParameterException with the specified detail message. A detail message is a String that describes this particular exception.


 Interface Key

Interface java.security.Key

Interface Members | This Package | All Packages

public interface Key
extends Serializable

The Key interface is the top-level interface for all keys. It defines the functionality shared by all key objects. All keys have three characteristics:

  • An Algorithm

    This is the key algorithm for that key. The key algorithm is usually an encryption or asymmetric operation algorithm (such as DSA or RSA), which will work with those algorithms and with related algorithms (such as MD5 with RSA, SHA-1 with RSA, Raw DSA, etc.) The name of the algorithm of a key is obtained using the getAlgorithm method.

  • An Encoded Form

    This is an external encoded form for the key used when a standard representation of the key is needed outside the Java Virtual Machine, as when transmitting the key to some other party. The key is encoded according to a standard format (such as X.509 or PKCS#8), and is returned using the getEncoded method.

  • A Format

    This is the name of the format of the encoded key. It is returned by the getFormat method.

Keys are generally obtained through key generators, certificates, or various Identity classes used to manage keys. There are no provisions in this release for the parsing of encoded keys and certificates.

See Also:
PublicKey, PrivateKey, KeyPair, KeyPairGenerator, Identity, IdentityScope, Signer


 Key Members

Key Members

Interface Overview | This Package | All Packages

Methods
Name | Description
getAlgorithm() | Returns the standard algorithm name this key is for.
getEncoded() | Returns the encoded key.
getFormat() | Returns the format used to encode the key or null if the key does not support encoding.


 Key.getAlgorithm

Key.getAlgorithm

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getAlgorithm()
Returns
the name of the algorithm this key is for, or null if the algorithm this key is for is unknown.
Description
Returns the standard algorithm name this key is for. For example, "DSA" would indicate that this key is a DSA key. Note that this method may return null, when the algorithm this key is for is unknown.

See Appendix A in the Java Cryptography Architecture API Specification & Reference for information about standard algorithm names.


 Key.getEncoded

Key.getEncoded

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract byte[] getEncoded()
Returns
the encoded key, or null if the key does not support encoding.
Description
Returns the encoded key.


 Key.getFormat

Key.getFormat

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getFormat()
Returns
the format used to encode the key.
Description
Returns the format used to encode the key or null if the key does not support encoding.


 Class KeyException

Class java.security.KeyException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.security.KeyException

public class KeyException
extends Exception

This is the basic key exception.

See Also:
Key, InvalidKeyException, KeyManagementException


 KeyException Members

KeyException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
KeyException() | Constructs a KeyException with no detail message.
KeyException(String) | Constructs a KeyException with the specified detail message.


 KeyException.KeyException

KeyException.KeyException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public KeyException()
Description
Constructs a KeyException with no detail message. A detail message is a String that describes this particular exception.

Syntax 2
public KeyException( String msg )
Parameters
msg
the detail message.
Description
Constructs a KeyException with the specified detail message. A detail message is a String that describes this particular exception.


 Class KeyManagementException

Class java.security.KeyManagementException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.security.KeyException
                           |
                           +----java.security.KeyManagementException

public class KeyManagementException
extends KeyException

This is the general key management exception, for all operations dealing with key management. Subclasses could include:

  • KeyIDConflict
  • KeyAuthorizationFailureException
  • ExpiredKeyException

See Also:
Key, KeyException


 KeyManagementException Members

KeyManagementException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
KeyManagementException() | Constructs a KeyManagementException with no detail message.
KeyManagementException(String) | Constructs a KeyManagementException with the specified detail message.


 KeyManagementException.KeyManagementException

KeyManagementException.KeyManagementException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public KeyManagementException()
Description
Constructs a KeyManagementException with no detail message. A detail message is a String that describes this particular exception.

Syntax 2
public KeyManagementException( String msg )
Parameters
msg
the detail message.
Description
Constructs a KeyManagementException with the specified detail message. A detail message is a String that describes this particular exception.


 Class KeyPair

Class java.security.KeyPair

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.security.KeyPair

public final class KeyPair
extends Object

This class is a simple holder for a key pair (a public key and a private key). It does not enforce any security, and, when initialized, should be treated like a PrivateKey.

See Also:
PublicKey, PrivateKey


 KeyPair Members

KeyPair Members

Class Overview | This Package | All Packages

Constructors
Name | Description
KeyPair(PublicKey, PrivateKey) | Constructs a key with the specified public key and private key.

Methods
Name | Description
getPrivate() | Returns the private key from this key pair.
getPublic() | Returns the public key from this key pair.


 KeyPair.KeyPair

KeyPair.KeyPair

Class Overview | Class Members | This Package | All Packages

Syntax
public KeyPair( PublicKey publicKey, PrivateKey privateKey )
Parameters
publicKey
the public key.
privateKey
the private key.
Description
Constructs a key with the specified public key and private key.


 KeyPair.getPrivate

KeyPair.getPrivate

Class Overview | Class Members | This Package | All Packages

Syntax
public PrivateKey getPrivate()
Returns
the private key.
Description
Returns the private key from this key pair.


 KeyPair.getPublic

KeyPair.getPublic

Class Overview | Class Members | This Package | All Packages

Syntax
public PublicKey getPublic()
Returns
the public key.
Description
Returns the public key from this key pair.


 Class KeyPairGenerator

Class java.security.KeyPairGenerator

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.security.KeyPairGenerator

public abstract class KeyPairGenerator
extends Object

The KeyPairGenerator class is used to generate pairs of public and private keys. Key generators are constructed using the getInstance factory methods (static methods that return instances of a given class).

Key generation is an area that sometimes does not lend itself well to algorithm independence. For example, it is possible to generate a DSA key pair specifying key family parameters (p, q and g), while it is not possible to do so for an RSA key pair. That is, those parameters are applicable to DSA but not to RSA.

There are therefore two ways to generate a key pair: in an algorithm-independent manner, and in an algorithm-specific manner. The only difference between the two is the initialization of the object.

All key pair generators share the concepts of a "strength" and a source of randomness. The measure of strength is universally shared by all algorithms, though it is interpreted differently for different algorithms. The initialize method in this KeyPairGenerator class takes these two universally shared types of arguments.

Since no other parameters are specified when you call this algorithm-independent initialize method, all other values, such as algorithm parameters, public exponent, etc., are defaulted to standard values.

It is sometimes desirable to initialize a key pair generator object using algorithm-specific semantics. For example, you may want to initialize a DSA key generator for a given set of parameters p, q and g, or an RSA key generator for a given public exponent.

This is done through algorithm-specific standard interfaces. Rather than calling the algorithm-independent KeyPairGenerator initialize method, the key pair generator is cast to an algorithm-specific interface so that one of its specialized parameter initialization methods can be called. An example is the DSAKeyPairGenerator interface (from java.security.interfaces).

See "The KeyPairGenerator Class" in the Java Cryptography Architecture API Specification & Reference for more information and examples.

See Also:
DSAKeyPairGenerator


 KeyPairGenerator Members

KeyPairGenerator Members

Class Overview | This Package | All Packages

Constructors
Name | Description
KeyPairGenerator(String) | Creates a KeyPairGenerator object for the specified algorithm.

Methods
Name | Description
generateKeyPair() | Generates a key pair.
getAlgorithm() | Returns the standard name of the algorithm for this key generator.
getInstance(String) | Generates a KeyPairGenerator object that implements the algorithm requested, as available in the environment.
getInstance(String, String) | Generates a KeyPairGenerator object implementing the specified algorithm, as supplied from the specified provider, if such an algorithm is available from the provider.
initialize(int) | Initializes the key pair generator for a certain strength using a system-provided source of randomness.
initialize(int, SecureRandom) | Initializes the key pair generator for a certain strength.


 KeyPairGenerator.KeyPairGenerator

KeyPairGenerator.KeyPairGenerator

Class Overview | Class Members | This Package | All Packages

Syntax
protected KeyPairGenerator( String algorithm )
Parameters
algorithm
the standard string name of the algorithm. See Appendix A in the Java Cryptography Architecture API Specification & Reference for information about standard algorithm names.
Description
Creates a KeyPairGenerator object for the specified algorithm.


 KeyPairGenerator.generateKeyPair

KeyPairGenerator.generateKeyPair

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract KeyPair generateKeyPair()
Description
Generates a key pair. Unless an initialization method is called using a KeyPairGenerator interface, algorithm-specific defaults will be used. This will generate a new key pair every time it is called.


 KeyPairGenerator.getAlgorithm

KeyPairGenerator.getAlgorithm

Class Overview | Class Members | This Package | All Packages

Syntax
public String getAlgorithm()
Returns
the standard string name of the algorithm.
Description
Returns the standard name of the algorithm for this key generator. See Appendix A in the Java Cryptography Architecture API Specification & Reference for information about standard algorithm names.


 KeyPairGenerator.getInstance

KeyPairGenerator.getInstance

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static KeyPairGenerator getInstance( String algorithm ) throws NoSuchAlgorithmException
Parameters
algorithm
the standard string name of the algorithm. See Appendix A in the Java Cryptography Architecture API Specification & Reference for information about standard algorithm names.
Returns
the new KeyPairGenerator object.
Description
Generates a KeyPairGenerator object that implements the algorithm requested, as available in the environment.

Exceptions
NoSuchAlgorithmException if the algorithm is not available in the environment.

Syntax 2
public static KeyPairGenerator getInstance( String algorithm, String provider ) throws NoSuchAlgorithmException, NoSuchProviderException
Parameters
algorithm
the standard string name of the algorithm. See Appendix A in the Java Cryptography Architecture API Specification & Reference for information about standard algorithm names.
provider
the string name of the provider.
Returns
the new KeyPairGenerator object.
Description
Generates a KeyPairGenerator object implementing the specified algorithm, as supplied from the specified provider, if such an algorithm is available from the provider.

Exceptions
NoSuchAlgorithmException if the algorithm is not available from the provider.
Exceptions
NoSuchProviderException if the provider is not available in the environment.
See Also
Provider


 KeyPairGenerator.initialize

KeyPairGenerator.initialize

Class Overview | Class Members | This Package | All Packages

Syntax 1
public abstract void initialize( int strength, SecureRandom random )
Parameters
strength
the strength of the key. This is an algorithm-specific metric, such as modulus length.
random
the source of randomness for this generator.
Description
Initializes the key pair generator for a certain strength.

Syntax 2
public void initialize( int strength )
Parameters
strength
the strength of the key. This is an algorithm-specific metric, such as modulus length.
Description
Initializes the key pair generator for a certain strength using a system-provided source of randomness.


 Class MessageDigest

Class java.security.MessageDigest

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.security.MessageDigest

public abstract class MessageDigest
extends Object

This MessageDigest class provides the functionality of a message digest algorithm, such as MD5 or SHA. Message digests are secure one-way hash functions that take arbitrary-sized data and output a fixed-length hash value.

Like other algorithm-based classes in Java Security, MessageDigest has two major components:

Message Digest API (Application Program Interface)
This is the interface of methods called by applications needing message digest services. The API consists of all public methods.
Message Digest SPI (Service Provider Interface)
This is the interface implemented by providers that supply specific algorithms. It consists of all methods whose names are prefixed by engine. Each such method is called by a correspondingly-named public API method. For example, the engineReset method is called by the reset method. The SPI methods are abstract; providers must supply a concrete implementation.

A MessageDigest object starts out initialized. The data is processed through it using the update methods. At any point reset can be called to reset the digest. Once all the data to be updated has been updated, one of the digest methods should be called to complete the hash computation.

The digest method can be called once for a given number of updates. After digest has been called, the MessageDigest object is reset to its initialized state.

Implementations are free to implement the Cloneable interface, and doing so will let client applications test cloneability using instanceof Cloneable before cloning:

 MessageDigest md = MessageDigest.getInstance("SHA");
 if (md instanceof Cloneable) {
     md.update(toChapter1);
     MessageDigest tc1 = md.clone();
     byte[] toChapter1Digest = tc1.digest;
     md.update(toChapter2);
     ...etc.
 } else {
     throw new DigestException("couldn't make digest of partial content");
 }

Note that if a given implementation is not cloneable, it is still possible to compute intermediate digests by instantiating several instances, if the number of digests is known in advance.

See Also:
DigestInputStream, DigestOutputStream


 MessageDigest Members

MessageDigest Members

Class Overview | This Package | All Packages

Constructors
Name | Description
MessageDigest(String) | Creates a message digest with the specified algorithm name.

Methods
Name | Description
clone() | Returns a clone if the implementation is cloneable.
digest() | Completes the hash computation by performing final operations such as padding.
digest(byte[]) | Performs a final update on the digest using the specified array of bytes, then completes the digest computation.
engineDigest() | SPI: Completes the hash computation by performing final operations such as padding.
engineReset() | SPI: Resets the digest for further use.
engineUpdate(byte) | SPI: Updates the digest using the specified byte.
engineUpdate(byte[], int, int) | SPI: Updates the digest using the specified array of bytes, starting at the specified offset.
getAlgorithm() | Returns a string that identifies the algorithm, independent of implementation details.
getInstance(String) | Generates a MessageDigest object that implements the specified digest algorithm.
getInstance(String, String) | Generates a MessageDigest object implementing the specified algorithm, as supplied from the specified provider, if such an algorithm is available from the provider.
isEqual(byte[], byte[]) | Compares two digests for equality.
reset() | Resets the digest for further use.
toString() | Returns a string representation of this message digest object.
update(byte) | Updates the digest using the specified byte.
update(byte[]) | Updates the digest using the specified array of bytes.
update(byte[], int, int) | Updates the digest using the specified array of bytes, starting at the specified offset.


 MessageDigest.MessageDigest

MessageDigest.MessageDigest

Class Overview | Class Members | This Package | All Packages

Syntax
protected MessageDigest( String algorithm )
Parameters
algorithm
the standard name of the digest algorithm. See Appendix A in the Java Cryptography Architecture API Specification & Reference for information about standard algorithm names.
Description
Creates a message digest with the specified algorithm name.


 MessageDigest.clone

MessageDigest.clone

Class Overview | Class Members | This Package | All Packages

Syntax
public Object clone() throws CloneNotSupportedException
Returns
a clone if the implementation is cloneable.
Description
Returns a clone if the implementation is cloneable.

Exceptions
CloneNotSupportedException if this is called on an implementation that does not support Cloneable.
Overrides
clone in class Object


 MessageDigest.digest

MessageDigest.digest

Class Overview | Class Members | This Package | All Packages

Syntax 1
public byte[] digest()
Returns
the array of bytes for the resulting hash value.
Description
Completes the hash computation by performing final operations such as padding. The digest is reset after this call is made.

Syntax 2
public byte[] digest( byte input[] )
Parameters
input
the input to be updated before the digest is completed.
Returns
the array of bytes for the resulting hash value.
Description
Performs a final update on the digest using the specified array of bytes, then completes the digest computation. That is, this method first calls update on the array, then calls digest().


 MessageDigest.engineDigest

MessageDigest.engineDigest

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract byte[] engineDigest()
Returns
the array of bytes for the resulting hash value.
Description
SPI: Completes the hash computation by performing final operations such as padding. Once engineDigest has been called, the engine should be reset (see reset). Resetting is the responsibility of the engine implementor.


 MessageDigest.engineReset

MessageDigest.engineReset

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract void engineReset()
Description
SPI: Resets the digest for further use.


 MessageDigest.engineUpdate

MessageDigest.engineUpdate

Class Overview | Class Members | This Package | All Packages

Syntax 1
protected abstract void engineUpdate( byte input )
Parameters
input
the byte to use for the update.
Description
SPI: Updates the digest using the specified byte.

Syntax 2
protected abstract void engineUpdate( byte input[], int offset, int len )
Parameters
input
the array of bytes to use for the update.
offset
the offset to start from in the array of bytes.
len
the number of bytes to use, starting at offset.
Description
SPI: Updates the digest using the specified array of bytes, starting at the specified offset. This should be a no-op if the digest has been finalized.


 MessageDigest.getAlgorithm

MessageDigest.getAlgorithm

Class Overview | Class Members | This Package | All Packages

Syntax
public final String getAlgorithm()
Description
Returns a string that identifies the algorithm, independent of implementation details. The name should be a standard Java Security name (such as "SHA", "MD5", and so on). See Appendix A in the Java Cryptography Architecture API Specification & Reference for information about standard algorithm names.


 MessageDigest.getInstance

MessageDigest.getInstance

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static MessageDigest getInstance( String algorithm ) throws NoSuchAlgorithmException
Parameters
algorithm
the name of the algorithm requested. See Appendix A in the Java Cryptography Architecture API Specification & Reference for information about standard algorithm names.
Returns
a Message Digest object implementing the specified algorithm.
Description
Generates a MessageDigest object that implements the specified digest algorithm. If the default provider package contains a MessageDigest subclass implementing the algorithm, an instance of that subclass is returned. If the algorithm is not available in the default package, other packages are searched.

Exceptions
NoSuchAlgorithmException if the algorithm is not available in the caller's environment.

Syntax 2
public static MessageDigest getInstance( String algorithm, String provider ) throws NoSuchAlgorithmException, NoSuchProviderException
Parameters
algorithm
the name of the algorithm requested. See Appendix A in the Java Cryptography Architecture API Specification & Reference for information about standard algorithm names.
provider
the name of the provider.
Returns
a Message Digest object implementing the specified algorithm.
Description
Generates a MessageDigest object implementing the specified algorithm, as supplied from the specified provider, if such an algorithm is available from the provider.

Exceptions
NoSuchAlgorithmException if the algorithm is not available in the package supplied by the requested provider.
Exceptions
NoSuchProviderException if the provider is not available in the environment.
See Also
Provider


 MessageDigest.isEqual

MessageDigest.isEqual

Class Overview | Class Members | This Package | All Packages

Syntax
public static boolean isEqual( byte digesta[], byte digestb[] )
Parameters
digesta
one of the digests to compare.
digestb
the other digest to compare.
Returns
true if the digests are equal, false otherwise.
Description
Compares two digests for equality. Does a simple byte compare.


 MessageDigest.reset

MessageDigest.reset

Class Overview | Class Members | This Package | All Packages

Syntax
public void reset()
Description
Resets the digest for further use.


 MessageDigest.toString

MessageDigest.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Description
Returns a string representation of this message digest object.

Overrides
toString in class Object


 MessageDigest.update

MessageDigest.update

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void update( byte input )
Parameters
input
the byte with which to update the digest.
Description
Updates the digest using the specified byte.

Syntax 2
public void update( byte input[], int offset, int len )
Parameters
input
the array of bytes.
offset
the offset to start from in the array of bytes.
len
the number of bytes to use, starting at offset.
Description
Updates the digest using the specified array of bytes, starting at the specified offset.

Syntax 3
public void update( byte input[] )
Parameters
input
the array of bytes.
Description
Updates the digest using the specified array of bytes.


 Class NoSuchAlgorithmException

Class java.security.NoSuchAlgorithmException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.security.NoSuchAlgorithmException

public class NoSuchAlgorithmException
extends Exception

This exception is thrown when a particular cryptographic algorithm is requested but is not available in the environment.


 NoSuchAlgorithmException Members

NoSuchAlgorithmException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
NoSuchAlgorithmException() | Constructs a NoSuchAlgorithmException with no detail message.
NoSuchAlgorithmException(String) | Constructs a NoSuchAlgorithmException with the specified detail message.


 NoSuchAlgorithmException.NoSuchAlgorithmException

NoSuchAlgorithmException.NoSuchAlgorithmException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public NoSuchAlgorithmException()
Description
Constructs a NoSuchAlgorithmException with no detail message. A detail message is a String that describes this particular exception.

Syntax 2
public NoSuchAlgorithmException( String msg )
Parameters
msg
the detail message.
Description
Constructs a NoSuchAlgorithmException with the specified detail message. A detail message is a String that describes this particular exception, which may, for example, specify which algorithm is not available.


 Class NoSuchProviderException

Class java.security.NoSuchProviderException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.security.NoSuchProviderException

public class NoSuchProviderException
extends Exception

This exception is thrown when a particular security provider is requested but is not available in the environment.


 NoSuchProviderException Members

NoSuchProviderException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
NoSuchProviderException() | Constructs a NoSuchProviderException with no detail message.
NoSuchProviderException(String) | Constructs a NoSuchProviderException with the specified detail message.


 NoSuchProviderException.NoSuchProviderException

NoSuchProviderException.NoSuchProviderException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public NoSuchProviderException()
Description
Constructs a NoSuchProviderException with no detail message. A detail message is a String that describes this particular exception.

Syntax 2
public NoSuchProviderException( String msg )
Parameters
msg
the detail message.
Description
Constructs a NoSuchProviderException with the specified detail message. A detail message is a String that describes this particular exception.


 Interface Principal

Interface java.security.Principal

Interface Members | This Package | All Packages

public interface Principal

This interface represents a principal. A principal can be an individual, a corporation, a program thread; anything which can have an identity. See the ACL white paper for more information.

See Also:
Identity, Certificate, Acl, Group


 Principal Members

Principal Members

Interface Overview | This Package | All Packages

Methods
Name | Description
equals(Object) | Compares this principal to the specified object.
getName() | Returns the name of this principal.
hashCode() | Returns a hashcode for this principal.
toString() | Returns a string representation of this principal.


 Principal.equals

Principal.equals

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean equals( Object another )
Parameters
another
the principal to compare with.
Returns
true if the principal passed in is the same as that encapsulated by this principal, false otherwise.
Description
Compares this principal to the specified object. Returns true if the object passed in matches the principal represented by the implementation of this interface.

Overrides
equals in class Object


 Principal.getName

Principal.getName

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getName()
Returns
the name of this principal.
Description
Returns the name of this principal.


 Principal.hashCode

Principal.hashCode

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int hashCode()
Returns
a hashcode for this principal.
Description
Returns a hashcode for this principal.

Overrides
hashCode in class Object


 Principal.toString

Principal.toString

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String toString()
Returns
a string representation of this principal.
Description
Returns a string representation of this principal.

Overrides
toString in class Object


 Interface PrivateKey

Interface java.security.PrivateKey

This Package | All Packages

public interface PrivateKey
extends Key

A private key. This interface contains no methods or constants. It merely serves to group (and provide type safety for) all private key interfaces. Note: The specialized private key interfaces extend this interface. See, for example, the DSAPrivateKey interface in java.security.interfaces.

See Also:
Key, PublicKey, Certificate, initVerify, DSAPrivateKey


 Class Provider

Class java.security.Provider

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.Dictionary
           |
           +----java.util.Hashtable
                   |
                   +----java.util.Properties
                           |
                           +----java.security.Provider

public abstract class Provider
extends Properties

This class represents a "provider" for the Java Security API. A provider implements some or all parts of Java Security, including:

  • Algorithms (such as DSA, RSA, MD5 or SHA-1).
  • Key generation and management facilities (such as for algorithm-specific keys).

Each provider has a name and a version number, and is configured in each runtime it is installed in.

There is a default provider that comes standard with the JDK. It is called the SUN Provider. See "The Provider Class" in the Java Cryptography Architecture API Specification & Reference for information about how providers work and how to install them.


 Provider Members

Provider Members

Class Overview | This Package | All Packages

Constructors
Name | Description
Provider(String, double, String) | Constructs a provider with the specified name, version number, and information.

Methods
Name | Description
getInfo() | Returns a human-readable description of the provider and its services.
getName() | Returns the name of this provider.
getVersion() | Returns the version number for this provider.
toString() | Returns a string with the name and the version number of this provider.


 Provider.Provider

Provider.Provider

Class Overview | Class Members | This Package | All Packages

Syntax
protected Provider( String name, double version, String info )
Parameters
name
the provider name.
version
the provider version number.
info
a description of the provider and its services.
Description
Constructs a provider with the specified name, version number, and information.


 Provider.getInfo

Provider.getInfo

Class Overview | Class Members | This Package | All Packages

Syntax
public String getInfo()
Returns
a description of the provider and its services.
Description
Returns a human-readable description of the provider and its services. This may return an HTML page, with relevant links.


 Provider.getName

Provider.getName

Class Overview | Class Members | This Package | All Packages

Syntax
public String getName()
Returns
the name of this provider.
Description
Returns the name of this provider.


 Provider.getVersion

Provider.getVersion

Class Overview | Class Members | This Package | All Packages

Syntax
public double getVersion()
Returns
the version number for this provider.
Description
Returns the version number for this provider.


 Provider.toString

Provider.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
the string with the name and the version number for this provider.
Description
Returns a string with the name and the version number of this provider.

Overrides
toString in class Hashtable


 Class ProviderException

Class java.security.ProviderException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.lang.RuntimeException
                           |
                           +----java.security.ProviderException

public class ProviderException
extends RuntimeException

A runtime exception for Provider exceptions (such as misconfiguration errors), which may be subclassed by Providers to throw specialized, provider-specific runtime errors.


 ProviderException Members

ProviderException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
ProviderException() | Constructs a ProviderException with no detail message.
ProviderException(String) | Constructs a ProviderException with the specified detail message.


 ProviderException.ProviderException

ProviderException.ProviderException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public ProviderException()
Description
Constructs a ProviderException with no detail message. A detail message is a String that describes this particular exception.

Syntax 2
public ProviderException( String s )
Parameters
s
the detail message.
Description
Constructs a ProviderException with the specified detail message. A detail message is a String that describes this particular exception.


 Interface PublicKey

Interface java.security.PublicKey

This Package | All Packages

public interface PublicKey
extends Key

A public key. This interface contains no methods or constants. It merely serves to group (and provide type safety for) all public key interfaces. Note: The specialized public key interfaces extend this interface. See, for example, the DSAPublicKey interface in java.security.interfaces.

See Also:
Key, PublicKey, Certificate, initVerify, DSAPublicKey


 Class SecureRandom

Class java.security.SecureRandom

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.Random
           |
           +----java.security.SecureRandom

public class SecureRandom
extends Random

This class provides a crytpographically strong pseudo-random number generator based on the SHA-1 hash algorithm.

The calls inherited from Random will be implemented in terms of the strengthened functionality.

See Also:
Random


 SecureRandom Members

SecureRandom Members

Class Overview | This Package | All Packages

Constructors
Name | Description
SecureRandom() | This empty constructor automatically seeds the generator.
SecureRandom(byte[]) | This constructor uses a user-provided seed in preference to the self-seeding algorithm referred to in the empty constructor description.

Methods
Name | Description
getSeed(int) | Returns the given number of seed bytes, computed using the seed generation algorithm that this class uses to seed itself.
next(int) | Generates an integer containing the user-specified number of pseudo-random bits (right justified, with leading zeros).
nextBytes(byte[]) | Generates a user-specified number of random bytes.
setSeed(byte[]) | Reseeds this random object.
setSeed(long) | Reseeds this random object, using the eight bytes contained in the given long seed.


 SecureRandom.SecureRandom

SecureRandom.SecureRandom

Class Overview | Class Members | This Package | All Packages

Syntax 1
public SecureRandom()
Description
This empty constructor automatically seeds the generator. We attempt to provide sufficient seed bytes to completely randomize the internal state of the generator (20 bytes). Note, however, that our seed generation algorithm has not been thoroughly studied or widely deployed. It relies on counting the number of times that the calling thread can yield while waiting for another thread to sleep for a specified interval.

The first time this constructor is called in a given Virtual Machine, it may take several seconds of CPU time to seed the generator, depending on the underlying hardware. Successive calls run quickly because they rely on the same (internal) pseudo-random number generator for their seed bits.

The seeding procedure implemented by this constructor ensures that the sequence of pseudo-random bytes produced by each SecureRandom instance yields no useful information about the byte-sequence produced by any other instance. If however, the user wishes to produce multiple instances with truly unrelated seeds, the following code yields the desired result (at substantial CPU cost per instance!):

 SecureRandom rnd = new SecureRandom(SecureRandom.getSeed(20));

Syntax 2
public SecureRandom( byte seed[] )
Parameters
seed
the seed.
Description
This constructor uses a user-provided seed in preference to the self-seeding algorithm referred to in the empty constructor description. It may be preferable to the empty constructor if the caller has access to high-quality random bytes from some physical device (for example, a radiation detector or a noisy diode).


 SecureRandom.getSeed

SecureRandom.getSeed

Class Overview | Class Members | This Package | All Packages

Syntax
public static byte[] getSeed( int numBytes )
Parameters
numBytes
the number of seed bytes to generate.
Returns
the seed bytes.
Description
Returns the given number of seed bytes, computed using the seed generation algorithm that this class uses to seed itself. This call may be used to seed other random number generators. While we attempt to return a "truly random" sequence of bytes, we do not know exactly how random the bytes returned by this call are. (See the empty constructor SecureRandom for a brief description of the underlying algorithm.) The prudent user will err on the side of caution and get extra seed bytes, although it should be noted that seed generation is somewhat costly.


 SecureRandom.next

SecureRandom.next

Class Overview | Class Members | This Package | All Packages

Syntax
protected final int next( int numBits )
Parameters
numBits
number of pseudo-random bits to be generated, where 0 <= numBits <= 32.
Description
Generates an integer containing the user-specified number of pseudo-random bits (right justified, with leading zeros). This method overrides a java.util.Random method, and serves to provide a source of random bits to all of the methods inherited from that class (for example, nextInt, nextLong, and nextFloat).

Overrides
next in class Random


 SecureRandom.nextBytes

SecureRandom.nextBytes

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void nextBytes( byte bytes[] )
Parameters
bytes
the array to be filled in with random bytes.
Description
Generates a user-specified number of random bytes. This method is used as the basis of all random entities returned by this class (except seed bytes). Thus, it may be overridden to change the behavior of the class.

Overrides
nextBytes in class Random


 SecureRandom.setSeed

SecureRandom.setSeed

Class Overview | Class Members | This Package | All Packages

Syntax 1
public synchronized void setSeed( byte seed[] )
Parameters
seed
the seed.
Description
Reseeds this random object. The given seed supplements, rather than replaces, the existing seed. Thus, repeated calls are guaranteed never to reduce randomness.

Syntax 2
public void setSeed( long seed )
Parameters
seed
the seed.
Description
Reseeds this random object, using the eight bytes contained in the given long seed. The given seed supplements, rather than replaces, the existing seed. Thus, repeated calls are guaranteed never to reduce randomness.

This method is defined for compatibility with java.util.Random.

Overrides
setSeed in class Random


 Class Security

Class java.security.Security

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.security.Security

public final class Security
extends Object

This class centralizes all security properties and common security methods. One of its primary uses is to manage providers.


 Security Members

Security Members

Class Overview | This Package | All Packages

Methods
Name | Description
addProvider(Provider) | Adds a provider to the next position available.
getAlgorithmProperty(String, String) | Gets a specified property for an algorithm.
getProperty(String) | Gets a security property.
getProvider(String) | Returns the provider installed with the specified name, if any.
getProviders() | Returns all providers currently installed.
insertProviderAt(Provider, int) | Adds a new provider, at a specified position.
removeProvider(String) | Removes the provider with the specified name.
setProperty(String, String) | Sets a security property.


 Security.addProvider

Security.addProvider

Class Overview | Class Members | This Package | All Packages

Syntax
public static int addProvider( Provider provider )
Parameters
provider
the provider to be added.
Returns
the preference position in which the provider was added, or -1 if the provider was not added because it is already installed.
Description
Adds a provider to the next position available.

See Also
getProvider, removeProvider


 Security.getAlgorithmProperty

Security.getAlgorithmProperty

Class Overview | Class Members | This Package | All Packages

Syntax
public static String getAlgorithmProperty( String algName, String propName )
Parameters
algName
the algorithm name.
propName
the name of the property to get.
Returns
the value of the specified property.
Description
Gets a specified property for an algorithm. The algorithm name should be a standard name. See Appendix A in the Java Cryptography Architecture API Specification & Reference for information about standard algorithm names. One possible use is by specialized algorithm parsers, which may map classes to algorithms which they understand (much like Key parsers do).


 Security.getProperty

Security.getProperty

Class Overview | Class Members | This Package | All Packages

Syntax
public static String getProperty( String key )
Parameters
key
the key of the property being retrieved.
Returns
the valeu of the security property corresponding to key.
Description
Gets a security property.


 Security.getProvider

Security.getProvider

Class Overview | Class Members | This Package | All Packages

Syntax
public static Provider getProvider( String name )
Parameters
name
the name of the provider to get.
Returns
the provider of the specified name.
Description
Returns the provider installed with the specified name, if any. Returns null if no provider with the speicified name is installed.

See Also
removeProvider, addProvider


 Security.getProviders

Security.getProviders

Class Overview | Class Members | This Package | All Packages

Syntax
public static Provider[] getProviders()
Returns
an array of all providers currently installed.
Description
Returns all providers currently installed.


 Security.insertProviderAt

Security.insertProviderAt

Class Overview | Class Members | This Package | All Packages

Syntax
public static int insertProviderAt( Provider provider, int position )
Parameters
provider
the provider to be added.
position
the preference position that the caller would like for this provider.
Returns
the actual preference position in which the provider was added, or -1 if the provider was not added because it is already installed.
Description
Adds a new provider, at a specified position. The position is the preference order in which providers are searched for requested algorithms. Note that it is not guaranteed that this preference will be respected. The position is 1-based, that is, 1 is most preferred, followed by 2, and so on. Sometimes it will be legal to add a provider, but only in the last position, in which case the position argument will be ignored.

A provider cannot be added if it is already installed.

See Also
getProvider, removeProvider


 Security.removeProvider

Security.removeProvider

Class Overview | Class Members | This Package | All Packages

Syntax
public static void removeProvider( String name )
Parameters
name
the name of the provider to remove.
Description
Removes the provider with the specified name. This method returns silently if the provider is not installed.

See Also
getProvider, addProvider


 Security.setProperty

Security.setProperty

Class Overview | Class Members | This Package | All Packages

Syntax
public static void setProperty( String key, String datum )
Parameters
key
the name of the property to be set.
datum
the value of the property to be set.
Description
Sets a security property.


 Class Signature

Class java.security.Signature

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.security.Signature

public abstract class Signature
extends Object

This Signature class is used to provide the functionality of a digital signature algorithm, such as RSA with MD5 or DSA. Digital signatures are used for authentication and integrity assurance of digital data.

Like other algorithm-based classes in Java Security, the Signature class has two major components:

Digital Signature API (Application Program Interface)
This is the interface of methods called by applications needing digital signature services. The API consists of all public methods.
Digital Signature SPI (Service Provider Interface)
This is the interface implemented by providers that supply specific algorithms. It consists of all methods whose names are prefixed by engine. Each such method is called by a correspondingly-named public API method. For example, the engineSign method is called by the sign method. The SPI methods are abstract; providers must supply a concrete implementation.

Also like other algorithm-based classes in Java Security, Signature provides implementation-independent algorithms, whereby a caller (application code) requests a particular signature algorithm and is handed back a properly initialized Signature object. It is also possible, if desired, to request a particular algorithm from a particular provider. See the getInstance methods.

Thus, there are two ways to request a Signature algorithm object: by specifying either just an algorithm name, or both an algorithm name and a package provider.

  • If just an algorithm name is specified, the system will determine if there is an implementation of the algorithm requested available in the environment, and if there is more than one, if there is a preferred one.
  • If both an algorithm name and a package provider are specified, the system will determine if there is an implementation of the algorithm in the package requested, and throw an exception if there is not.

A Signature object can be used to generate and verify digital signatures.

There are three phases to the use of a Signature object for either signing data or verifying a signature:

  1. Initialization, with either
    • a public key, which initializes the signature for verification (see initVerify), or
    • a private key, which initializes the signature for signing (see initSign).

  2. Updating

    Depending on the type of initialization, this will update the bytes to be signed or verified. See the update methods.

  3. Signing or Verifying

    a signature on all updated bytes. See sign and verify.


 Signature Members

Signature Members

Class Overview | This Package | All Packages

Fields
Name | Description
SIGN | Possible state value, signifying that this signature object has been initialized for signing.
state | Current state of this signature object.
UNINITIALIZED | Possible state value, signifying that this signature object has not yet been initialized.
VERIFY | Possible state value, signifying that this signature object has been initialized for verification.

Constructors
Name | Description
Signature(String) | Creates a Signature object for the specified algorithm.

Methods
Name | Description
clone() | Returns a clone if the implementation is cloneable.
engineGetParameter(String) | SPI: Gets the value of the specified algorithm parameter.
engineInitSign(PrivateKey) | SPI: Initializes this signature object with the specified private key for signing operations.
engineInitVerify(PublicKey) | SPI: Initializes this signature object with the specified public key for verification operations.
engineSetParameter(String, Object) | SPI: Sets the specified algorithm parameter to the specified value.
engineSign() | SPI: Returns the signature bytes of all the data updated so far.
engineUpdate(byte) | SPI: Updates the data to be signed or verified using the specified byte.
engineUpdate(byte[], int, int) | SPI: Updates the data to be signed or verified, using the specified array of bytes, starting at the specified offset.
engineVerify(byte[]) | SPI: Verifies the passed-in signature.
getAlgorithm() | Returns the name of the algorithm for this signature object.
getInstance(String) | Generates a Signature object that implements the specified algorithm.
getInstance(String, String) | Generates a Signature object implementing the specified algorithm, as supplied from the specified provider, if such an algorithm is available from the provider.
getParameter(String) | Gets the value of the specified algorithm parameter.
initSign(PrivateKey) | Initialize this object for signing.
initVerify(PublicKey) | Initializes this object for verification.
setParameter(String, Object) | Sets the specified algorithm parameter to the specified value.
sign() | Returns the signature bytes of all the data updated.
toString() | Returns a string representation of this signature object, providing information that includes the state of the object and the name of the algorithm used.
update(byte) | Updates the data to be signed or verified by a byte.
update(byte[]) | Updates the data to be signed or verified, using the specified array of bytes.
update(byte[], int, int) | Updates the data to be signed or verified, using the specified array of bytes, starting at the specified offset.
verify(byte[]) | Verifies the passed-in signature.


 Signature.SIGN

Signature.SIGN

Class Overview | Class Members | This Package | All Packages

Syntax
protected static final int SIGN
Description
Possible state value, signifying that this signature object has been initialized for signing.


 Signature.state

Signature.state

Class Overview | Class Members | This Package | All Packages

Syntax
protected int state
Description
Current state of this signature object.


 Signature.UNINITIALIZED

Signature.UNINITIALIZED

Class Overview | Class Members | This Package | All Packages

Syntax
protected static final int UNINITIALIZED
Description
Possible state value, signifying that this signature object has not yet been initialized.


 Signature.VERIFY

Signature.VERIFY

Class Overview | Class Members | This Package | All Packages

Syntax
protected static final int VERIFY
Description
Possible state value, signifying that this signature object has been initialized for verification.


 Signature.Signature

Signature.Signature

Class Overview | Class Members | This Package | All Packages

Syntax
protected Signature( String algorithm )
Parameters
algorithm
the standard string name of the algorithm. See Appendix A in the Java Cryptography Architecture API Specification & Reference for information about standard algorithm names.
Description
Creates a Signature object for the specified algorithm.


 Signature.clone

Signature.clone

Class Overview | Class Members | This Package | All Packages

Syntax
public Object clone() throws CloneNotSupportedException
Returns
a clone if the implementation is cloneable.
Description
Returns a clone if the implementation is cloneable.

Exceptions
CloneNotSupportedException if this is called on an implementation that does not support Cloneable.
Overrides
clone in class Object


 Signature.engineGetParameter

Signature.engineGetParameter

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract Object engineGetParameter( String param ) throws InvalidParameterException
Parameters
param
the string name of the parameter.
Returns
the object that represents the parameter value, or null if there is none.
Description
SPI: Gets the value of the specified algorithm parameter. This method supplies a general-purpose mechanism through which it is possible to get the various parameters of this object. A parameter may be any settable parameter for the algorithm, such as a parameter size, or a source of random bits for signature generation (if appropriate), or an indication of whether or not to perform a specific but optional computation. A uniform algorithm-specific naming scheme for each parameter is desirable but left unspecified at this time.

Exceptions
InvalidParameterException if param is an invalid parameter for this engine, or another exception occurs while trying to get this parameter.


 Signature.engineInitSign

Signature.engineInitSign

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract void engineInitSign( PrivateKey privateKey ) throws InvalidKeyException
Parameters
privateKey
the private key of the identity whose signature will be generated.
Description
SPI: Initializes this signature object with the specified private key for signing operations.

Exceptions
InvalidKeyException if the key is improperly encoded, parameters are missing, and so on.


 Signature.engineInitVerify

Signature.engineInitVerify

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract void engineInitVerify( PublicKey publicKey ) throws InvalidKeyException
Parameters
publicKey
the public key of the identity whose signature is going to be verified.
Description
SPI: Initializes this signature object with the specified public key for verification operations.

Exceptions
InvalidKeyException if the key is improperly encoded, parameters are missing, and so on.


 Signature.engineSetParameter

Signature.engineSetParameter

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract void engineSetParameter( String param, Object value ) throws InvalidParameterException
Parameters
param
the string identifier of the parameter.
value
the parameter value.
Description
SPI: Sets the specified algorithm parameter to the specified value. This method supplies a general-purpose mechanism through which it is possible to set the various parameters of this object. A parameter may be any settable parameter for the algorithm, such as a parameter size, or a source of random bits for signature generation (if appropriate), or an indication of whether or not to perform a specific but optional computation. A uniform algorithm-specific naming scheme for each parameter is desirable but left unspecified at this time.

Exceptions
InvalidParameterException if param is an invalid parameter for this signature algorithm engine, the parameter is already set and cannot be set again, a security exception occurs, and so on.


 Signature.engineSign

Signature.engineSign

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract byte[] engineSign() throws SignatureException
Returns
the signature bytes of the signing operation's result.
Description
SPI: Returns the signature bytes of all the data updated so far. The signature returned is X.509-encoded. For more information about the X.509 encoding, see "Why should I care about X.509 certificates?"

Exceptions
SignatureException if the engine is not initialized properly.


 Signature.engineUpdate

Signature.engineUpdate

Class Overview | Class Members | This Package | All Packages

Syntax 1
protected abstract void engineUpdate( byte b ) throws SignatureException
Parameters
b
the byte to use for the update.
Description
SPI: Updates the data to be signed or verified using the specified byte.

Exceptions
SignatureException if the engine is not initialized properly.

Syntax 2
protected abstract void engineUpdate( byte b[], int off, int len ) throws SignatureException
Parameters
data
the array of bytes.
off
the offset to start from in the array of bytes.
len
the number of bytes to use, starting at offset.
Description
SPI: Updates the data to be signed or verified, using the specified array of bytes, starting at the specified offset.

Exceptions
SignatureException if the engine is not initialized properly.


 Signature.engineVerify

Signature.engineVerify

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract boolean engineVerify( byte sigBytes[] ) throws SignatureException
Parameters
sigBytes
the signature bytes to be verified.
Returns
true if the signature was verified, false if not.
Description
SPI: Verifies the passed-in signature. The signature bytes are expected to be X.509-encoded. For more information about the X.509 encoding, see "Why should I care about X.509 certificates?"

Exceptions
SignatureException if the engine is not initialized properly, or the passed-in signature is improperly encoded or of the wrong type, etc.


 Signature.getAlgorithm

Signature.getAlgorithm

Class Overview | Class Members | This Package | All Packages

Syntax
public final String getAlgorithm()
Returns
the name of the algorithm for this signature object.
Description
Returns the name of the algorithm for this signature object.


 Signature.getInstance

Signature.getInstance

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static Signature getInstance( String algorithm ) throws NoSuchAlgorithmException
Parameters
algorithm
the standard name of the algorithm requested. See Appendix A in the Java Cryptography Architecture API Specification & Reference for information about standard algorithm names.
Returns
the new Signature object.
Description
Generates a Signature object that implements the specified algorithm. If the default provider package contains a Signature subclass implementing the algorithm, an instance of that subclass is returned. If the algorithm is not available in the default package, other packages are searched.

Exceptions
NoSuchAlgorithmException if the algorithm is not available in the environment.

Syntax 2
public static Signature getInstance( String algorithm, String provider ) throws NoSuchAlgorithmException, NoSuchProviderException
Parameters
algorithm
the name of the algorithm requested. See Appendix A in the Java Cryptography Architecture API Specification & Reference for information about standard algorithm names.
provider
the name of the provider.
Returns
the new Signature object.
Description
Generates a Signature object implementing the specified algorithm, as supplied from the specified provider, if such an algorithm is available from the provider.

Exceptions
NoSuchAlgorithmException if the algorithm is not available in the package supplied by the requested provider.
Exceptions
NoSuchProviderException if the provider is not available in the environment.
See Also
Provider


 Signature.getParameter

Signature.getParameter

Class Overview | Class Members | This Package | All Packages

Syntax
public final Object getParameter( String param ) throws InvalidParameterException
Parameters
param
the string name of the parameter.
Returns
the object that represents the parameter value, or null if there is none.
Description
Gets the value of the specified algorithm parameter. This method supplies a general-purpose mechanism through which it is possible to get the various parameters of this object. A parameter may be any settable parameter for the algorithm, such as a parameter size, or a source of random bits for signature generation (if appropriate), or an indication of whether or not to perform a specific but optional computation. A uniform algorithm-specific naming scheme for each parameter is desirable but left unspecified at this time.

Exceptions
InvalidParameterException if param is an invalid parameter for this engine, or another exception occurs while trying to get this parameter.


 Signature.initSign

Signature.initSign

Class Overview | Class Members | This Package | All Packages

Syntax
public final void initSign( PrivateKey privateKey ) throws InvalidKeyException
Parameters
privateKey
the private key of the identity whose signature is going to be generated.
Description
Initialize this object for signing. If this method is called again with a different argument, it negates the effect of this call.

Exceptions
InvalidKeyException if the key is invalid.


 Signature.initVerify

Signature.initVerify

Class Overview | Class Members | This Package | All Packages

Syntax
public final void initVerify( PublicKey publicKey ) throws InvalidKeyException
Parameters
publicKey
the public key of the identity whose signature is going to be verified.
Description
Initializes this object for verification. If this method is called again with a different argument, it negates the effect of this call.

Exceptions
InvalidKeyException if the key is invalid.


 Signature.setParameter

Signature.setParameter

Class Overview | Class Members | This Package | All Packages

Syntax
public final void setParameter( String param, Object value ) throws InvalidParameterException
Parameters
param
the string identifier of the parameter.
value
the parameter value.
Description
Sets the specified algorithm parameter to the specified value. This method supplies a general-purpose mechanism through which it is possible to set the various parameters of this object. A parameter may be any settable parameter for the algorithm, such as a parameter size, or a source of random bits for signature generation (if appropriate), or an indication of whether or not to perform a specific but optional computation. A uniform algorithm-specific naming scheme for each parameter is desirable but left unspecified at this time.

Exceptions
InvalidParameterException if param is an invalid parameter for this signature algorithm engine, the parameter is already set and cannot be set again, a security exception occurs, and so on.


 Signature.sign

Signature.sign

Class Overview | Class Members | This Package | All Packages

Syntax
public final byte[] sign() throws SignatureException
Returns
the signature bytes of the signing operation's result.
Description
Returns the signature bytes of all the data updated. The signature returned is X.509-encoded.

A call to this method resets this signature object to the state it was in when previously initialized for signing via a call to initSign(PrivateKey). That is, the object is reset and available to generate another signature from the same signer, if desired, via new calls to update and sign.

Exceptions
SignatureException if this signature object is not initialized properly.


 Signature.toString

Signature.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string representation of this signature object.
Description
Returns a string representation of this signature object, providing information that includes the state of the object and the name of the algorithm used.

Overrides
toString in class Object


 Signature.update

Signature.update

Class Overview | Class Members | This Package | All Packages

Syntax 1
public final void update( byte b ) throws SignatureException
Parameters
b
the byte to use for the update.
Description
Updates the data to be signed or verified by a byte.

Exceptions
SignatureException if this signature object is not initialized properly.

Syntax 2
public final void update( byte data[] ) throws SignatureException
Parameters
data
the byte array to use for the update.
Description
Updates the data to be signed or verified, using the specified array of bytes.

Exceptions
SignatureException if this signature object is not initialized properly.

Syntax 3
public final void update( byte data[], int off, int len ) throws SignatureException
Parameters
data
the array of bytes.
off
the offset to start from in the array of bytes.
len
the number of bytes to use, starting at offset.
Description
Updates the data to be signed or verified, using the specified array of bytes, starting at the specified offset.

Exceptions
SignatureException if this signature object is not initialized properly.


 Signature.verify

Signature.verify

Class Overview | Class Members | This Package | All Packages

Syntax
public final boolean verify( byte signature[] ) throws SignatureException
Parameters
signature
the signature bytes to be verified.
Returns
true if the signature was verified, false if not.
Description
Verifies the passed-in signature. The signature bytes are expected to be X.509-encoded.

A call to this method resets this signature object to the state it was in when previously initialized for verification via a call to initVerify(PublicKey). That is, the object is reset and available to verify another signature from the identity whose public key was specified in the call to initVerify.

Exceptions
SignatureException if this signature object is not initialized properly, or the passed-in signature is improperly encoded or of the wrong type, etc.


 Class SignatureException

Class java.security.SignatureException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.security.SignatureException

public class SignatureException
extends Exception

This is the generic Signature exception.


 SignatureException Members

SignatureException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
SignatureException() | Constructs a SignatureException with no detail message.
SignatureException(String) | Constructs a SignatureException with the specified detail message.


 SignatureException.SignatureException

SignatureException.SignatureException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public SignatureException()
Description
Constructs a SignatureException with no detail message. A detail message is a String that describes this particular exception.

Syntax 2
public SignatureException( String msg )
Parameters
msg
the detail message.
Description
Constructs a SignatureException with the specified detail message. A detail message is a String that describes this particular exception.


 Class Signer

Class java.security.Signer

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.security.Identity
           |
           +----java.security.Signer

public abstract class Signer
extends Identity

This class is used to represent an Identity that can also digitally sign data.

The management of a signer's private keys is an important and sensitive issue that should be handled by subclasses as appropriate to their intended use.

See Also:
Identity


 Signer Members

Signer Members

Class Overview | This Package | All Packages

Constructors
Name | Description
Signer() | Creates a signer.
Signer(String) | Creates a signer with the specified identity name.
Signer(String, IdentityScope) | Creates a signer with the specified identity name and scope.

Methods
Name | Description
getPrivateKey() | Returns this signer's private key.
setKeyPair(KeyPair) | Sets the key pair (public key and private key) for this signer.
toString() | Returns a string of information about the signer.


 Signer.Signer

Signer.Signer

Class Overview | Class Members | This Package | All Packages

Syntax 1
protected Signer()
Description
Creates a signer. This constructor should only be used for serialization.

Syntax 2
public Signer( String name )
Parameters
name
the identity name.
Description
Creates a signer with the specified identity name.

Syntax 3
public Signer( String name, IdentityScope scope ) throws KeyManagementException
Parameters
name
the identity name.
scope
the scope of the identity.
Description
Creates a signer with the specified identity name and scope.

Exceptions
KeyManagementException if there is already an identity with the same name in the scope.


 Signer.getPrivateKey

Signer.getPrivateKey

Class Overview | Class Members | This Package | All Packages

Syntax
public PrivateKey getPrivateKey()
Returns
this signer's private key, or null if the private key has not yet been set.
Description
Returns this signer's private key.


 Signer.setKeyPair

Signer.setKeyPair

Class Overview | Class Members | This Package | All Packages

Syntax
public final void setKeyPair( KeyPair pair ) throws InvalidParameterException, KeyException
Parameters
pair
an initialized key pair.
Description
Sets the key pair (public key and private key) for this signer.

Exceptions
InvalidParameterException if the key pair is not properly initialized.
Exceptions
KeyException if the key pair cannot be set for any other reason.


 Signer.toString

Signer.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string of information about the signer.
Description
Returns a string of information about the signer.

Overrides
toString in class Identity


 Package java.security.acl

Package java.security.acl

All Packages

Interfaces

  • Acl
  • AclEntry
  • Group
  • Owner
  • Permission

    • Exceptions

  • AclNotFoundException
  • LastOwnerException
  • NotOwnerException


 Interface Acl

Interface java.security.acl.Acl

Interface Members | This Package | All Packages

public interface Acl
extends Owner

Interface representing an Access Control List (ACL). An Access Control List is a data structure used to guard access to resources.

An ACL can be thought of as a data structure with multiple ACL entries. Each ACL entry, of interface type AclEntry, contains a set of permissions associated with a particular principal. (A principal represents an entity such as an individual user or a group). Additionally, each ACL entry is specified as being either positive or negative. If positive, the permissions are to be granted to the associated principal. If negative, the permissions are to be denied.

The ACL Entries in each ACL observe the following rules:

  • Each principal can have at most one positive ACL entry and one negative entry; that is, multiple positive or negative ACL entries are not allowed for any principal. Each entry specifies the set of permissions that are to be granted (if positive) or denied (if negative).

  • If there is no entry for a particular principal, then the principal is considered to have a null (empty) permission set.

  • If there is a positive entry that grants a principal a particular permission, and a negative entry that denies the principal the same permission, the result is as though the permission was never granted or denied.

  • Individual permissions always override permissions of the group(s) to which the individual belongs. That is, individual negative permissions (specific denial of permissions) override the groups' positive permissions. And individual positive permissions override the groups' negative permissions.

The java.security.acl package provides the interfaces to the ACL and related data structures (ACL entries, groups, permissions, etc.), and the sun.security.acl classes provide a default implementation of the interfaces. For example, java.security.acl.Acl provides the interface to an ACL and the sun.security.acl.AclImpl class provides the default implementation of the interface.

The java.security.acl.Acl interface extends the java.security.acl.Owner interface. The Owner interface is used to maintain a list of owners for each ACL. Only owners are allowed to modify an ACL. For example, only an owner can call the ACL's addEntry method to add a new ACL entry to the ACL.

See Also:
AclEntry, Owner, getPermissions


 Acl Members

Acl Members

Interface Overview | This Package | All Packages

Methods
Name | Description
addEntry(Principal, AclEntry) | Adds an ACL entry to this ACL.
checkPermission(Principal, Permission) | Checks whether or not the specified principal has the specified permission.
entries() | Returns an enumeration of the entries in this ACL.
getName() | Returns the name of this ACL.
getPermissions(Principal) | Returns an enumeration for the set of allowed permissions for the specified principal (representing an entity such as an individual or a group).
removeEntry(Principal, AclEntry) | Removes an ACL entry from this ACL.
setName(Principal, String) | Sets the name of this ACL.
toString() | Returns a string representation of the ACL contents.


 Acl.addEntry

Acl.addEntry

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean addEntry( Principal caller, AclEntry entry ) throws NotOwnerException
Parameters
caller
the principal invoking this method. It must be an owner of this ACL.
entry
the ACL entry to be added to this ACL.
Returns
true on success, false if an entry of the same type (positive or negative) for the same principal is already present in this ACL.
Description
Adds an ACL entry to this ACL. An entry associates a principal (e.g., an individual or a group) with a set of permissions. Each principal can have at most one positive ACL entry (specifying permissions to be granted to the principal) and one negative ACL entry (specifying permissions to be denied). If there is already an ACL entry of the same type (negative or positive) already in the ACL, false is returned.

Exceptions
NotOwnerException if the caller principal is not an owner of this ACL.


 Acl.checkPermission

Acl.checkPermission

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean checkPermission( Principal principal, Permission permission )
Parameters
principal
the principal, assumed to be a valid authenticated Principal.
permission
the permission to be checked for.
Returns
true if the principal has the specified permission, false otherwise.
Description
Checks whether or not the specified principal has the specified permission. If it does, true is returned, otherwise false is returned. More specifically, this method checks whether the passed permission is a member of the allowed permission set of the specified principal. The allowed permission set is determined by the same algorithm as is used by the getPermissions method.

See Also
getPermissions


 Acl.entries

Acl.entries

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Enumeration entries()
Returns
an enumeration of the entries in this ACL.
Description
Returns an enumeration of the entries in this ACL. Each element in the enumeration is of type AclEntry.


 Acl.getName

Acl.getName

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getName()
Returns
the name of this ACL.
Description
Returns the name of this ACL.


 Acl.getPermissions

Acl.getPermissions

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Enumeration getPermissions( Principal user )
Parameters
user
the principal whose permission set is to be returned.
Returns
the permission set specifying the permissions the principal is allowed.
Description
Returns an enumeration for the set of allowed permissions for the specified principal (representing an entity such as an individual or a group). This set of allowed permissions is calculated as follows:

  • If there is no entry in this Access Control List for the specified principal, an empty permission set is returned.

  • Otherwise, the principal's group permission sets are determined. (A principal can belong to one or more groups, where a group is a group of principals, represented by the Group interface.) The group positive permission set is the union of all the positive permissions of each group that the principal belongs to. The group negative permission set is the union of all the negative permissions of each group that the principal belongs to. If there is a specific permission that occurs in both the positive permission set and the negative permission set, it is removed from both.

    The individual positive and negative permission sets are also determined. The positive permission set contains the permissions specified in the positive ACL entry (if any) for the principal. Similarly, the negative permission set contains the permissions specified in the negative ACL entry (if any) for the principal. The individual positive (or negative) permission set is considered to be null if there is not a positive (negative) ACL entry for the principal in this ACL.

    The set of permissions granted to the principal is then calculated using the simple rule that individual permissions always override the group permissions. That is, the principal's individual negative permission set (specific denial of permissions) overrides the group positive permission set, and the principal's individual positive permission set overrides the group negative permission set.


 Acl.removeEntry

Acl.removeEntry

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean removeEntry( Principal caller, AclEntry entry ) throws NotOwnerException
Parameters
caller
the principal invoking this method. It must be an owner of this ACL.
entry
the ACL entry to be removed from this ACL.
Returns
true on success, false if the entry is not part of this ACL.
Description
Removes an ACL entry from this ACL.

Exceptions
NotOwnerException if the caller principal is not an owner of this Acl.


 Acl.setName

Acl.setName

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setName( Principal caller, String name ) throws NotOwnerException
Parameters
caller
the principal invoking this method. It must be an owner of this ACL.
name
the name to be given to this ACL.
Description
Sets the name of this ACL.

Exceptions
NotOwnerException if the caller principal is not an owner of this ACL.


 Acl.toString

Acl.toString

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String toString()
Returns
a string representation of the ACL contents.
Description
Returns a string representation of the ACL contents.

Overrides
toString in class Object


 Interface AclEntry

Interface java.security.acl.AclEntry

Interface Members | This Package | All Packages

public interface AclEntry
extends Cloneable

This is the interface used for representing one entry in an Access Control List (ACL).

An ACL can be thought of as a data structure with multiple ACL entry objects. Each ACL entry object contains a set of permissions associated with a particular principal. (A principal represents an entity such as an individual user or a group). Additionally, each ACL entry is specified as being either positive or negative. If positive, the permissions are to be granted to the associated principal. If negative, the permissions are to be denied. Each principal can have at most one positive ACL entry and one negative entry; that is, multiple positive or negative ACL entries are not allowed for any principal. Note: ACL entries are by default positive. An entry becomes a negative entry only if the setNegativePermissions method is called on it.

See Also:
Acl


 AclEntry Members

AclEntry Members

Interface Overview | This Package | All Packages

Methods
Name | Description
addPermission(Permission) | Adds the specified permission to this ACL entry.
checkPermission(Permission) | Checks if the specified permission is part of the permission set in this entry.
clone() | Clones this ACL entry.
getPrincipal() | Returns the principal for which permissions are granted or denied by this ACL entry.
isNegative() | Returns true if this is a negative ACL entry (one denying the associated principal the set of permissions in the entry), false otherwise.
permissions() | Returns an enumeration of the permissions in this ACL entry.
removePermission(Permission) | Removes the specified permission from this ACL entry.
setNegativePermissions() | Sets this ACL entry to be a negative one.
setPrincipal(Principal) | Specifies the principal for which permissions are granted or denied by this ACL entry.
toString() | Returns a string representation of the contents of this ACL entry.


 AclEntry.addPermission

AclEntry.addPermission

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean addPermission( Permission permission )
Parameters
permission
the permission to be associated with the principal in this entry.
Returns
true if the permission was added, false if the permission was already part of this entry's permission set.
Description
Adds the specified permission to this ACL entry. Note: An entry can have multiple permissions.


 AclEntry.checkPermission

AclEntry.checkPermission

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean checkPermission( Permission permission )
Parameters
permission
the permission to be checked for.
Returns
true if the permission is part of the permission set in this entry, false otherwise.
Description
Checks if the specified permission is part of the permission set in this entry.


 AclEntry.clone

AclEntry.clone

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Object clone()
Returns
a clone of this ACL entry.
Description
Clones this ACL entry.

Overrides
clone in class Object


 AclEntry.getPrincipal

AclEntry.getPrincipal

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Principal getPrincipal()
Returns
the principal associated with this entry.
Description
Returns the principal for which permissions are granted or denied by this ACL entry. Returns null if there is no principal set for this entry yet.


 AclEntry.isNegative

AclEntry.isNegative

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean isNegative()
Returns
true if this is a negative ACL entry, false if it's not.
Description
Returns true if this is a negative ACL entry (one denying the associated principal the set of permissions in the entry), false otherwise.


 AclEntry.permissions

AclEntry.permissions

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Enumeration permissions()
Returns
an enumeration of the permissions in this ACL entry.
Description
Returns an enumeration of the permissions in this ACL entry.


 AclEntry.removePermission

AclEntry.removePermission

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean removePermission( Permission permission )
Parameters
permission
the permission to be removed from this entry.
Returns
true if the permission is removed, false if the permission was not part of this entry's permission set.
Description
Removes the specified permission from this ACL entry.


 AclEntry.setNegativePermissions

AclEntry.setNegativePermissions

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setNegativePermissions()
Description
Sets this ACL entry to be a negative one. That is, the associated principal (e.g., a user or a group) will be denied the permission set specified in the entry. Note: ACL entries are by default positive. An entry becomes a negative entry only if this setNegativePermissions method is called on it.


 AclEntry.setPrincipal

AclEntry.setPrincipal

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean setPrincipal( Principal user )
Parameters
user
the principal to be set for this entry.
Returns
true if the principal is set, false if there was already a principal set for this entry.
Description
Specifies the principal for which permissions are granted or denied by this ACL entry. If a principal was already set for this ACL entry, false is returned, otherwise true is returned.


 AclEntry.toString

AclEntry.toString

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String toString()
Returns
a string representation of the contents.
Description
Returns a string representation of the contents of this ACL entry.

Overrides
toString in class Object


 Class AclNotFoundException

Class java.security.acl.AclNotFoundException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.security.acl.AclNotFoundException

public class AclNotFoundException
extends Exception

This is an exception that is thrown whenever a reference is made to a non-existent ACL (Access Control List).


 AclNotFoundException Members

AclNotFoundException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
AclNotFoundException() | Constructs an AclNotFoundException.


 AclNotFoundException.AclNotFoundException

AclNotFoundException.AclNotFoundException

Class Overview | Class Members | This Package | All Packages

Syntax
public AclNotFoundException()
Description
Constructs an AclNotFoundException.


 Interface Group

Interface java.security.acl.Group

Interface Members | This Package | All Packages

public interface Group
extends Principal

This interface is used to represent a group of principals. (A principal represents an entity such as an individual user or a company).

Note that Group extends Principal. Thus, either a Principal or a Group can be passed as an argument to methods containing a Principal parameter. For example, you can add either a Principal or a Group to a Group object by calling the object's addMember method, passing it the Principal or Group.


 Group Members

Group Members

Interface Overview | This Package | All Packages

Methods
Name | Description
addMember(Principal) | Adds the specified member to the group.
isMember(Principal) | Returns true if the passed principal is a member of the group.
members() | Returns an enumeration of the members in the group.
removeMember(Principal) | Removes the specified member from the group.


 Group.addMember

Group.addMember

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean addMember( Principal user )
Parameters
user
the principal to add to this group.
Returns
true if the member was successfully added, false if the principal was already a member.
Description
Adds the specified member to the group.


 Group.isMember

Group.isMember

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean isMember( Principal member )
Parameters
member
the principal whose membership is to be checked.
Returns
true if the principal is a member of this group, false otherwise.
Description
Returns true if the passed principal is a member of the group. This method does a recursive search, so if a principal belongs to a group which is a member of this group, true is returned.


 Group.members

Group.members

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Enumeration members()
Returns
an enumeration of the group members.
Description
Returns an enumeration of the members in the group. The returned objects can be instances of either Principal or Group (which is a subclass of Principal).


 Group.removeMember

Group.removeMember

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean removeMember( Principal user )
Parameters
user
the principal to remove from this group.
Returns
true if the principal was removed, or false if the principal was not a member.
Description
Removes the specified member from the group.


 Class LastOwnerException

Class java.security.acl.LastOwnerException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.security.acl.LastOwnerException

public class LastOwnerException
extends Exception

This is an exception that is thrown whenever an attempt is made to delete the last owner of an Access Control List.

See Also:
deleteOwner


 LastOwnerException Members

LastOwnerException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
LastOwnerException() | Constructs a LastOwnerException.


 LastOwnerException.LastOwnerException

LastOwnerException.LastOwnerException

Class Overview | Class Members | This Package | All Packages

Syntax
public LastOwnerException()
Description
Constructs a LastOwnerException.


 Class NotOwnerException

Class java.security.acl.NotOwnerException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.security.acl.NotOwnerException

public class NotOwnerException
extends Exception

This is an exception that is thrown whenever the modification of an object (such as an Access Control List) is only allowed to be done by an owner of the object, but the Principal attempting the modification is not an owner.


 NotOwnerException Members

NotOwnerException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
NotOwnerException() | Constructs a NotOwnerException.


 NotOwnerException.NotOwnerException

NotOwnerException.NotOwnerException

Class Overview | Class Members | This Package | All Packages

Syntax
public NotOwnerException()
Description
Constructs a NotOwnerException.


 Interface Owner

Interface java.security.acl.Owner

Interface Members | This Package | All Packages

public interface Owner

Interface for managing owners of Access Control Lists (ACLs) or ACL configurations. (Note that the Acl interface in the java.security.acl package extends this Owner interface.) The initial owner Principal should be specified as an argument to the constructor of the class implementing this interface.

See Also:
Acl


 Owner Members

Owner Members

Interface Overview | This Package | All Packages

Methods
Name | Description
addOwner(Principal, Principal) | Adds an owner.
deleteOwner(Principal, Principal) | Deletes an owner.
isOwner(Principal) | Returns true if the given principal is an owner of the ACL.


 Owner.addOwner

Owner.addOwner

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean addOwner( Principal caller, Principal owner ) throws NotOwnerException
Parameters
caller
the principal invoking this method. It must be an owner of the ACL.
owner
the owner that should be added to the list of owners.
Returns
true if successful, false if owner is already an owner.
Description
Adds an owner. Only owners can modify ACL contents. The caller principal must be an owner of the ACL in order to invoke this method. That is, only an owner can add another owner. The initial owner is configured at ACL construction time.

Exceptions
NotOwnerException if the caller principal is not an owner of the ACL.


 Owner.deleteOwner

Owner.deleteOwner

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean deleteOwner( Principal caller, Principal owner ) throws NotOwnerException, LastOwnerException
Parameters
caller
the principal invoking this method. It must be an owner of the ACL.
owner
the owner to be removed from the list of owners.
Returns
true if the owner is removed, false if the owner is not part of the list of owners.
Description
Deletes an owner. If this is the last owner in the ACL, an exception is raised.

The caller principal must be an owner of the ACL in order to invoke this method.

Exceptions
NotOwnerException if the caller principal is not an owner of the ACL.
Exceptions
LastOwnerException if there is only one owner left, so that deleteOwner would leave the ACL owner-less.


 Owner.isOwner

Owner.isOwner

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean isOwner( Principal owner )
Parameters
owner
the principal to be checked to determine whether or not it is an owner.
Returns
true if the passed principal is in the list of owners, false if not.
Description
Returns true if the given principal is an owner of the ACL.


 Interface Permission

Interface java.security.acl.Permission

Interface Members | This Package | All Packages

public interface Permission

This interface represents a permission, such as that used to grant a particular type of access to a resource.


 Permission Members

Permission Members

Interface Overview | This Package | All Packages

Methods
Name | Description
equals(Object) | Returns true if the object passed matches the permission represented in this interface.
toString() | Prints a string representation of this permission.


 Permission.equals

Permission.equals

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean equals( Object another )
Parameters
another
the Permission object to compare with.
Returns
true if the Permission objects are equal, false otherwise
Description
Returns true if the object passed matches the permission represented in this interface.

Overrides
equals in class Object


 Permission.toString

Permission.toString

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String toString()
Returns
the string representation of the permission.
Description
Prints a string representation of this permission.

Overrides
toString in class Object


 Package java.security.interfaces

Package java.security.interfaces

All Packages

Interfaces

  • DSAKey
  • DSAKeyPairGenerator
  • DSAParams
  • DSAPrivateKey
  • DSAPublicKey


 Interface DSAKey

Interface java.security.interfaces.DSAKey

Interface Members | This Package | All Packages

public interface DSAKey

The interface to a DSA public or private key. DSA (Digital Signature Algorithm) is defined in NIST's FIPS-186.

See Also:
DSAParams, Key, Signature


 DSAKey Members

DSAKey Members

Interface Overview | This Package | All Packages

Methods
Name | Description
getParams() | Returns the DSA-specific key parameters.


 DSAKey.getParams

DSAKey.getParams

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract DSAParams getParams()
Returns
the DSA-specific key parameters.
Description
Returns the DSA-specific key parameters. These parameters are never secret.

See Also
DSAParams


 Interface DSAKeyPairGenerator

Interface java.security.interfaces.DSAKeyPairGenerator

Interface Members | This Package | All Packages

public interface DSAKeyPairGenerator

An interface to an object capable of generating DSA key pairs.

The initialize methods may each be called any number of times. If no initialize method is called on a DSAKeyPairGenerator, the default is to generate 1024-bit keys, using precomputed p, q and g parameters and an instance of SecureRandom as the random bit source.

Users wishing to indicate DSA-specific parameters, and to generate a key pair suitable for use with the DSA algorithm typically

  1. Get a key pair generator for the DSA algorithm by calling the KeyPairGenerator getInstance method with "DSA" as its argument.

  2. Initialize the generator by casting the result to a DSAKeyPairGenerator and calling one of the initialize methods from this DSAKeyPairGenerator interface.

  3. Generate a key pair by calling the generateKeyPair method from the KeyPairGenerator class.

Note: it is not always necessary to do do algorithm-specific initialization for a DSA key pair generator. That is, it is not always necessary to call an initialize method in this interface. Algorithm-independent initialization using the initialize method in the KeyPairGenerator interface is all that is needed when you accept defaults for algorithm-specific parameters.

See Also:
KeyPairGenerator


 DSAKeyPairGenerator Members

DSAKeyPairGenerator Members

Interface Overview | This Package | All Packages

Methods
Name | Description
initialize(DSAParams, SecureRandom) | Initializes the key pair generator using p, q and g, the DSA family parameters.
initialize(int, boolean, SecureRandom) | Initializes the key pair generator for a given modulus length, without parameters.


 DSAKeyPairGenerator.initialize

DSAKeyPairGenerator.initialize

Interface Overview | Interface Members | This Package | All Packages

Syntax 1
public abstract void initialize( DSAParams params, SecureRandom random ) throws InvalidParameterException
Parameters
params
the parameters to use to generate the keys.
random
the random bit source to use to generate key bits.
Description
Initializes the key pair generator using p, q and g, the DSA family parameters.

Exceptions
InvalidParameterException if the parameters passed are invalid or null.

Syntax 2
public abstract void initialize( int modlen, boolean genParams, SecureRandom random ) throws InvalidParameterException
Parameters
modlen
the modulus length, in bits. Valid values are any multiple of 8 between 512 and 1024, inclusive.
random
the random bit source to use to generate key bits.
genParams
whether or not to generate new parameters for the modulus length requested.
Description
Initializes the key pair generator for a given modulus length, without parameters.

If genParams is true, this method will generate new p, q and g parameters. If it is false, the method will use precomputed parameters for the modulus length requested. If there are no precomputed parameters for that modulus length, an exception will be thrown. It is guaranteed that there will always be default parameters for modulus lengths of 512 and 1024 bits.

Exceptions
InvalidParameterException if the modulus length is not between 512 and 1024, or if genParams is false and there are not precomputed parameters for the modulus length requested.


 Interface DSAParams

Interface java.security.interfaces.DSAParams

Interface Members | This Package | All Packages

public interface DSAParams

Interface to a DSA-specific set of key parameters, which defines a DSA key family. DSA (Digital Signature Algorithm) is defined in NIST's FIPS-186.

See Also:
DSAKey, Key, Signature


 DSAParams Members

DSAParams Members

Interface Overview | This Package | All Packages

Methods
Name | Description
getG() | Returns the base, g.
getP() | Returns the prime, p.
getQ() | Returns the subprime, q.


 DSAParams.getG

DSAParams.getG

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract BigInteger getG()
Returns
the base, g.
Description
Returns the base, g.


 DSAParams.getP

DSAParams.getP

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract BigInteger getP()
Returns
the prime, p.
Description
Returns the prime, p.


 DSAParams.getQ

DSAParams.getQ

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract BigInteger getQ()
Returns
the subprime, q.
Description
Returns the subprime, q.


 Interface DSAPrivateKey

Interface java.security.interfaces.DSAPrivateKey

Interface Members | This Package | All Packages

public interface DSAPrivateKey
extends DSAKey, PrivateKey

The standard interface to a DSA private key. DSA (Digital Signature Algorithm) is defined in NIST's FIPS-186.

See Also:
Key, Signature, DSAKey, DSAPublicKey


 DSAPrivateKey Members

DSAPrivateKey Members

Interface Overview | This Package | All Packages

Methods
Name | Description
getX() | Returns the value of the private key, x.


 DSAPrivateKey.getX

DSAPrivateKey.getX

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract BigInteger getX()
Returns
the value of the private key, x.
Description
Returns the value of the private key, x.


 Interface DSAPublicKey

Interface java.security.interfaces.DSAPublicKey

Interface Members | This Package | All Packages

public interface DSAPublicKey
extends DSAKey, PublicKey

The interface to a DSA public key. DSA (Digital Signature Algorithm) is defined in NIST's FIPS-186.

See Also:
Key, KeyParams, Signature


 DSAPublicKey Members

DSAPublicKey Members

Interface Overview | This Package | All Packages

Methods
Name | Description
getY() | Returns the value of the public key, y.


 DSAPublicKey.getY

DSAPublicKey.getY

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract BigInteger getY()
Returns
the value of the public key, y.
Description
Returns the value of the public key, y.


 Package java.sql

Package java.sql

All Packages

Interfaces

  • CallableStatement
  • Connection
  • DatabaseMetaData
  • Driver
  • PreparedStatement
  • ResultSet
  • ResultSetMetaData
  • Statement

    • Classes

  • Date
  • DriverManager
  • DriverPropertyInfo
  • Time
  • Timestamp
  • Types

    • Exceptions

  • DataTruncation
  • SQLException
  • SQLWarning


 Interface CallableStatement

Interface java.sql.CallableStatement

Interface Members | This Package | All Packages

public interface CallableStatement
extends PreparedStatement

CallableStatement is used to execute SQL stored procedures.

JDBC provides a stored procedure SQL escape that allows stored procedures to be called in a standard way for all RDBMS's. This escape syntax has one form that includes a result parameter and one that does not. If used, the result parameter must be registered as an OUT parameter. The other parameters may be used for input, output or both. Parameters are refered to sequentially, by number. The first parameter is 1.

{?= call [,, ...]}
{call [,, ...]}

IN parameter values are set using the set methods inherited from PreparedStatement. The type of all OUT parameters must be registered prior to executing the stored procedure; their values are retrieved after execution via the get methods provided here.

A Callable statement may return a ResultSet or multiple ResultSets. Multiple ResultSets are handled using operations inherited from Statement.

For maximum portability, a call's ResultSets and update counts should be processed prior to getting the values of output parameters.

See Also:
prepareCall, ResultSet


 CallableStatement Members

CallableStatement Members

Interface Overview | This Package | All Packages

Methods
Name | Description
getBigDecimal(int, int) | Get the value of a NUMERIC parameter as a java.math.BigDecimal object.
getBoolean(int) | Get the value of a BIT parameter as a Java boolean.
getByte(int) | Get the value of a TINYINT parameter as a Java byte.
getBytes(int) | Get the value of a SQL BINARY or VARBINARY parameter as a Java byte[]
getDate(int) | Get the value of a SQL DATE parameter as a java.sql.Date object
getDouble(int) | Get the value of a DOUBLE parameter as a Java double.
getFloat(int) | Get the value of a FLOAT parameter as a Java float.
getInt(int) | Get the value of an INTEGER parameter as a Java int.
getLong(int) | Get the value of a BIGINT parameter as a Java long.
getObject(int) | Get the value of a parameter as a Java object.
getShort(int) | Get the value of a SMALLINT parameter as a Java short.
getString(int) | Get the value of a CHAR, VARCHAR, or LONGVARCHAR parameter as a Java String.
getTime(int) | Get the value of a SQL TIME parameter as a java.sql.Time object.
getTimestamp(int) | Get the value of a SQL TIMESTAMP parameter as a java.sql.Timestamp object.
registerOutParameter(int, int) | Before executing a stored procedure call, you must explicitly call registerOutParameter to register the java.sql.Type of each out parameter.
registerOutParameter(int, int, int) | Use this version of registerOutParameter for registering Numeric or Decimal out parameters.
wasNull() | An OUT parameter may have the value of SQL NULL; wasNull reports whether the last value read has this special value.


 CallableStatement.getBigDecimal

CallableStatement.getBigDecimal

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract BigDecimal getBigDecimal( int parameterIndex, int scale ) throws SQLException
Parameters
parameterIndex
the first parameter is 1, the second is 2, ...
scale
a value greater than or equal to zero representing the desired number of digits to the right of the decimal point
Returns
the parameter value; if the value is SQL NULL, the result is null
Description
Get the value of a NUMERIC parameter as a java.math.BigDecimal object.

Exceptions
SQLException if a database-access error occurs.


 CallableStatement.getBoolean

CallableStatement.getBoolean

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean getBoolean( int parameterIndex ) throws SQLException
Parameters
parameterIndex
the first parameter is 1, the second is 2, ...
Returns
the parameter value; if the value is SQL NULL, the result is false
Description
Get the value of a BIT parameter as a Java boolean.

Exceptions
SQLException if a database-access error occurs.


 CallableStatement.getByte

CallableStatement.getByte

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract byte getByte( int parameterIndex ) throws SQLException
Parameters
parameterIndex
the first parameter is 1, the second is 2, ...
Returns
the parameter value; if the value is SQL NULL, the result is 0
Description
Get the value of a TINYINT parameter as a Java byte.

Exceptions
SQLException if a database-access error occurs.


 CallableStatement.getBytes

CallableStatement.getBytes

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract byte[] getBytes( int parameterIndex ) throws SQLException
Parameters
parameterIndex
the first parameter is 1, the second is 2, ...
Returns
the parameter value; if the value is SQL NULL, the result is null
Description
Get the value of a SQL BINARY or VARBINARY parameter as a Java byte[]

Exceptions
SQLException if a database-access error occurs.


 CallableStatement.getDate

CallableStatement.getDate

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Date getDate( int parameterIndex ) throws SQLException
Parameters
parameterIndex
the first parameter is 1, the second is 2, ...
Returns
the parameter value; if the value is SQL NULL, the result is null
Description
Get the value of a SQL DATE parameter as a java.sql.Date object

Exceptions
SQLException if a database-access error occurs.


 CallableStatement.getDouble

CallableStatement.getDouble

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract double getDouble( int parameterIndex ) throws SQLException
Parameters
parameterIndex
the first parameter is 1, the second is 2, ...
Returns
the parameter value; if the value is SQL NULL, the result is 0
Description
Get the value of a DOUBLE parameter as a Java double.

Exceptions
SQLException if a database-access error occurs.


 CallableStatement.getFloat

CallableStatement.getFloat

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract float getFloat( int parameterIndex ) throws SQLException
Parameters
parameterIndex
the first parameter is 1, the second is 2, ...
Returns
the parameter value; if the value is SQL NULL, the result is 0
Description
Get the value of a FLOAT parameter as a Java float.

Exceptions
SQLException if a database-access error occurs.


 CallableStatement.getInt

CallableStatement.getInt

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getInt( int parameterIndex ) throws SQLException
Parameters
parameterIndex
the first parameter is 1, the second is 2, ...
Returns
the parameter value; if the value is SQL NULL, the result is 0
Description
Get the value of an INTEGER parameter as a Java int.

Exceptions
SQLException if a database-access error occurs.


 CallableStatement.getLong

CallableStatement.getLong

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract long getLong( int parameterIndex ) throws SQLException
Parameters
parameterIndex
the first parameter is 1, the second is 2, ...
Returns
the parameter value; if the value is SQL NULL, the result is 0
Description
Get the value of a BIGINT parameter as a Java long.

Exceptions
SQLException if a database-access error occurs.


 CallableStatement.getObject

CallableStatement.getObject

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Object getObject( int parameterIndex ) throws SQLException
Parameters
parameterIndex
The first parameter is 1, the second is 2, ...
Returns
A java.lang.Object holding the OUT parameter value.
Description
Get the value of a parameter as a Java object.

This method returns a Java object whose type coresponds to the SQL type that was registered for this parameter using registerOutParameter.

Note that this method may be used to read datatabase-specific, abstract data types. This is done by specifying a targetSqlType of java.sql.types.OTHER, which allows the driver to return a database-specific Java type.

Exceptions
SQLException if a database-access error occurs.
See Also
Types


 CallableStatement.getShort

CallableStatement.getShort

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract short getShort( int parameterIndex ) throws SQLException
Parameters
parameterIndex
the first parameter is 1, the second is 2, ...
Returns
the parameter value; if the value is SQL NULL, the result is 0
Description
Get the value of a SMALLINT parameter as a Java short.

Exceptions
SQLException if a database-access error occurs.


 CallableStatement.getString

CallableStatement.getString

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getString( int parameterIndex ) throws SQLException
Parameters
parameterIndex
the first parameter is 1, the second is 2, ...
Returns
the parameter value; if the value is SQL NULL, the result is null
Description
Get the value of a CHAR, VARCHAR, or LONGVARCHAR parameter as a Java String.

Exceptions
SQLException if a database-access error occurs.


 CallableStatement.getTime

CallableStatement.getTime

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Time getTime( int parameterIndex ) throws SQLException
Parameters
parameterIndex
the first parameter is 1, the second is 2, ...
Returns
the parameter value; if the value is SQL NULL, the result is null
Description
Get the value of a SQL TIME parameter as a java.sql.Time object.

Exceptions
SQLException if a database-access error occurs.


 CallableStatement.getTimestamp

CallableStatement.getTimestamp

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Timestamp getTimestamp( int parameterIndex ) throws SQLException
Parameters
parameterIndex
the first parameter is 1, the second is 2, ...
Returns
the parameter value; if the value is SQL NULL, the result is null
Description
Get the value of a SQL TIMESTAMP parameter as a java.sql.Timestamp object.

Exceptions
SQLException if a database-access error occurs.


 CallableStatement.registerOutParameter

CallableStatement.registerOutParameter

Interface Overview | Interface Members | This Package | All Packages

Syntax 1
public abstract void registerOutParameter( int parameterIndex, int sqlType ) throws SQLException
Parameters
parameterIndex
the first parameter is 1, the second is 2,...
sqlType
SQL type code defined by java.sql.Types; for parameters of type Numeric or Decimal use the version of registerOutParameter that accepts a scale value
Description
Before executing a stored procedure call, you must explicitly call registerOutParameter to register the java.sql.Type of each out parameter.

Note: When reading the value of an out parameter, you must use the getXXX method whose Java type XXX corresponds to the parameter's registered SQL type.

Exceptions
SQLException if a database-access error occurs.
See Also
Type

Syntax 2
public abstract void registerOutParameter( int parameterIndex, int sqlType, int scale ) throws SQLException
Parameters
parameterIndex
the first parameter is 1, the second is 2, ...
sqlType
use either java.sql.Type.NUMERIC or java.sql.Type.DECIMAL
scale
a value greater than or equal to zero representing the desired number of digits to the right of the decimal point
Description
Use this version of registerOutParameter for registering Numeric or Decimal out parameters.

Note: When reading the value of an out parameter, you must use the getXXX method whose Java type XXX corresponds to the parameter's registered SQL type.

Exceptions
SQLException if a database-access error occurs.
See Also
Type


 CallableStatement.wasNull

CallableStatement.wasNull

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean wasNull() throws SQLException
Returns
true if the last parameter read was SQL NULL
Description
An OUT parameter may have the value of SQL NULL; wasNull reports whether the last value read has this special value.

Note: You must first call getXXX on a parameter to read its value and then call wasNull() to see if the value was SQL NULL.

Exceptions
SQLException if a database-access error occurs.


 Interface Connection

Interface java.sql.Connection

Interface Members | This Package | All Packages

public interface Connection

A Connection represents a session with a specific database. Within the context of a Connection, SQL statements are executed and results are returned.

A Connection's database is able to provide information describing its tables, its supported SQL grammar, its stored procedures, the capabilities of this connection, etc. This information is obtained with the getMetaData method.

Note: By default the Connection automatically commits changes after executing each statement. If auto commit has been disabled, an explicit commit must be done or database changes will not be saved.

See Also:
getConnection, Statement, ResultSet, DatabaseMetaData


 Connection Members

Connection Members

Interface Overview | This Package | All Packages

Fields
Name | Description
TRANSACTION_NONE | Transactions are not supported.
TRANSACTION_READ_COMMITTED | Dirty reads are prevented; non-repeatable reads and phantom reads can occur.
TRANSACTION_READ_UNCOMMITTED | Dirty reads, non-repeatable reads and phantom reads can occur.
TRANSACTION_REPEATABLE_READ | Dirty reads and non-repeatable reads are prevented; phantom reads can occur.
TRANSACTION_SERIALIZABLE | Dirty reads, non-repeatable reads and phantom reads are prevented.

Methods
Name | Description
clearWarnings() | After this call, getWarnings returns null until a new warning is reported for this Connection.
close() | In some cases, it is desirable to immediately release a Connection's database and JDBC resources instead of waiting for them to be automatically released; the close method provides this immediate release.
commit() | Commit makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by the Connection.
createStatement() | SQL statements without parameters are normally executed using Statement objects.
getAutoCommit() | Get the current auto-commit state.
getCatalog() | Return the Connection's current catalog name.
getMetaData() | A Connection's database is able to provide information describing its tables, its supported SQL grammar, its stored procedures, the capabilities of this connection, etc.
getTransactionIsolation() | Get this Connection's current transaction isolation mode.
getWarnings() | The first warning reported by calls on this Connection is returned.
isClosed() | Tests to see if a Connection is closed.
isReadOnly() | Tests to see if the connection is in read-only mode.
nativeSQL(String) | A driver may convert the JDBC sql grammar into its system's native SQL grammar prior to sending it; nativeSQL returns the native form of the statement that the driver would have sent.
prepareCall(String) | A SQL stored procedure call statement is handled by creating a CallableStatement for it.
prepareStatement(String) | A SQL statement with or without IN parameters can be pre-compiled and stored in a PreparedStatement object.
rollback() | Rollback drops all changes made since the previous commit/rollback and releases any database locks currently held by the Connection.
setAutoCommit(boolean) | If a connection is in auto-commit mode, then all its SQL statements will be executed and committed as individual transactions.
setCatalog(String) | A sub-space of this Connection's database may be selected by setting a catalog name.
setReadOnly(boolean) | You can put a connection in read-only mode as a hint to enable database optimizations.
setTransactionIsolation(int) | You can call this method to try to change the transaction isolation level using one of the TRANSACTION_* values.


 Connection.TRANSACTION_NONE

Connection.TRANSACTION_NONE

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int TRANSACTION_NONE
Description
Transactions are not supported.


 Connection.TRANSACTION_READ_COMMITTED

Connection.TRANSACTION_READ_COMMITTED

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int TRANSACTION_READ_COMMITTED
Description
Dirty reads are prevented; non-repeatable reads and phantom reads can occur.


 Connection.TRANSACTION_READ_UNCOMMITTED

Connection.TRANSACTION_READ_UNCOMMITTED

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int TRANSACTION_READ_UNCOMMITTED
Description
Dirty reads, non-repeatable reads and phantom reads can occur.


 Connection.TRANSACTION_REPEATABLE_READ

Connection.TRANSACTION_REPEATABLE_READ

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int TRANSACTION_REPEATABLE_READ
Description
Dirty reads and non-repeatable reads are prevented; phantom reads can occur.


 Connection.TRANSACTION_SERIALIZABLE

Connection.TRANSACTION_SERIALIZABLE

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int TRANSACTION_SERIALIZABLE
Description
Dirty reads, non-repeatable reads and phantom reads are prevented.


 Connection.clearWarnings

Connection.clearWarnings

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void clearWarnings() throws SQLException
Description
After this call, getWarnings returns null until a new warning is reported for this Connection.

Exceptions
SQLException if a database-access error occurs.


 Connection.close

Connection.close

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void close() throws SQLException
Description
In some cases, it is desirable to immediately release a Connection's database and JDBC resources instead of waiting for them to be automatically released; the close method provides this immediate release.

Note: A Connection is automatically closed when it is garbage collected. Certain fatal errors also result in a closed Connection.

Exceptions
SQLException if a database-access error occurs.


 Connection.commit

Connection.commit

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void commit() throws SQLException
Description
Commit makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by the Connection. This method should only be used when auto commit has been disabled.

Exceptions
SQLException if a database-access error occurs.
See Also
setAutoCommit


 Connection.createStatement

Connection.createStatement

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Statement createStatement() throws SQLException
Returns
a new Statement object
Description
SQL statements without parameters are normally executed using Statement objects. If the same SQL statement is executed many times, it is more efficient to use a PreparedStatement

Exceptions
SQLException if a database-access error occurs.


 Connection.getAutoCommit

Connection.getAutoCommit

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean getAutoCommit() throws SQLException
Returns
Current state of auto-commit mode.
Description
Get the current auto-commit state.

Exceptions
SQLException if a database-access error occurs.
See Also
setAutoCommit


 Connection.getCatalog

Connection.getCatalog

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getCatalog() throws SQLException
Returns
the current catalog name or null
Description
Return the Connection's current catalog name.

Exceptions
SQLException if a database-access error occurs.


 Connection.getMetaData

Connection.getMetaData

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract DatabaseMetaData getMetaData() throws SQLException
Returns
a DatabaseMetaData object for this Connection
Description
A Connection's database is able to provide information describing its tables, its supported SQL grammar, its stored procedures, the capabilities of this connection, etc. This information is made available through a DatabaseMetaData object.

Exceptions
SQLException if a database-access error occurs.


 Connection.getTransactionIsolation

Connection.getTransactionIsolation

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getTransactionIsolation() throws SQLException
Returns
the current TRANSACTION_* mode value
Description
Get this Connection's current transaction isolation mode.

Exceptions
SQLException if a database-access error occurs.


 Connection.getWarnings

Connection.getWarnings

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract SQLWarning getWarnings() throws SQLException
Returns
the first SQLWarning or null
Description
The first warning reported by calls on this Connection is returned.

Note: Subsequent warnings will be chained to this SQLWarning.

Exceptions
SQLException if a database-access error occurs.


 Connection.isClosed

Connection.isClosed

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean isClosed() throws SQLException
Returns
true if the connection is closed; false if it's still open
Description
Tests to see if a Connection is closed.

Exceptions
SQLException if a database-access error occurs.


 Connection.isReadOnly

Connection.isReadOnly

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean isReadOnly() throws SQLException
Returns
true if connection is read-only
Description
Tests to see if the connection is in read-only mode.

Exceptions
SQLException if a database-access error occurs.


 Connection.nativeSQL

Connection.nativeSQL

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String nativeSQL( String sql ) throws SQLException
Parameters
sql
a SQL statement that may contain one or more '?' parameter placeholders
Returns
the native form of this statement
Description
A driver may convert the JDBC sql grammar into its system's native SQL grammar prior to sending it; nativeSQL returns the native form of the statement that the driver would have sent.

Exceptions
SQLException if a database-access error occurs.


 Connection.prepareCall

Connection.prepareCall

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract CallableStatement prepareCall( String sql ) throws SQLException
Parameters
sql
a SQL statement that may contain one or more '?' parameter placeholders. Typically this statement is a JDBC function call escape string.
Returns
a new CallableStatement object containing the pre-compiled SQL statement
Description
A SQL stored procedure call statement is handled by creating a CallableStatement for it. The CallableStatement provides methods for setting up its IN and OUT parameters, and methods for executing it.

Note: This method is optimized for handling stored procedure call statements. Some drivers may send the call statement to the database when the prepareCall is done; others may wait until the CallableStatement is executed. This has no direct affect on users; however, it does affect which method throws certain SQLExceptions.

Exceptions
SQLException if a database-access error occurs.


 Connection.prepareStatement

Connection.prepareStatement

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract PreparedStatement prepareStatement( String sql ) throws SQLException
Parameters
sql
a SQL statement that may contain one or more '?' IN parameter placeholders
Returns
a new PreparedStatement object containing the pre-compiled statement
Description
A SQL statement with or without IN parameters can be pre-compiled and stored in a PreparedStatement object. This object can then be used to efficiently execute this statement multiple times.

Note: This method is optimized for handling parametric SQL statements that benefit from precompilation. If the driver supports precompilation, prepareStatement will send the statement to the database for precompilation. Some drivers may not support precompilation. In this case, the statement may not be sent to the database until the PreparedStatement is executed. This has no direct affect on users; however, it does affect which method throws certain SQLExceptions.

Exceptions
SQLException if a database-access error occurs.


 Connection.rollback

Connection.rollback

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void rollback() throws SQLException
Description
Rollback drops all changes made since the previous commit/rollback and releases any database locks currently held by the Connection. This method should only be used when auto commit has been disabled.

Exceptions
SQLException if a database-access error occurs.
See Also
setAutoCommit


 Connection.setAutoCommit

Connection.setAutoCommit

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setAutoCommit( boolean autoCommit ) throws SQLException
Parameters
autoCommit
true enables auto-commit; false disables auto-commit.
Description
If a connection is in auto-commit mode, then all its SQL statements will be executed and committed as individual transactions. Otherwise, its SQL statements are grouped into transactions that are terminated by either commit() or rollback(). By default, new connections are in auto-commit mode. The commit occurs when the statement completes or the next execute occurs, whichever comes first. In the case of statements returning a ResultSet, the statement completes when the last row of the ResultSet has been retrieved or the ResultSet has been closed. In advanced cases, a single statement may return multiple results as well as output parameter values. Here the commit occurs when all results and output param values have been retrieved.

Exceptions
SQLException if a database-access error occurs.


 Connection.setCatalog

Connection.setCatalog

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setCatalog( String catalog ) throws SQLException
Description
A sub-space of this Connection's database may be selected by setting a catalog name. If the driver does not support catalogs it will silently ignore this request.

Exceptions
SQLException if a database-access error occurs.


 Connection.setReadOnly

Connection.setReadOnly

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setReadOnly( boolean readOnly ) throws SQLException
Parameters
readOnly
true enables read-only mode; false disables read-only mode.
Description
You can put a connection in read-only mode as a hint to enable database optimizations.

Note: setReadOnly cannot be called while in the middle of a transaction.

Exceptions
SQLException if a database-access error occurs.


 Connection.setTransactionIsolation

Connection.setTransactionIsolation

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setTransactionIsolation( int level ) throws SQLException
Parameters
level
one of the TRANSACTION_* isolation values with the exception of TRANSACTION_NONE; some databases may not support other values
Description
You can call this method to try to change the transaction isolation level using one of the TRANSACTION_* values.

Note: setTransactionIsolation cannot be called while in the middle of a transaction.

Exceptions
SQLException if a database-access error occurs.
See Also
supportsTransactionIsolationLevel


 Class DataTruncation

Class java.sql.DataTruncation

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.sql.SQLException
                           |
                           +----java.sql.SQLWarning
                                   |
                                   +----java.sql.DataTruncation

public class DataTruncation
extends SQLWarning

When JDBC unexpectedly truncates a data value, it reports a DataTruncation warning (on reads) or throws a DataTruncation exception (on writes).

The SQLstate for a DataTruncation is "01004".


 DataTruncation Members

DataTruncation Members

Class Overview | This Package | All Packages

Constructors
Name | Description
DataTruncation(int, boolean, boolean, int, int) | Create a DataTruncation object.

Methods
Name | Description
getDataSize() | Get the number of bytes of data that should have been transferred.
getIndex() | Get the index of the column or parameter that was truncated.
getParameter() | Is this a truncated parameter value?
getRead() | Was this a read truncation?
getTransferSize() | Get the number of bytes of data actually transferred.


 DataTruncation.DataTruncation

DataTruncation.DataTruncation

Class Overview | Class Members | This Package | All Packages

Syntax
public DataTruncation( int index, boolean parameter, boolean read, int dataSize, int transferSize )
Parameters
index
The index of the parameter or column value
parameter
true if a parameter value was truncated
read
true if a read was truncated
dataSize
the original size of the data
transferSize
the size after truncation
Description

Create a DataTruncation object. The SQLState is initialized to 01004, the reason is set to "Data truncation" and the vendorCode is set to the SQLException default.


 DataTruncation.getDataSize

DataTruncation.getDataSize

Class Overview | Class Members | This Package | All Packages

Syntax
public int getDataSize()
Returns
the number of bytes of data that should have been transferred
Description
Get the number of bytes of data that should have been transferred. This number may be approximate if data conversions were being performed. The value may be "-1" if the size is unknown.


 DataTruncation.getIndex

DataTruncation.getIndex

Class Overview | Class Members | This Package | All Packages

Syntax
public int getIndex()
Returns
the index of the truncated paramter or column value.
Description
Get the index of the column or parameter that was truncated.

This may be -1 if the column or parameter index is unknown, in which case the "parameter" and "read" fields should be ignored.


 DataTruncation.getParameter

DataTruncation.getParameter

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean getParameter()
Returns
True if the value was a parameter; false if it was a column value.
Description
Is this a truncated parameter value?


 DataTruncation.getRead

DataTruncation.getRead

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean getRead()
Returns
True if the value was truncated when read from the database; false if the data was truncated on a write.
Description
Was this a read truncation?


 DataTruncation.getTransferSize

DataTruncation.getTransferSize

Class Overview | Class Members | This Package | All Packages

Syntax
public int getTransferSize()
Returns
the number of bytes of data actually transferred
Description
Get the number of bytes of data actually transferred. The value may be "-1" if the size is unknown.


 Interface DatabaseMetaData

Interface java.sql.DatabaseMetaData

Interface Members | This Package | All Packages

public interface DatabaseMetaData

This class provides information about the database as a whole.

Many of the methods here return lists of information in ResultSets. You can use the normal ResultSet methods such as getString and getInt to retrieve the data from these ResultSets. If a given form of metadata is not available, these methods should throw a SQLException.

Some of these methods take arguments that are String patterns. These arguments all have names such as fooPattern. Within a pattern String, "%" means match any substring of 0 or more characters, and "_" means match any one character. Only metadata entries matching the search pattern are returned. If a search pattern argument is set to a null ref, it means that argument's criteria should be dropped from the search.

A SQLException will be thrown if a driver does not support a meta data method. In the case of methods that return a ResultSet, either a ResultSet (which may be empty) is returned or a SQLException is thrown.


 DatabaseMetaData Members

DatabaseMetaData Members

Interface Overview | This Package | All Packages

Fields
Name | Description
bestRowNotPseudo | BEST ROW PSEUDO_COLUMN - is NOT a pseudo column.
bestRowPseudo | BEST ROW PSEUDO_COLUMN - is a pseudo column.
bestRowSession | BEST ROW SCOPE - valid for remainder of current session.
bestRowTemporary | BEST ROW SCOPE - very temporary, while using row.
bestRowTransaction | BEST ROW SCOPE - valid for remainder of current transaction.
bestRowUnknown | BEST ROW PSEUDO_COLUMN - may or may not be pseudo column.
columnNoNulls | COLUMN NULLABLE - might not allow NULL values.
columnNullable | COLUMN NULLABLE - definitely allows NULL values.
columnNullableUnknown | COLUMN NULLABLE - nullability unknown.
importedKeyCascade | IMPORT KEY UPDATE_RULE and DELETE_RULE - for update, change imported key to agree with primary key update; for delete, delete rows that import a deleted key.
importedKeyInitiallyDeferred | IMPORT KEY DEFERRABILITY - see SQL92 for definition
importedKeyInitiallyImmediate | IMPORT KEY DEFERRABILITY - see SQL92 for definition
importedKeyNoAction | IMPORT KEY UPDATE_RULE and DELETE_RULE - do not allow update or delete of primary key if it has been imported.
importedKeyNotDeferrable | IMPORT KEY DEFERRABILITY - see SQL92 for definition
importedKeyRestrict | IMPORT KEY UPDATE_RULE and DELETE_RULE - do not allow update or delete of primary key if it has been imported.
importedKeySetDefault | IMPORT KEY UPDATE_RULE and DELETE_RULE - change imported key to default values if its primary key has been updated or deleted.
importedKeySetNull | IMPORT KEY UPDATE_RULE and DELETE_RULE - change imported key to NULL if its primary key has been updated or deleted.
procedureColumnIn | COLUMN_TYPE - IN parameter.
procedureColumnInOut | COLUMN_TYPE - INOUT parameter.
procedureColumnOut | COLUMN_TYPE - OUT parameter.
procedureColumnResult | COLUMN_TYPE - result column in ResultSet.
procedureColumnReturn | COLUMN_TYPE - procedure return value.
procedureColumnUnknown | COLUMN_TYPE - nobody knows.
procedureNoNulls | TYPE NULLABLE - does not allow NULL values.
procedureNoResult | PROCEDURE_TYPE - Does not return a result.
procedureNullable | TYPE NULLABLE - allows NULL values.
procedureNullableUnknown | TYPE NULLABLE - nullability unknown.
procedureResultUnknown | PROCEDURE_TYPE - May return a result.
procedureReturnsResult | PROCEDURE_TYPE - Returns a result.
tableIndexClustered | INDEX INFO TYPE - this identifies a clustered index
tableIndexHashed | INDEX INFO TYPE - this identifies a hashed index
tableIndexOther | INDEX INFO TYPE - this identifies some other form of index
tableIndexStatistic | INDEX INFO TYPE - this identifies table statistics that are returned in conjuction with a table's index descriptions
typeNoNulls | TYPE NULLABLE - does not allow NULL values.
typeNullable | TYPE NULLABLE - allows NULL values.
typeNullableUnknown | TYPE NULLABLE - nullability unknown.
typePredBasic | TYPE INFO SEARCHABLE - Supported except for WHERE ..
typePredChar | TYPE INFO SEARCHABLE - Only supported with WHERE ..
typePredNone | TYPE INFO SEARCHABLE - No support.
typeSearchable | TYPE INFO SEARCHABLE - Supported for all WHERE ...
versionColumnNotPseudo | VERSION COLUMNS PSEUDO_COLUMN - is NOT a pseudo column.
versionColumnPseudo | VERSION COLUMNS PSEUDO_COLUMN - is a pseudo column.
versionColumnUnknown | VERSION COLUMNS PSEUDO_COLUMN - may or may not be pseudo column.

Methods
Name | Description
allProceduresAreCallable() | Can all the procedures returned by getProcedures be called by the current user?
allTablesAreSelectable() | Can all the tables returned by getTable be SELECTed by the current user?
dataDefinitionCausesTransactionCommit() | Does a data definition statement within a transaction force the transaction to commit?
dataDefinitionIgnoredInTransactions() | Is a data definition statement within a transaction ignored?
doesMaxRowSizeIncludeBlobs() | Did getMaxRowSize() include LONGVARCHAR and LONGVARBINARY blobs?
getBestRowIdentifier(String, String, String, int, boolean) | Get a description of a table's optimal set of columns that uniquely identifies a row.
getCatalogs() | Get the catalog names available in this database.
getCatalogSeparator() | What's the separator between catalog and table name?
getCatalogTerm() | What's the database vendor's preferred term for "catalog"?
getColumnPrivileges(String, String, String, String) | Get a description of the access rights for a table's columns.
getColumns(String, String, String, String) | Get a description of table columns available in a catalog.
getCrossReference(String, String, String, String, String, String) | Get a description of the foreign key columns in the foreign key table that reference the primary key columns of the primary key table (describe how one table imports another's key.) This should normally return a single foreign key/primary key pair (most tables only import a foreign key from a table once.) They are ordered by FKTABLE_CAT, FKTABLE_SCHEM, FKTABLE_NAME, and KEY_SEQ.
getDatabaseProductName() | What's the name of this database product?
getDatabaseProductVersion() | What's the version of this database product?
getDefaultTransactionIsolation() | What's the database's default transaction isolation level? The values are defined in java.sql.Connection.
getDriverMajorVersion() | What's this JDBC driver's major version number?
getDriverMinorVersion() | What's this JDBC driver's minor version number?
getDriverName() | What's the name of this JDBC driver?
getDriverVersion() | What's the version of this JDBC driver?
getExportedKeys(String, String, String) | Get a description of the foreign key columns that reference a table's primary key columns (the foreign keys exported by a table).
getExtraNameCharacters() | Get all the "extra" characters that can be used in unquoted identifier names (those beyond a-z, A-Z, 0-9 and _).
getIdentifierQuoteString() | What's the string used to quote SQL identifiers? This returns a space " " if identifier quoting isn't supported.
getImportedKeys(String, String, String) | Get a description of the primary key columns that are referenced by a table's foreign key columns (the primary keys imported by a table).
getIndexInfo(String, String, String, boolean, boolean) | Get a description of a table's indices and statistics.
getMaxBinaryLiteralLength() | How many hex characters can you have in an inline binary literal?
getMaxCatalogNameLength() | What's the maximum length of a catalog name?
getMaxCharLiteralLength() | What's the max length for a character literal?
getMaxColumnNameLength() | What's the limit on column name length?
getMaxColumnsInGroupBy() | What's the maximum number of columns in a "GROUP BY" clause?
getMaxColumnsInIndex() | What's the maximum number of columns allowed in an index?
getMaxColumnsInOrderBy() | What's the maximum number of columns in an "ORDER BY" clause?
getMaxColumnsInSelect() | What's the maximum number of columns in a "SELECT" list?
getMaxColumnsInTable() | What's the maximum number of columns in a table?
getMaxConnections() | How many active connections can we have at a time to this database?
getMaxCursorNameLength() | What's the maximum cursor name length?
getMaxIndexLength() | What's the maximum length of an index (in bytes)?
getMaxProcedureNameLength() | What's the maximum length of a procedure name?
getMaxRowSize() | What's the maximum length of a single row?
getMaxSchemaNameLength() | What's the maximum length allowed for a schema name?
getMaxStatementLength() | What's the maximum length of a SQL statement?
getMaxStatements() | How many active statements can we have open at one time to this database?
getMaxTableNameLength() | What's the maximum length of a table name?
getMaxTablesInSelect() | What's the maximum number of tables in a SELECT?
getMaxUserNameLength() | What's the maximum length of a user name?
getNumericFunctions() | Get a comma separated list of math functions.
getPrimaryKeys(String, String, String) | Get a description of a table's primary key columns.
getProcedureColumns(String, String, String, String) | Get a description of a catalog's stored procedure parameters and result columns.
getProcedures(String, String, String) | Get a description of stored procedures available in a catalog.
getProcedureTerm() | What's the database vendor's preferred term for "procedure"?
getSchemas() | Get the schema names available in this database.
getSchemaTerm() | What's the database vendor's preferred term for "schema"?
getSearchStringEscape() | This is the string that can be used to escape '_' or '%' in the string pattern style catalog search parameters.
getSQLKeywords() | Get a comma separated list of all a database's SQL keywords that are NOT also SQL92 keywords.
getStringFunctions() | Get a comma separated list of string functions.
getSystemFunctions() | Get a comma separated list of system functions.
getTablePrivileges(String, String, String) | Get a description of the access rights for each table available in a catalog.
getTables(String, String, String, String[]) | Get a description of tables available in a catalog.
getTableTypes() | Get the table types available in this database.
getTimeDateFunctions() | Get a comma separated list of time and date functions.
getTypeInfo() | Get a description of all the standard SQL types supported by this database.
getURL() | What's the url for this database?
getUserName() | What's our user name as known to the database?
getVersionColumns(String, String, String) | Get a description of a table's columns that are automatically updated when any value in a row is updated.
isCatalogAtStart() | Does a catalog appear at the start of a qualified table name? (Otherwise it appears at the end)
isReadOnly() | Is the database in read-only mode?
nullPlusNonNullIsNull() | Are concatenations between NULL and non-NULL values NULL? A JDBC-Compliant driver always returns true.
nullsAreSortedAtEnd() | Are NULL values sorted at the end regardless of sort order?
nullsAreSortedAtStart() | Are NULL values sorted at the start regardless of sort order?
nullsAreSortedHigh() | Are NULL values sorted high?
nullsAreSortedLow() | Are NULL values sorted low?
storesLowerCaseIdentifiers() | Does the database treat mixed case unquoted SQL identifiers as case insensitive and store them in lower case?
storesLowerCaseQuotedIdentifiers() | Does the database treat mixed case quoted SQL identifiers as case insensitive and store them in lower case?
storesMixedCaseIdentifiers() | Does the database treat mixed case unquoted SQL identifiers as case insensitive and store them in mixed case?
storesMixedCaseQuotedIdentifiers() | Does the database treat mixed case quoted SQL identifiers as case insensitive and store them in mixed case?
storesUpperCaseIdentifiers() | Does the database treat mixed case unquoted SQL identifiers as case insensitive and store them in upper case?
storesUpperCaseQuotedIdentifiers() | Does the database treat mixed case quoted SQL identifiers as case insensitive and store them in upper case?
supportsAlterTableWithAddColumn() | Is "ALTER TABLE" with add column supported?
supportsAlterTableWithDropColumn() | Is "ALTER TABLE" with drop column supported?
supportsANSI92EntryLevelSQL() | Is the ANSI92 entry level SQL grammar supported? All JDBC-Compliant drivers must return true.
supportsANSI92FullSQL() | Is the ANSI92 full SQL grammar supported?
supportsANSI92IntermediateSQL() | Is the ANSI92 intermediate SQL grammar supported?
supportsCatalogsInDataManipulation() | Can a catalog name be used in a data manipulation statement?
supportsCatalogsInIndexDefinitions() | Can a catalog name be used in an index definition statement?
supportsCatalogsInPrivilegeDefinitions() | Can a catalog name be used in a privilege definition statement?
supportsCatalogsInProcedureCalls() | Can a catalog name be used in a procedure call statement?
supportsCatalogsInTableDefinitions() | Can a catalog name be used in a table definition statement?
supportsColumnAliasing() | Is column aliasing supported? If so, the SQL AS clause can be used to provide names for computed columns or to provide alias names for columns as required.
supportsConvert() | Is the CONVERT function between SQL types supported?
supportsConvert(int, int) | Is CONVERT between the given SQL types supported?
supportsCoreSQLGrammar() | Is the ODBC Core SQL grammar supported?
supportsCorrelatedSubqueries() | Are correlated subqueries supported? A JDBC-Compliant driver always returns true.
supportsDataDefinitionAndDataManipulationTransactions() | Are both data definition and data manipulation statements within a transaction supported?
supportsDataManipulationTransactionsOnly() | Are only data manipulation statements within a transaction supported?
supportsDifferentTableCorrelationNames() | If table correlation names are supported, are they restricted to be different from the names of the tables?
supportsExpressionsInOrderBy() | Are expressions in "ORDER BY" lists supported?
supportsExtendedSQLGrammar() | Is the ODBC Extended SQL grammar supported?
supportsFullOuterJoins() | Are full nested outer joins supported?
supportsGroupBy() | Is some form of "GROUP BY" clause supported?
supportsGroupByBeyondSelect() | Can a "GROUP BY" clause add columns not in the SELECT provided it specifies all the columns in the SELECT?
supportsGroupByUnrelated() | Can a "GROUP BY" clause use columns not in the SELECT?
supportsIntegrityEnhancementFacility() | Is the SQL Integrity Enhancement Facility supported?
supportsLikeEscapeClause() | Is the escape character in "LIKE" clauses supported? A JDBC-Compliant driver always returns true.
supportsLimitedOuterJoins() | Is there limited support for outer joins? (This will be true if supportFullOuterJoins is true.)
supportsMinimumSQLGrammar() | Is the ODBC Minimum SQL grammar supported? All JDBC-Compliant drivers must return true.
supportsMixedCaseIdentifiers() | Does the database treat mixed case unquoted SQL identifiers as case sensitive and as a result store them in mixed case? A JDBC-Compliant driver will always return false.
supportsMixedCaseQuotedIdentifiers() | Does the database treat mixed case quoted SQL identifiers as case sensitive and as a result store them in mixed case? A JDBC-Compliant driver will always return true.
supportsMultipleResultSets() | Are multiple ResultSets from a single execute supported?
supportsMultipleTransactions() | Can we have multiple transactions open at once (on different connections)?
supportsNonNullableColumns() | Can columns be defined as non-nullable? A JDBC-Compliant driver always returns true.
supportsOpenCursorsAcrossCommit() | Can cursors remain open across commits?
supportsOpenCursorsAcrossRollback() | Can cursors remain open across rollbacks?
supportsOpenStatementsAcrossCommit() | Can statements remain open across commits?
supportsOpenStatementsAcrossRollback() | Can statements remain open across rollbacks?
supportsOrderByUnrelated() | Can an "ORDER BY" clause use columns not in the SELECT?
supportsOuterJoins() | Is some form of outer join supported?
supportsPositionedDelete() | Is positioned DELETE supported?
supportsPositionedUpdate() | Is positioned UPDATE supported?
supportsSchemasInDataManipulation() | Can a schema name be used in a data manipulation statement?
supportsSchemasInIndexDefinitions() | Can a schema name be used in an index definition statement?
supportsSchemasInPrivilegeDefinitions() | Can a schema name be used in a privilege definition statement?
supportsSchemasInProcedureCalls() | Can a schema name be used in a procedure call statement?
supportsSchemasInTableDefinitions() | Can a schema name be used in a table definition statement?
supportsSelectForUpdate() | Is SELECT for UPDATE supported?
supportsStoredProcedures() | Are stored procedure calls using the stored procedure escape syntax supported?
supportsSubqueriesInComparisons() | Are subqueries in comparison expressions supported? A JDBC-Compliant driver always returns true.
supportsSubqueriesInExists() | Are subqueries in 'exists' expressions supported? A JDBC-Compliant driver always returns true.
supportsSubqueriesInIns() | Are subqueries in 'in' statements supported? A JDBC-Compliant driver always returns true.
supportsSubqueriesInQuantifieds() | Are subqueries in quantified expressions supported? A JDBC-Compliant driver always returns true.
supportsTableCorrelationNames() | Are table correlation names supported? A JDBC-Compliant driver always returns true.
supportsTransactionIsolationLevel(int) | Does the database support the given transaction isolation level?
supportsTransactions() | Are transactions supported? If not, commit is a noop and the isolation level is TRANSACTION_NONE.
supportsUnion() | Is SQL UNION supported?
supportsUnionAll() | Is SQL UNION ALL supported?
usesLocalFilePerTable() | Does the database use a file for each table?
usesLocalFiles() | Does the database store tables in a local file?


 DatabaseMetaData.bestRowNotPseudo

DatabaseMetaData.bestRowNotPseudo

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int bestRowNotPseudo
Description
BEST ROW PSEUDO_COLUMN - is NOT a pseudo column.


 DatabaseMetaData.bestRowPseudo

DatabaseMetaData.bestRowPseudo

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int bestRowPseudo
Description
BEST ROW PSEUDO_COLUMN - is a pseudo column.


 DatabaseMetaData.bestRowSession

DatabaseMetaData.bestRowSession

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int bestRowSession
Description
BEST ROW SCOPE - valid for remainder of current session.


 DatabaseMetaData.bestRowTemporary

DatabaseMetaData.bestRowTemporary

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int bestRowTemporary
Description
BEST ROW SCOPE - very temporary, while using row.


 DatabaseMetaData.bestRowTransaction

DatabaseMetaData.bestRowTransaction

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int bestRowTransaction
Description
BEST ROW SCOPE - valid for remainder of current transaction.


 DatabaseMetaData.bestRowUnknown

DatabaseMetaData.bestRowUnknown

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int bestRowUnknown
Description
BEST ROW PSEUDO_COLUMN - may or may not be pseudo column.


 DatabaseMetaData.columnNoNulls

DatabaseMetaData.columnNoNulls

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int columnNoNulls
Description
COLUMN NULLABLE - might not allow NULL values.


 DatabaseMetaData.columnNullable

DatabaseMetaData.columnNullable

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int columnNullable
Description
COLUMN NULLABLE - definitely allows NULL values.


 DatabaseMetaData.columnNullableUnknown

DatabaseMetaData.columnNullableUnknown

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int columnNullableUnknown
Description
COLUMN NULLABLE - nullability unknown.


 DatabaseMetaData.importedKeyCascade

DatabaseMetaData.importedKeyCascade

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int importedKeyCascade
Description
IMPORT KEY UPDATE_RULE and DELETE_RULE - for update, change imported key to agree with primary key update; for delete, delete rows that import a deleted key.


 DatabaseMetaData.importedKeyInitiallyDeferred

DatabaseMetaData.importedKeyInitiallyDeferred

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int importedKeyInitiallyDeferred
Description
IMPORT KEY DEFERRABILITY - see SQL92 for definition


 DatabaseMetaData.importedKeyInitiallyImmediate

DatabaseMetaData.importedKeyInitiallyImmediate

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int importedKeyInitiallyImmediate
Description
IMPORT KEY DEFERRABILITY - see SQL92 for definition


 DatabaseMetaData.importedKeyNoAction

DatabaseMetaData.importedKeyNoAction

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int importedKeyNoAction
Description
IMPORT KEY UPDATE_RULE and DELETE_RULE - do not allow update or delete of primary key if it has been imported.


 DatabaseMetaData.importedKeyNotDeferrable

DatabaseMetaData.importedKeyNotDeferrable

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int importedKeyNotDeferrable
Description
IMPORT KEY DEFERRABILITY - see SQL92 for definition


 DatabaseMetaData.importedKeyRestrict

DatabaseMetaData.importedKeyRestrict

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int importedKeyRestrict
Description
IMPORT KEY UPDATE_RULE and DELETE_RULE - do not allow update or delete of primary key if it has been imported.


 DatabaseMetaData.importedKeySetDefault

DatabaseMetaData.importedKeySetDefault

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int importedKeySetDefault
Description
IMPORT KEY UPDATE_RULE and DELETE_RULE - change imported key to default values if its primary key has been updated or deleted.


 DatabaseMetaData.importedKeySetNull

DatabaseMetaData.importedKeySetNull

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int importedKeySetNull
Description
IMPORT KEY UPDATE_RULE and DELETE_RULE - change imported key to NULL if its primary key has been updated or deleted.


 DatabaseMetaData.procedureColumnIn

DatabaseMetaData.procedureColumnIn

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int procedureColumnIn
Description
COLUMN_TYPE - IN parameter.


 DatabaseMetaData.procedureColumnInOut

DatabaseMetaData.procedureColumnInOut

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int procedureColumnInOut
Description
COLUMN_TYPE - INOUT parameter.


 DatabaseMetaData.procedureColumnOut

DatabaseMetaData.procedureColumnOut

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int procedureColumnOut
Description
COLUMN_TYPE - OUT parameter.


 DatabaseMetaData.procedureColumnResult

DatabaseMetaData.procedureColumnResult

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int procedureColumnResult
Description
COLUMN_TYPE - result column in ResultSet.


 DatabaseMetaData.procedureColumnReturn

DatabaseMetaData.procedureColumnReturn

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int procedureColumnReturn
Description
COLUMN_TYPE - procedure return value.


 DatabaseMetaData.procedureColumnUnknown

DatabaseMetaData.procedureColumnUnknown

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int procedureColumnUnknown
Description
COLUMN_TYPE - nobody knows.


 DatabaseMetaData.procedureNoNulls

DatabaseMetaData.procedureNoNulls

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int procedureNoNulls
Description
TYPE NULLABLE - does not allow NULL values.


 DatabaseMetaData.procedureNoResult

DatabaseMetaData.procedureNoResult

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int procedureNoResult
Description
PROCEDURE_TYPE - Does not return a result.


 DatabaseMetaData.procedureNullable

DatabaseMetaData.procedureNullable

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int procedureNullable
Description
TYPE NULLABLE - allows NULL values.


 DatabaseMetaData.procedureNullableUnknown

DatabaseMetaData.procedureNullableUnknown

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int procedureNullableUnknown
Description
TYPE NULLABLE - nullability unknown.


 DatabaseMetaData.procedureResultUnknown

DatabaseMetaData.procedureResultUnknown

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int procedureResultUnknown
Description
PROCEDURE_TYPE - May return a result.


 DatabaseMetaData.procedureReturnsResult

DatabaseMetaData.procedureReturnsResult

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int procedureReturnsResult
Description
PROCEDURE_TYPE - Returns a result.


 DatabaseMetaData.tableIndexClustered

DatabaseMetaData.tableIndexClustered

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final short tableIndexClustered
Description
INDEX INFO TYPE - this identifies a clustered index


 DatabaseMetaData.tableIndexHashed

DatabaseMetaData.tableIndexHashed

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final short tableIndexHashed
Description
INDEX INFO TYPE - this identifies a hashed index


 DatabaseMetaData.tableIndexOther

DatabaseMetaData.tableIndexOther

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final short tableIndexOther
Description
INDEX INFO TYPE - this identifies some other form of index


 DatabaseMetaData.tableIndexStatistic

DatabaseMetaData.tableIndexStatistic

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final short tableIndexStatistic
Description
INDEX INFO TYPE - this identifies table statistics that are returned in conjuction with a table's index descriptions


 DatabaseMetaData.typeNoNulls

DatabaseMetaData.typeNoNulls

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int typeNoNulls
Description
TYPE NULLABLE - does not allow NULL values.


 DatabaseMetaData.typeNullable

DatabaseMetaData.typeNullable

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int typeNullable
Description
TYPE NULLABLE - allows NULL values.


 DatabaseMetaData.typeNullableUnknown

DatabaseMetaData.typeNullableUnknown

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int typeNullableUnknown
Description
TYPE NULLABLE - nullability unknown.


 DatabaseMetaData.typePredBasic

DatabaseMetaData.typePredBasic

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int typePredBasic
Description
TYPE INFO SEARCHABLE - Supported except for WHERE .. LIKE.


 DatabaseMetaData.typePredChar

DatabaseMetaData.typePredChar

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int typePredChar
Description
TYPE INFO SEARCHABLE - Only supported with WHERE .. LIKE.


 DatabaseMetaData.typePredNone

DatabaseMetaData.typePredNone

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int typePredNone
Description
TYPE INFO SEARCHABLE - No support.


 DatabaseMetaData.typeSearchable

DatabaseMetaData.typeSearchable

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int typeSearchable
Description
TYPE INFO SEARCHABLE - Supported for all WHERE ...


 DatabaseMetaData.versionColumnNotPseudo

DatabaseMetaData.versionColumnNotPseudo

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int versionColumnNotPseudo
Description
VERSION COLUMNS PSEUDO_COLUMN - is NOT a pseudo column.


 DatabaseMetaData.versionColumnPseudo

DatabaseMetaData.versionColumnPseudo

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int versionColumnPseudo
Description
VERSION COLUMNS PSEUDO_COLUMN - is a pseudo column.


 DatabaseMetaData.versionColumnUnknown

DatabaseMetaData.versionColumnUnknown

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int versionColumnUnknown
Description
VERSION COLUMNS PSEUDO_COLUMN - may or may not be pseudo column.


 DatabaseMetaData.allProceduresAreCallable

DatabaseMetaData.allProceduresAreCallable

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean allProceduresAreCallable() throws SQLException
Returns
true if so
Description
Can all the procedures returned by getProcedures be called by the current user?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.allTablesAreSelectable

DatabaseMetaData.allTablesAreSelectable

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean allTablesAreSelectable() throws SQLException
Returns
true if so
Description
Can all the tables returned by getTable be SELECTed by the current user?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.dataDefinitionCausesTransactionCommit

DatabaseMetaData.dataDefinitionCausesTransactionCommit

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean dataDefinitionCausesTransactionCommit() throws SQLException
Returns
true if so
Description
Does a data definition statement within a transaction force the transaction to commit?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.dataDefinitionIgnoredInTransactions

DatabaseMetaData.dataDefinitionIgnoredInTransactions

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean dataDefinitionIgnoredInTransactions() throws SQLException
Returns
true if so
Description
Is a data definition statement within a transaction ignored?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.doesMaxRowSizeIncludeBlobs

DatabaseMetaData.doesMaxRowSizeIncludeBlobs

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean doesMaxRowSizeIncludeBlobs() throws SQLException
Returns
true if so
Description
Did getMaxRowSize() include LONGVARCHAR and LONGVARBINARY blobs?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getBestRowIdentifier

DatabaseMetaData.getBestRowIdentifier

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract ResultSet getBestRowIdentifier( String catalog, String schema, String table, int scope, boolean nullable ) throws SQLException
Parameters
catalog
a catalog name; "" retrieves those without a catalog; null means drop catalog name from the selection criteria
schema
a schema name; "" retrieves those without a schema
table
a table name
scope
the scope of interest; use same values as SCOPE
nullable
include columns that are nullable?
Returns
ResultSet - each row is a column description
Description
Get a description of a table's optimal set of columns that uniquely identifies a row. They are ordered by SCOPE.

Each column description has the following columns:

  1. SCOPE short => actual scope of result
    • bestRowTemporary - very temporary, while using row
    • bestRowTransaction - valid for remainder of current transaction
    • bestRowSession - valid for remainder of current session
  2. COLUMN_NAME String => column name
  3. DATA_TYPE short => SQL data type from java.sql.Types
  4. TYPE_NAME String => Data source dependent type name
  5. COLUMN_SIZE int => precision
  6. BUFFER_LENGTH int => not used
  7. DECIMAL_DIGITS short => scale
  8. PSEUDO_COLUMN short => is this a pseudo column like an Oracle ROWID
    • bestRowUnknown - may or may not be pseudo column
    • bestRowNotPseudo - is NOT a pseudo column
    • bestRowPseudo - is a pseudo column

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getCatalogs

DatabaseMetaData.getCatalogs

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract ResultSet getCatalogs() throws SQLException
Returns
ResultSet - each row has a single String column that is a catalog name
Description
Get the catalog names available in this database. The results are ordered by catalog name.

The catalog column is:

  1. TABLE_CAT String => catalog name

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getCatalogSeparator

DatabaseMetaData.getCatalogSeparator

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getCatalogSeparator() throws SQLException
Returns
the separator string
Description
What's the separator between catalog and table name?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getCatalogTerm

DatabaseMetaData.getCatalogTerm

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getCatalogTerm() throws SQLException
Returns
the vendor term
Description
What's the database vendor's preferred term for "catalog"?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getColumnPrivileges

DatabaseMetaData.getColumnPrivileges

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract ResultSet getColumnPrivileges( String catalog, String schema, String table, String columnNamePattern ) throws SQLException
Parameters
catalog
a catalog name; "" retrieves those without a catalog; null means drop catalog name from the selection criteria
schema
a schema name; "" retrieves those without a schema
table
a table name
columnNamePattern
a column name pattern
Returns
ResultSet - each row is a column privilege description
Description
Get a description of the access rights for a table's columns.

Only privileges matching the column name criteria are returned. They are ordered by COLUMN_NAME and PRIVILEGE.

Each privilige description has the following columns:

  1. TABLE_CAT String => table catalog (may be null)
  2. TABLE_SCHEM String => table schema (may be null)
  3. TABLE_NAME String => table name
  4. COLUMN_NAME String => column name
  5. GRANTOR => grantor of access (may be null)
  6. GRANTEE String => grantee of access
  7. PRIVILEGE String => name of access (SELECT, INSERT, UPDATE, REFRENCES, ...)
  8. IS_GRANTABLE String => "YES" if grantee is permitted to grant to others; "NO" if not; null if unknown

Exceptions
SQLException if a database-access error occurs.
See Also
getSearchStringEscape


 DatabaseMetaData.getColumns

DatabaseMetaData.getColumns

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract ResultSet getColumns( String catalog, String schemaPattern, String tableNamePattern, String columnNamePattern ) throws SQLException
Parameters
catalog
a catalog name; "" retrieves those without a catalog; null means drop catalog name from the selection criteria
schemaPattern
a schema name pattern; "" retrieves those without a schema
tableNamePattern
a table name pattern
columnNamePattern
a column name pattern
Returns
ResultSet - each row is a column description
Description
Get a description of table columns available in a catalog.

Only column descriptions matching the catalog, schema, table and column name criteria are returned. They are ordered by TABLE_SCHEM, TABLE_NAME and ORDINAL_POSITION.

Each column description has the following columns:

  1. TABLE_CAT String => table catalog (may be null)
  2. TABLE_SCHEM String => table schema (may be null)
  3. TABLE_NAME String => table name
  4. COLUMN_NAME String => column name
  5. DATA_TYPE short => SQL type from java.sql.Types
  6. TYPE_NAME String => Data source dependent type name
  7. COLUMN_SIZE int => column size. For char or date types this is the maximum number of characters, for numeric or decimal types this is precision.
  8. BUFFER_LENGTH is not used.
  9. DECIMAL_DIGITS int => the number of fractional digits
  10. NUM_PREC_RADIX int => Radix (typically either 10 or 2)
  11. NULLABLE int => is NULL allowed?
    • columnNoNulls - might not allow NULL values
    • columnNullable - definitely allows NULL values
    • columnNullableUnknown - nullability unknown
  12. REMARKS String => comment describing column (may be null)
  13. COLUMN_DEF String => default value (may be null)
  14. SQL_DATA_TYPE int => unused
  15. SQL_DATETIME_SUB int => unused
  16. CHAR_OCTET_LENGTH int => for char types the maximum number of bytes in the column
  17. ORDINAL_POSITION int => index of column in table (starting at 1)
  18. IS_NULLABLE String => "NO" means column definitely does not allow NULL values; "YES" means the column might allow NULL values. An empty string means nobody knows.

Exceptions
SQLException if a database-access error occurs.
See Also
getSearchStringEscape


 DatabaseMetaData.getCrossReference

DatabaseMetaData.getCrossReference

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract ResultSet getCrossReference( String primaryCatalog, String primarySchema, String primaryTable, String foreignCatalog, String foreignSchema, String foreignTable ) throws SQLException
Parameters
primaryCatalog
a catalog name; "" retrieves those without a catalog; null means drop catalog name from the selection criteria
primarySchema
a schema name pattern; "" retrieves those without a schema
primaryTable
the table name that exports the key
foreignCatalog
a catalog name; "" retrieves those without a catalog; null means drop catalog name from the selection criteria
foreignSchema
a schema name pattern; "" retrieves those without a schema
foreignTable
the table name that imports the key
Returns
ResultSet - each row is a foreign key column description
Description
Get a description of the foreign key columns in the foreign key table that reference the primary key columns of the primary key table (describe how one table imports another's key.) This should normally return a single foreign key/primary key pair (most tables only import a foreign key from a table once.) They are ordered by FKTABLE_CAT, FKTABLE_SCHEM, FKTABLE_NAME, and KEY_SEQ.

Each foreign key column description has the following columns:

  1. PKTABLE_CAT String => primary key table catalog (may be null)
  2. PKTABLE_SCHEM String => primary key table schema (may be null)
  3. PKTABLE_NAME String => primary key table name
  4. PKCOLUMN_NAME String => primary key column name
  5. FKTABLE_CAT String => foreign key table catalog (may be null) being exported (may be null)
  6. FKTABLE_SCHEM String => foreign key table schema (may be null) being exported (may be null)
  7. FKTABLE_NAME String => foreign key table name being exported
  8. FKCOLUMN_NAME String => foreign key column name being exported
  9. KEY_SEQ short => sequence number within foreign key
  10. UPDATE_RULE short => What happens to foreign key when primary is updated:
    • importedNoAction - do not allow update of primary key if it has been imported
    • importedKeyCascade - change imported key to agree with primary key update
    • importedKeySetNull - change imported key to NULL if its primary key has been updated
    • importedKeySetDefault - change imported key to default values if its primary key has been updated
    • importedKeyRestrict - same as importedKeyNoAction (for ODBC 2.x compatibility)
  11. DELETE_RULE short => What happens to the foreign key when primary is deleted.
    • importedKeyNoAction - do not allow delete of primary key if it has been imported
    • importedKeyCascade - delete rows that import a deleted key
    • importedKeySetNull - change imported key to NULL if its primary key has been deleted
    • importedKeyRestrict - same as importedKeyNoAction (for ODBC 2.x compatibility)
    • importedKeySetDefault - change imported key to default if its primary key has been deleted
  12. FK_NAME String => foreign key name (may be null)
  13. PK_NAME String => primary key name (may be null)
  14. DEFERRABILITY short => can the evaluation of foreign key constraints be deferred until commit
    • importedKeyInitiallyDeferred - see SQL92 for definition
    • importedKeyInitiallyImmediate - see SQL92 for definition
    • importedKeyNotDeferrable - see SQL92 for definition

Exceptions
SQLException if a database-access error occurs.
See Also
getImportedKeys


 DatabaseMetaData.getDatabaseProductName

DatabaseMetaData.getDatabaseProductName

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getDatabaseProductName() throws SQLException
Returns
database product name
Description
What's the name of this database product?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getDatabaseProductVersion

DatabaseMetaData.getDatabaseProductVersion

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getDatabaseProductVersion() throws SQLException
Returns
database version
Description
What's the version of this database product?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getDefaultTransactionIsolation

DatabaseMetaData.getDefaultTransactionIsolation

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getDefaultTransactionIsolation() throws SQLException
Returns
the default isolation level
Description
What's the database's default transaction isolation level? The values are defined in java.sql.Connection.

Exceptions
SQLException if a database-access error occurs.
See Also
Connection


 DatabaseMetaData.getDriverMajorVersion

DatabaseMetaData.getDriverMajorVersion

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getDriverMajorVersion()
Returns
JDBC driver major version
Description
What's this JDBC driver's major version number?


 DatabaseMetaData.getDriverMinorVersion

DatabaseMetaData.getDriverMinorVersion

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getDriverMinorVersion()
Returns
JDBC driver minor version number
Description
What's this JDBC driver's minor version number?


 DatabaseMetaData.getDriverName

DatabaseMetaData.getDriverName

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getDriverName() throws SQLException
Returns
JDBC driver name
Description
What's the name of this JDBC driver?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getDriverVersion

DatabaseMetaData.getDriverVersion

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getDriverVersion() throws SQLException
Returns
JDBC driver version
Description
What's the version of this JDBC driver?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getExportedKeys

DatabaseMetaData.getExportedKeys

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract ResultSet getExportedKeys( String catalog, String schema, String table ) throws SQLException
Parameters
catalog
a catalog name; "" retrieves those without a catalog; null means drop catalog name from the selection criteria
schema
a schema name pattern; "" retrieves those without a schema
table
a table name
Returns
ResultSet - each row is a foreign key column description
Description
Get a description of the foreign key columns that reference a table's primary key columns (the foreign keys exported by a table). They are ordered by FKTABLE_CAT, FKTABLE_SCHEM, FKTABLE_NAME, and KEY_SEQ.

Each foreign key column description has the following columns:

  1. PKTABLE_CAT String => primary key table catalog (may be null)
  2. PKTABLE_SCHEM String => primary key table schema (may be null)
  3. PKTABLE_NAME String => primary key table name
  4. PKCOLUMN_NAME String => primary key column name
  5. FKTABLE_CAT String => foreign key table catalog (may be null) being exported (may be null)
  6. FKTABLE_SCHEM String => foreign key table schema (may be null) being exported (may be null)
  7. FKTABLE_NAME String => foreign key table name being exported
  8. FKCOLUMN_NAME String => foreign key column name being exported
  9. KEY_SEQ short => sequence number within foreign key
  10. UPDATE_RULE short => What happens to foreign key when primary is updated:
    • importedNoAction - do not allow update of primary key if it has been imported
    • importedKeyCascade - change imported key to agree with primary key update
    • importedKeySetNull - change imported key to NULL if its primary key has been updated
    • importedKeySetDefault - change imported key to default values if its primary key has been updated
    • importedKeyRestrict - same as importedKeyNoAction (for ODBC 2.x compatibility)
  11. DELETE_RULE short => What happens to the foreign key when primary is deleted.
    • importedKeyNoAction - do not allow delete of primary key if it has been imported
    • importedKeyCascade - delete rows that import a deleted key
    • importedKeySetNull - change imported key to NULL if its primary key has been deleted
    • importedKeyRestrict - same as importedKeyNoAction (for ODBC 2.x compatibility)
    • importedKeySetDefault - change imported key to default if its primary key has been deleted
  12. FK_NAME String => foreign key name (may be null)
  13. PK_NAME String => primary key name (may be null)
  14. DEFERRABILITY short => can the evaluation of foreign key constraints be deferred until commit
    • importedKeyInitiallyDeferred - see SQL92 for definition
    • importedKeyInitiallyImmediate - see SQL92 for definition
    • importedKeyNotDeferrable - see SQL92 for definition

Exceptions
SQLException if a database-access error occurs.
See Also
getImportedKeys


 DatabaseMetaData.getExtraNameCharacters

DatabaseMetaData.getExtraNameCharacters

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getExtraNameCharacters() throws SQLException
Returns
the string containing the extra characters
Description
Get all the "extra" characters that can be used in unquoted identifier names (those beyond a-z, A-Z, 0-9 and _).

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getIdentifierQuoteString

DatabaseMetaData.getIdentifierQuoteString

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getIdentifierQuoteString() throws SQLException
Returns
the quoting string
Description
What's the string used to quote SQL identifiers? This returns a space " " if identifier quoting isn't supported. A JDBC-Compliant driver always uses a double quote character.

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getImportedKeys

DatabaseMetaData.getImportedKeys

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract ResultSet getImportedKeys( String catalog, String schema, String table ) throws SQLException
Parameters
catalog
a catalog name; "" retrieves those without a catalog; null means drop catalog name from the selection criteria
schema
a schema name pattern; "" retrieves those without a schema
table
a table name
Returns
ResultSet - each row is a primary key column description
Description
Get a description of the primary key columns that are referenced by a table's foreign key columns (the primary keys imported by a table). They are ordered by PKTABLE_CAT, PKTABLE_SCHEM, PKTABLE_NAME, and KEY_SEQ.

Each primary key column description has the following columns:

  1. PKTABLE_CAT String => primary key table catalog being imported (may be null)
  2. PKTABLE_SCHEM String => primary key table schema being imported (may be null)
  3. PKTABLE_NAME String => primary key table name being imported
  4. PKCOLUMN_NAME String => primary key column name being imported
  5. FKTABLE_CAT String => foreign key table catalog (may be null)
  6. FKTABLE_SCHEM String => foreign key table schema (may be null)
  7. FKTABLE_NAME String => foreign key table name
  8. FKCOLUMN_NAME String => foreign key column name
  9. KEY_SEQ short => sequence number within foreign key
  10. UPDATE_RULE short => What happens to foreign key when primary is updated:
    • importedNoAction - do not allow update of primary key if it has been imported
    • importedKeyCascade - change imported key to agree with primary key update
    • importedKeySetNull - change imported key to NULL if its primary key has been updated
    • importedKeySetDefault - change imported key to default values if its primary key has been updated
    • importedKeyRestrict - same as importedKeyNoAction (for ODBC 2.x compatibility)
  11. DELETE_RULE short => What happens to the foreign key when primary is deleted.
    • importedKeyNoAction - do not allow delete of primary key if it has been imported
    • importedKeyCascade - delete rows that import a deleted key
    • importedKeySetNull - change imported key to NULL if its primary key has been deleted
    • importedKeyRestrict - same as importedKeyNoAction (for ODBC 2.x compatibility)
    • importedKeySetDefault - change imported key to default if its primary key has been deleted
  12. FK_NAME String => foreign key name (may be null)
  13. PK_NAME String => primary key name (may be null)
  14. DEFERRABILITY short => can the evaluation of foreign key constraints be deferred until commit
    • importedKeyInitiallyDeferred - see SQL92 for definition
    • importedKeyInitiallyImmediate - see SQL92 for definition
    • importedKeyNotDeferrable - see SQL92 for definition

Exceptions
SQLException if a database-access error occurs.
See Also
getExportedKeys


 DatabaseMetaData.getIndexInfo

DatabaseMetaData.getIndexInfo

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract ResultSet getIndexInfo( String catalog, String schema, String table, boolean unique, boolean approximate ) throws SQLException
Parameters
catalog
a catalog name; "" retrieves those without a catalog; null means drop catalog name from the selection criteria
schema
a schema name pattern; "" retrieves those without a schema
table
a table name
unique
when true, return only indices for unique values; when false, return indices regardless of whether unique or not
approximate
when true, result is allowed to reflect approximate or out of data values; when false, results are requested to be accurate
Returns
ResultSet - each row is an index column description
Description
Get a description of a table's indices and statistics. They are ordered by NON_UNIQUE, TYPE, INDEX_NAME, and ORDINAL_POSITION.

Each index column description has the following columns:

  1. TABLE_CAT String => table catalog (may be null)
  2. TABLE_SCHEM String => table schema (may be null)
  3. TABLE_NAME String => table name
  4. NON_UNIQUE boolean => Can index values be non-unique? false when TYPE is tableIndexStatistic
  5. INDEX_QUALIFIER String => index catalog (may be null); null when TYPE is tableIndexStatistic
  6. INDEX_NAME String => index name; null when TYPE is tableIndexStatistic
  7. TYPE short => index type:
    • tableIndexStatistic - this identifies table statistics that are returned in conjuction with a table's index descriptions
    • tableIndexClustered - this is a clustered index
    • tableIndexHashed - this is a hashed index
    • tableIndexOther - this is some other style of index
  8. ORDINAL_POSITION short => column sequence number within index; zero when TYPE is tableIndexStatistic
  9. COLUMN_NAME String => column name; null when TYPE is tableIndexStatistic
  10. ASC_OR_DESC String => column sort sequence, "A" => ascending, "D" => descending, may be null if sort sequence is not supported; null when TYPE is tableIndexStatistic
  11. CARDINALITY int => When TYPE is tableIndexStatistic, then this is the number of rows in the table; otherwise, it is the number of unique values in the index.
  12. PAGES int => When TYPE is tableIndexStatisic then this is the number of pages used for the table, otherwise it is the number of pages used for the current index.
  13. FILTER_CONDITION String => Filter condition, if any. (may be null)

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getMaxBinaryLiteralLength

DatabaseMetaData.getMaxBinaryLiteralLength

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getMaxBinaryLiteralLength() throws SQLException
Returns
max literal length
Description
How many hex characters can you have in an inline binary literal?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getMaxCatalogNameLength

DatabaseMetaData.getMaxCatalogNameLength

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getMaxCatalogNameLength() throws SQLException
Returns
max name length in bytes
Description
What's the maximum length of a catalog name?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getMaxCharLiteralLength

DatabaseMetaData.getMaxCharLiteralLength

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getMaxCharLiteralLength() throws SQLException
Returns
max literal length
Description
What's the max length for a character literal?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getMaxColumnNameLength

DatabaseMetaData.getMaxColumnNameLength

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getMaxColumnNameLength() throws SQLException
Returns
max literal length
Description
What's the limit on column name length?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getMaxColumnsInGroupBy

DatabaseMetaData.getMaxColumnsInGroupBy

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getMaxColumnsInGroupBy() throws SQLException
Returns
max number of columns
Description
What's the maximum number of columns in a "GROUP BY" clause?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getMaxColumnsInIndex

DatabaseMetaData.getMaxColumnsInIndex

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getMaxColumnsInIndex() throws SQLException
Returns
max columns
Description
What's the maximum number of columns allowed in an index?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getMaxColumnsInOrderBy

DatabaseMetaData.getMaxColumnsInOrderBy

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getMaxColumnsInOrderBy() throws SQLException
Returns
max columns
Description
What's the maximum number of columns in an "ORDER BY" clause?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getMaxColumnsInSelect

DatabaseMetaData.getMaxColumnsInSelect

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getMaxColumnsInSelect() throws SQLException
Returns
max columns
Description
What's the maximum number of columns in a "SELECT" list?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getMaxColumnsInTable

DatabaseMetaData.getMaxColumnsInTable

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getMaxColumnsInTable() throws SQLException
Returns
max columns
Description
What's the maximum number of columns in a table?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getMaxConnections

DatabaseMetaData.getMaxConnections

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getMaxConnections() throws SQLException
Returns
max connections
Description
How many active connections can we have at a time to this database?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getMaxCursorNameLength

DatabaseMetaData.getMaxCursorNameLength

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getMaxCursorNameLength() throws SQLException
Returns
max cursor name length in bytes
Description
What's the maximum cursor name length?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getMaxIndexLength

DatabaseMetaData.getMaxIndexLength

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getMaxIndexLength() throws SQLException
Returns
max index length in bytes
Description
What's the maximum length of an index (in bytes)?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getMaxProcedureNameLength

DatabaseMetaData.getMaxProcedureNameLength

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getMaxProcedureNameLength() throws SQLException
Returns
max name length in bytes
Description
What's the maximum length of a procedure name?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getMaxRowSize

DatabaseMetaData.getMaxRowSize

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getMaxRowSize() throws SQLException
Returns
max row size in bytes
Description
What's the maximum length of a single row?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getMaxSchemaNameLength

DatabaseMetaData.getMaxSchemaNameLength

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getMaxSchemaNameLength() throws SQLException
Returns
max name length in bytes
Description
What's the maximum length allowed for a schema name?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getMaxStatementLength

DatabaseMetaData.getMaxStatementLength

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getMaxStatementLength() throws SQLException
Returns
max length in bytes
Description
What's the maximum length of a SQL statement?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getMaxStatements

DatabaseMetaData.getMaxStatements

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getMaxStatements() throws SQLException
Returns
the maximum
Description
How many active statements can we have open at one time to this database?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getMaxTableNameLength

DatabaseMetaData.getMaxTableNameLength

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getMaxTableNameLength() throws SQLException
Returns
max name length in bytes
Description
What's the maximum length of a table name?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getMaxTablesInSelect

DatabaseMetaData.getMaxTablesInSelect

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getMaxTablesInSelect() throws SQLException
Returns
the maximum
Description
What's the maximum number of tables in a SELECT?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getMaxUserNameLength

DatabaseMetaData.getMaxUserNameLength

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getMaxUserNameLength() throws SQLException
Returns
max name length in bytes
Description
What's the maximum length of a user name?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getNumericFunctions

DatabaseMetaData.getNumericFunctions

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getNumericFunctions() throws SQLException
Returns
the list
Description
Get a comma separated list of math functions.

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getPrimaryKeys

DatabaseMetaData.getPrimaryKeys

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract ResultSet getPrimaryKeys( String catalog, String schema, String table ) throws SQLException
Parameters
catalog
a catalog name; "" retrieves those without a catalog; null means drop catalog name from the selection criteria
schema
a schema name pattern; "" retrieves those without a schema
table
a table name
Returns
ResultSet - each row is a primary key column description
Description
Get a description of a table's primary key columns. They are ordered by COLUMN_NAME.

Each primary key column description has the following columns:

  1. TABLE_CAT String => table catalog (may be null)
  2. TABLE_SCHEM String => table schema (may be null)
  3. TABLE_NAME String => table name
  4. COLUMN_NAME String => column name
  5. KEY_SEQ short => sequence number within primary key
  6. PK_NAME String => primary key name (may be null)

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getProcedureColumns

DatabaseMetaData.getProcedureColumns

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract ResultSet getProcedureColumns( String catalog, String schemaPattern, String procedureNamePattern, String columnNamePattern ) throws SQLException
Parameters
catalog
a catalog name; "" retrieves those without a catalog; null means drop catalog name from the selection criteria
schemaPattern
a schema name pattern; "" retrieves those without a schema
procedureNamePattern
a procedure name pattern
columnNamePattern
a column name pattern
Returns
ResultSet - each row is a stored procedure parameter or column description
Description
Get a description of a catalog's stored procedure parameters and result columns.

Only descriptions matching the schema, procedure and parameter name criteria are returned. They are ordered by PROCEDURE_SCHEM and PROCEDURE_NAME. Within this, the return value, if any, is first. Next are the parameter descriptions in call order. The column descriptions follow in column number order.

Each row in the ResultSet is a parameter description or column description with the following fields:

  1. PROCEDURE_CAT String => procedure catalog (may be null)
  2. PROCEDURE_SCHEM String => procedure schema (may be null)
  3. PROCEDURE_NAME String => procedure name
  4. COLUMN_NAME String => column/parameter name
  5. COLUMN_TYPE Short => kind of column/parameter:
    • procedureColumnUnknown - nobody knows
    • procedureColumnIn - IN parameter
    • procedureColumnInOut - INOUT parameter
    • procedureColumnOut - OUT parameter
    • procedureColumnReturn - procedure return value
    • procedureColumnResult - result column in ResultSet
  6. DATA_TYPE short => SQL type from java.sql.Types
  7. TYPE_NAME String => SQL type name
  8. PRECISION int => precision
  9. LENGTH int => length in bytes of data
  10. SCALE short => scale
  11. RADIX short => radix
  12. NULLABLE short => can it contain NULL?
    • procedureNoNulls - does not allow NULL values
    • procedureNullable - allows NULL values
    • procedureNullableUnknown - nullability unknown
  13. REMARKS String => comment describing parameter/column

Note: Some databases may not return the column descriptions for a procedure. Additional columns beyond REMARKS can be defined by the database.

Exceptions
SQLException if a database-access error occurs.
See Also
getSearchStringEscape


 DatabaseMetaData.getProcedures

DatabaseMetaData.getProcedures

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract ResultSet getProcedures( String catalog, String schemaPattern, String procedureNamePattern ) throws SQLException
Parameters
catalog
a catalog name; "" retrieves those without a catalog; null means drop catalog name from the selection criteria
schemaPattern
a schema name pattern; "" retrieves those without a schema
procedureNamePattern
a procedure name pattern
Returns
ResultSet - each row is a procedure description
Description
Get a description of stored procedures available in a catalog.

Only procedure descriptions matching the schema and procedure name criteria are returned. They are ordered by PROCEDURE_SCHEM, and PROCEDURE_NAME.

Each procedure description has the the following columns:

  1. PROCEDURE_CAT String => procedure catalog (may be null)
  2. PROCEDURE_SCHEM String => procedure schema (may be null)
  3. PROCEDURE_NAME String => procedure name
  4. reserved for future use
  5. reserved for future use
  6. reserved for future use
  7. REMARKS String => explanatory comment on the procedure
  8. PROCEDURE_TYPE short => kind of procedure:
    • procedureResultUnknown - May return a result
    • procedureNoResult - Does not return a result
    • procedureReturnsResult - Returns a result

Exceptions
SQLException if a database-access error occurs.
See Also
getSearchStringEscape


 DatabaseMetaData.getProcedureTerm

DatabaseMetaData.getProcedureTerm

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getProcedureTerm() throws SQLException
Returns
the vendor term
Description
What's the database vendor's preferred term for "procedure"?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getSchemas

DatabaseMetaData.getSchemas

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract ResultSet getSchemas() throws SQLException
Returns
ResultSet - each row has a single String column that is a schema name
Description
Get the schema names available in this database. The results are ordered by schema name.

The schema column is:

  1. TABLE_SCHEM String => schema name

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getSchemaTerm

DatabaseMetaData.getSchemaTerm

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getSchemaTerm() throws SQLException
Returns
the vendor term
Description
What's the database vendor's preferred term for "schema"?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getSearchStringEscape

DatabaseMetaData.getSearchStringEscape

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getSearchStringEscape() throws SQLException
Returns
the string used to escape wildcard characters
Description
This is the string that can be used to escape '_' or '%' in the string pattern style catalog search parameters.

The '_' character represents any single character.

The '%' character represents any sequence of zero or more characters.

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getSQLKeywords

DatabaseMetaData.getSQLKeywords

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getSQLKeywords() throws SQLException
Returns
the list
Description
Get a comma separated list of all a database's SQL keywords that are NOT also SQL92 keywords.

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getStringFunctions

DatabaseMetaData.getStringFunctions

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getStringFunctions() throws SQLException
Returns
the list
Description
Get a comma separated list of string functions.

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getSystemFunctions

DatabaseMetaData.getSystemFunctions

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getSystemFunctions() throws SQLException
Returns
the list
Description
Get a comma separated list of system functions.

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getTablePrivileges

DatabaseMetaData.getTablePrivileges

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract ResultSet getTablePrivileges( String catalog, String schemaPattern, String tableNamePattern ) throws SQLException
Parameters
catalog
a catalog name; "" retrieves those without a catalog; null means drop catalog name from the selection criteria
schemaPattern
a schema name pattern; "" retrieves those without a schema
tableNamePattern
a table name pattern
Returns
ResultSet - each row is a table privilege description
Description
Get a description of the access rights for each table available in a catalog. Note that a table privilege applies to one or more columns in the table. It would be wrong to assume that this priviledge applies to all columns (this may be true for some systems but is not true for all.)

Only privileges matching the schema and table name criteria are returned. They are ordered by TABLE_SCHEM, TABLE_NAME, and PRIVILEGE.

Each privilige description has the following columns:

  1. TABLE_CAT String => table catalog (may be null)
  2. TABLE_SCHEM String => table schema (may be null)
  3. TABLE_NAME String => table name
  4. GRANTOR => grantor of access (may be null)
  5. GRANTEE String => grantee of access
  6. PRIVILEGE String => name of access (SELECT, INSERT, UPDATE, REFRENCES, ...)
  7. IS_GRANTABLE String => "YES" if grantee is permitted to grant to others; "NO" if not; null if unknown

Exceptions
SQLException if a database-access error occurs.
See Also
getSearchStringEscape


 DatabaseMetaData.getTables

DatabaseMetaData.getTables

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract ResultSet getTables( String catalog, String schemaPattern, String tableNamePattern, String types[] ) throws SQLException
Parameters
catalog
a catalog name; "" retrieves those without a catalog; null means drop catalog name from the selection criteria
schemaPattern
a schema name pattern; "" retrieves those without a schema
tableNamePattern
a table name pattern
types
a list of table types to include; null returns all types
Returns
ResultSet - each row is a table description
Description
Get a description of tables available in a catalog.

Only table descriptions matching the catalog, schema, table name and type criteria are returned. They are ordered by TABLE_TYPE, TABLE_SCHEM and TABLE_NAME.

Each table description has the following columns:

  1. TABLE_CAT String => table catalog (may be null)
  2. TABLE_SCHEM String => table schema (may be null)
  3. TABLE_NAME String => table name
  4. TABLE_TYPE String => table type. Typical types are "TABLE", "VIEW", "SYSTEM TABLE", "GLOBAL TEMPORARY", "LOCAL TEMPORARY", "ALIAS", "SYNONYM".
  5. REMARKS String => explanatory comment on the table

Note: Some databases may not return information for all tables.

Exceptions
SQLException if a database-access error occurs.
See Also
getSearchStringEscape


 DatabaseMetaData.getTableTypes

DatabaseMetaData.getTableTypes

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract ResultSet getTableTypes() throws SQLException
Returns
ResultSet - each row has a single String column that is a table type
Description
Get the table types available in this database. The results are ordered by table type.

The table type is:

  1. TABLE_TYPE String => table type. Typical types are "TABLE", "VIEW", "SYSTEM TABLE", "GLOBAL TEMPORARY", "LOCAL TEMPORARY", "ALIAS", "SYNONYM".

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getTimeDateFunctions

DatabaseMetaData.getTimeDateFunctions

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getTimeDateFunctions() throws SQLException
Returns
the list
Description
Get a comma separated list of time and date functions.

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getTypeInfo

DatabaseMetaData.getTypeInfo

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract ResultSet getTypeInfo() throws SQLException
Returns
ResultSet - each row is a SQL type description
Description
Get a description of all the standard SQL types supported by this database. They are ordered by DATA_TYPE and then by how closely the data type maps to the corresponding JDBC SQL type.

Each type description has the following columns:

  1. TYPE_NAME String => Type name
  2. DATA_TYPE short => SQL data type from java.sql.Types
  3. PRECISION int => maximum precision
  4. LITERAL_PREFIX String => prefix used to quote a literal (may be null)
  5. LITERAL_SUFFIX String => suffix used to quote a literal (may be null)
  6. CREATE_PARAMS String => parameters used in creating the type (may be null)
  7. NULLABLE short => can you use NULL for this type?
    • typeNoNulls - does not allow NULL values
    • typeNullable - allows NULL values
    • typeNullableUnknown - nullability unknown
  8. CASE_SENSITIVE boolean=> is it case sensitive?
  9. SEARCHABLE short => can you use "WHERE" based on this type:
    • typePredNone - No support
    • typePredChar - Only supported with WHERE .. LIKE
    • typePredBasic - Supported except for WHERE .. LIKE
    • typeSearchable - Supported for all WHERE ..
  10. UNSIGNED_ATTRIBUTE boolean => is it unsigned?
  11. FIXED_PREC_SCALE boolean => can it be a money value?
  12. AUTO_INCREMENT boolean => can it be used for an auto-increment value?
  13. LOCAL_TYPE_NAME String => localized version of type name (may be null)
  14. MINIMUM_SCALE short => minimum scale supported
  15. MAXIMUM_SCALE short => maximum scale supported
  16. SQL_DATA_TYPE int => unused
  17. SQL_DATETIME_SUB int => unused
  18. NUM_PREC_RADIX int => usually 2 or 10

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getURL

DatabaseMetaData.getURL

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getURL() throws SQLException
Returns
the url or null if it can't be generated
Description
What's the url for this database?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getUserName

DatabaseMetaData.getUserName

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getUserName() throws SQLException
Returns
our database user name
Description
What's our user name as known to the database?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.getVersionColumns

DatabaseMetaData.getVersionColumns

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract ResultSet getVersionColumns( String catalog, String schema, String table ) throws SQLException
Parameters
catalog
a catalog name; "" retrieves those without a catalog; null means drop catalog name from the selection criteria
schema
a schema name; "" retrieves those without a schema
table
a table name
Returns
ResultSet - each row is a column description
Description
Get a description of a table's columns that are automatically updated when any value in a row is updated. They are unordered.

Each column description has the following columns:

  1. SCOPE short => is not used
  2. COLUMN_NAME String => column name
  3. DATA_TYPE short => SQL data type from java.sql.Types
  4. TYPE_NAME String => Data source dependent type name
  5. COLUMN_SIZE int => precision
  6. BUFFER_LENGTH int => length of column value in bytes
  7. DECIMAL_DIGITS short => scale
  8. PSEUDO_COLUMN short => is this a pseudo column like an Oracle ROWID
    • versionColumnUnknown - may or may not be pseudo column
    • versionColumnNotPseudo - is NOT a pseudo column
    • versionColumnPseudo - is a pseudo column

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.isCatalogAtStart

DatabaseMetaData.isCatalogAtStart

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean isCatalogAtStart() throws SQLException
Returns
true if it appears at the start
Description
Does a catalog appear at the start of a qualified table name? (Otherwise it appears at the end)

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.isReadOnly

DatabaseMetaData.isReadOnly

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean isReadOnly() throws SQLException
Returns
true if so
Description
Is the database in read-only mode?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.nullPlusNonNullIsNull

DatabaseMetaData.nullPlusNonNullIsNull

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean nullPlusNonNullIsNull() throws SQLException
Returns
true if so
Description
Are concatenations between NULL and non-NULL values NULL? A JDBC-Compliant driver always returns true.

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.nullsAreSortedAtEnd

DatabaseMetaData.nullsAreSortedAtEnd

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean nullsAreSortedAtEnd() throws SQLException
Returns
true if so
Description
Are NULL values sorted at the end regardless of sort order?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.nullsAreSortedAtStart

DatabaseMetaData.nullsAreSortedAtStart

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean nullsAreSortedAtStart() throws SQLException
Returns
true if so
Description
Are NULL values sorted at the start regardless of sort order?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.nullsAreSortedHigh

DatabaseMetaData.nullsAreSortedHigh

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean nullsAreSortedHigh() throws SQLException
Returns
true if so
Description
Are NULL values sorted high?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.nullsAreSortedLow

DatabaseMetaData.nullsAreSortedLow

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean nullsAreSortedLow() throws SQLException
Returns
true if so
Description
Are NULL values sorted low?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.storesLowerCaseIdentifiers

DatabaseMetaData.storesLowerCaseIdentifiers

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean storesLowerCaseIdentifiers() throws SQLException
Returns
true if so
Description
Does the database treat mixed case unquoted SQL identifiers as case insensitive and store them in lower case?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.storesLowerCaseQuotedIdentifiers

DatabaseMetaData.storesLowerCaseQuotedIdentifiers

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean storesLowerCaseQuotedIdentifiers() throws SQLException
Returns
true if so
Description
Does the database treat mixed case quoted SQL identifiers as case insensitive and store them in lower case?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.storesMixedCaseIdentifiers

DatabaseMetaData.storesMixedCaseIdentifiers

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean storesMixedCaseIdentifiers() throws SQLException
Returns
true if so
Description
Does the database treat mixed case unquoted SQL identifiers as case insensitive and store them in mixed case?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.storesMixedCaseQuotedIdentifiers

DatabaseMetaData.storesMixedCaseQuotedIdentifiers

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean storesMixedCaseQuotedIdentifiers() throws SQLException
Returns
true if so
Description
Does the database treat mixed case quoted SQL identifiers as case insensitive and store them in mixed case?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.storesUpperCaseIdentifiers

DatabaseMetaData.storesUpperCaseIdentifiers

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean storesUpperCaseIdentifiers() throws SQLException
Returns
true if so
Description
Does the database treat mixed case unquoted SQL identifiers as case insensitive and store them in upper case?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.storesUpperCaseQuotedIdentifiers

DatabaseMetaData.storesUpperCaseQuotedIdentifiers

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean storesUpperCaseQuotedIdentifiers() throws SQLException
Returns
true if so
Description
Does the database treat mixed case quoted SQL identifiers as case insensitive and store them in upper case?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsAlterTableWithAddColumn

DatabaseMetaData.supportsAlterTableWithAddColumn

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsAlterTableWithAddColumn() throws SQLException
Returns
true if so
Description
Is "ALTER TABLE" with add column supported?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsAlterTableWithDropColumn

DatabaseMetaData.supportsAlterTableWithDropColumn

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsAlterTableWithDropColumn() throws SQLException
Returns
true if so
Description
Is "ALTER TABLE" with drop column supported?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsANSI92EntryLevelSQL

DatabaseMetaData.supportsANSI92EntryLevelSQL

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsANSI92EntryLevelSQL() throws SQLException
Returns
true if so
Description
Is the ANSI92 entry level SQL grammar supported? All JDBC-Compliant drivers must return true.

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsANSI92FullSQL

DatabaseMetaData.supportsANSI92FullSQL

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsANSI92FullSQL() throws SQLException
Returns
true if so
Description
Is the ANSI92 full SQL grammar supported?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsANSI92IntermediateSQL

DatabaseMetaData.supportsANSI92IntermediateSQL

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsANSI92IntermediateSQL() throws SQLException
Returns
true if so
Description
Is the ANSI92 intermediate SQL grammar supported?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsCatalogsInDataManipulation

DatabaseMetaData.supportsCatalogsInDataManipulation

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsCatalogsInDataManipulation() throws SQLException
Returns
true if so
Description
Can a catalog name be used in a data manipulation statement?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsCatalogsInIndexDefinitions

DatabaseMetaData.supportsCatalogsInIndexDefinitions

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsCatalogsInIndexDefinitions() throws SQLException
Returns
true if so
Description
Can a catalog name be used in an index definition statement?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsCatalogsInPrivilegeDefinitions

DatabaseMetaData.supportsCatalogsInPrivilegeDefinitions

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsCatalogsInPrivilegeDefinitions() throws SQLException
Returns
true if so
Description
Can a catalog name be used in a privilege definition statement?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsCatalogsInProcedureCalls

DatabaseMetaData.supportsCatalogsInProcedureCalls

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsCatalogsInProcedureCalls() throws SQLException
Returns
true if so
Description
Can a catalog name be used in a procedure call statement?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsCatalogsInTableDefinitions

DatabaseMetaData.supportsCatalogsInTableDefinitions

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsCatalogsInTableDefinitions() throws SQLException
Returns
true if so
Description
Can a catalog name be used in a table definition statement?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsColumnAliasing

DatabaseMetaData.supportsColumnAliasing

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsColumnAliasing() throws SQLException
Returns
true if so
Description
Is column aliasing supported?

If so, the SQL AS clause can be used to provide names for computed columns or to provide alias names for columns as required. A JDBC-Compliant driver always returns true.

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsConvert

DatabaseMetaData.supportsConvert

Interface Overview | Interface Members | This Package | All Packages

Syntax 1
public abstract boolean supportsConvert() throws SQLException
Returns
true if so
Description
Is the CONVERT function between SQL types supported?

Exceptions
SQLException if a database-access error occurs.

Syntax 2
public abstract boolean supportsConvert( int fromType, int toType ) throws SQLException
Parameters
fromType
the type to convert from
toType
the type to convert to
Returns
true if so
Description
Is CONVERT between the given SQL types supported?

Exceptions
SQLException if a database-access error occurs.
See Also
Types


 DatabaseMetaData.supportsCoreSQLGrammar

DatabaseMetaData.supportsCoreSQLGrammar

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsCoreSQLGrammar() throws SQLException
Returns
true if so
Description
Is the ODBC Core SQL grammar supported?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsCorrelatedSubqueries

DatabaseMetaData.supportsCorrelatedSubqueries

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsCorrelatedSubqueries() throws SQLException
Returns
true if so
Description
Are correlated subqueries supported? A JDBC-Compliant driver always returns true.

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsDataDefinitionAndDataManipulationTransactions

DatabaseMetaData.supportsDataDefinitionAndDataManipulationTransactions

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsDataDefinitionAndDataManipulationTransactions() throws SQLException
Returns
true if so
Description
Are both data definition and data manipulation statements within a transaction supported?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsDataManipulationTransactionsOnly

DatabaseMetaData.supportsDataManipulationTransactionsOnly

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsDataManipulationTransactionsOnly() throws SQLException
Returns
true if so
Description
Are only data manipulation statements within a transaction supported?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsDifferentTableCorrelationNames

DatabaseMetaData.supportsDifferentTableCorrelationNames

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsDifferentTableCorrelationNames() throws SQLException
Returns
true if so
Description
If table correlation names are supported, are they restricted to be different from the names of the tables?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsExpressionsInOrderBy

DatabaseMetaData.supportsExpressionsInOrderBy

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsExpressionsInOrderBy() throws SQLException
Returns
true if so
Description
Are expressions in "ORDER BY" lists supported?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsExtendedSQLGrammar

DatabaseMetaData.supportsExtendedSQLGrammar

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsExtendedSQLGrammar() throws SQLException
Returns
true if so
Description
Is the ODBC Extended SQL grammar supported?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsFullOuterJoins

DatabaseMetaData.supportsFullOuterJoins

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsFullOuterJoins() throws SQLException
Returns
true if so
Description
Are full nested outer joins supported?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsGroupBy

DatabaseMetaData.supportsGroupBy

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsGroupBy() throws SQLException
Returns
true if so
Description
Is some form of "GROUP BY" clause supported?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsGroupByBeyondSelect

DatabaseMetaData.supportsGroupByBeyondSelect

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsGroupByBeyondSelect() throws SQLException
Returns
true if so
Description
Can a "GROUP BY" clause add columns not in the SELECT provided it specifies all the columns in the SELECT?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsGroupByUnrelated

DatabaseMetaData.supportsGroupByUnrelated

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsGroupByUnrelated() throws SQLException
Returns
true if so
Description
Can a "GROUP BY" clause use columns not in the SELECT?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsIntegrityEnhancementFacility

DatabaseMetaData.supportsIntegrityEnhancementFacility

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsIntegrityEnhancementFacility() throws SQLException
Returns
true if so
Description
Is the SQL Integrity Enhancement Facility supported?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsLikeEscapeClause

DatabaseMetaData.supportsLikeEscapeClause

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsLikeEscapeClause() throws SQLException
Returns
true if so
Description
Is the escape character in "LIKE" clauses supported? A JDBC-Compliant driver always returns true.

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsLimitedOuterJoins

DatabaseMetaData.supportsLimitedOuterJoins

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsLimitedOuterJoins() throws SQLException
Returns
true if so
Description
Is there limited support for outer joins? (This will be true if supportFullOuterJoins is true.)

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsMinimumSQLGrammar

DatabaseMetaData.supportsMinimumSQLGrammar

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsMinimumSQLGrammar() throws SQLException
Returns
true if so
Description
Is the ODBC Minimum SQL grammar supported? All JDBC-Compliant drivers must return true.

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsMixedCaseIdentifiers

DatabaseMetaData.supportsMixedCaseIdentifiers

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsMixedCaseIdentifiers() throws SQLException
Returns
true if so
Description
Does the database treat mixed case unquoted SQL identifiers as case sensitive and as a result store them in mixed case? A JDBC-Compliant driver will always return false.

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsMixedCaseQuotedIdentifiers

DatabaseMetaData.supportsMixedCaseQuotedIdentifiers

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsMixedCaseQuotedIdentifiers() throws SQLException
Returns
true if so
Description
Does the database treat mixed case quoted SQL identifiers as case sensitive and as a result store them in mixed case? A JDBC-Compliant driver will always return true.

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsMultipleResultSets

DatabaseMetaData.supportsMultipleResultSets

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsMultipleResultSets() throws SQLException
Returns
true if so
Description
Are multiple ResultSets from a single execute supported?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsMultipleTransactions

DatabaseMetaData.supportsMultipleTransactions

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsMultipleTransactions() throws SQLException
Returns
true if so
Description
Can we have multiple transactions open at once (on different connections)?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsNonNullableColumns

DatabaseMetaData.supportsNonNullableColumns

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsNonNullableColumns() throws SQLException
Returns
true if so
Description
Can columns be defined as non-nullable? A JDBC-Compliant driver always returns true.

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsOpenCursorsAcrossCommit

DatabaseMetaData.supportsOpenCursorsAcrossCommit

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsOpenCursorsAcrossCommit() throws SQLException
Returns
true if cursors always remain open; false if they might not remain open
Description
Can cursors remain open across commits?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsOpenCursorsAcrossRollback

DatabaseMetaData.supportsOpenCursorsAcrossRollback

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsOpenCursorsAcrossRollback() throws SQLException
Returns
true if cursors always remain open; false if they might not remain open
Description
Can cursors remain open across rollbacks?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsOpenStatementsAcrossCommit

DatabaseMetaData.supportsOpenStatementsAcrossCommit

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsOpenStatementsAcrossCommit() throws SQLException
Returns
true if statements always remain open; false if they might not remain open
Description
Can statements remain open across commits?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsOpenStatementsAcrossRollback

DatabaseMetaData.supportsOpenStatementsAcrossRollback

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsOpenStatementsAcrossRollback() throws SQLException
Returns
true if statements always remain open; false if they might not remain open
Description
Can statements remain open across rollbacks?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsOrderByUnrelated

DatabaseMetaData.supportsOrderByUnrelated

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsOrderByUnrelated() throws SQLException
Returns
true if so
Description
Can an "ORDER BY" clause use columns not in the SELECT?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsOuterJoins

DatabaseMetaData.supportsOuterJoins

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsOuterJoins() throws SQLException
Returns
true if so
Description
Is some form of outer join supported?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsPositionedDelete

DatabaseMetaData.supportsPositionedDelete

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsPositionedDelete() throws SQLException
Returns
true if so
Description
Is positioned DELETE supported?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsPositionedUpdate

DatabaseMetaData.supportsPositionedUpdate

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsPositionedUpdate() throws SQLException
Returns
true if so
Description
Is positioned UPDATE supported?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsSchemasInDataManipulation

DatabaseMetaData.supportsSchemasInDataManipulation

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsSchemasInDataManipulation() throws SQLException
Returns
true if so
Description
Can a schema name be used in a data manipulation statement?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsSchemasInIndexDefinitions

DatabaseMetaData.supportsSchemasInIndexDefinitions

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsSchemasInIndexDefinitions() throws SQLException
Returns
true if so
Description
Can a schema name be used in an index definition statement?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsSchemasInPrivilegeDefinitions

DatabaseMetaData.supportsSchemasInPrivilegeDefinitions

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsSchemasInPrivilegeDefinitions() throws SQLException
Returns
true if so
Description
Can a schema name be used in a privilege definition statement?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsSchemasInProcedureCalls

DatabaseMetaData.supportsSchemasInProcedureCalls

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsSchemasInProcedureCalls() throws SQLException
Returns
true if so
Description
Can a schema name be used in a procedure call statement?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsSchemasInTableDefinitions

DatabaseMetaData.supportsSchemasInTableDefinitions

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsSchemasInTableDefinitions() throws SQLException
Returns
true if so
Description
Can a schema name be used in a table definition statement?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsSelectForUpdate

DatabaseMetaData.supportsSelectForUpdate

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsSelectForUpdate() throws SQLException
Returns
true if so
Description
Is SELECT for UPDATE supported?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsStoredProcedures

DatabaseMetaData.supportsStoredProcedures

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsStoredProcedures() throws SQLException
Returns
true if so
Description
Are stored procedure calls using the stored procedure escape syntax supported?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsSubqueriesInComparisons

DatabaseMetaData.supportsSubqueriesInComparisons

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsSubqueriesInComparisons() throws SQLException
Returns
true if so
Description
Are subqueries in comparison expressions supported? A JDBC-Compliant driver always returns true.

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsSubqueriesInExists

DatabaseMetaData.supportsSubqueriesInExists

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsSubqueriesInExists() throws SQLException
Returns
true if so
Description
Are subqueries in 'exists' expressions supported? A JDBC-Compliant driver always returns true.

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsSubqueriesInIns

DatabaseMetaData.supportsSubqueriesInIns

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsSubqueriesInIns() throws SQLException
Returns
true if so
Description
Are subqueries in 'in' statements supported? A JDBC-Compliant driver always returns true.

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsSubqueriesInQuantifieds

DatabaseMetaData.supportsSubqueriesInQuantifieds

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsSubqueriesInQuantifieds() throws SQLException
Returns
true if so
Description
Are subqueries in quantified expressions supported? A JDBC-Compliant driver always returns true.

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsTableCorrelationNames

DatabaseMetaData.supportsTableCorrelationNames

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsTableCorrelationNames() throws SQLException
Returns
true if so
Description
Are table correlation names supported? A JDBC-Compliant driver always returns true.

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsTransactionIsolationLevel

DatabaseMetaData.supportsTransactionIsolationLevel

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsTransactionIsolationLevel( int level ) throws SQLException
Parameters
level
the values are defined in java.sql.Connection
Returns
true if so
Description
Does the database support the given transaction isolation level?

Exceptions
SQLException if a database-access error occurs.
See Also
Connection


 DatabaseMetaData.supportsTransactions

DatabaseMetaData.supportsTransactions

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsTransactions() throws SQLException
Returns
true if transactions are supported
Description
Are transactions supported? If not, commit is a noop and the isolation level is TRANSACTION_NONE.

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsUnion

DatabaseMetaData.supportsUnion

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsUnion() throws SQLException
Returns
true if so
Description
Is SQL UNION supported?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.supportsUnionAll

DatabaseMetaData.supportsUnionAll

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean supportsUnionAll() throws SQLException
Returns
true if so
Description
Is SQL UNION ALL supported?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.usesLocalFilePerTable

DatabaseMetaData.usesLocalFilePerTable

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean usesLocalFilePerTable() throws SQLException
Returns
true if the database uses a local file for each table
Description
Does the database use a file for each table?

Exceptions
SQLException if a database-access error occurs.


 DatabaseMetaData.usesLocalFiles

DatabaseMetaData.usesLocalFiles

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean usesLocalFiles() throws SQLException
Returns
true if so
Description
Does the database store tables in a local file?

Exceptions
SQLException if a database-access error occurs.


 Class Date

Class java.sql.Date

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.Date
           |
           +----java.sql.Date

public class Date
extends Date

This class is a thin wrapper around java.util.Date that allows JDBC to identify this as a SQL DATE value. It adds formatting and parsing operations to support the JDBC escape syntax for date values.


 Date Members

Date Members

Class Overview | This Package | All Packages

Constructors
Name | Description
Date(int, int, int) | Construct a Date
Date(long) | Construct a Date using a milliseconds time value

Methods
Name | Description
getHours() | Returns the hour represented by this date.
getMinutes() | Returns the number of minutes past the hour represented by this date.
getSeconds() | Returns the number of seconds past the minute represented by this date.
setHours(int) | Sets the hour of this date to the specified value.
setMinutes(int) | Sets the minutes of this date to the specified value.
setSeconds(int) | Sets the seconds of this date to the specified value.
setTime(long) | Set a Date using a milliseconds time value
toString() | Format a date in JDBC date escape format
valueOf(String) | Convert a string in JDBC date escape format to a Date value


 Date.Date

Date.Date

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Date( int year, int month, int day )
Parameters
year
year-1900
month
0 to 11
day
1 to 31
Description
Construct a Date

Syntax 2
public Date( long date )
Parameters
date
milliseconds since January 1, 1970, 00:00:00 GMT
Description
Construct a Date using a milliseconds time value


 Date.getHours

Date.getHours

Class Overview | Class Members | This Package | All Packages

Syntax
public int getHours()
Description
Returns the hour represented by this date.

Overrides
getHours in class Date


 Date.getMinutes

Date.getMinutes

Class Overview | Class Members | This Package | All Packages

Syntax
public int getMinutes()
Description
Returns the number of minutes past the hour represented by this date.

Overrides
getMinutes in class Date


 Date.getSeconds

Date.getSeconds

Class Overview | Class Members | This Package | All Packages

Syntax
public int getSeconds()
Description
Returns the number of seconds past the minute represented by this date.

Overrides
getSeconds in class Date


 Date.setHours

Date.setHours

Class Overview | Class Members | This Package | All Packages

Syntax
public void setHours( int i )
Description
Sets the hour of this date to the specified value.

Overrides
setHours in class Date


 Date.setMinutes

Date.setMinutes

Class Overview | Class Members | This Package | All Packages

Syntax
public void setMinutes( int i )
Description
Sets the minutes of this date to the specified value.

Overrides
setMinutes in class Date


 Date.setSeconds

Date.setSeconds

Class Overview | Class Members | This Package | All Packages

Syntax
public void setSeconds( int i )
Description
Sets the seconds of this date to the specified value.

Overrides
setSeconds in class Date


 Date.setTime

Date.setTime

Class Overview | Class Members | This Package | All Packages

Syntax
public void setTime( long date )
Parameters
date
milliseconds since January 1, 1970, 00:00:00 GMT
Description
Set a Date using a milliseconds time value

Overrides
setTime in class Date


 Date.toString

Date.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a String in yyyy-mm-dd format
Description
Format a date in JDBC date escape format

Overrides
toString in class Date


 Date.valueOf

Date.valueOf

Class Overview | Class Members | This Package | All Packages

Syntax
public static Date valueOf( String s )
Parameters
s
date in format "yyyy-mm-dd"
Returns
corresponding Date
Description
Convert a string in JDBC date escape format to a Date value


 Interface Driver

Interface java.sql.Driver

Interface Members | This Package | All Packages

public interface Driver

The Java SQL framework allows for multiple database drivers.

Each driver should supply a class that implements the Driver interface.

The DriverManager will try to load as many drivers as it can find and then for any given connection request, it will ask each driver in turn to try to connect to the target URL.

It is strongly recommended that each Driver class should be small and standalone so that the Driver class can be loaded and queried without bringing in vast quantities of supporting code.

When a Driver class is loaded, it should create an instance of itself and register it with the DriverManager. This means that a user can load and register a driver by doing Class.forName("foo.bah.Driver").

See Also:
DriverManager, Connection


 Driver Members

Driver Members

Interface Overview | This Package | All Packages

Methods
Name | Description
acceptsURL(String) | Returns true if the driver thinks that it can open a connection to the given URL.
connect(String, Properties) | Try to make a database connection to the given URL.
getMajorVersion() | Get the driver's major version number.
getMinorVersion() | Get the driver's minor version number.
getPropertyInfo(String, Properties) | The getPropertyInfo method is intended to allow a generic GUI tool to discover what properties it should prompt a human for in order to get enough information to connect to a database.
jdbcCompliant() | Report whether the Driver is a genuine JDBC COMPLIANT (tm) driver.


 Driver.acceptsURL

Driver.acceptsURL

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean acceptsURL( String url ) throws SQLException
Parameters
url
The URL of the database.
Returns
True if this driver can connect to the given URL.
Description
Returns true if the driver thinks that it can open a connection to the given URL. Typically drivers will return true if they understand the subprotocol specified in the URL and false if they don't.

Exceptions
SQLException if a database-access error occurs.


 Driver.connect

Driver.connect

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Connection connect( String url, Properties info ) throws SQLException
Parameters
url
The URL of the database to connect to
info
a list of arbitrary string tag/value pairs as connection arguments; normally at least a "user" and "password" property should be included
Returns
a Connection to the URL
Description
Try to make a database connection to the given URL. The driver should return "null" if it realizes it is the wrong kind of driver to connect to the given URL. This will be common, as when the JDBC driver manager is asked to connect to a given URL it passes the URL to each loaded driver in turn.

The driver should raise a SQLException if it is the right driver to connect to the given URL, but has trouble connecting to the database.

The java.util.Properties argument can be used to passed arbitrary string tag/value pairs as connection arguments. Normally at least "user" and "password" properties should be included in the Properties.

Exceptions
SQLException if a database-access error occurs.


 Driver.getMajorVersion

Driver.getMajorVersion

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getMajorVersion()
Description
Get the driver's major version number. Initially this should be 1.


 Driver.getMinorVersion

Driver.getMinorVersion

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getMinorVersion()
Description
Get the driver's minor version number. Initially this should be 0.


 Driver.getPropertyInfo

Driver.getPropertyInfo

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract DriverPropertyInfo[] getPropertyInfo( String url, Properties info ) throws SQLException
Parameters
url
The URL of the database to connect to.
info
A proposed list of tag/value pairs that will be sent on connect open.
Returns
An array of DriverPropertyInfo objects describing possible properties. This array may be an empty array if no properties are required.
Description

The getPropertyInfo method is intended to allow a generic GUI tool to discover what properties it should prompt a human for in order to get enough information to connect to a database. Note that depending on the values the human has supplied so far, additional values may become necessary, so it may be necessary to iterate though several calls to getPropertyInfo.

Exceptions
SQLException if a database-access error occurs.


 Driver.jdbcCompliant

Driver.jdbcCompliant

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean jdbcCompliant()
Description
Report whether the Driver is a genuine JDBC COMPLIANT (tm) driver. A driver may only report "true" here if it passes the JDBC compliance tests, otherwise it is required to return false. JDBC compliance requires full support for the JDBC API and full support for SQL 92 Entry Level. It is expected that JDBC compliant drivers will be available for all the major commercial databases. This method is not intended to encourage the development of non-JDBC compliant drivers, but is a recognition of the fact that some vendors are interested in using the JDBC API and framework for lightweight databases that do not support full database functionality, or for special databases such as document information retrieval where a SQL implementation may not be feasible.


 Class DriverManager

Class java.sql.DriverManager

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.sql.DriverManager

public class DriverManager
extends Object

The DriverManager provides a basic service for managing a set of JDBC drivers.

As part of its initialization, the DriverManager class will attempt to load the driver classes referenced in the "jdbc.drivers" system property. This allows a user to customize the JDBC Drivers used by their applications. For example in your ~/.hotjava/properties file you might specify: jdbc.drivers=foo.bah.Driver:wombat.sql.Driver:bad.taste.ourDriver A program can also explicitly load JDBC drivers at any time. For example, the my.sql.Driver is loaded with the following statement: Class.forName("my.sql.Driver");

When getConnection is called the DriverManager will attempt to locate a suitable driver from amongst those loaded at initialization and those loaded explicitly using the same classloader as the current applet or application.

See Also:
Driver, Connection


 DriverManager Members

DriverManager Members

Class Overview | This Package | All Packages

Methods
Name | Description
deregisterDriver(Driver) | Drop a Driver from the DriverManager's list.
getConnection(String) | Attempt to establish a connection to the given database URL.
getConnection(String, Properties) | Attempt to establish a connection to the given database URL.
getConnection(String, String, String) | Attempt to establish a connection to the given database URL.
getDriver(String) | Attempt to locate a driver that understands the given URL.
getDrivers() | Return an Enumeration of all the currently loaded JDBC drivers which the current caller has access to.
getLoginTimeout() | Get the maximum time in seconds that all drivers can wait when attempting to log in to a database.
getLogStream() | Get the logging/tracing PrintStream that is used by the DriverManager and all drivers.
println(String) | Print a message to the current JDBC log stream
registerDriver(Driver) | A newly loaded driver class should call registerDriver to make itself known to the DriverManager.
setLoginTimeout(int) | Set the maximum time in seconds that all drivers can wait when attempting to log in to a database.
setLogStream(PrintStream) | Set the logging/tracing PrintStream that is used by the DriverManager and all drivers.


 DriverManager.deregisterDriver

DriverManager.deregisterDriver

Class Overview | Class Members | This Package | All Packages

Syntax
public static void deregisterDriver( Driver driver ) throws SQLException
Parameters
driver
the JDBC Driver to drop
Description
Drop a Driver from the DriverManager's list. Applets can only deregister Drivers from their own classloader.

Exceptions
SQLException if a database-access error occurs.


 DriverManager.getConnection

DriverManager.getConnection

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static synchronized Connection getConnection( String url, Properties info ) throws SQLException
Parameters
url
a database url of the form jdbc:subprotocol:subname
info
a list of arbitrary string tag/value pairs as connection arguments; normally at least a "user" and "password" property should be included
Returns
a Connection to the URL
Description
Attempt to establish a connection to the given database URL. The DriverManager attempts to select an appropriate driver from the set of registered JDBC drivers.

Exceptions
SQLException if a database-access error occurs.

Syntax 2
public static synchronized Connection getConnection( String url, String user, String password ) throws SQLException
Parameters
url
a database url of the form jdbc:subprotocol:subname
user
the database user on whose behalf the Connection is being made
password
the user's password
Returns
a Connection to the URL
Description
Attempt to establish a connection to the given database URL. The DriverManager attempts to select an appropriate driver from the set of registered JDBC drivers.

Exceptions
SQLException if a database-access error occurs.

Syntax 3
public static synchronized Connection getConnection( String url ) throws SQLException
Parameters
url
a database url of the form jdbc:subprotocol:subname
Returns
a Connection to the URL
Description
Attempt to establish a connection to the given database URL. The DriverManager attempts to select an appropriate driver from the set of registered JDBC drivers.

Exceptions
SQLException if a database-access error occurs.


 DriverManager.getDriver

DriverManager.getDriver

Class Overview | Class Members | This Package | All Packages

Syntax
public static Driver getDriver( String url ) throws SQLException
Parameters
url
a database url of the form jdbc:subprotocol:subname
Returns
a Driver that can connect to the URL
Description
Attempt to locate a driver that understands the given URL. The DriverManager attempts to select an appropriate driver from the set of registered JDBC drivers.

Exceptions
SQLException if a database-access error occurs.


 DriverManager.getDrivers

DriverManager.getDrivers

Class Overview | Class Members | This Package | All Packages

Syntax
public static Enumeration getDrivers()
Returns
the list of JDBC Drivers loaded by the caller's class loader
Description
Return an Enumeration of all the currently loaded JDBC drivers which the current caller has access to.

Note: The classname of a driver can be found using d.getClass().getName()


 DriverManager.getLoginTimeout

DriverManager.getLoginTimeout

Class Overview | Class Members | This Package | All Packages

Syntax
public static int getLoginTimeout()
Returns
the driver login time limit
Description
Get the maximum time in seconds that all drivers can wait when attempting to log in to a database.


 DriverManager.getLogStream

DriverManager.getLogStream

Class Overview | Class Members | This Package | All Packages

Syntax
public static PrintStream getLogStream()
Returns
the logging/tracing PrintStream; if disabled, is null
Description
Get the logging/tracing PrintStream that is used by the DriverManager and all drivers.


 DriverManager.println

DriverManager.println

Class Overview | Class Members | This Package | All Packages

Syntax
public static void println( String message )
Parameters
message
a log or tracing message
Description
Print a message to the current JDBC log stream


 DriverManager.registerDriver

DriverManager.registerDriver

Class Overview | Class Members | This Package | All Packages

Syntax
public static synchronized void registerDriver( Driver driver ) throws SQLException
Parameters
driver
the new JDBC Driver
Description
A newly loaded driver class should call registerDriver to make itself known to the DriverManager.

Exceptions
SQLException if a database-access error occurs.


 DriverManager.setLoginTimeout

DriverManager.setLoginTimeout

Class Overview | Class Members | This Package | All Packages

Syntax
public static void setLoginTimeout( int seconds )
Parameters
seconds
the driver login time limit
Description
Set the maximum time in seconds that all drivers can wait when attempting to log in to a database.


 DriverManager.setLogStream

DriverManager.setLogStream

Class Overview | Class Members | This Package | All Packages

Syntax
public static void setLogStream( PrintStream out )
Parameters
out
the new logging/tracing PrintStream; to disable, set to null
Description
Set the logging/tracing PrintStream that is used by the DriverManager and all drivers.


 Class DriverPropertyInfo

Class java.sql.DriverPropertyInfo

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.sql.DriverPropertyInfo

public class DriverPropertyInfo
extends Object

The DriverPropertyInfo class is only of interest to advanced programmers who need to interact with a Driver via getDriverProperties to discover and supply properties for connections.


 DriverPropertyInfo Members

DriverPropertyInfo Members

Class Overview | This Package | All Packages

Fields
Name | Description
choices | If the value may be selected from a particular set of values, then this is an array of the possible values.
description | A brief description of the property.
name | The name of the property.
required | "required" is true if a value must be supplied for this property during Driver.connect.
value | "value" specifies the current value of the property, based on a combination of the information supplied to getPropertyInfo, the Java environment, and driver supplied default values.

Constructors
Name | Description
DriverPropertyInfo(String, String) | Constructor a DriverPropertyInfo with a name and value; other members default to their initial values.


 DriverPropertyInfo.choices

DriverPropertyInfo.choices

Class Overview | Class Members | This Package | All Packages

Syntax
public String choices[]
Description
If the value may be selected from a particular set of values, then this is an array of the possible values. Otherwise it should be null.


 DriverPropertyInfo.description

DriverPropertyInfo.description

Class Overview | Class Members | This Package | All Packages

Syntax
public String description
Description
A brief description of the property. This may be null.


 DriverPropertyInfo.name

DriverPropertyInfo.name

Class Overview | Class Members | This Package | All Packages

Syntax
public String name
Description
The name of the property.


 DriverPropertyInfo.required

DriverPropertyInfo.required

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean required
Description
"required" is true if a value must be supplied for this property during Driver.connect. Otherwise the property is optional.


 DriverPropertyInfo.value

DriverPropertyInfo.value

Class Overview | Class Members | This Package | All Packages

Syntax
public String value
Description
"value" specifies the current value of the property, based on a combination of the information supplied to getPropertyInfo, the Java environment, and driver supplied default values. This may be null if no value is known.


 DriverPropertyInfo.DriverPropertyInfo

DriverPropertyInfo.DriverPropertyInfo

Class Overview | Class Members | This Package | All Packages

Syntax
public DriverPropertyInfo( String name, String value )
Parameters
name
the name of the property
value
the current value, which may be null
Description
Constructor a DriverPropertyInfo with a name and value; other members default to their initial values.


 Interface PreparedStatement

Interface java.sql.PreparedStatement

Interface Members | This Package | All Packages

public interface PreparedStatement
extends Statement

A SQL statement is pre-compiled and stored in a PreparedStatement object. This object can then be used to efficiently execute this statement multiple times.

Note: The setXXX methods for setting IN parameter values must specify types that are compatible with the defined SQL type of the input parameter. For instance, if the IN parameter has SQL type Integer then setInt should be used.

If arbitrary parameter type conversions are required then the setObject method should be used with a target SQL type.

See Also:
prepareStatement, ResultSet


 PreparedStatement Members

PreparedStatement Members

Interface Overview | This Package | All Packages

Methods
Name | Description
clearParameters() | In general, parameter values remain in force for repeated use of a Statement.
execute() | Some prepared statements return multiple results; the execute method handles these complex statements as well as the simpler form of statements handled by executeQuery and executeUpdate.
executeQuery() | A prepared SQL query is executed and its ResultSet is returned.
executeUpdate() | Execute a SQL INSERT, UPDATE or DELETE statement.
setAsciiStream(int, InputStream, int) | When a very large ASCII value is input to a LONGVARCHAR parameter, it may be more practical to send it via a java.io.InputStream.
setBigDecimal(int, BigDecimal) | Set a parameter to a java.lang.BigDecimal value.
setBinaryStream(int, InputStream, int) | When a very large binary value is input to a LONGVARBINARY parameter, it may be more practical to send it via a java.io.InputStream.
setBoolean(int, boolean) | Set a parameter to a Java boolean value.
setByte(int, byte) | Set a parameter to a Java byte value.
setBytes(int, byte[]) | Set a parameter to a Java array of bytes.
setDate(int, Date) | Set a parameter to a java.sql.Date value.
setDouble(int, double) | Set a parameter to a Java double value.
setFloat(int, float) | Set a parameter to a Java float value.
setInt(int, int) | Set a parameter to a Java int value.
setLong(int, long) | Set a parameter to a Java long value.
setNull(int, int) | Set a parameter to SQL NULL.
setObject(int, Object) | Set the value of a parameter using an object; use the java.lang equivalent objects for integral values.
setObject(int, Object, int) | This method is like setObject above, but assumes a scale of zero.
setObject(int, Object, int, int) | Set the value of a parameter using an object; use the java.lang equivalent objects for integral values.
setShort(int, short) | Set a parameter to a Java short value.
setString(int, String) | Set a parameter to a Java String value.
setTime(int, Time) | Set a parameter to a java.sql.Time value.
setTimestamp(int, Timestamp) | Set a parameter to a java.sql.Timestamp value.
setUnicodeStream(int, InputStream, int) | When a very large UNICODE value is input to a LONGVARCHAR parameter, it may be more practical to send it via a java.io.InputStream.


 PreparedStatement.clearParameters

PreparedStatement.clearParameters

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void clearParameters() throws SQLException
Description

In general, parameter values remain in force for repeated use of a Statement. Setting a parameter value automatically clears its previous value. However, in some cases it is useful to immediately release the resources used by the current parameter values; this can be done by calling clearParameters.

Exceptions
SQLException if a database-access error occurs.


 PreparedStatement.execute

PreparedStatement.execute

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean execute() throws SQLException
Description
Some prepared statements return multiple results; the execute method handles these complex statements as well as the simpler form of statements handled by executeQuery and executeUpdate.

Exceptions
SQLException if a database-access error occurs.
See Also
execute


 PreparedStatement.executeQuery

PreparedStatement.executeQuery

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract ResultSet executeQuery() throws SQLException
Returns
a ResultSet that contains the data produced by the query; never null
Description
A prepared SQL query is executed and its ResultSet is returned.

Exceptions
SQLException if a database-access error occurs.


 PreparedStatement.executeUpdate

PreparedStatement.executeUpdate

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int executeUpdate() throws SQLException
Returns
either the row count for INSERT, UPDATE or DELETE; or 0 for SQL statements that return nothing
Description
Execute a SQL INSERT, UPDATE or DELETE statement. In addition, SQL statements that return nothing such as SQL DDL statements can be executed.

Exceptions
SQLException if a database-access error occurs.


 PreparedStatement.setAsciiStream

PreparedStatement.setAsciiStream

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setAsciiStream( int parameterIndex, InputStream x, int length ) throws SQLException
Parameters
parameterIndex
the first parameter is 1, the second is 2, ...
x
the java input stream which contains the ASCII parameter value
length
the number of bytes in the stream
Description
When a very large ASCII value is input to a LONGVARCHAR parameter, it may be more practical to send it via a java.io.InputStream. JDBC will read the data from the stream as needed, until it reaches end-of-file. The JDBC driver will do any necessary conversion from ASCII to the database char format.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Exceptions
SQLException if a database-access error occurs.


 PreparedStatement.setBigDecimal

PreparedStatement.setBigDecimal

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setBigDecimal( int parameterIndex, BigDecimal x ) throws SQLException
Parameters
parameterIndex
the first parameter is 1, the second is 2, ...
x
the parameter value
Description
Set a parameter to a java.lang.BigDecimal value. The driver converts this to a SQL NUMERIC value when it sends it to the database.

Exceptions
SQLException if a database-access error occurs.


 PreparedStatement.setBinaryStream

PreparedStatement.setBinaryStream

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setBinaryStream( int parameterIndex, InputStream x, int length ) throws SQLException
Parameters
parameterIndex
the first parameter is 1, the second is 2, ...
x
the java input stream which contains the binary parameter value
length
the number of bytes in the stream
Description
When a very large binary value is input to a LONGVARBINARY parameter, it may be more practical to send it via a java.io.InputStream. JDBC will read the data from the stream as needed, until it reaches end-of-file.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Exceptions
SQLException if a database-access error occurs.


 PreparedStatement.setBoolean

PreparedStatement.setBoolean

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setBoolean( int parameterIndex, boolean x ) throws SQLException
Parameters
parameterIndex
the first parameter is 1, the second is 2, ...
x
the parameter value
Description
Set a parameter to a Java boolean value. The driver converts this to a SQL BIT value when it sends it to the database.

Exceptions
SQLException if a database-access error occurs.


 PreparedStatement.setByte

PreparedStatement.setByte

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setByte( int parameterIndex, byte x ) throws SQLException
Parameters
parameterIndex
the first parameter is 1, the second is 2, ...
x
the parameter value
Description
Set a parameter to a Java byte value. The driver converts this to a SQL TINYINT value when it sends it to the database.

Exceptions
SQLException if a database-access error occurs.


 PreparedStatement.setBytes

PreparedStatement.setBytes

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setBytes( int parameterIndex, byte x[] ) throws SQLException
Parameters
parameterIndex
the first parameter is 1, the second is 2, ...
x
the parameter value
Description
Set a parameter to a Java array of bytes. The driver converts this to a SQL VARBINARY or LONGVARBINARY (depending on the argument's size relative to the driver's limits on VARBINARYs) when it sends it to the database.

Exceptions
SQLException if a database-access error occurs.


 PreparedStatement.setDate

PreparedStatement.setDate

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setDate( int parameterIndex, Date x ) throws SQLException
Parameters
parameterIndex
the first parameter is 1, the second is 2, ...
x
the parameter value
Description
Set a parameter to a java.sql.Date value. The driver converts this to a SQL DATE value when it sends it to the database.

Exceptions
SQLException if a database-access error occurs.


 PreparedStatement.setDouble

PreparedStatement.setDouble

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setDouble( int parameterIndex, double x ) throws SQLException
Parameters
parameterIndex
the first parameter is 1, the second is 2, ...
x
the parameter value
Description
Set a parameter to a Java double value. The driver converts this to a SQL DOUBLE value when it sends it to the database.

Exceptions
SQLException if a database-access error occurs.


 PreparedStatement.setFloat

PreparedStatement.setFloat

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setFloat( int parameterIndex, float x ) throws SQLException
Parameters
parameterIndex
the first parameter is 1, the second is 2, ...
x
the parameter value
Description
Set a parameter to a Java float value. The driver converts this to a SQL FLOAT value when it sends it to the database.

Exceptions
SQLException if a database-access error occurs.


 PreparedStatement.setInt

PreparedStatement.setInt

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setInt( int parameterIndex, int x ) throws SQLException
Parameters
parameterIndex
the first parameter is 1, the second is 2, ...
x
the parameter value
Description
Set a parameter to a Java int value. The driver converts this to a SQL INTEGER value when it sends it to the database.

Exceptions
SQLException if a database-access error occurs.


 PreparedStatement.setLong

PreparedStatement.setLong

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setLong( int parameterIndex, long x ) throws SQLException
Parameters
parameterIndex
the first parameter is 1, the second is 2, ...
x
the parameter value
Description
Set a parameter to a Java long value. The driver converts this to a SQL BIGINT value when it sends it to the database.

Exceptions
SQLException if a database-access error occurs.


 PreparedStatement.setNull

PreparedStatement.setNull

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setNull( int parameterIndex, int sqlType ) throws SQLException
Parameters
parameterIndex
the first parameter is 1, the second is 2, ...
sqlType
SQL type code defined by java.sql.Types
Description
Set a parameter to SQL NULL.

Note: You must specify the parameter's SQL type.

Exceptions
SQLException if a database-access error occurs.


 PreparedStatement.setObject

PreparedStatement.setObject

Interface Overview | Interface Members | This Package | All Packages

Syntax 1
public abstract void setObject( int parameterIndex, Object x, int targetSqlType, int scale ) throws SQLException
Parameters
parameterIndex
The first parameter is 1, the second is 2, ...
x
The object containing the input parameter value
targetSqlType
The SQL type (as defined in java.sql.Types) to be sent to the database. The scale argument may further qualify this type.
scale
For java.sql.Types.DECIMAL or java.sql.Types.NUMERIC types this is the number of digits after the decimal. For all other types this value will be ignored,
Description

Set the value of a parameter using an object; use the java.lang equivalent objects for integral values.

The given Java object will be converted to the targetSqlType before being sent to the database.

Note that this method may be used to pass datatabase- specific abstract data types. This is done by using a Driver- specific Java type and using a targetSqlType of java.sql.types.OTHER.

Exceptions
SQLException if a database-access error occurs.
See Also
Types

Syntax 2
public abstract void setObject( int parameterIndex, Object x, int targetSqlType ) throws SQLException
Description
This method is like setObject above, but assumes a scale of zero.

Exceptions
SQLException if a database-access error occurs.

Syntax 3
public abstract void setObject( int parameterIndex, Object x ) throws SQLException
Parameters
parameterIndex
The first parameter is 1, the second is 2, ...
x
The object containing the input parameter value
Description

Set the value of a parameter using an object; use the java.lang equivalent objects for integral values.

The JDBC specification specifies a standard mapping from Java Object types to SQL types. The given argument java object will be converted to the corresponding SQL type before being sent to the database.

Note that this method may be used to pass datatabase specific abstract data types, by using a Driver specific Java type.

Exceptions
SQLException if a database-access error occurs.


 PreparedStatement.setShort

PreparedStatement.setShort

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setShort( int parameterIndex, short x ) throws SQLException
Parameters
parameterIndex
the first parameter is 1, the second is 2, ...
x
the parameter value
Description
Set a parameter to a Java short value. The driver converts this to a SQL SMALLINT value when it sends it to the database.

Exceptions
SQLException if a database-access error occurs.


 PreparedStatement.setString

PreparedStatement.setString

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setString( int parameterIndex, String x ) throws SQLException
Parameters
parameterIndex
the first parameter is 1, the second is 2, ...
x
the parameter value
Description
Set a parameter to a Java String value. The driver converts this to a SQL VARCHAR or LONGVARCHAR value (depending on the arguments size relative to the driver's limits on VARCHARs) when it sends it to the database.

Exceptions
SQLException if a database-access error occurs.


 PreparedStatement.setTime

PreparedStatement.setTime

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setTime( int parameterIndex, Time x ) throws SQLException
Parameters
parameterIndex
the first parameter is 1, the second is 2, ...
x
the parameter value
Description
Set a parameter to a java.sql.Time value. The driver converts this to a SQL TIME value when it sends it to the database.

Exceptions
SQLException if a database-access error occurs.


 PreparedStatement.setTimestamp

PreparedStatement.setTimestamp

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setTimestamp( int parameterIndex, Timestamp x ) throws SQLException
Parameters
parameterIndex
the first parameter is 1, the second is 2, ...
x
the parameter value
Description
Set a parameter to a java.sql.Timestamp value. The driver converts this to a SQL TIMESTAMP value when it sends it to the database.

Exceptions
SQLException if a database-access error occurs.


 PreparedStatement.setUnicodeStream

PreparedStatement.setUnicodeStream

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setUnicodeStream( int parameterIndex, InputStream x, int length ) throws SQLException
Parameters
parameterIndex
the first parameter is 1, the second is 2, ...
x
the java input stream which contains the UNICODE parameter value
length
the number of bytes in the stream
Description
When a very large UNICODE value is input to a LONGVARCHAR parameter, it may be more practical to send it via a java.io.InputStream. JDBC will read the data from the stream as needed, until it reaches end-of-file. The JDBC driver will do any necessary conversion from UNICODE to the database char format.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Exceptions
SQLException if a database-access error occurs.


 Interface ResultSet

Interface java.sql.ResultSet

Interface Members | This Package | All Packages

public interface ResultSet

A ResultSet provides access to a table of data generated by executing a Statement. The table rows are retrieved in sequence. Within a row its column values can be accessed in any order.

A ResultSet maintains a cursor pointing to its current row of data. Initially the cursor is positioned before the first row. The 'next' method moves the cursor to the next row.

The getXXX methods retrieve column values for the current row. You can retrieve values either using the index number of the column, or by using the name of the column. In general using the column index will be more efficient. Columns are numbered from 1.

For maximum portability, ResultSet columns within each row should be read in left-to-right order and each column should be read only once.

For the getXXX methods, the JDBC driver attempts to convert the underlying data to the specified Java type and returns a suitable Java value. See the JDBC specification for allowable mappings from SQL types to Java types with the ResultSet.getXXX methods.

Column names used as input to getXXX methods are case insensitive. When performing a getXXX using a column name, if several columns have the same name, then the value of the first matching column will be returned. The column name option is designed to be used when column names are used in the SQL query. For columns that are NOT explicitly named in the query, it is best to use column numbers. If column names were used there is no way for the programmer to guarantee that they actually refer to the intended columns.

A ResultSet is automatically closed by the Statement that generated it when that Statement is closed, re-executed, or is used to retrieve the next result from a sequence of multiple results.

The number, types and properties of a ResultSet's columns are provided by the ResulSetMetaData object returned by the getMetaData method.

See Also:
executeQuery, getResultSet, ResultSetMetaData


 ResultSet Members

ResultSet Members

Interface Overview | This Package | All Packages

Methods
Name | Description
clearWarnings() | After this call getWarnings returns null until a new warning is reported for this ResultSet.
close() | In some cases, it is desirable to immediately release a ResultSet's database and JDBC resources instead of waiting for this to happen when it is automatically closed; the close method provides this immediate release.
findColumn(String) | Map a Resultset column name to a ResultSet column index.
getAsciiStream(int) | A column value can be retrieved as a stream of ASCII characters and then read in chunks from the stream.
getAsciiStream(String) | A column value can be retrieved as a stream of ASCII characters and then read in chunks from the stream.
getBigDecimal(int, int) | Get the value of a column in the current row as a java.lang.BigDecimal object.
getBigDecimal(String, int) | Get the value of a column in the current row as a java.lang.BigDecimal object.
getBinaryStream(int) | A column value can be retrieved as a stream of uninterpreted bytes and then read in chunks from the stream.
getBinaryStream(String) | A column value can be retrieved as a stream of uninterpreted bytes and then read in chunks from the stream.
getBoolean(int) | Get the value of a column in the current row as a Java boolean.
getBoolean(String) | Get the value of a column in the current row as a Java boolean.
getByte(int) | Get the value of a column in the current row as a Java byte.
getByte(String) | Get the value of a column in the current row as a Java byte.
getBytes(int) | Get the value of a column in the current row as a Java byte array.
getBytes(String) | Get the value of a column in the current row as a Java byte array.
getCursorName() | Get the name of the SQL cursor used by this ResultSet.
getDate(int) | Get the value of a column in the current row as a java.sql.Date object.
getDate(String) | Get the value of a column in the current row as a java.sql.Date object.
getDouble(int) | Get the value of a column in the current row as a Java double.
getDouble(String) | Get the value of a column in the current row as a Java double.
getFloat(int) | Get the value of a column in the current row as a Java float.
getFloat(String) | Get the value of a column in the current row as a Java float.
getInt(int) | Get the value of a column in the current row as a Java int.
getInt(String) | Get the value of a column in the current row as a Java int.
getLong(int) | Get the value of a column in the current row as a Java long.
getLong(String) | Get the value of a column in the current row as a Java long.
getMetaData() | The number, types and properties of a ResultSet's columns are provided by the getMetaData method.
getObject(int) | Get the value of a column in the current row as a Java object.
getObject(String) | Get the value of a column in the current row as a Java object.
getShort(int) | Get the value of a column in the current row as a Java short.
getShort(String) | Get the value of a column in the current row as a Java short.
getString(int) | Get the value of a column in the current row as a Java String.
getString(String) | Get the value of a column in the current row as a Java String.
getTime(int) | Get the value of a column in the current row as a java.sql.Time object.
getTime(String) | Get the value of a column in the current row as a java.sql.Time object.
getTimestamp(int) | Get the value of a column in the current row as a java.sql.Timestamp object.
getTimestamp(String) | Get the value of a column in the current row as a java.sql.Timestamp object.
getUnicodeStream(int) | A column value can be retrieved as a stream of Unicode characters and then read in chunks from the stream.
getUnicodeStream(String) | A column value can be retrieved as a stream of Unicode characters and then read in chunks from the stream.
getWarnings() | The first warning reported by calls on this ResultSet is returned.
next() | A ResultSet is initially positioned before its first row; the first call to next makes the first row the current row; the second call makes the second row the current row, etc.
wasNull() | A column may have the value of SQL NULL; wasNull reports whether the last column read had this special value.


 ResultSet.clearWarnings

ResultSet.clearWarnings

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void clearWarnings() throws SQLException
Description
After this call getWarnings returns null until a new warning is reported for this ResultSet.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.close

ResultSet.close

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void close() throws SQLException
Description
In some cases, it is desirable to immediately release a ResultSet's database and JDBC resources instead of waiting for this to happen when it is automatically closed; the close method provides this immediate release.

Note: A ResultSet is automatically closed by the Statement that generated it when that Statement is closed, re-executed, or is used to retrieve the next result from a sequence of multiple results. A ResultSet is also automatically closed when it is garbage collected.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.findColumn

ResultSet.findColumn

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int findColumn( String columnName ) throws SQLException
Parameters
columnName
the name of the column
Returns
the column index
Description
Map a Resultset column name to a ResultSet column index.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getAsciiStream

ResultSet.getAsciiStream

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract InputStream getAsciiStream( int columnIndex ) throws SQLException
Parameters
columnIndex
the first column is 1, the second is 2, ...
Returns
a Java input stream that delivers the database column value as a stream of one byte ASCII characters. If the value is SQL NULL then the result is null.
Description
A column value can be retrieved as a stream of ASCII characters and then read in chunks from the stream. This method is particularly suitable for retrieving large LONGVARCHAR values. The JDBC driver will do any necessary conversion from the database format into ASCII.

Note: All the data in the returned stream must be read prior to getting the value of any other column. The next call to a get method implicitly closes the stream. . Also, a stream may return 0 for available() whether there is data available or not.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getAsciiStream

ResultSet.getAsciiStream

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract InputStream getAsciiStream( String columnName ) throws SQLException
Parameters
columnName
is the SQL name of the column
Returns
a Java input stream that delivers the database column value as a stream of one byte ASCII characters. If the value is SQL NULL then the result is null.
Description
A column value can be retrieved as a stream of ASCII characters and then read in chunks from the stream. This method is particularly suitable for retrieving large LONGVARCHAR values. The JDBC driver will do any necessary conversion from the database format into ASCII.

Note: All the data in the returned stream must be read prior to getting the value of any other column. The next call to a get method implicitly closes the stream.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getBigDecimal

ResultSet.getBigDecimal

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract BigDecimal getBigDecimal( int columnIndex, int scale ) throws SQLException
Parameters
columnIndex
the first column is 1, the second is 2, ...
scale
the number of digits to the right of the decimal
Returns
the column value; if the value is SQL NULL, the result is null
Description
Get the value of a column in the current row as a java.lang.BigDecimal object.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getBigDecimal

ResultSet.getBigDecimal

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract BigDecimal getBigDecimal( String columnName, int scale ) throws SQLException
Parameters
columnName
is the SQL name of the column
scale
the number of digits to the right of the decimal
Returns
the column value; if the value is SQL NULL, the result is null
Description
Get the value of a column in the current row as a java.lang.BigDecimal object.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getBinaryStream

ResultSet.getBinaryStream

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract InputStream getBinaryStream( int columnIndex ) throws SQLException
Parameters
columnIndex
the first column is 1, the second is 2, ...
Returns
a Java input stream that delivers the database column value as a stream of uninterpreted bytes. If the value is SQL NULL then the result is null.
Description
A column value can be retrieved as a stream of uninterpreted bytes and then read in chunks from the stream. This method is particularly suitable for retrieving large LONGVARBINARY values.

Note: All the data in the returned stream must be read prior to getting the value of any other column. The next call to a get method implicitly closes the stream. Also, a stream may return 0 for available() whether there is data available or not.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getBinaryStream

ResultSet.getBinaryStream

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract InputStream getBinaryStream( String columnName ) throws SQLException
Parameters
columnName
is the SQL name of the column
Returns
a Java input stream that delivers the database column value as a stream of uninterpreted bytes. If the value is SQL NULL then the result is null.
Description
A column value can be retrieved as a stream of uninterpreted bytes and then read in chunks from the stream. This method is particularly suitable for retrieving large LONGVARBINARY values.

Note: All the data in the returned stream must be read prior to getting the value of any other column. The next call to a get method implicitly closes the stream.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getBoolean

ResultSet.getBoolean

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean getBoolean( int columnIndex ) throws SQLException
Parameters
columnIndex
the first column is 1, the second is 2, ...
Returns
the column value; if the value is SQL NULL, the result is false
Description
Get the value of a column in the current row as a Java boolean.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getBoolean

ResultSet.getBoolean

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean getBoolean( String columnName ) throws SQLException
Parameters
columnName
is the SQL name of the column
Returns
the column value; if the value is SQL NULL, the result is false
Description
Get the value of a column in the current row as a Java boolean.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getByte

ResultSet.getByte

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract byte getByte( int columnIndex ) throws SQLException
Parameters
columnIndex
the first column is 1, the second is 2, ...
Returns
the column value; if the value is SQL NULL, the result is 0
Description
Get the value of a column in the current row as a Java byte.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getByte

ResultSet.getByte

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract byte getByte( String columnName ) throws SQLException
Parameters
columnName
is the SQL name of the column
Returns
the column value; if the value is SQL NULL, the result is 0
Description
Get the value of a column in the current row as a Java byte.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getBytes

ResultSet.getBytes

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract byte[] getBytes( int columnIndex ) throws SQLException
Parameters
columnIndex
the first column is 1, the second is 2, ...
Returns
the column value; if the value is SQL NULL, the result is null
Description
Get the value of a column in the current row as a Java byte array. The bytes represent the raw values returned by the driver.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getBytes

ResultSet.getBytes

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract byte[] getBytes( String columnName ) throws SQLException
Parameters
columnName
is the SQL name of the column
Returns
the column value; if the value is SQL NULL, the result is null
Description
Get the value of a column in the current row as a Java byte array. The bytes represent the raw values returned by the driver.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getCursorName

ResultSet.getCursorName

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getCursorName() throws SQLException
Returns
the ResultSet's SQL cursor name
Description
Get the name of the SQL cursor used by this ResultSet.

In SQL, a result table is retrieved through a cursor that is named. The current row of a result can be updated or deleted using a positioned update/delete statement that references the cursor name.

JDBC supports this SQL feature by providing the name of the SQL cursor used by a ResultSet. The current row of a ResultSet is also the current row of this SQL cursor.

Note: If positioned update is not supported a SQLException is thrown

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getDate

ResultSet.getDate

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Date getDate( int columnIndex ) throws SQLException
Parameters
columnIndex
the first column is 1, the second is 2, ...
Returns
the column value; if the value is SQL NULL, the result is null
Description
Get the value of a column in the current row as a java.sql.Date object.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getDate

ResultSet.getDate

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Date getDate( String columnName ) throws SQLException
Parameters
columnName
is the SQL name of the column
Returns
the column value; if the value is SQL NULL, the result is null
Description
Get the value of a column in the current row as a java.sql.Date object.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getDouble

ResultSet.getDouble

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract double getDouble( int columnIndex ) throws SQLException
Parameters
columnIndex
the first column is 1, the second is 2, ...
Returns
the column value; if the value is SQL NULL, the result is 0
Description
Get the value of a column in the current row as a Java double.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getDouble

ResultSet.getDouble

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract double getDouble( String columnName ) throws SQLException
Parameters
columnName
is the SQL name of the column
Returns
the column value; if the value is SQL NULL, the result is 0
Description
Get the value of a column in the current row as a Java double.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getFloat

ResultSet.getFloat

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract float getFloat( int columnIndex ) throws SQLException
Parameters
columnIndex
the first column is 1, the second is 2, ...
Returns
the column value; if the value is SQL NULL, the result is 0
Description
Get the value of a column in the current row as a Java float.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getFloat

ResultSet.getFloat

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract float getFloat( String columnName ) throws SQLException
Parameters
columnName
is the SQL name of the column
Returns
the column value; if the value is SQL NULL, the result is 0
Description
Get the value of a column in the current row as a Java float.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getInt

ResultSet.getInt

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getInt( int columnIndex ) throws SQLException
Parameters
columnIndex
the first column is 1, the second is 2, ...
Returns
the column value; if the value is SQL NULL, the result is 0
Description
Get the value of a column in the current row as a Java int.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getInt

ResultSet.getInt

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getInt( String columnName ) throws SQLException
Parameters
columnName
is the SQL name of the column
Returns
the column value; if the value is SQL NULL, the result is 0
Description
Get the value of a column in the current row as a Java int.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getLong

ResultSet.getLong

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract long getLong( int columnIndex ) throws SQLException
Parameters
columnIndex
the first column is 1, the second is 2, ...
Returns
the column value; if the value is SQL NULL, the result is 0
Description
Get the value of a column in the current row as a Java long.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getLong

ResultSet.getLong

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract long getLong( String columnName ) throws SQLException
Parameters
columnName
is the SQL name of the column
Returns
the column value; if the value is SQL NULL, the result is 0
Description
Get the value of a column in the current row as a Java long.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getMetaData

ResultSet.getMetaData

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract ResultSetMetaData getMetaData() throws SQLException
Returns
the description of a ResultSet's columns
Description
The number, types and properties of a ResultSet's columns are provided by the getMetaData method.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getObject

ResultSet.getObject

Interface Overview | Interface Members | This Package | All Packages

Syntax 1
public abstract Object getObject( int columnIndex ) throws SQLException
Parameters
columnIndex
the first column is 1, the second is 2, ...
Returns
A java.lang.Object holding the column value.
Description

Get the value of a column in the current row as a Java object.

This method will return the value of the given column as a Java object. The type of the Java object will be the default Java Object type corresponding to the column's SQL type, following the mapping specified in the JDBC spec.

This method may also be used to read datatabase specific abstract data types.

Exceptions
SQLException if a database-access error occurs.

Syntax 2
public abstract Object getObject( String columnName ) throws SQLException
Parameters
columnName
is the SQL name of the column
Returns
A java.lang.Object holding the column value.
Description

Get the value of a column in the current row as a Java object.

This method will return the value of the given column as a Java object. The type of the Java object will be the default Java Object type corresponding to the column's SQL type, following the mapping specified in the JDBC spec.

This method may also be used to read datatabase specific abstract data types.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getShort

ResultSet.getShort

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract short getShort( int columnIndex ) throws SQLException
Parameters
columnIndex
the first column is 1, the second is 2, ...
Returns
the column value; if the value is SQL NULL, the result is 0
Description
Get the value of a column in the current row as a Java short.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getShort

ResultSet.getShort

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract short getShort( String columnName ) throws SQLException
Parameters
columnName
is the SQL name of the column
Returns
the column value; if the value is SQL NULL, the result is 0
Description
Get the value of a column in the current row as a Java short.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getString

ResultSet.getString

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getString( int columnIndex ) throws SQLException
Parameters
columnIndex
the first column is 1, the second is 2, ...
Returns
the column value; if the value is SQL NULL, the result is null
Description
Get the value of a column in the current row as a Java String.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getString

ResultSet.getString

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getString( String columnName ) throws SQLException
Parameters
columnName
is the SQL name of the column
Returns
the column value; if the value is SQL NULL, the result is null
Description
Get the value of a column in the current row as a Java String.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getTime

ResultSet.getTime

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Time getTime( int columnIndex ) throws SQLException
Parameters
columnIndex
the first column is 1, the second is 2, ...
Returns
the column value; if the value is SQL NULL, the result is null
Description
Get the value of a column in the current row as a java.sql.Time object.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getTime

ResultSet.getTime

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Time getTime( String columnName ) throws SQLException
Parameters
columnName
is the SQL name of the column
Returns
the column value; if the value is SQL NULL, the result is null
Description
Get the value of a column in the current row as a java.sql.Time object.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getTimestamp

ResultSet.getTimestamp

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Timestamp getTimestamp( int columnIndex ) throws SQLException
Parameters
columnIndex
the first column is 1, the second is 2, ...
Returns
the column value; if the value is SQL NULL, the result is null
Description
Get the value of a column in the current row as a java.sql.Timestamp object.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getTimestamp

ResultSet.getTimestamp

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Timestamp getTimestamp( String columnName ) throws SQLException
Parameters
columnName
is the SQL name of the column
Returns
the column value; if the value is SQL NULL, the result is null
Description
Get the value of a column in the current row as a java.sql.Timestamp object.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getUnicodeStream

ResultSet.getUnicodeStream

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract InputStream getUnicodeStream( int columnIndex ) throws SQLException
Parameters
columnIndex
the first column is 1, the second is 2, ...
Returns
a Java input stream that delivers the database column value as a stream of two byte Unicode characters. If the value is SQL NULL then the result is null.
Description
A column value can be retrieved as a stream of Unicode characters and then read in chunks from the stream. This method is particularly suitable for retrieving large LONGVARCHAR values. The JDBC driver will do any necessary conversion from the database format into Unicode.

Note: All the data in the returned stream must be read prior to getting the value of any other column. The next call to a get method implicitly closes the stream. . Also, a stream may return 0 for available() whether there is data available or not.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getUnicodeStream

ResultSet.getUnicodeStream

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract InputStream getUnicodeStream( String columnName ) throws SQLException
Parameters
columnName
is the SQL name of the column
Returns
a Java input stream that delivers the database column value as a stream of two byte Unicode characters. If the value is SQL NULL then the result is null.
Description
A column value can be retrieved as a stream of Unicode characters and then read in chunks from the stream. This method is particularly suitable for retrieving large LONGVARCHAR values. The JDBC driver will do any necessary conversion from the database format into Unicode.

Note: All the data in the returned stream must be read prior to getting the value of any other column. The next call to a get method implicitly closes the stream.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.getWarnings

ResultSet.getWarnings

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract SQLWarning getWarnings() throws SQLException
Returns
the first SQLWarning or null
Description

The first warning reported by calls on this ResultSet is returned. Subsequent ResultSet warnings will be chained to this SQLWarning.

The warning chain is automatically cleared each time a new row is read.

Note: This warning chain only covers warnings caused by ResultSet methods. Any warning caused by statement methods (such as reading OUT parameters) will be chained on the Statement object.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.next

ResultSet.next

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean next() throws SQLException
Returns
true if the new current row is valid; false if there are no more rows
Description
A ResultSet is initially positioned before its first row; the first call to next makes the first row the current row; the second call makes the second row the current row, etc.

If an input stream from the previous row is open, it is implicitly closed. The ResultSet's warning chain is cleared when a new row is read.

Exceptions
SQLException if a database-access error occurs.


 ResultSet.wasNull

ResultSet.wasNull

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean wasNull() throws SQLException
Returns
true if last column read was SQL NULL
Description
A column may have the value of SQL NULL; wasNull reports whether the last column read had this special value. Note that you must first call getXXX on a column to try to read its value and then call wasNull() to find if the value was the SQL NULL.

Exceptions
SQLException if a database-access error occurs.


 Interface ResultSetMetaData

Interface java.sql.ResultSetMetaData

Interface Members | This Package | All Packages

public interface ResultSetMetaData

A ResultSetMetaData object can be used to find out about the types and properties of the columns in a ResultSet.


 ResultSetMetaData Members

ResultSetMetaData Members

Interface Overview | This Package | All Packages

Fields
Name | Description
columnNoNulls | Does not allow NULL values.
columnNullable | Allows NULL values.
columnNullableUnknown | Nullability unknown.

Methods
Name | Description
getCatalogName(int) | What's a column's table's catalog name?
getColumnCount() | What's the number of columns in the ResultSet?
getColumnDisplaySize(int) | What's the column's normal max width in chars?
getColumnLabel(int) | What's the suggested column title for use in printouts and displays?
getColumnName(int) | What's a column's name?
getColumnType(int) | What's a column's SQL type?
getColumnTypeName(int) | What's a column's data source specific type name?
getPrecision(int) | What's a column's number of decimal digits?
getScale(int) | What's a column's number of digits to right of the decimal point?
getSchemaName(int) | What's a column's table's schema?
getTableName(int) | What's a column's table name?
isAutoIncrement(int) | Is the column automatically numbered, thus read-only?
isCaseSensitive(int) | Does a column's case matter?
isCurrency(int) | Is the column a cash value?
isDefinitelyWritable(int) | Will a write on the column definitely succeed?
isNullable(int) | Can you put a NULL in this column?
isReadOnly(int) | Is a column definitely not writable?
isSearchable(int) | Can the column be used in a where clause?
isSigned(int) | Is the column a signed number?
isWritable(int) | Is it possible for a write on the column to succeed?


 ResultSetMetaData.columnNoNulls

ResultSetMetaData.columnNoNulls

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int columnNoNulls
Description
Does not allow NULL values.


 ResultSetMetaData.columnNullable

ResultSetMetaData.columnNullable

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int columnNullable
Description
Allows NULL values.


 ResultSetMetaData.columnNullableUnknown

ResultSetMetaData.columnNullableUnknown

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final int columnNullableUnknown
Description
Nullability unknown.


 ResultSetMetaData.getCatalogName

ResultSetMetaData.getCatalogName

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getCatalogName( int column ) throws SQLException
Parameters
column
the first column is 1, the second is 2, ...
Returns
column name or "" if not applicable.
Description
What's a column's table's catalog name?

Exceptions
SQLException if a database-access error occurs.


 ResultSetMetaData.getColumnCount

ResultSetMetaData.getColumnCount

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getColumnCount() throws SQLException
Returns
the number
Description
What's the number of columns in the ResultSet?

Exceptions
SQLException if a database-access error occurs.


 ResultSetMetaData.getColumnDisplaySize

ResultSetMetaData.getColumnDisplaySize

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getColumnDisplaySize( int column ) throws SQLException
Parameters
column
the first column is 1, the second is 2, ...
Returns
max width
Description
What's the column's normal max width in chars?

Exceptions
SQLException if a database-access error occurs.


 ResultSetMetaData.getColumnLabel

ResultSetMetaData.getColumnLabel

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getColumnLabel( int column ) throws SQLException
Parameters
column
the first column is 1, the second is 2, ...
Returns
true if so
Description
What's the suggested column title for use in printouts and displays?

Exceptions
SQLException if a database-access error occurs.


 ResultSetMetaData.getColumnName

ResultSetMetaData.getColumnName

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getColumnName( int column ) throws SQLException
Parameters
column
the first column is 1, the second is 2, ...
Returns
column name
Description
What's a column's name?

Exceptions
SQLException if a database-access error occurs.


 ResultSetMetaData.getColumnType

ResultSetMetaData.getColumnType

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getColumnType( int column ) throws SQLException
Parameters
column
the first column is 1, the second is 2, ...
Returns
SQL type
Description
What's a column's SQL type?

Exceptions
SQLException if a database-access error occurs.
See Also
Types


 ResultSetMetaData.getColumnTypeName

ResultSetMetaData.getColumnTypeName

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getColumnTypeName( int column ) throws SQLException
Parameters
column
the first column is 1, the second is 2, ...
Returns
type name
Description
What's a column's data source specific type name?

Exceptions
SQLException if a database-access error occurs.


 ResultSetMetaData.getPrecision

ResultSetMetaData.getPrecision

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getPrecision( int column ) throws SQLException
Parameters
column
the first column is 1, the second is 2, ...
Returns
precision
Description
What's a column's number of decimal digits?

Exceptions
SQLException if a database-access error occurs.


 ResultSetMetaData.getScale

ResultSetMetaData.getScale

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getScale( int column ) throws SQLException
Parameters
column
the first column is 1, the second is 2, ...
Returns
scale
Description
What's a column's number of digits to right of the decimal point?

Exceptions
SQLException if a database-access error occurs.


 ResultSetMetaData.getSchemaName

ResultSetMetaData.getSchemaName

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getSchemaName( int column ) throws SQLException
Parameters
column
the first column is 1, the second is 2, ...
Returns
schema name or "" if not applicable
Description
What's a column's table's schema?

Exceptions
SQLException if a database-access error occurs.


 ResultSetMetaData.getTableName

ResultSetMetaData.getTableName

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract String getTableName( int column ) throws SQLException
Returns
table name or "" if not applicable
Description
What's a column's table name?

Exceptions
SQLException if a database-access error occurs.


 ResultSetMetaData.isAutoIncrement

ResultSetMetaData.isAutoIncrement

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean isAutoIncrement( int column ) throws SQLException
Parameters
column
the first column is 1, the second is 2, ...
Returns
true if so
Description
Is the column automatically numbered, thus read-only?

Exceptions
SQLException if a database-access error occurs.


 ResultSetMetaData.isCaseSensitive

ResultSetMetaData.isCaseSensitive

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean isCaseSensitive( int column ) throws SQLException
Parameters
column
the first column is 1, the second is 2, ...
Returns
true if so
Description
Does a column's case matter?

Exceptions
SQLException if a database-access error occurs.


 ResultSetMetaData.isCurrency

ResultSetMetaData.isCurrency

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean isCurrency( int column ) throws SQLException
Parameters
column
the first column is 1, the second is 2, ...
Returns
true if so
Description
Is the column a cash value?

Exceptions
SQLException if a database-access error occurs.


 ResultSetMetaData.isDefinitelyWritable

ResultSetMetaData.isDefinitelyWritable

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean isDefinitelyWritable( int column ) throws SQLException
Parameters
column
the first column is 1, the second is 2, ...
Returns
true if so
Description
Will a write on the column definitely succeed?

Exceptions
SQLException if a database-access error occurs.


 ResultSetMetaData.isNullable

ResultSetMetaData.isNullable

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int isNullable( int column ) throws SQLException
Parameters
column
the first column is 1, the second is 2, ...
Returns
columnNoNulls, columnNullable or columnNullableUnknown
Description
Can you put a NULL in this column?

Exceptions
SQLException if a database-access error occurs.


 ResultSetMetaData.isReadOnly

ResultSetMetaData.isReadOnly

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean isReadOnly( int column ) throws SQLException
Parameters
column
the first column is 1, the second is 2, ...
Returns
true if so
Description
Is a column definitely not writable?

Exceptions
SQLException if a database-access error occurs.


 ResultSetMetaData.isSearchable

ResultSetMetaData.isSearchable

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean isSearchable( int column ) throws SQLException
Parameters
column
the first column is 1, the second is 2, ...
Returns
true if so
Description
Can the column be used in a where clause?

Exceptions
SQLException if a database-access error occurs.


 ResultSetMetaData.isSigned

ResultSetMetaData.isSigned

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean isSigned( int column ) throws SQLException
Parameters
column
the first column is 1, the second is 2, ...
Returns
true if so
Description
Is the column a signed number?

Exceptions
SQLException if a database-access error occurs.


 ResultSetMetaData.isWritable

ResultSetMetaData.isWritable

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean isWritable( int column ) throws SQLException
Parameters
column
the first column is 1, the second is 2, ...
Returns
true if so
Description
Is it possible for a write on the column to succeed?

Exceptions
SQLException if a database-access error occurs.


 Class SQLException

Class java.sql.SQLException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.sql.SQLException

public class SQLException
extends Exception

The SQLException class provides information on a database access error.

Each SQLException provides several kinds of information:

  • a string describing the error. This is used as the Java Exception message, and is available via the getMesage() method
  • A "SQLstate" string which follows the XOPEN SQLstate conventions. The values of the SQLState string as described in the XOPEN SQL spec.
  • An integer error code that is vendor specific. Normally this will be the actual error code returned by the underlying database.
  • A chain to a next Exception. This can be used to provided additional error information.


 SQLException Members

SQLException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
SQLException() | Construct an SQLException; reason defaults to null, SQLState defaults to null and vendorCode defaults to 0.
SQLException(String) | Construct an SQLException with a reason; SQLState defaults to null and vendorCode defaults to 0.
SQLException(String, String) | Construct an SQLException with a reason and SQLState; vendorCode defaults to 0.
SQLException(String, String, int) | Construct a fully-specified SQLException

Methods
Name | Description
getErrorCode() | Get the vendor specific exception code
getNextException() | Get the exception chained to this one.
getSQLState() | Get the SQLState
setNextException(SQLException) | Add an SQLException to the end of the chain.


 SQLException.SQLException

SQLException.SQLException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public SQLException( String reason, String SQLState, int vendorCode )
Parameters
reason
a description of the exception
SQLState
an XOPEN code identifying the exception
vendorCode
a database vendor specific exception code
Description
Construct a fully-specified SQLException

Syntax 2
public SQLException( String reason, String SQLState )
Parameters
reason
a description of the exception
SQLState
an XOPEN code identifying the exception
Description
Construct an SQLException with a reason and SQLState; vendorCode defaults to 0.

Syntax 3
public SQLException( String reason )
Parameters
reason
a description of the exception
Description
Construct an SQLException with a reason; SQLState defaults to null and vendorCode defaults to 0.

Syntax 4
public SQLException()
Description
Construct an SQLException; reason defaults to null, SQLState defaults to null and vendorCode defaults to 0.


 SQLException.getErrorCode

SQLException.getErrorCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int getErrorCode()
Returns
the vendor's error code
Description
Get the vendor specific exception code


 SQLException.getNextException

SQLException.getNextException

Class Overview | Class Members | This Package | All Packages

Syntax
public SQLException getNextException()
Returns
the next SQLException in the chain, null if none
Description
Get the exception chained to this one.


 SQLException.getSQLState

SQLException.getSQLState

Class Overview | Class Members | This Package | All Packages

Syntax
public String getSQLState()
Returns
the SQLState value
Description
Get the SQLState


 SQLException.setNextException

SQLException.setNextException

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setNextException( SQLException ex )
Parameters
ex
the new end of the SQLException chain
Description
Add an SQLException to the end of the chain.


 Class SQLWarning

Class java.sql.SQLWarning

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.sql.SQLException
                           |
                           +----java.sql.SQLWarning

public class SQLWarning
extends SQLException

The SQLWarning class provides information on a database access warnings. Warnings are silently chained to the object whose method caused it to be reported.

See Also:
getWarnings, getWarnings, getWarnings


 SQLWarning Members

SQLWarning Members

Class Overview | This Package | All Packages

Constructors
Name | Description
SQLWarning() | Construct an SQLWarning ; reason defaults to null, SQLState defaults to null and vendorCode defaults to 0.
SQLWarning(String) | Construct an SQLWarning with a reason; SQLState defaults to null and vendorCode defaults to 0.
SQLWarning(String, String) | Construct an SQLWarning with a reason and SQLState; vendorCode defaults to 0.
SQLWarning(String, String, int) | Construct a fully specified SQLWarning.

Methods
Name | Description
getNextWarning() | Get the warning chained to this one
setNextWarning(SQLWarning) | Add an SQLWarning to the end of the chain.


 SQLWarning.SQLWarning

SQLWarning.SQLWarning

Class Overview | Class Members | This Package | All Packages

Syntax 1
public SQLWarning( String reason, String SQLstate, int vendorCode )
Parameters
reason
a description of the warning
SQLState
an XOPEN code identifying the warning
vendorCode
a database vendor specific warning code
Description
Construct a fully specified SQLWarning.

Syntax 2
public SQLWarning( String reason, String SQLstate )
Parameters
reason
a description of the warning
SQLState
an XOPEN code identifying the warning
Description
Construct an SQLWarning with a reason and SQLState; vendorCode defaults to 0.

Syntax 3
public SQLWarning( String reason )
Parameters
reason
a description of the warning
Description
Construct an SQLWarning with a reason; SQLState defaults to null and vendorCode defaults to 0.

Syntax 4
public SQLWarning()
Description
Construct an SQLWarning ; reason defaults to null, SQLState defaults to null and vendorCode defaults to 0.


 SQLWarning.getNextWarning

SQLWarning.getNextWarning

Class Overview | Class Members | This Package | All Packages

Syntax
public SQLWarning getNextWarning()
Returns
the next SQLException in the chain, null if none
Description
Get the warning chained to this one


 SQLWarning.setNextWarning

SQLWarning.setNextWarning

Class Overview | Class Members | This Package | All Packages

Syntax
public void setNextWarning( SQLWarning w )
Parameters
w
the new end of the SQLException chain
Description
Add an SQLWarning to the end of the chain.


 Interface Statement

Interface java.sql.Statement

Interface Members | This Package | All Packages

public interface Statement

A Statement object is used for executing a static SQL statement and obtaining the results produced by it.

Only one ResultSet per Statement can be open at any point in time. Therefore, if the reading of one ResultSet is interleaved with the reading of another, each must have been generated by different Statements. All statement execute methods implicitly close a statment's current ResultSet if an open one exists.

See Also:
createStatement, ResultSet


 Statement Members

Statement Members

Interface Overview | This Package | All Packages

Methods
Name | Description
cancel() | Cancel can be used by one thread to cancel a statement that is being executed by another thread.
clearWarnings() | After this call, getWarnings returns null until a new warning is reported for this Statement.
close() | In many cases, it is desirable to immediately release a Statements's database and JDBC resources instead of waiting for this to happen when it is automatically closed; the close method provides this immediate release.
execute(String) | Execute a SQL statement that may return multiple results.
executeQuery(String) | Execute a SQL statement that returns a single ResultSet.
executeUpdate(String) | Execute a SQL INSERT, UPDATE or DELETE statement.
getMaxFieldSize() | The maxFieldSize limit (in bytes) is the maximum amount of data returned for any column value; it only applies to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR columns.
getMaxRows() | The maxRows limit is the maximum number of rows that a ResultSet can contain.
getMoreResults() | getMoreResults moves to a Statement's next result.
getQueryTimeout() | The queryTimeout limit is the number of seconds the driver will wait for a Statement to execute.
getResultSet() | getResultSet returns the current result as a ResultSet.
getUpdateCount() | getUpdateCount returns the current result as an update count; if the result is a ResultSet or there are no more results, -1 is returned.
getWarnings() | The first warning reported by calls on this Statement is returned.
setCursorName(String) | setCursorname defines the SQL cursor name that will be used by subsequent Statement execute methods.
setEscapeProcessing(boolean) | If escape scanning is on (the default), the driver will do escape substitution before sending the SQL to the database.
setMaxFieldSize(int) | The maxFieldSize limit (in bytes) is set to limit the size of data that can be returned for any column value; it only applies to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR fields.
setMaxRows(int) | The maxRows limit is set to limit the number of rows that any ResultSet can contain.
setQueryTimeout(int) | The queryTimeout limit is the number of seconds the driver will wait for a Statement to execute.


 Statement.cancel

Statement.cancel

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void cancel() throws SQLException
Description
Cancel can be used by one thread to cancel a statement that is being executed by another thread.

Exceptions
SQLException if a database-access error occurs.


 Statement.clearWarnings

Statement.clearWarnings

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void clearWarnings() throws SQLException
Description
After this call, getWarnings returns null until a new warning is reported for this Statement.

Exceptions
SQLException if a database-access error occurs.


 Statement.close

Statement.close

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void close() throws SQLException
Description
In many cases, it is desirable to immediately release a Statements's database and JDBC resources instead of waiting for this to happen when it is automatically closed; the close method provides this immediate release.

Note: A Statement is automatically closed when it is garbage collected. When a Statement is closed, its current ResultSet, if one exists, is also closed.

Exceptions
SQLException if a database-access error occurs.


 Statement.execute

Statement.execute

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean execute( String sql ) throws SQLException
Parameters
sql
any SQL statement
Returns
true if the next result is a ResultSet; false if it is an update count or there are no more results
Description
Execute a SQL statement that may return multiple results. Under some (uncommon) situations a single SQL statement may return multiple result sets and/or update counts. Normally you can ignore this, unless you're executing a stored procedure that you know may return multiple results, or unless you're dynamically executing an unknown SQL string. The "execute", "getMoreResults", "getResultSet" and "getUpdateCount" methods let you navigate through multiple results. The "execute" method executes a SQL statement and indicates the form of the first result. You can then use getResultSet or getUpdateCount to retrieve the result, and getMoreResults to move to any subsequent result(s).

Exceptions
SQLException if a database-access error occurs.
See Also
getResultSet, getUpdateCount, getMoreResults


 Statement.executeQuery

Statement.executeQuery

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract ResultSet executeQuery( String sql ) throws SQLException
Parameters
sql
typically this is a static SQL SELECT statement
Returns
a ResultSet that contains the data produced by the query; never null
Description
Execute a SQL statement that returns a single ResultSet.

Exceptions
SQLException if a database-access error occurs.


 Statement.executeUpdate

Statement.executeUpdate

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int executeUpdate( String sql ) throws SQLException
Parameters
sql
a SQL INSERT, UPDATE or DELETE statement or a SQL statement that returns nothing
Returns
either the row count for INSERT, UPDATE or DELETE or 0 for SQL statements that return nothing
Description
Execute a SQL INSERT, UPDATE or DELETE statement. In addition, SQL statements that return nothing such as SQL DDL statements can be executed.

Exceptions
SQLException if a database-access error occurs.


 Statement.getMaxFieldSize

Statement.getMaxFieldSize

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getMaxFieldSize() throws SQLException
Returns
the current max column size limit; zero means unlimited
Description
The maxFieldSize limit (in bytes) is the maximum amount of data returned for any column value; it only applies to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR columns. If the limit is exceeded, the excess data is silently discarded.

Exceptions
SQLException if a database-access error occurs.


 Statement.getMaxRows

Statement.getMaxRows

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getMaxRows() throws SQLException
Returns
the current max row limit; zero means unlimited
Description
The maxRows limit is the maximum number of rows that a ResultSet can contain. If the limit is exceeded, the excess rows are silently dropped.

Exceptions
SQLException if a database-access error occurs.


 Statement.getMoreResults

Statement.getMoreResults

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean getMoreResults() throws SQLException
Returns
true if the next result is a ResultSet; false if it is an update count or there are no more results
Description
getMoreResults moves to a Statement's next result. It returns true if this result is a ResultSet. getMoreResults also implicitly closes any current ResultSet obtained with getResultSet. There are no more results when (!getMoreResults() && (getUpdateCount() == -1)

Exceptions
SQLException if a database-access error occurs.
See Also
execute


 Statement.getQueryTimeout

Statement.getQueryTimeout

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getQueryTimeout() throws SQLException
Returns
the current query timeout limit in seconds; zero means unlimited
Description
The queryTimeout limit is the number of seconds the driver will wait for a Statement to execute. If the limit is exceeded, a SQLException is thrown.

Exceptions
SQLException if a database-access error occurs.


 Statement.getResultSet

Statement.getResultSet

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract ResultSet getResultSet() throws SQLException
Returns
the current result as a ResultSet; null if the result is an update count or there are no more results
Description
getResultSet returns the current result as a ResultSet. It should only be called once per result.

Exceptions
SQLException if a database-access error occurs.
See Also
execute


 Statement.getUpdateCount

Statement.getUpdateCount

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getUpdateCount() throws SQLException
Returns
the current result as an update count; -1 if it is a ResultSet or there are no more results
Description
getUpdateCount returns the current result as an update count; if the result is a ResultSet or there are no more results, -1 is returned. It should only be called once per result.

Exceptions
SQLException if a database-access error occurs.
See Also
execute


 Statement.getWarnings

Statement.getWarnings

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract SQLWarning getWarnings() throws SQLException
Returns
the first SQLWarning or null
Description
The first warning reported by calls on this Statement is returned. A Statment's execute methods clear its SQLWarning chain. Subsequent Statement warnings will be chained to this SQLWarning.

The warning chain is automatically cleared each time a statement is (re)executed.

Note: If you are processing a ResultSet then any warnings associated with ResultSet reads will be chained on the ResultSet object.

Exceptions
SQLException if a database-access error occurs.


 Statement.setCursorName

Statement.setCursorName

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setCursorName( String name ) throws SQLException
Parameters
name
the new cursor name.
Description
setCursorname defines the SQL cursor name that will be used by subsequent Statement execute methods. This name can then be used in SQL positioned update/delete statements to identify the current row in the ResultSet generated by this statement. If the database doesn't support positioned update/delete, this method is a noop.

Note: By definition, positioned update/delete execution must be done by a different Statement than the one which generated the ResultSet being used for positioning. Also, cursor names must be unique within a Connection.

Exceptions
SQLException if a database-access error occurs.


 Statement.setEscapeProcessing

Statement.setEscapeProcessing

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setEscapeProcessing( boolean enable ) throws SQLException
Parameters
enable
true to enable; false to disable
Description
If escape scanning is on (the default), the driver will do escape substitution before sending the SQL to the database. Note: Since prepared statements have usually been parsed prior to making this call, disabling escape processing for prepared statements will like have no affect.

Exceptions
SQLException if a database-access error occurs.


 Statement.setMaxFieldSize

Statement.setMaxFieldSize

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setMaxFieldSize( int max ) throws SQLException
Parameters
max
the new max column size limit; zero means unlimited
Description
The maxFieldSize limit (in bytes) is set to limit the size of data that can be returned for any column value; it only applies to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR fields. If the limit is exceeded, the excess data is silently discarded. For maximum portability use values greater than 256.

Exceptions
SQLException if a database-access error occurs.


 Statement.setMaxRows

Statement.setMaxRows

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setMaxRows( int max ) throws SQLException
Parameters
max
the new max rows limit; zero means unlimited
Description
The maxRows limit is set to limit the number of rows that any ResultSet can contain. If the limit is exceeded, the excess rows are silently dropped.

Exceptions
SQLException if a database-access error occurs.


 Statement.setQueryTimeout

Statement.setQueryTimeout

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void setQueryTimeout( int seconds ) throws SQLException
Parameters
seconds
the new query timeout limit in seconds; zero means unlimited
Description
The queryTimeout limit is the number of seconds the driver will wait for a Statement to execute. If the limit is exceeded, a SQLException is thrown.

Exceptions
SQLException if a database-access error occurs.


 Class Time

Class java.sql.Time

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.Date
           |
           +----java.sql.Time

public class Time
extends Date

This class is a thin wrapper around java.util.Date that allows JDBC to identify this as a SQL TIME value. It adds formatting and parsing operations to support the JDBC escape syntax for time values.


 Time Members

Time Members

Class Overview | This Package | All Packages

Constructors
Name | Description
Time(int, int, int) | Construct a Time Object
Time(long) | Construct a Time using a milliseconds time value

Methods
Name | Description
getDate() | Returns the day of the month represented by this date.
getDay() | Returns the day of the week represented by this date.
getMonth() | Returns the month represented by this date.
getYear() | Returns the year represented by this date, minus 1900.
setDate(int) | Sets the day of the month of this date to the specified value.
setMonth(int) | Sets the month of this date to the specified value.
setTime(long) | Set a Time using a milliseconds time value
setYear(int) | Sets the year of this date to be the specified value plus 1900.
toString() | Format a time in JDBC date escape format
valueOf(String) | Convert a string in JDBC time escape format to a Time value


 Time.Time

Time.Time

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Time( int hour, int minute, int second )
Parameters
hour
0 to 23
minute
0 to 59
second
0 to 59
Description
Construct a Time Object

Syntax 2
public Time( long time )
Parameters
time
milliseconds since January 1, 1970, 00:00:00 GMT
Description
Construct a Time using a milliseconds time value


 Time.getDate

Time.getDate

Class Overview | Class Members | This Package | All Packages

Syntax
public int getDate()
Description
Returns the day of the month represented by this date.

Overrides
getDate in class Date


 Time.getDay

Time.getDay

Class Overview | Class Members | This Package | All Packages

Syntax
public int getDay()
Description
Returns the day of the week represented by this date.

Overrides
getDay in class Date


 Time.getMonth

Time.getMonth

Class Overview | Class Members | This Package | All Packages

Syntax
public int getMonth()
Description
Returns the month represented by this date.

Overrides
getMonth in class Date


 Time.getYear

Time.getYear

Class Overview | Class Members | This Package | All Packages

Syntax
public int getYear()
Description
Returns the year represented by this date, minus 1900.

Overrides
getYear in class Date


 Time.setDate

Time.setDate

Class Overview | Class Members | This Package | All Packages

Syntax
public void setDate( int i )
Description
Sets the day of the month of this date to the specified value.

Overrides
setDate in class Date


 Time.setMonth

Time.setMonth

Class Overview | Class Members | This Package | All Packages

Syntax
public void setMonth( int i )
Description
Sets the month of this date to the specified value.

Overrides
setMonth in class Date


 Time.setTime

Time.setTime

Class Overview | Class Members | This Package | All Packages

Syntax
public void setTime( long time )
Parameters
time
milliseconds since January 1, 1970, 00:00:00 GMT
Description
Set a Time using a milliseconds time value

Overrides
setTime in class Date


 Time.setYear

Time.setYear

Class Overview | Class Members | This Package | All Packages

Syntax
public void setYear( int i )
Description
Sets the year of this date to be the specified value plus 1900.

Overrides
setYear in class Date


 Time.toString

Time.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a String in hh:mm:ss format
Description
Format a time in JDBC date escape format

Overrides
toString in class Date


 Time.valueOf

Time.valueOf

Class Overview | Class Members | This Package | All Packages

Syntax
public static Time valueOf( String s )
Parameters
s
time in format "hh:mm:ss"
Returns
corresponding Time
Description
Convert a string in JDBC time escape format to a Time value


 Class Timestamp

Class java.sql.Timestamp

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.Date
           |
           +----java.sql.Timestamp

public class Timestamp
extends Date

This class is a thin wrapper around java.util.Date that allows JDBC to identify this as a SQL TIMESTAMP value. It adds the ability to hold the SQL TIMESTAMP nanos value and provides formatting and parsing operations to support the JDBC escape syntax for timestamp values.

Note: This type is a composite of a java.util.Date and a separate nanos value. Only integral seconds are stored in the java.util.Date component. The fractional seconds - the nanos - are separate. The getTime method will only return integral seconds. If a time value that includes the fractional seconds is desired you must convert nanos to milliseconds (nanos/1000000) and add this to the getTime value. Also note that the hashcode() method uses the underlying java.util.Data implementation and therefore does not include nanos in its computation.


 Timestamp Members

Timestamp Members

Class Overview | This Package | All Packages

Constructors
Name | Description
Timestamp(int, int, int, int, int, int, int) | Construct a Timestamp Object
Timestamp(long) | Construct a Timestamp using a milliseconds time value.

Methods
Name | Description
after(Timestamp) | Is this timestamp later than the timestamp argument?
before(Timestamp) | Is this timestamp earlier than the timestamp argument?
equals(Timestamp) | Test Timestamp values for equality
getNanos() | Get the Timestamp's nanos value
setNanos(int) | Set the Timestamp's nanos value
toString() | Format a timestamp in JDBC timestamp escape format
valueOf(String) | Convert a string in JDBC timestamp escape format to a Timestamp value


 Timestamp.Timestamp

Timestamp.Timestamp

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Timestamp( int year, int month, int date, int hour, int minute, int second, int nano )
Parameters
year
year-1900
month
0 to 11
day
1 to 31
hour
0 to 23
minute
0 to 59
second
0 to 59
nano
0 to 999,999,999
Description
Construct a Timestamp Object

Syntax 2
public Timestamp( long time )
Parameters
time
milliseconds since January 1, 1970, 00:00:00 GMT
Description
Construct a Timestamp using a milliseconds time value. The integral seconds are stored in the underlying date value; the fractional seconds are stored in the nanos value.


 Timestamp.after

Timestamp.after

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean after( Timestamp ts )
Parameters
ts
the Timestamp value to compare with
Description
Is this timestamp later than the timestamp argument?


 Timestamp.before

Timestamp.before

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean before( Timestamp ts )
Parameters
ts
the Timestamp value to compare with
Description
Is this timestamp earlier than the timestamp argument?


 Timestamp.equals

Timestamp.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Timestamp ts )
Parameters
ts
the Timestamp value to compare with
Description
Test Timestamp values for equality


 Timestamp.getNanos

Timestamp.getNanos

Class Overview | Class Members | This Package | All Packages

Syntax
public int getNanos()
Returns
the Timestamp's fractional seconds component
Description
Get the Timestamp's nanos value


 Timestamp.setNanos

Timestamp.setNanos

Class Overview | Class Members | This Package | All Packages

Syntax
public void setNanos( int n )
Parameters
n
the new fractional seconds component
Description
Set the Timestamp's nanos value


 Timestamp.toString

Timestamp.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a String in yyyy-mm-dd hh:mm:ss.fffffffff format
Description
Format a timestamp in JDBC timestamp escape format

Overrides
toString in class Date


 Timestamp.valueOf

Timestamp.valueOf

Class Overview | Class Members | This Package | All Packages

Syntax
public static Timestamp valueOf( String s )
Parameters
s
timestamp in format "yyyy-mm-dd hh:mm:ss.fffffffff"
Returns
corresponding Timestamp
Description
Convert a string in JDBC timestamp escape format to a Timestamp value


 Class Types

Class java.sql.Types

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.sql.Types

public class Types
extends Object

This class defines constants that are used to identify SQL types. The actual type constant values are equivalent to those in XOPEN.


 Types Members

Types Members

Class Overview | This Package | All Packages

Fields
Name | Description
BIGINT |
BINARY |
BIT |
CHAR |
DATE |
DECIMAL |
DOUBLE |
FLOAT |
INTEGER |
LONGVARBINARY |
LONGVARCHAR |
NULL |
NUMERIC |
OTHER | OTHER indicates that the SQL type is database specific and gets mapped to a Java object which can be accessed via getObject and setObject.
REAL |
SMALLINT |
TIME |
TIMESTAMP |
TINYINT |
VARBINARY |
VARCHAR |


 Types.BIGINT

Types.BIGINT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int BIGINT


 Types.BINARY

Types.BINARY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int BINARY


 Types.BIT

Types.BIT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int BIT


 Types.CHAR

Types.CHAR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int CHAR


 Types.DATE

Types.DATE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int DATE


 Types.DECIMAL

Types.DECIMAL

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int DECIMAL


 Types.DOUBLE

Types.DOUBLE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int DOUBLE


 Types.FLOAT

Types.FLOAT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int FLOAT


 Types.INTEGER

Types.INTEGER

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int INTEGER


 Types.LONGVARBINARY

Types.LONGVARBINARY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int LONGVARBINARY


 Types.LONGVARCHAR

Types.LONGVARCHAR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int LONGVARCHAR


 Types.NULL

Types.NULL

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int NULL


 Types.NUMERIC

Types.NUMERIC

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int NUMERIC


 Types.OTHER

Types.OTHER

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int OTHER
Description
OTHER indicates that the SQL type is database specific and gets mapped to a Java object which can be accessed via getObject and setObject.


 Types.REAL

Types.REAL

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int REAL


 Types.SMALLINT

Types.SMALLINT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SMALLINT


 Types.TIME

Types.TIME

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int TIME


 Types.TIMESTAMP

Types.TIMESTAMP

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int TIMESTAMP


 Types.TINYINT

Types.TINYINT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int TINYINT


 Types.VARBINARY

Types.VARBINARY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VARBINARY


 Types.VARCHAR

Types.VARCHAR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int VARCHAR


 Package java.text

Package java.text

All Packages

Interfaces

  • CharacterIterator

    • Classes

  • BreakIterator
  • ChoiceFormat
  • CollationElementIterator
  • CollationKey
  • Collator
  • DateFormat
  • DateFormatSymbols
  • DecimalFormat
  • DecimalFormatSymbols
  • FieldPosition
  • Format
  • MessageFormat
  • NumberFormat
  • ParsePosition
  • RuleBasedCollator
  • SimpleDateFormat
  • StringCharacterIterator

    • Exceptions

  • ParseException


 Class BreakIterator

Class java.text.BreakIterator

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.text.BreakIterator

public abstract class BreakIterator
extends Object
implements Cloneable, Serializable

The BreakIterator class implements methods for finding the location of boundaries in text. Instances of BreakIterator maintain a current position and scan over text returning the index of characters where boundaries occur. Internally, BreakIterator scans text using a CharacterIterator, and is thus able to scan text held by any object implementing that protocol. A StringCharacterIterator is used to scan String objects passed to setText.

You use the factory methods provided by this class to create instances of various types of break iterators. In particular, use getWordIterator, getLineIterator, getSentenceIterator, and getCharacterIterator to create BreakIterators that perform word, line, sentence, and character boundary analysis respectively. A single BreakIterator can work only on one unit (word, line, sentence, and so on). You must use a different iterator for each unit boundary analysis you wish to perform.

Line boundary analysis determines where a text string can be broken when line-wrapping. The mechanism correctly handles punctuation and hyphenated words.

Sentence boundary analysis allows selection with correct interpretation of periods within numbers and abbreviations, and trailing punctuation marks such as quotation marks and parentheses.

Word boundary analysis is used by search and replace functions, as well as within text editing applications that allow the user to select words with a double click. Word selection provides correct interpretation of punctuation marks within and following words. Characters that are not part of a word, such as symbols or punctuation marks, have word-breaks on both sides.

Character boundary analysis allows users to interact with characters as they expect to, for example, when moving the cursor through a text string. Character boundary analysis provides correct navigation of through character strings, regardless of how the character is stored. For example, an accented character might be stored as a base character and a diacritical mark. What users consider to be a character can differ between languages.

BreakIterator is intended for use with natural languages only. Do not use this class to tokenize a programming language.

Examples:

Creating and using text boundaries

 public static void main(String args[]) {
      if (args.length == 1) {
          String stringToExamine = args[0];
          //print each word in order
          BreakIterator boundary = BreakIterator.getWordInstance();
          boundary.setText(stringToExamine);
          printEachForward(boundary, stringToExamine);
          //print each sentence in reverse order
          boundary = BreakIterator.getSentenceInstance(Locale.US);
          boundary.setText(stringToExamine);
          printEachBackward(boundary, stringToExamine);
          printFirst(boundary, stringToExamine);
          printLast(boundary, stringToExamine);
      }
 }
Print each element in order
 public static void printEachForward(BreakIterator boundary, String source) {
     int start = boundary.first();
     for (int end = boundary.next();
          end != BreakIterator.DONE;
          start = end, end = boundary.next()) {
          System.out.println(source.substring(start,end));
     }
 }
Print each element in reverse order
 public static void printEachBackward(BreakIterator boundary, String source) {
     int end = boundary.last();
     for (int start = boundary.previous();
          start != BreakIterator.DONE;
          end = start, start = boundary.previous()) {
         System.out.println(source.substring(start,end));
     }
 }
Print first element
 public static void printFirst(BreakIterator boundary, String source) {
     int start = boundary.first();
     int end = boundary.next();
     System.out.println(source.substring(start,end));
 }
Print last element
 public static void printLast(BreakIterator boundary, String source) {
     int end = boundary.last();
     int start = boundary.previous();
     System.out.println(source.substring(start,end));
 }
Print the element at a specified position
 public static void printAt(BreakIterator boundary, int pos, String source) {
     int end = boundary.following(pos);
     int start = boundary.previous();
     System.out.println(source.substring(start,end));
 }

See Also:
CharacterIterator


 BreakIterator Members

BreakIterator Members

Class Overview | This Package | All Packages

Fields
Name | Description
DONE | DONE is returned by previous() and next() after all valid boundaries have been returned.

Constructors
Name | Description
BreakIterator() | Constructor.

Methods
Name | Description
clone() | Create a copy of this boundary
current() | Return character index of the text boundary that was most recently returned by next(), previous(), first(), or last()
first() | Return the first boundary.
following(int) | Return the first boundary following the specified offset.
getAvailableLocales() | Get the set of Locales for which TextBoundaries are installed
getCharacterInstance() | Create BreakIterator for character-breaks using default locale Returns an instance of a BreakIterator implementing character breaks.
getCharacterInstance(Locale) | Create BreakIterator for character-breaks using specified locale Returns an instance of a BreakIterator implementing character breaks.
getLineInstance() | Create BreakIterator for line-breaks using default locale.
getLineInstance(Locale) | Create BreakIterator for line-breaks using default locale.
getSentenceInstance() | Create BreakIterator for sentence-breaks using default locale Returns an instance of a BreakIterator implementing sentence breaks.
getSentenceInstance(Locale) | Create BreakIterator for sentence-breaks using specified locale Returns an instance of a BreakIterator implementing sentence breaks.
getText() | Get the text being scanned
getWordInstance() | Create BreakIterator for word-breaks using default locale.
getWordInstance(Locale) | Create BreakIterator for word-breaks using default locale.
last() | Return the last boundary.
next() | Return the boundary following the current boundary.
next(int) | Return the nth boundary from the current boundary
previous() | Return the boundary preceding the current boundary.
setText(CharacterIterator) | Set a new text for scanning.
setText(String) | Set a new text string to be scanned.


 BreakIterator.DONE

BreakIterator.DONE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int DONE
Description
DONE is returned by previous() and next() after all valid boundaries have been returned.


 BreakIterator.BreakIterator

BreakIterator.BreakIterator

Class Overview | Class Members | This Package | All Packages

Syntax
protected BreakIterator()
Description
Constructor. BreakIterator is stateless and has no default behavior.


 BreakIterator.clone

BreakIterator.clone

Class Overview | Class Members | This Package | All Packages

Syntax
public Object clone()
Returns
A copy of this
Description
Create a copy of this boundary

Overrides
clone in class Object


 BreakIterator.current

BreakIterator.current

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract int current()
Returns
The boundary most recently returned.
Description
Return character index of the text boundary that was most recently returned by next(), previous(), first(), or last()


 BreakIterator.first

BreakIterator.first

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract int first()
Returns
The character index of the first text boundary.
Description
Return the first boundary. The iterator's current position is set to the first boundary.


 BreakIterator.following

BreakIterator.following

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract int following( int offset )
Parameters
offset
the offset to begin scanning. Valid values are determined by the CharacterIterator passed to setText(). Invalid values cause an IllegalArgumentException to be thrown.
Returns
The first boundary after the specified offset.
Description
Return the first boundary following the specified offset. The value returned is always greater than the offset or the value BreakIterator.DONE


 BreakIterator.getAvailableLocales

BreakIterator.getAvailableLocales

Class Overview | Class Members | This Package | All Packages

Syntax
public static synchronized Locale[] getAvailableLocales()
Returns
available locales
Description
Get the set of Locales for which TextBoundaries are installed


 BreakIterator.getCharacterInstance

BreakIterator.getCharacterInstance

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static BreakIterator getCharacterInstance()
Returns
A BreakIterator for character-breaks
Description
Create BreakIterator for character-breaks using default locale Returns an instance of a BreakIterator implementing character breaks. Character breaks are boundaries of combining character sequences.

See Also
getDefault

Syntax 2
public static BreakIterator getCharacterInstance( Locale where )
Parameters
where
the local. If a specific character break is not avaliable for the specified local, a default character break is returned.
Returns
A BreakIterator for character-breaks
Description
Create BreakIterator for character-breaks using specified locale Returns an instance of a BreakIterator implementing character breaks. Character breaks are boundaries of combining character sequences.


 BreakIterator.getLineInstance

BreakIterator.getLineInstance

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static BreakIterator getLineInstance()
Returns
A BreakIterator for line-breaks
Description
Create BreakIterator for line-breaks using default locale. Returns an instance of a BreakIterator implementing line breaks. Line breaks are logically possible line breaks, actual line breaks are usually determined based on display width. LineBreak is usefull for word wrapping text.

See Also
getDefault

Syntax 2
public static BreakIterator getLineInstance( Locale where )
Parameters
where
the local. If a specific LineBreak is not avaliable for the specified local, a default LineBreak is returned.
Returns
A BreakIterator for line-breaks
Description
Create BreakIterator for line-breaks using default locale. Returns an instance of a BreakIterator implementing line breaks. Line breaks are logically possible line breaks, actual line breaks are usually determined based on display width. LineBreak is usefull for word wrapping text.


 BreakIterator.getSentenceInstance

BreakIterator.getSentenceInstance

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static BreakIterator getSentenceInstance()
Returns
A BreakIterator for sentence-breaks
Description
Create BreakIterator for sentence-breaks using default locale Returns an instance of a BreakIterator implementing sentence breaks.

See Also
getDefault

Syntax 2
public static BreakIterator getSentenceInstance( Locale where )
Parameters
where
the local. If a specific SentenceBreak is not avaliable for the specified local, a default SentenceBreak is returned.
Returns
A BreakIterator for sentence-breaks
Description
Create BreakIterator for sentence-breaks using specified locale Returns an instance of a BreakIterator implementing sentence breaks.


 BreakIterator.getText

BreakIterator.getText

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract CharacterIterator getText()
Returns
the text being scanned
Description
Get the text being scanned


 BreakIterator.getWordInstance

BreakIterator.getWordInstance

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static BreakIterator getWordInstance()
Returns
A BreakIterator for word-breaks
Description
Create BreakIterator for word-breaks using default locale. Returns an instance of a BreakIterator implementing word breaks. WordBreak is usefull for word selection (ex. double click)

See Also
getDefault

Syntax 2
public static BreakIterator getWordInstance( Locale where )
Parameters
where
the local. If a specific WordBreak is not avaliable for the specified local, a default WordBreak is returned.
Returns
A BreakIterator for word-breaks
Description
Create BreakIterator for word-breaks using default locale. Returns an instance of a BreakIterator implementing word breaks. WordBreak is usefull for word selection (ex. double click)


 BreakIterator.last

BreakIterator.last

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract int last()
Returns
The character index of the last text boundary.
Description
Return the last boundary. The iterator's current position is set to the last boundary.


 BreakIterator.next

BreakIterator.next

Class Overview | Class Members | This Package | All Packages

Syntax 1
public abstract int next( int n )
Parameters
n
which boundary to return. A value of 0 does nothing. Negative values move to previous boundaries and positive values move to later boundaries.
Returns
The index of the nth boundary from the current position.
Description
Return the nth boundary from the current boundary

Syntax 2
public abstract int next()
Returns
The character index of the next text boundary or DONE if all boundaries have been returned. Equivalent to next(1).
Description
Return the boundary following the current boundary.


 BreakIterator.previous

BreakIterator.previous

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract int previous()
Returns
The character index of the previous text boundary or DONE if all boundaries have been returned.
Description
Return the boundary preceding the current boundary.


 BreakIterator.setText

BreakIterator.setText

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void setText( String newText )
Parameters
newText
new text to scan.
Description
Set a new text string to be scanned. The current scan position is reset to first().

Syntax 2
public abstract void setText( CharacterIterator newText )
Parameters
newText
new text to scan.
Description
Set a new text for scanning. The current scan position is reset to first().


 Interface CharacterIterator

Interface java.text.CharacterIterator

Interface Members | This Package | All Packages

public interface CharacterIterator
extends Cloneable

This interface defines a protocol for bidirectional iteration over text. The iterator iterates over a bounded sequence of characters. Characters are indexed with values beginning with the value returned by getBeginIndex and continuing through the value returned by getEndIndex()-1. The index of the current character can be retrieved by calling getIndex. Calling setIndex will move the iterator to a new position within the sequence of characters. If at any time the iterator's current index moves outside the range of getBeginIndex and getEndIndex, previous() and next() will return DONE, signaling that the iterator has reached the end of the sequence.

Examples:

Traverse the text from start to finish

 public void traverseForward(CharacterIterator iter) {
     for(char c = iter.first(); c != CharacterIterator.DONE; c = iter.next()) {
         processChar(c);
     }
 }
Traverse the text backwards, from end to start
 public void traverseBackward(CharacterIterator iter) {
     for(char c = iter.last(); c != CharacterIterator.DONE; c = iter.prev()) {
         processChar(c);
     }
 }
Traverse both forward and backward from a given position in the text. Calls to notBoundary() in this example represents some additional stopping criteria.
 public void traverseOut(CharacterIterator iter, int pos) {
     for (char c = iter.setIndex(pos);
          c != CharacterIterator.DONE && notBoundary(c);
          c = iter.next()) {}
 int end = iter.getIndex();
 for (char c = iter.setIndex(pos);
     c != CharacterIterator.DONE && notBoundary(c);
     c = iter.prev()) {}
 int start = iter.getIndex();
 processSection(start,end);
 }

See Also:
StringCharacterIterator


 CharacterIterator Members

CharacterIterator Members

Interface Overview | This Package | All Packages

Fields
Name | Description
DONE | Constant that is returned when the iterator has reached either the end or the beginning of the text.

Methods
Name | Description
clone() | Create a copy of this iterator
current() | Get the character at the current position (as returned by getIndex()).
first() | Set the position to getBeginIndex() and return the character at that position.
getBeginIndex() | Return the start index of the text.
getEndIndex() | Return the end index of the text.
getIndex() | Return the current index.
last() | Set the position to getEndIndex()-1, return the character at that position.
next() | Increment the iterator's index by one and return the character at the new index.
previous() | Decrement the iterator's index by one and return the character at the new index.
setIndex(int) | Set the position to the specified position in the text and return that character.


 CharacterIterator.DONE

CharacterIterator.DONE

Interface Overview | Interface Members | This Package | All Packages

Syntax
public static final char DONE
Description
Constant that is returned when the iterator has reached either the end or the beginning of the text. The unicode 2.0 standard states that '\\uFFFF' is an invalid unicode value and should not occur in any valid unicode string.


 CharacterIterator.clone

CharacterIterator.clone

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Object clone()
Returns
A copy of this
Description
Create a copy of this iterator

Overrides
clone in class Object


 CharacterIterator.current

CharacterIterator.current

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract char current()
Returns
the character at the current position or DONE if the current position is off the end of the text.
Description
Get the character at the current position (as returned by getIndex()).

See Also
getIndex


 CharacterIterator.first

CharacterIterator.first

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract char first()
Returns
the first character in the text
Description
Set the position to getBeginIndex() and return the character at that position.

See Also
getBeginIndex


 CharacterIterator.getBeginIndex

CharacterIterator.getBeginIndex

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getBeginIndex()
Returns
the index at which the text begins.
Description
Return the start index of the text.


 CharacterIterator.getEndIndex

CharacterIterator.getEndIndex

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getEndIndex()
Returns
the index at which the text end.
Description
Return the end index of the text. This index is the index of the first character following the end of the text.


 CharacterIterator.getIndex

CharacterIterator.getIndex

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract int getIndex()
Returns
the current index.
Description
Return the current index.


 CharacterIterator.last

CharacterIterator.last

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract char last()
Returns
the last character in the text
Description
Set the position to getEndIndex()-1, return the character at that position.

See Also
getEndIndex


 CharacterIterator.next

CharacterIterator.next

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract char next()
Returns
the character at the new position or DONE if the current position is off the end of the text.
Description
Increment the iterator's index by one and return the character at the new index. If the resulting index is greater or equal to getEndIndex(), the current index is reset to getEndIndex() and a value of DONE is returned.


 CharacterIterator.previous

CharacterIterator.previous

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract char previous()
Returns
the character at the new position or DONE if the current position is off the end of the text.
Description
Decrement the iterator's index by one and return the character at the new index. If the resulting index is less than getBeginIndex(), the current index is reset to getBeginIndex() and a value of DONE is returned.


 CharacterIterator.setIndex

CharacterIterator.setIndex

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract char setIndex( int position )
Parameters
position
the position within the text. Valid values range from getBeginIndex() to getEndIndex() - 1. An IllegalArgumentException is thrown if an invalid value is supplied.
Returns
the character at the specified position.
Description
Set the position to the specified position in the text and return that character.


 Class ChoiceFormat

Class java.text.ChoiceFormat

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.text.Format
           |
           +----java.text.NumberFormat
                   |
                   +----java.text.ChoiceFormat

public class ChoiceFormat
extends NumberFormat

A ChoiceFormat allows you to attach a format to a range of numbers. It is generally used in a MessageFormat for handling plurals. The choice is specified with an ascending list of doubles, where each item specifies a half-open interval up to the next item:

 X matches j if and only if limit[j] <= X < limit[j+1]
If there is no match, then either the first or last index is used, depending on whether the number (X) is too low or too high.

Note: ChoiceFormat differs from the other Format classes in that you create a ChoiceFormat object with a constructor (not with a getInstance style factory method). The factory methods aren't necessary because ChoiceFormat doesn't require any complex setup for a given locale. In fact, ChoiceFormat doesn't implement any locale specific behavior.

When creating a ChoiceFormat, you must specify an array of formats and an array of limits. The length of these arrays must be the same. For example,

  •      limits = {1,2,3,4,5,6,7}
formats = {"Sun","Mon","Tue","Wed","Thur","Fri","Sat"}

     limits = {0, 1, ChoiceFormat.nextDouble(1)}
formats = {"no files", "one file", "many files"}
(nextDouble can be used to get the next higher double, to
     make the half-open interval.)

Here is a simple example that shows formatting and parsing:

 double[] limits = {1,2,3,4,5,6,7};
 String[] monthNames = {"Sun","Mon","Tue","Wed","Thur","Fri","Sat"};
 ChoiceFormat form = new ChoiceFormat(limits, monthNames);
 ParsePosition status = new ParsePosition(0);
 for (double i = 0.0; i <= 8.0; ++i) {
     status.setIndex(0);
     System.out.println(i + " -> " + form.format(i) + " -> "
                              + form.parse(form.format(i),status));
 }
Here is a more complex example, with a pattern format:
 double[] filelimits = {0,1,2};
 String[] filepart = {"are no files","is one file","are {2} files"};
 ChoiceFormat fileform = new ChoiceFormat(filelimits, filepart);
 Format[] testFormats = {fileform, null, NumberFormat.getInstance()};
 MessageFormat pattform = new MessageFormat("There {0} on {1}");
 pattform.setFormats(testFormats);
 Object[] testArgs = {null, "ADisk", null};
 for (int i = 0; i < 4; ++i) {
     testArgs[0] = new Integer(i);
     testArgs[2] = testArgs[0];
     System.out.println(pattform.format(testArgs));
 }

See Also:
DecimalFormat, MessageFormat


 ChoiceFormat Members

ChoiceFormat Members

Class Overview | This Package | All Packages

Constructors
Name | Description
ChoiceFormat(double[], String[]) | Constructs with the limits and the corresponding formats.
ChoiceFormat(String) | Constructs with limits and corresponding formats based on the pattern.

Methods
Name | Description
applyPattern(String) | Sets the pattern.
clone() | Overrides Cloneable
equals(Object) | Equality comparision between two
format(double, StringBuffer, FieldPosition) | Specialization of format.
format(long, StringBuffer, FieldPosition) | Specialization of format.
getFormats() | Get the formats passed in the constructor.
getLimits() | Get the limits passed in the constructor.
hashCode() | Generates a hash code for the message format object.
nextDouble(double) | Finds the least double greater than d.
nextDouble(double, boolean) |
parse(String, ParsePosition) | Returns a Long if possible (e.g.
previousDouble(double) | Finds the greatest double less than d.
setChoices(double[], String[]) | Set the choices to be used in formatting.
toPattern() | Gets the pattern.


 ChoiceFormat.ChoiceFormat

ChoiceFormat.ChoiceFormat

Class Overview | Class Members | This Package | All Packages

Syntax 1
public ChoiceFormat( String newPattern )
Description
Constructs with limits and corresponding formats based on the pattern.

Syntax 2
public ChoiceFormat( double limits[], String formats[] )
Description
Constructs with the limits and the corresponding formats.

See Also
setChoices


 ChoiceFormat.applyPattern

ChoiceFormat.applyPattern

Class Overview | Class Members | This Package | All Packages

Syntax
public void applyPattern( String newPattern )
Parameters
newPattern
See the class description.
Description
Sets the pattern.


 ChoiceFormat.clone

ChoiceFormat.clone

Class Overview | Class Members | This Package | All Packages

Syntax
public Object clone()
Description
Overrides Cloneable

Overrides
clone in class NumberFormat


 ChoiceFormat.equals

ChoiceFormat.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Description
Equality comparision between two

Overrides
equals in class NumberFormat


 ChoiceFormat.format

ChoiceFormat.format

Class Overview | Class Members | This Package | All Packages

Syntax 1
public StringBuffer format( long number, StringBuffer toAppendTo, FieldPosition status )
Description
Specialization of format. This method really calls format(double, StringBuffer, FieldPosition) thus the range of longs that are supported is only equal to the range that can be stored by double. This will never be a practical limitation.

Overrides
format in class NumberFormat

Syntax 2
public StringBuffer format( double number, StringBuffer toAppendTo, FieldPosition status )
Description
Specialization of format.

Overrides
format in class NumberFormat


 ChoiceFormat.getFormats

ChoiceFormat.getFormats

Class Overview | Class Members | This Package | All Packages

Syntax
public Object[] getFormats()
Returns
the formats.
Description
Get the formats passed in the constructor.


 ChoiceFormat.getLimits

ChoiceFormat.getLimits

Class Overview | Class Members | This Package | All Packages

Syntax
public double[] getLimits()
Returns
the limits.
Description
Get the limits passed in the constructor.


 ChoiceFormat.hashCode

ChoiceFormat.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int hashCode()
Description
Generates a hash code for the message format object.

Overrides
hashCode in class NumberFormat


 ChoiceFormat.nextDouble

ChoiceFormat.nextDouble

Class Overview | Class Members | This Package | All Packages

Syntax
public static final double nextDouble( double d )
Description
Finds the least double greater than d. If NaN, returns same value.

Used to make half-open intervals.

See Also
previousDouble


 ChoiceFormat.nextDouble

ChoiceFormat.nextDouble

Class Overview | Class Members | This Package | All Packages

Syntax
public static double nextDouble( double d, boolean positive )


 ChoiceFormat.parse

ChoiceFormat.parse

Class Overview | Class Members | This Package | All Packages

Syntax
public Number parse( String text, ParsePosition status )
Description
Returns a Long if possible (e.g.

Overrides
parse in class NumberFormat


 ChoiceFormat.previousDouble

ChoiceFormat.previousDouble

Class Overview | Class Members | This Package | All Packages

Syntax
public static final double previousDouble( double d )
Description
Finds the greatest double less than d. If NaN, returns same value.

See Also
nextDouble


 ChoiceFormat.setChoices

ChoiceFormat.setChoices

Class Overview | Class Members | This Package | All Packages

Syntax
public void setChoices( double limits[], String formats[] )
Parameters
limits
contains the top value that you want parsed with that format,and should be in ascending sorted order. When formatting X, the choice will be the i, where limit[i] <= X < limit[i+1].
formats
are the formats you want to use for each limit. They can be either Format objects or Strings. When formatting with object Y, if the object is a NumberFormat, then ((NumberFormat) Y).format(X) is called. Otherwise Y.toString() is called.
Description
Set the choices to be used in formatting.


 ChoiceFormat.toPattern

ChoiceFormat.toPattern

Class Overview | Class Members | This Package | All Packages

Syntax
public String toPattern()
Description
Gets the pattern.


 Class CollationElementIterator

Class java.text.CollationElementIterator

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.text.CollationElementIterator

public final class CollationElementIterator
extends Object

The CollationElementIterator class is used as an iterator to walk through each character of an international string. Use the iterator to return the ordering priority of the positioned character. The ordering priority of a character, which we refer to as a key, defines how a character is collated in the given collation object.

For example, consider the following in Spanish:

 "ca" -> the first key is key('c') and second key is key('a').
 "cha" -> the first key is key('ch') and second key is key('a').
And in German,
 "äb"-> the first key is key('a'), the second key is key('e'), and
 the third key is key('b').
The key of a character is an integer composed of primary order(short), secondary order(byte), and tertiary order(byte). Java strictly defines the size and signedness of its primitive data types. Therefore, the static functions primaryOrder, secondaryOrder, and tertiaryOrder return int, short, and short respectively to ensure the correctness of the key value.

Example of the iterator usage,

 // get the first key of the string
 String str = "This is a test";
 CollationElementIterator c =
     new CollationElementIterator(str, 0, str.length(),
                                  Collator.getInstance());
 int primaryOrder = CollationElementIterator.primaryOrder(c->next());

CollationElementIterator.next returns the collation order of the next character. A collation order consists of primary order, secondary order and tertiary order. The data type of the collation order is int. The first 16 bits of a collation order is its primary order; the next 8 bits is the secondary order and the last 8 bits is the tertiary order.

See Also:
Collator, RuleBasedCollator


 CollationElementIterator Members

CollationElementIterator Members

Class Overview | This Package | All Packages

Fields
Name | Description
NULLORDER | Null order which indicates the end of string is reached by the cursor.

Methods
Name | Description
next() | Get the ordering priority of the next character in the string.
primaryOrder(int) | Get the primary order of a collation order.
reset() | Resets the cursor to the beginning of the string.
secondaryOrder(int) | Get the secondary order of a collation order.
tertiaryOrder(int) | Get the tertiary order of a collation order.


 CollationElementIterator.NULLORDER

CollationElementIterator.NULLORDER

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int NULLORDER
Description
Null order which indicates the end of string is reached by the cursor.


 CollationElementIterator.next

CollationElementIterator.next

Class Overview | Class Members | This Package | All Packages

Syntax
public int next()
Returns
the next character's ordering. Returns NULLORDER if the end of string is reached.
Description
Get the ordering priority of the next character in the string.


 CollationElementIterator.primaryOrder

CollationElementIterator.primaryOrder

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int primaryOrder( int order )
Parameters
order
the collation order
Returns
the primary order of a collation order.
Description
Get the primary order of a collation order.


 CollationElementIterator.reset

CollationElementIterator.reset

Class Overview | Class Members | This Package | All Packages

Syntax
public void reset()
Description
Resets the cursor to the beginning of the string.


 CollationElementIterator.secondaryOrder

CollationElementIterator.secondaryOrder

Class Overview | Class Members | This Package | All Packages

Syntax
public static final short secondaryOrder( int order )
Parameters
order
the collation order
Returns
the secondary order of a collation order.
Description
Get the secondary order of a collation order.


 CollationElementIterator.tertiaryOrder

CollationElementIterator.tertiaryOrder

Class Overview | Class Members | This Package | All Packages

Syntax
public static final short tertiaryOrder( int order )
Parameters
order
the collation order
Returns
the tertiary order of a collation order.
Description
Get the tertiary order of a collation order.


 Class CollationKey

Class java.text.CollationKey

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.text.CollationKey

public final class CollationKey
extends Object

A CollationKey represents a String under the rules of a specific Collator object. Comparing two CollationKeys returns the relative order of the Strings they represent. Using CollationKeys to compare Strings is generally faster than using Collator.compare. Thus, when the Strings must be compared multiple times, for example when sorting a list of Strings. It's more efficient to use CollationKeys.

You can not create CollationKeys directly. Rather, generate them by calling Collator.getCollationKey. You can only compare CollationKeys generated from the same Collator object.

Generating a CollationKey for a String involves examining the entire String and converting it to series of bits that can be compared bitwise. This allows fast comparisons once the keys are generated. The cost of generating keys is recouped in faster comparisons when Strings need to be compared many times. On the other hand, the result of a comparison is often determined by the first couple of characters of each String. Collator.compare examines only as many characters as it needs which allows it to be faster when doing single comparisons.

The following example shows how CollationKeys might be used to sort a list of Strings.

 // Create an array of CollationKeys for the Strings to be sorted.
 Collator myCollator = Collator.getInstance();
 CollationKey[] keys = new CollationKey[3];
 keys[0] = myCollator.getCollationKey("Tom");
 keys[1] = myCollator.getCollationKey("Dick");
 keys[2] = myCollator.getCollationKey("Harry");
 sort( keys );

 //...

 // Inside body of sort routine, compare keys this way
 if( keys[i].compareTo( keys[j] ) > 0 )
    // swap keys[i] and keys[j]

 //...

 // Finally, when we've returned from sort.
 System.out.println( keys[0].getSourceString() );
 System.out.println( keys[1].getSourceString() );
 System.out.println( keys[2].getSourceString() );

See Also:
Collator, RuleBasedCollator


 CollationKey Members

CollationKey Members

Class Overview | This Package | All Packages

Methods
Name | Description
compareTo(CollationKey) | Compare this CollationKey to the target CollationKey.
equals(Object) | Compare this CollationKey and the target CollationKey for equality.
getSourceString() | Returns the String that this CollationKey represents.
hashCode() | Creates a hash code for this CollationKey.
toByteArray() | Converts the CollationKey to a sequence of bits.


 CollationKey.compareTo

CollationKey.compareTo

Class Overview | Class Members | This Package | All Packages

Syntax
public int compareTo( CollationKey target )
Parameters
target
target CollationKey
Returns
Returns an integer value. Value is less than zero if this is less than target, value is zero if this and target are equal and value is greater than zero if this is greater than target.
Description
Compare this CollationKey to the target CollationKey. The collation rules of the Collator object which created these keys are applied. Note: CollationKeys created by different Collators can not be compared.

See Also
compare


 CollationKey.equals

CollationKey.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object target )
Parameters
target
the CollationKey to compare to.
Returns
Returns true if two objects are equal, false otherwise.
Description
Compare this CollationKey and the target CollationKey for equality. The collation rules of the Collator object which created these keys are applied. Note: CollationKeys created by different Collators can not be compared.

Overrides
equals in class Object


 CollationKey.getSourceString

CollationKey.getSourceString

Class Overview | Class Members | This Package | All Packages

Syntax
public String getSourceString()
Description
Returns the String that this CollationKey represents.


 CollationKey.hashCode

CollationKey.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int hashCode()
Returns
the hash value based on the string's collation order.
Description
Creates a hash code for this CollationKey. The hash value is calculated on the key itself, not the String from which the key was created. Thus if x and y are CollationKeys, then x.hashCode(x) == y.hashCode() if x.equals(y) is true. This allows language-sensitive comparison in a hash table. See the CollatinKey class description for an example.

Overrides
hashCode in class Object


 CollationKey.toByteArray

CollationKey.toByteArray

Class Overview | Class Members | This Package | All Packages

Syntax
public byte[] toByteArray()
Description
Converts the CollationKey to a sequence of bits. If two CollationKeys could be legitimately compared, then one could compare the byte arrays for each of those keys to obtain the same result. Byte arrays are organized most significant byte first.


 Class Collator

Class java.text.Collator

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.text.Collator

public abstract class Collator
extends Object
implements Cloneable, Serializable

The Collator class performs locale-sensitive String comparison. You use this class to build searching and sorting routines for natural language text.

Collator is an abstract base class. Subclasses implement specific collation strategies. One subclass, RuleBasedCollator, is currently provided with the JDK and is applicable to a wide set of languages. Other subclasses may be created to handle more specialized needs.

Like other locale-sensitive classes, you can use the static factory method, getInstance, to obtain the appropriate Collator object for a given locale. You will only need to look at the subclasses of Collator if you need to understand the details of a particular collation strategy or if you need to modify that strategy.

The following example shows how to compare two strings using the Collator for the default locale.

 // Compare two strings in the default locale
 Collator myCollator = Collator.getInstance();
 if( myCollator.compare("abc", "ABC") < 0 )
     System.out.println("abc is less than ABC");
 else
     System.out.println("abc is greater than or equal to ABC");

You can set a Collator's strength property to determine the level of difference considered significant in comparisons. Four strengths are provided: PRIMARY, SECONDARY, TERTIARY, and IDENTICAL. The exact assignment of strengths to language features is locale dependant. For example, in Czech, "e" and "f" are considered primary differences, while "e" and "ê" are secondary differences, "e" and "E" are tertiary differences and "e" and "e" are identical. The following shows how both case and accents could be ignored for US English.

 //Get the Collator for US English and set its strength to PRIMARY
 Collator usCollator = Collator.getInstance(Locale.US);
 usCollator.setStrength(Collator.PRIMARY);
 if( usCollator.compare("abc", "ABC") == 0 ) {
     System.out.println("Strings are equivalent");
 }

For comparing Strings exactly once, the compare method provides the best performance. When sorting a list of Strings however, it is generally necessary to compare each String multiple times. In this case, CollationKeys provide better performance. The CollationKey class converts a String to a series of bits that can be compared bitwise against other CollationKeys. A CollationKey is created by a Collator object for a given String.
Note: CollationKeys from different Collators can not be compared. See the class description for CollationKey for an example using CollationKeys.

See Also:
RuleBasedCollator, CollationKey, CollationElementIterator, Locale


 Collator Members

Collator Members

Class Overview | This Package | All Packages

Fields
Name | Description
CANONICAL_DECOMPOSITION | Decomposition mode value.
FULL_DECOMPOSITION | Decomposition mode value.
IDENTICAL | Collator strength value.
NO_DECOMPOSITION | Decomposition mode value.
PRIMARY | Collator strength value.
SECONDARY | Collator strength value.
TERTIARY | Collator strength value.

Constructors
Name | Description
Collator() | Default constructor.

Methods
Name | Description
clone() | Overrides Cloneable
compare(String, String) | Compares the source string to the target string according to the collation rules for this Collator.
equals(Object) | Compares the equality of two Collators.
equals(String, String) | Convenience method for comparing the equality of two strings based on this Collator's collation rules.
getAvailableLocales() | Get the set of Locales for which Collators are installed.
getCollationKey(String) | Transforms the String into a series of bits that can be compared bitwise to other CollationKeys.
getDecomposition() | Get the decomposition mode of this Collator.
getInstance() | Gets the Collator for the current default locale.
getInstance(Locale) | Gets the Collator for the desired locale.
getStrength() | Returns this Collator's strength property.
hashCode() | Generates the hash code for this Collator.
setDecomposition(int) | Set the decomposition mode of this Collator.
setStrength(int) | Sets this Collator's strength property.


 Collator.CANONICAL_DECOMPOSITION

Collator.CANONICAL_DECOMPOSITION

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int CANONICAL_DECOMPOSITION
Description
Decomposition mode value. With CANONICAL_DECOMPOSITION set, characters that are canonical variants according to Unicode 2.0 will be decomposed for collation. This is the default setting and should be used to get correct collation of accented characters.

See Also
getDecomposition, setDecomposition


 Collator.FULL_DECOMPOSITION

Collator.FULL_DECOMPOSITION

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int FULL_DECOMPOSITION
Description
Decomposition mode value. With FULL_DECOMPOSITION set, both Unicode canonical variants and Unicode compatibility variants will be decomposed for collation. This causes not only accented characters to be collated, but also characters that have special formats to be collated with their norminal form. For example, the half-width and full-width ASCII and Katakana characters are then collated together. FULL_DECOMPOSITION is the most complete and therefore the slowest decomposition mode.

See Also
getDecomposition, setDecomposition


 Collator.IDENTICAL

Collator.IDENTICAL

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int IDENTICAL
Description
Collator strength value. When set, all differences are considered significant during comparison. The assignment of strengths to language features is locale dependant. A common example is for characters with equivalent Unicode spellings ("ä" vs "a?") to be considered IDENTICAL.


 Collator.NO_DECOMPOSITION

Collator.NO_DECOMPOSITION

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int NO_DECOMPOSITION
Description
Decomposition mode value. With NO_DECOMPOSITION set, accented characters will not be decomposed for collation. This provides the fastest collation but will only produce correct results for languages that do not use accents.

See Also
getDecomposition, setDecomposition


 Collator.PRIMARY

Collator.PRIMARY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int PRIMARY
Description
Collator strength value. When set, only PRIMARY differences are considered significant during comparison. The assignment of strengths to language features is locale dependant. A common example is for different base letters ("a" vs "b") to be considered a PRIMARY difference.

See Also
setStrength, getStrength


 Collator.SECONDARY

Collator.SECONDARY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SECONDARY
Description
Collator strength value. When set, only SECONDARY and above differences are considered significant during comparison. The assignment of strengths to language features is locale dependant. A common example is for different accented forms of the same base letter ("a" vs "ä") to be considered a SECONDARY difference.

See Also
setStrength, getStrength


 Collator.TERTIARY

Collator.TERTIARY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int TERTIARY
Description
Collator strength value. When set, only TERTIARY and above differences are considered significant during comparison. The assignment of strengths to language features is locale dependant. A common example is for case differences ("a" vs "A") to be considered a TERTIARY difference.

See Also
setStrength, getStrength


 Collator.Collator

Collator.Collator

Class Overview | Class Members | This Package | All Packages

Syntax
protected Collator()
Description
Default constructor. This constructor is protected so subclasses can get access to it. Users typically create a Collator sub-class by calling the factory method getInstance.

See Also
getInstance


 Collator.clone

Collator.clone

Class Overview | Class Members | This Package | All Packages

Syntax
public Object clone()
Description
Overrides Cloneable

Overrides
clone in class Object


 Collator.compare

Collator.compare

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract int compare( String source, String target )
Parameters
source
the source string.
target
the target string.
Returns
Returns an integer value. Value is less than zero if source is less than target, value is zero if source and target are equal, value is greater than zero if source is greater than target.
Description
Compares the source string to the target string according to the collation rules for this Collator. Returns an integer less than, equal to or greater than zero depending on whether the source String is less than, equal to or greater than the target string. See the Collator class description for an example of use.

For a one time comparison, this method has the best performance. If a given String will be involved in multiple comparisons, CollationKey.compareTo has the best performance. See the Collator class description for an example using CollationKeys.

See Also
CollationKey, getCollationKey


 Collator.equals

Collator.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( String source, String target )
Parameters
source
the source string to be compared with.
target
the target string to be compared with.
Returns
true if the strings are equal according to the collation rules. false, otherwise.
Description
Convenience method for comparing the equality of two strings based on this Collator's collation rules.

See Also
compare


 Collator.equals

Collator.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object that )
Parameters
that
the Collator to be compared with this.
Returns
true if this Collator is the same as that Collator; false otherwise.
Description
Compares the equality of two Collators.

Overrides
equals in class Object


 Collator.getAvailableLocales

Collator.getAvailableLocales

Class Overview | Class Members | This Package | All Packages

Syntax
public static synchronized Locale[] getAvailableLocales()
Returns
the list of available locales which collators are installed.
Description
Get the set of Locales for which Collators are installed.


 Collator.getCollationKey

Collator.getCollationKey

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract CollationKey getCollationKey( String source )
Parameters
source
the string to be transformed into a collation key.
Returns
the CollationKey for the given String based on this Collator's collation rules. If the source String is null, a null CollationKey is returned.
Description
Transforms the String into a series of bits that can be compared bitwise to other CollationKeys. CollationKeys provide better performance than Collator.compare when Strings are involved in multiple comparisons. See the Collator class description for an example using CollationKeys.

See Also
CollationKey, compare


 Collator.getDecomposition

Collator.getDecomposition

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized int getDecomposition()
Returns
the decomposition mode
Description
Get the decomposition mode of this Collator. Decomposition mode determines how Unicode composed characters are handled. Adjusting decomposition mode allows the user to select between faster and more complete collation behavior.

The three values for decomposition mode are:

  • NO_DECOMPOSITION,
  • CANONICAL_DECOMPOSITION
  • FULL_DECOMPOSITION.
See the documentation for these three constants for a description of their meaning.

See Also
setDecomposition, NO_DECOMPOSITION, CANONICAL_DECOMPOSITION, FULL_DECOMPOSITION


 Collator.getInstance

Collator.getInstance

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static synchronized Collator getInstance()
Returns
the Collator for the default locale.(for example, en_US)
Description
Gets the Collator for the current default locale. The default locale is determined by java.util.Locale.getDefault.

See Also
getDefault

Syntax 2
public static synchronized Collator getInstance( Locale desiredLocale )
Parameters
desiredLocale
the desired locale.
Returns
the Collator for the desired locale.
Description
Gets the Collator for the desired locale.

See Also
Locale, ResourceBundle


 Collator.getStrength

Collator.getStrength

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized int getStrength()
Returns
this Collator's current strength property.
Description
Returns this Collator's strength property. The strength property determines the minimum level of difference considered significant during comparison. See the Collator class description for an example of use.

See Also
setStrength, PRIMARY, SECONDARY, TERTIARY, IDENTICAL


 Collator.hashCode

Collator.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract synchronized int hashCode()
Description
Generates the hash code for this Collator.

Overrides
hashCode in class Object


 Collator.setDecomposition

Collator.setDecomposition

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setDecomposition( int decompositionMode )
Parameters
the
new decomposition mode
Description
Set the decomposition mode of this Collator. See getDecomposition for a description of decomposition mode.

Exceptions
IllegalArgumentException If the given value is not a valid decomposition mode.
See Also
getDecomposition, NO_DECOMPOSITION, CANONICAL_DECOMPOSITION, FULL_DECOMPOSITION


 Collator.setStrength

Collator.setStrength

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setStrength( int newStrength )
Parameters
the
new strength value.
Description
Sets this Collator's strength property. The strength property determines the minimum level of difference considered significant during comparison. See the Collator class description for an example of use.

Exceptions
IllegalArgumentException If the new strength value is not one of PRIMARY, SECONDARY, TERTIARY or IDENTICAL.
See Also
getStrength, PRIMARY, SECONDARY, TERTIARY, IDENTICAL


 Class DateFormat

Class java.text.DateFormat

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.text.Format
           |
           +----java.text.DateFormat

public abstract class DateFormat
extends Format
implements Cloneable

DateFormat is an abstract class for date/time formatting subclasses which formats and parses dates or time in a language-independent manner. The date/time formatting subclass, such as SimpleDateFormat, allows for formatting (i.e., millis -> text), parsing (text -> millis), and normalization. Formats/Parses a date or time, which is the standard millis since 24:00 GMT, Jan 1, 1970

DateFormat provides many class methods for obtaining default date/time formatters based on the default or a given loacle and a number of formatting styles. The formatting styles include FULL, LONG, MEDIUM, and SHORT. More detail and examples of using these styles are provided in the method descriptions.

DateFormat helps you to format and parse dates for any locale. Your code can be completely independent of the locale conventions for months, days of the week, or even the calendar format: lunar vs. solar.

To format a date for the current Locale, use one of the static factory methods:

  myString = DateFormat.getDateInstance().format(myDate);

If you are formatting multiple numbers, it is more efficient to get the format and use it multiple times so that the system doesn't have to fetch the information about the local language and country conventions multiple times.

  DateFormat df = DateFormat.getDateInstance();
  for (int i = 0; i < a.length; ++i) {
    output.println(df.format(myDate[i]) + "; ");
  }

To format a number for a different Locale, specify it in the call to getDateInstance().

  DateFormat df = DateFormat.getDateInstance(Locale.FRANCE);

You can use a DateFormat to parse also.

  myDate = df.parse(myString);

Use getDate to get the normal date format for that country. There are other static factory methods available. Use getTime to get the time format for that country. Use getDateTime to get a date and time format. You can pass in different options to these factory methods to control the length of the result; from SHORT to MEDIUM to LONG to FULL. The exact result depends on the locale, but generally:

  • SHORT is completely numeric, such as 12.13.52 or 3:30pm
  • MEDIUM is longer, such as Jan 12, 1952
  • LONG is longer, such as January 12, 1952 or 3:30:32pm
  • FULL is pretty completely specified, such as Tuesday, April 12, 1952 AD or 3:30:42pm PST.

You can also set the time zone on the format if you wish. If you want even more control over the format or parsing, (or want to give your users more control), you can try casting the DateFormat you get from the factory methods to a SimpleDateFormat. This will work for the majority of countries; just remember to put it in a try block in case you encounter an unusual one.

You can also use forms of the parse and format methods with ParsePosition and FieldPosition to allow you to

  • pregressively parse through pieces of a string.
  • align any particular field, or find out where it is for selection on the screen.

See Also:
Format, NumberFormat, SimpleDateFormat, Calendar, GregorianCalendar, TimeZone


 DateFormat Members

DateFormat Members

Class Overview | This Package | All Packages

Fields
Name | Description
AM_PM_FIELD | Useful constant for AM_PM field alignment.
calendar | The calendar that DateFormat uses to produce the time field values needed to implement date/time formatting.
DATE_FIELD | Useful constant for DATE field alignment.
DAY_OF_WEEK_FIELD | Useful constant for DAY_OF_WEEK field alignment.
DAY_OF_WEEK_IN_MONTH_FIELD | Useful constant for DAY_OF_WEEK_IN_MONTH field alignment.
DAY_OF_YEAR_FIELD | Useful constant for DAY_OF_YEAR field alignment.
DEFAULT | Constant for default style pattern.
ERA_FIELD | Useful constant for ERA field alignment.
FULL | Constant for full style pattern.
HOUR0_FIELD | Useful constant for zero-based HOUR field alignment.
HOUR1_FIELD | Useful constant for one-based HOUR field alignment.
HOUR_OF_DAY0_FIELD | Useful constant for zero-based HOUR_OF_DAY field alignment.
HOUR_OF_DAY1_FIELD | Useful constant for one-based HOUR_OF_DAY field alignment.
LONG | Constant for long style pattern.
MEDIUM | Constant for medium style pattern.
MILLISECOND_FIELD | Useful constant for MILLISECOND field alignment.
MINUTE_FIELD | Useful constant for MINUTE field alignment.
MONTH_FIELD | Useful constant for MONTH field alignment.
numberFormat | The number formatter that DateFormat uses to format numbers in dates and times.
SECOND_FIELD | Useful constant for SECOND field alignment.
SHORT | Constant for short style pattern.
TIMEZONE_FIELD | Useful constant for TIMEZONE field alignment.
WEEK_OF_MONTH_FIELD | Useful constant for WEEK_OF_MONTH field alignment.
WEEK_OF_YEAR_FIELD | Useful constant for WEEK_OF_YEAR field alignment.
YEAR_FIELD | Useful constant for YEAR field alignment.

Constructors
Name | Description
DateFormat() |

Methods
Name | Description
clone() | Overrides Cloneable
equals(Object) | Overrides equals
format(Date) | Formats a Date into a date/time string.
format(Date, StringBuffer, FieldPosition) | Formats a Date into a date/time string.
format(Object, StringBuffer, FieldPosition) | Overrides Format.
getAvailableLocales() | Gets the set of locales for which DateFormats are installed.
getCalendar() | Gets the calendar associated with this date/time formatter.
getDateInstance() | Gets the date formatter with the default formatting style for the default locale.
getDateInstance(int) | Gets the date formatter with the given formatting style for the default locale.
getDateInstance(int, Locale) | Gets the date formatter with the given formatting style for the given locale.
getDateTimeInstance() | Gets the date/time formatter with the default formatting style for the default locale.
getDateTimeInstance(int, int) | Gets the date/time formatter with the given date and time formatting styles for the default locale.
getDateTimeInstance(int, int, Locale) | Gets the date/time formatter with the given formatting styles for the given locale.
getInstance() | Get a default date/time formatter that uses the SHORT style for both the date and the time.
getNumberFormat() | Gets the number formatter which this date/time formatter uses to format and parse a time.
getTimeInstance() | Gets the time formatter with the default formatting style for the default locale.
getTimeInstance(int) | Gets the time formatter with the given formatting style for the default locale.
getTimeInstance(int, Locale) | Gets the time formatter with the given formatting style for the given locale.
getTimeZone() | Gets the time zone.
hashCode() | Overrides hashCode
isLenient() | Tell whether date/time parsing is to be lenient.
parse(String) | Parse a date/time string.
parse(String, ParsePosition) | Parse a date/time string according to the given parse position.
parseObject(String, ParsePosition) | Parse a date/time string into an Object.
setCalendar(Calendar) | Set the calendar to be used by this date format.
setLenient(boolean) | Specify whether or not date/time parsing is to be lenient.
setNumberFormat(NumberFormat) | Allows you to set the number formatter.
setTimeZone(TimeZone) | Sets the time zone for the calendar of this DateFormat object.


 DateFormat.AM_PM_FIELD

DateFormat.AM_PM_FIELD

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int AM_PM_FIELD
Description
Useful constant for AM_PM field alignment. Used in FieldPosition of date/time formatting.


 DateFormat.calendar

DateFormat.calendar

Class Overview | Class Members | This Package | All Packages

Syntax
protected Calendar calendar
Description
The calendar that DateFormat uses to produce the time field values needed to implement date/time formatting. Subclasses should initialize this to the default calendar for the locale associated with this DateFormat.


 DateFormat.DATE_FIELD

DateFormat.DATE_FIELD

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int DATE_FIELD
Description
Useful constant for DATE field alignment. Used in FieldPosition of date/time formatting.


 DateFormat.DAY_OF_WEEK_FIELD

DateFormat.DAY_OF_WEEK_FIELD

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int DAY_OF_WEEK_FIELD
Description
Useful constant for DAY_OF_WEEK field alignment. Used in FieldPosition of date/time formatting.


 DateFormat.DAY_OF_WEEK_IN_MONTH_FIELD

DateFormat.DAY_OF_WEEK_IN_MONTH_FIELD

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int DAY_OF_WEEK_IN_MONTH_FIELD
Description
Useful constant for DAY_OF_WEEK_IN_MONTH field alignment. Used in FieldPosition of date/time formatting.


 DateFormat.DAY_OF_YEAR_FIELD

DateFormat.DAY_OF_YEAR_FIELD

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int DAY_OF_YEAR_FIELD
Description
Useful constant for DAY_OF_YEAR field alignment. Used in FieldPosition of date/time formatting.


 DateFormat.DEFAULT

DateFormat.DEFAULT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int DEFAULT
Description
Constant for default style pattern.


 DateFormat.ERA_FIELD

DateFormat.ERA_FIELD

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int ERA_FIELD
Description
Useful constant for ERA field alignment. Used in FieldPosition of date/time formatting.


 DateFormat.FULL

DateFormat.FULL

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int FULL
Description
Constant for full style pattern.


 DateFormat.HOUR0_FIELD

DateFormat.HOUR0_FIELD

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HOUR0_FIELD
Description
Useful constant for zero-based HOUR field alignment. Used in FieldPosition of date/time formatting. HOUR0_FIELD is used for the zero-based 12-hour clock. For example, 11:30 PM + 1 hour results in 00:30 AM.


 DateFormat.HOUR1_FIELD

DateFormat.HOUR1_FIELD

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HOUR1_FIELD
Description
Useful constant for one-based HOUR field alignment. Used in FieldPosition of date/time formatting. HOUR1_FIELD is used for the one-based 12-hour clock. For example, 11:30 PM + 1 hour results in 12:30 AM.


 DateFormat.HOUR_OF_DAY0_FIELD

DateFormat.HOUR_OF_DAY0_FIELD

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HOUR_OF_DAY0_FIELD
Description
Useful constant for zero-based HOUR_OF_DAY field alignment. Used in FieldPosition of date/time formatting. HOUR_OF_DAY0_FIELD is used for the zero-based 24-hour clock. For example, 23:59 + 01:00 results in 00:59.


 DateFormat.HOUR_OF_DAY1_FIELD

DateFormat.HOUR_OF_DAY1_FIELD

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HOUR_OF_DAY1_FIELD
Description
Useful constant for one-based HOUR_OF_DAY field alignment. Used in FieldPosition of date/time formatting. HOUR_OF_DAY1_FIELD is used for the one-based 24-hour clock. For example, 23:59 + 01:00 results in 24:59.


 DateFormat.LONG

DateFormat.LONG

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int LONG
Description
Constant for long style pattern.


 DateFormat.MEDIUM

DateFormat.MEDIUM

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int MEDIUM
Description
Constant for medium style pattern.


 DateFormat.MILLISECOND_FIELD

DateFormat.MILLISECOND_FIELD

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int MILLISECOND_FIELD
Description
Useful constant for MILLISECOND field alignment. Used in FieldPosition of date/time formatting.


 DateFormat.MINUTE_FIELD

DateFormat.MINUTE_FIELD

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int MINUTE_FIELD
Description
Useful constant for MINUTE field alignment. Used in FieldPosition of date/time formatting.


 DateFormat.MONTH_FIELD

DateFormat.MONTH_FIELD

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int MONTH_FIELD
Description
Useful constant for MONTH field alignment. Used in FieldPosition of date/time formatting.


 DateFormat.numberFormat

DateFormat.numberFormat

Class Overview | Class Members | This Package | All Packages

Syntax
protected NumberFormat numberFormat
Description
The number formatter that DateFormat uses to format numbers in dates and times. Subclasses should initialize this to the default number format for the locale associated with this DateFormat.


 DateFormat.SECOND_FIELD

DateFormat.SECOND_FIELD

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SECOND_FIELD
Description
Useful constant for SECOND field alignment. Used in FieldPosition of date/time formatting.


 DateFormat.SHORT

DateFormat.SHORT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SHORT
Description
Constant for short style pattern.


 DateFormat.TIMEZONE_FIELD

DateFormat.TIMEZONE_FIELD

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int TIMEZONE_FIELD
Description
Useful constant for TIMEZONE field alignment. Used in FieldPosition of date/time formatting.


 DateFormat.WEEK_OF_MONTH_FIELD

DateFormat.WEEK_OF_MONTH_FIELD

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int WEEK_OF_MONTH_FIELD
Description
Useful constant for WEEK_OF_MONTH field alignment. Used in FieldPosition of date/time formatting.


 DateFormat.WEEK_OF_YEAR_FIELD

DateFormat.WEEK_OF_YEAR_FIELD

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int WEEK_OF_YEAR_FIELD
Description
Useful constant for WEEK_OF_YEAR field alignment. Used in FieldPosition of date/time formatting.


 DateFormat.YEAR_FIELD

DateFormat.YEAR_FIELD

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int YEAR_FIELD
Description
Useful constant for YEAR field alignment. Used in FieldPosition of date/time formatting.


 DateFormat.DateFormat

DateFormat.DateFormat

Class Overview | Class Members | This Package | All Packages

Syntax
protected DateFormat()


 DateFormat.clone

DateFormat.clone

Class Overview | Class Members | This Package | All Packages

Syntax
public Object clone()
Description
Overrides Cloneable

Overrides
clone in class Format


 DateFormat.equals

DateFormat.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Description
Overrides equals

Overrides
equals in class Object


 DateFormat.format

DateFormat.format

Class Overview | Class Members | This Package | All Packages

Syntax 1
public final StringBuffer format( Object obj, StringBuffer toAppendTo, FieldPosition fieldPosition )
Parameters
obj
must be a Number or a Date.
toAppendTo
the string buffer for the returning time string.
status
the formatting status. On input: an alignment field, if desired. On output: the offsets of the alignment field.
Returns
the formatted time string.
Description
Overrides Format. Formats a time object into a time string. Examples of time objects are a time value expressed in milliseconds and a Date object.

Overrides
format in class Format
See Also
Format

Syntax 2
public abstract StringBuffer format( Date date, StringBuffer toAppendTo, FieldPosition fieldPosition )
Parameters
date
a Date to be formatted into a date/time string.
toAppendTo
the string buffer for the returning date/time string.
status
the formatting status. On input: an alignment field, if desired. On output: the offsets of the alignment field. For example, given a time text "1996.07.10 AD at 15:08:56 PDT", if the given status.field is DateFormat.YEAR_FIELD, the offsets status.beginIndex and status.getEndIndex will be set to 0 and 4, respectively. Notice that if the same time field appears more than once in a pattern, the status will be set for the first occurence of that time field. For instance, formatting a Date to the time string "1 PM PDT (Pacific Daylight Time)" using the pattern "h a z (zzzz)" and the alignment field DateFormat.TIMEZONE_FIELD, the offsets status.beginIndex and status.getEndIndex will be set to 5 and 8, respectively, for the first occurence of the timezone pattern character 'z'.
Returns
the formatted date/time string.
Description
Formats a Date into a date/time string.

Syntax 3
public final String format( Date date )
Parameters
date
the time value to be formatted into a time string.
Returns
the formatted time string.
Description
Formats a Date into a date/time string.


 DateFormat.getAvailableLocales

DateFormat.getAvailableLocales

Class Overview | Class Members | This Package | All Packages

Syntax
public static Locale[] getAvailableLocales()
Returns
the set of locales for which DateFormats are installed.
Description
Gets the set of locales for which DateFormats are installed.


 DateFormat.getCalendar

DateFormat.getCalendar

Class Overview | Class Members | This Package | All Packages

Syntax
public Calendar getCalendar()
Returns
the calendar associated with this date/time formatter.
Description
Gets the calendar associated with this date/time formatter.


 DateFormat.getDateInstance

DateFormat.getDateInstance

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static final DateFormat getDateInstance()
Returns
a date formatter.
Description
Gets the date formatter with the default formatting style for the default locale.

Syntax 2
public static final DateFormat getDateInstance( int style )
Parameters
style
the given formatting style. For example, SHORT for "M/d/yy" in the US locale.
Returns
a date formatter.
Description
Gets the date formatter with the given formatting style for the default locale.

Syntax 3
public static final DateFormat getDateInstance( int style, Locale aLocale )
Parameters
style
the given formatting style. For example, SHORT for "M/d/yy" in the US locale.
inLocale
the given locale.
Returns
a date formatter.
Description
Gets the date formatter with the given formatting style for the given locale.


 DateFormat.getDateTimeInstance

DateFormat.getDateTimeInstance

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static final DateFormat getDateTimeInstance()
Returns
a date/time formatter.
Description
Gets the date/time formatter with the default formatting style for the default locale.

Syntax 2
public static final DateFormat getDateTimeInstance( int dateStyle, int timeStyle )
Parameters
dateStyle
the given date formatting style. For example, SHORT for "M/d/yy" in the US locale.
timeStyle
the given time formatting style. For example, SHORT for "h:mm a" in the US locale.
Returns
a date/time formatter.
Description
Gets the date/time formatter with the given date and time formatting styles for the default locale.

Syntax 3
public static final DateFormat getDateTimeInstance( int dateStyle, int timeStyle, Locale aLocale )
Parameters
dateStyle
the given date formatting style.
timeStyle
the given time formatting style.
inLocale
the given locale.
Returns
a date/time formatter.
Description
Gets the date/time formatter with the given formatting styles for the given locale.


 DateFormat.getInstance

DateFormat.getInstance

Class Overview | Class Members | This Package | All Packages

Syntax
public static final DateFormat getInstance()
Description
Get a default date/time formatter that uses the SHORT style for both the date and the time.


 DateFormat.getNumberFormat

DateFormat.getNumberFormat

Class Overview | Class Members | This Package | All Packages

Syntax
public NumberFormat getNumberFormat()
Returns
the number formatter which this date/time formatter uses.
Description
Gets the number formatter which this date/time formatter uses to format and parse a time.


 DateFormat.getTimeInstance

DateFormat.getTimeInstance

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static final DateFormat getTimeInstance()
Returns
a time formatter.
Description
Gets the time formatter with the default formatting style for the default locale.

Syntax 2
public static final DateFormat getTimeInstance( int style )
Parameters
style
the given formatting style. For example, SHORT for "h:mm a" in the US locale.
Returns
a time formatter.
Description
Gets the time formatter with the given formatting style for the default locale.

Syntax 3
public static final DateFormat getTimeInstance( int style, Locale aLocale )
Parameters
style
the given formatting style. For example, SHORT for "h:mm a" in the US locale.
inLocale
the given locale.
Returns
a time formatter.
Description
Gets the time formatter with the given formatting style for the given locale.


 DateFormat.getTimeZone

DateFormat.getTimeZone

Class Overview | Class Members | This Package | All Packages

Syntax
public TimeZone getTimeZone()
Returns
the time zone associated with the calendar of DateFormat.
Description
Gets the time zone.


 DateFormat.hashCode

DateFormat.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int hashCode()
Description
Overrides hashCode

Overrides
hashCode in class Object


 DateFormat.isLenient

DateFormat.isLenient

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isLenient()
Description
Tell whether date/time parsing is to be lenient.


 DateFormat.parse

DateFormat.parse

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Date parse( String text ) throws ParseException
Description
Parse a date/time string.

Exceptions
ParseException If the given string cannot be parsed as a date.
See Also
parse

Syntax 2
public abstract Date parse( String text, ParsePosition pos )
Parameters
text
The date/time string to be parsed
pos
On input, the position at which to start parsing; on output, the position at which parsing terminated, or the start position if the parse failed.
Returns
A Date, or null if the input could not be parsed
Description
Parse a date/time string according to the given parse position. For example, a time text "07/10/96 4:5 PM, PDT" will be parsed into a Date that is equivalent to Date(837039928046).

By default, parsing is lenient: If the input is not in the form used by this object's format method but can still be parsed as a date, then the parse succeeds. Clients may insist on strict adherence to the format by calling setLenient(false).

See Also
setLenient


 DateFormat.parseObject

DateFormat.parseObject

Class Overview | Class Members | This Package | All Packages

Syntax
public Object parseObject( String source, ParsePosition pos )
Description
Parse a date/time string into an Object. This convenience method simply calls parse(String, ParsePosition).

Overrides
parseObject in class Format
See Also
parse


 DateFormat.setCalendar

DateFormat.setCalendar

Class Overview | Class Members | This Package | All Packages

Syntax
public void setCalendar( Calendar newCalendar )
Description
Set the calendar to be used by this date format. Initially, the default calendar for the specified or default locale is used.


 DateFormat.setLenient

DateFormat.setLenient

Class Overview | Class Members | This Package | All Packages

Syntax
public void setLenient( boolean lenient )
Description
Specify whether or not date/time parsing is to be lenient. With lenient parsing, the parser may use heuristics to interpret inputs that do not precisely match this object's format. With strict parsing, inputs must match this object's format.

See Also
setLenient


 DateFormat.setNumberFormat

DateFormat.setNumberFormat

Class Overview | Class Members | This Package | All Packages

Syntax
public void setNumberFormat( NumberFormat newNumberFormat )
Parameters
newNumberFormat
the given new NumberFormat.
Description
Allows you to set the number formatter.


 DateFormat.setTimeZone

DateFormat.setTimeZone

Class Overview | Class Members | This Package | All Packages

Syntax
public void setTimeZone( TimeZone zone )
Parameters
zone
the given new time zone.
Description
Sets the time zone for the calendar of this DateFormat object.


 Class DateFormatSymbols

Class java.text.DateFormatSymbols

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.text.DateFormatSymbols

public class DateFormatSymbols
extends Object
implements Serializable, Cloneable

DateFormatSymbols is a public class for encapsulating localizable date-time formatting data, such as the names of the months, the names of the days of the week, and the time zone data. DateFormat and SimpleDateFormat both use DateFormatSymbols to encapsulate this information.

Typically you shouldn't use DateFormatSymbols directly. Rather, you are encouraged to create a date-time formatter with the DateFormat class's factory methods: getTimeInstance, getDateInstance, or getDateTimeInstance. These methods automatically create a DateFormatSymbols for the formatter so that you don't have to. After the formatter is created, you may modify its format pattern using the setPattern method. For more information about creating formatters using DateFormat's factory methods, see DateFormat.

If you decide to create a date-time formatter with a specific format pattern for a specific locale, you can do so with:

 new SimpleDateFormat(aPattern, new DateFormatSymbols(aLocale)).

DateFormatSymbols objects are clonable. When you obtain a DateFormatSymbols object, feel free to modify the date-time formatting data. For instance, you can replace the localized date-time format pattern characters with the ones that you feel easy to remember. Or you can change the representative cities to your favorite ones.

New DateFormatSymbols subclasses may be added to support SimpleDateFormat for date-time formatting for additional locales.

See Also:
DateFormat, SimpleDateFormat, SimpleTimeZone


 DateFormatSymbols Members

DateFormatSymbols Members

Class Overview | This Package | All Packages

Constructors
Name | Description
DateFormatSymbols() | Construct a DateFormatSymbols object by loading format data from resources for the default locale.
DateFormatSymbols(Locale) | Construct a DateFormatSymbols object by loading format data from resources for the given locale.

Methods
Name | Description
clone() | Overrides Cloneable
equals(Object) | Override equals
getAmPmStrings() | Gets ampm strings.
getEras() | Gets era strings.
getLocalPatternChars() | Gets localized date-time pattern characters.
getMonths() | Gets month strings.
getShortMonths() | Gets short month strings.
getShortWeekdays() | Gets short weekday strings.
getWeekdays() | Gets weekday strings.
getZoneStrings() | Gets timezone strings.
hashCode() | Override hashCode.
setAmPmStrings(String[]) | Sets ampm strings.
setEras(String[]) | Sets era strings.
setLocalPatternChars(String) | Sets localized date-time pattern characters.
setMonths(String[]) | Sets month strings.
setShortMonths(String[]) | Sets short month strings.
setShortWeekdays(String[]) | Sets short weekday strings.
setWeekdays(String[]) | Sets weekday strings.
setZoneStrings(String[][]) | Sets timezone strings.


 DateFormatSymbols.DateFormatSymbols

DateFormatSymbols.DateFormatSymbols

Class Overview | Class Members | This Package | All Packages

Syntax 1
public DateFormatSymbols()
Description
Construct a DateFormatSymbols object by loading format data from resources for the default locale.

Exceptions
MissingResourceException if the resources for the default locale cannot be found or cannot be loaded.

Syntax 2
public DateFormatSymbols( Locale locale )
Description
Construct a DateFormatSymbols object by loading format data from resources for the given locale.

Exceptions
MissingResourceException if the resources for the specified locale cannot be found or cannot be loaded.


 DateFormatSymbols.clone

DateFormatSymbols.clone

Class Overview | Class Members | This Package | All Packages

Syntax
public Object clone()
Description
Overrides Cloneable

Overrides
clone in class Object


 DateFormatSymbols.equals

DateFormatSymbols.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Description
Override equals

Overrides
equals in class Object


 DateFormatSymbols.getAmPmStrings

DateFormatSymbols.getAmPmStrings

Class Overview | Class Members | This Package | All Packages

Syntax
public String[] getAmPmStrings()
Returns
the weekday strings.
Description
Gets ampm strings. For example: "AM" and "PM".


 DateFormatSymbols.getEras

DateFormatSymbols.getEras

Class Overview | Class Members | This Package | All Packages

Syntax
public String[] getEras()
Returns
the era strings.
Description
Gets era strings. For example: "AD" and "BC".


 DateFormatSymbols.getLocalPatternChars

DateFormatSymbols.getLocalPatternChars

Class Overview | Class Members | This Package | All Packages

Syntax
public String getLocalPatternChars()
Returns
the localized date-time pattern characters.
Description
Gets localized date-time pattern characters. For example: 'u', 't', etc.


 DateFormatSymbols.getMonths

DateFormatSymbols.getMonths

Class Overview | Class Members | This Package | All Packages

Syntax
public String[] getMonths()
Returns
the month strings.
Description
Gets month strings. For example: "January", "February", etc.


 DateFormatSymbols.getShortMonths

DateFormatSymbols.getShortMonths

Class Overview | Class Members | This Package | All Packages

Syntax
public String[] getShortMonths()
Returns
the short month strings.
Description
Gets short month strings. For example: "Jan", "Feb", etc.


 DateFormatSymbols.getShortWeekdays

DateFormatSymbols.getShortWeekdays

Class Overview | Class Members | This Package | All Packages

Syntax
public String[] getShortWeekdays()
Returns
the short weekday strings.
Description
Gets short weekday strings. For example: "Sun", "Mon", etc.


 DateFormatSymbols.getWeekdays

DateFormatSymbols.getWeekdays

Class Overview | Class Members | This Package | All Packages

Syntax
public String[] getWeekdays()
Returns
the weekday strings.
Description
Gets weekday strings. For example: "Sunday", "Monday", etc.


 DateFormatSymbols.getZoneStrings

DateFormatSymbols.getZoneStrings

Class Overview | Class Members | This Package | All Packages

Syntax
public String[][] getZoneStrings()
Returns
the timezone strings.
Description
Gets timezone strings.


 DateFormatSymbols.hashCode

DateFormatSymbols.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int hashCode()
Description
Override hashCode. Generates a hash code for the DateFormatSymbols object.

Overrides
hashCode in class Object


 DateFormatSymbols.setAmPmStrings

DateFormatSymbols.setAmPmStrings

Class Overview | Class Members | This Package | All Packages

Syntax
public void setAmPmStrings( String newAmpms[] )
Parameters
newAmpms
the new ampm strings.
Description
Sets ampm strings. For example: "AM" and "PM".


 DateFormatSymbols.setEras

DateFormatSymbols.setEras

Class Overview | Class Members | This Package | All Packages

Syntax
public void setEras( String newEras[] )
Parameters
newEras
the new era strings.
Description
Sets era strings. For example: "AD" and "BC".


 DateFormatSymbols.setLocalPatternChars

DateFormatSymbols.setLocalPatternChars

Class Overview | Class Members | This Package | All Packages

Syntax
public void setLocalPatternChars( String newLocalPatternChars )
Parameters
newLocalPatternChars
the new localized date-time pattern characters.
Description
Sets localized date-time pattern characters. For example: 'u', 't', etc.


 DateFormatSymbols.setMonths

DateFormatSymbols.setMonths

Class Overview | Class Members | This Package | All Packages

Syntax
public void setMonths( String newMonths[] )
Parameters
newMonths
the new month strings.
Description
Sets month strings. For example: "January", "February", etc.


 DateFormatSymbols.setShortMonths

DateFormatSymbols.setShortMonths

Class Overview | Class Members | This Package | All Packages

Syntax
public void setShortMonths( String newShortMonths[] )
Parameters
newShortMonths
the new short month strings.
Description
Sets short month strings. For example: "Jan", "Feb", etc.


 DateFormatSymbols.setShortWeekdays

DateFormatSymbols.setShortWeekdays

Class Overview | Class Members | This Package | All Packages

Syntax
public void setShortWeekdays( String newShortWeekdays[] )
Parameters
newShortWeekdays
the new short weekday strings.
Description
Sets short weekday strings. For example: "Sun", "Mon", etc.


 DateFormatSymbols.setWeekdays

DateFormatSymbols.setWeekdays

Class Overview | Class Members | This Package | All Packages

Syntax
public void setWeekdays( String newWeekdays[] )
Parameters
newWeekdays
the new weekday strings.
Description
Sets weekday strings. For example: "Sunday", "Monday", etc.


 DateFormatSymbols.setZoneStrings

DateFormatSymbols.setZoneStrings

Class Overview | Class Members | This Package | All Packages

Syntax
public void setZoneStrings( String newZoneStrings[][] )
Parameters
newZoneStrings
the new timezone strings.
Description
Sets timezone strings.


 Class DecimalFormat

Class java.text.DecimalFormat

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.text.Format
           |
           +----java.text.NumberFormat
                   |
                   +----java.text.DecimalFormat

public class DecimalFormat
extends NumberFormat

DecimalFormat is a concrete subclass of NumberFormat for formatting decimal numbers. This class allows for a variety of parameters, and localization to Western, Arabic, or Indic numbers.

Normally, you get the proper NumberFormat for a specific locale (including the default locale) using one of NumberFormat's factory methods such as getInstance. You may then modify it from there (after testing to make sure it is a DecimalFormat, of course!)

Either the prefixes or the suffixes must be different for the parse to distinguish positive from negative. Parsing will be unreliable if the digits, thousands or decimal separators are the same, or if any of them occur in the prefixes or suffixes.

Special cases:

NaN is formatted as a single character, typically \\uFFFD.

+/-Infinity is formatted as a single character, typically \\u221E, plus the positive and negative pre/suffixes.

Note: this class is designed for common users; for very large or small numbers, use a format that can express exponential values.

Example:

 // normally we would have a GUI with a menu for this
 Locale[] locales = NumberFormat.getAvailableLocales();
 double myNumber = -1234.56;
 NumberFormat form;
 // just for fun, we print out a number with the locale number, currency
 // and percent format for each locale we can.
 for (int j = 0; j < 3; ++j) {
     System.out.println("FORMAT");
     for (int i = 0; i < locales.length; ++i) {
         if (locales[i].getCountry().length() == 0) {
            // skip language-only
            continue;
         }
         System.out.print(locales[i].getDisplayName());
         switch (j) {
         default:
             form = NumberFormat.getInstance(locales[i]); break;
         case 1:
             form = NumberFormat.getCurrencyInstance(locales[i]); break;
         case 0:
             form = NumberFormat.getPercentInstance(locales[i]); break;
         }
         try {
             System.out.print(": " + ((DecimalFormat)form).toPattern()
                          + " -> " + form.format(myNumber));
         } catch (IllegalArgumentException iae) { }
         try {
             System.out.println(" -> " + form.parse(form.format(myNumber)));
         } catch (ParseException pe) { }
     }
 }
The following shows the structure of the pattern.
 pattern    := subpattern{;subpattern}
 subpattern := {prefix}integer{.fraction}{suffix}
 prefix     := '\\u0000'..'\\uFFFD' - specialCharacters
 suffix     := '\\u0000'..'\\uFFFD' - specialCharacters
 integer    := '#'* '0'* '0'
 fraction   := '0'* '#'*
 Notation:
  X*       0 or more instances of X
  (X | Y)  either X or Y.
  X..Y     any character from X up to Y, inclusive.
  S - T    characters in S, except those in T
The first subpattern is for positive numbers. The second (optional) subpattern is for negative numbers. (In both cases, ',' can occur inside the integer portion--it is just too messy to indicate in BNF.)

Here are the special characters used in the parts of the subpattern, with notes on their usage.

 Symbol Meaning
 0      a digit
 #      a digit, zero shows as absent
 .      placeholder for decimal separator
 ,      placeholder for grouping separator.
 ;      separates formats.
 -      default negative prefix.
 %      divide by 100 and show as percentage
 X      any other characters can be used in the prefix or suffix
 '      used to quote special characters in a prefix or suffix.

Notes

If there is no explicit negative subpattern, - is prefixed to the positive form. That is, "0.00" alone is equivalent to "0.00;-0.00".

Illegal formats, such as "#.#.#" or mixing '_' and '*' in the same format, will cause an ParseException to be thrown. From that ParseException, you can find the place in the string where the error occurred.

The grouping separator is commonly used for thousands, but in some countries for ten-thousands. The interval is a constant number of digits between the grouping characters, such as 100,000,000 or 1,0000,0000. If you supply a pattern with multiple grouping characters, the interval between the last one and the end of the integer is the one that is used. So "#,##,###,####" == "######,####" == "##,####,####".

This class only handles localized digits where the 10 digits are contiguous in Unicode, from 0 to 9. Other digits sets (such as superscripts) would need a different subclass.

See Also:
Format, NumberFormat, ChoiceFormat


 DecimalFormat Members

DecimalFormat Members

Class Overview | This Package | All Packages

Constructors
Name | Description
DecimalFormat() | Create a DecimalFormat using the default pattern and symbols for the default locale.
DecimalFormat(String) | Create a DecimalFormat from the given pattern and the symbols for the default locale.
DecimalFormat(String, DecimalFormatSymbols) | Create a DecimalFormat from the given pattern and symbols.

Methods
Name | Description
applyLocalizedPattern(String) | Apply the given pattern to this Format object.
applyPattern(String) | Apply the given pattern to this Format object.
clone() | Standard override; no change in semantics.
equals(Object) | Overrides equals
format(double, StringBuffer, FieldPosition) | Specialization of format.
format(long, StringBuffer, FieldPosition) | Specialization of format.
getDecimalFormatSymbols() | Returns the decimal format symbols, which is generally not changed by the programmer or user.
getGroupingSize() | Return the grouping size.
getMultiplier() | Get the multiplier for use in percent, permill, etc.
getNegativePrefix() | Get the negative prefix.
getNegativeSuffix() | Get the negative suffix.
getPositivePrefix() | Get the positive prefix.
getPositiveSuffix() | Get the positive suffix.
hashCode() | Overrides hashCode
isDecimalSeparatorAlwaysShown() | Allows you to get the behavior of the decimal separator with integers.
parse(String, ParsePosition) | Returns a Long if possible (e.g.
setDecimalFormatSymbols(DecimalFormatSymbols) | Sets the decimal format symbols, which is generally not changed by the programmer or user.
setDecimalSeparatorAlwaysShown(boolean) | Allows you to set the behavior of the decimal separator with integers.
setGroupingSize(int) | Set the grouping size.
setMultiplier(int) | Set the multiplier for use in percent, permill, etc.
setNegativePrefix(String) | Set the negative prefix.
setNegativeSuffix(String) | Set the positive suffix.
setPositivePrefix(String) | Set the positive prefix.
setPositiveSuffix(String) | Set the positive suffix.
toLocalizedPattern() | Synthesizes a localized pattern string that represents the current state of this Format object.
toPattern() | Synthesizes a pattern string that represents the current state of this Format object.


 DecimalFormat.DecimalFormat

DecimalFormat.DecimalFormat

Class Overview | Class Members | This Package | All Packages

Syntax 1
public DecimalFormat()
Description
Create a DecimalFormat using the default pattern and symbols for the default locale. This is a convenient way to obtain a DecimalFormat when internationalization is not the main concern.

To obtain standard formats for a given locale, use the factory methods on NumberFormat such as getNumberInstance. These factories will return the most appropriate sub-class of NumberFormat for a given locale.

See Also
getInstance, getNumberInstance, getCurrencyInstance, getPercentInstance

Syntax 2
public DecimalFormat( String pattern )
Parameters
pattern
A non-localized pattern string.
Description
Create a DecimalFormat from the given pattern and the symbols for the default locale. This is a convenient way to obtain a DecimalFormat when internationalization is not the main concern.

To obtain standard formats for a given locale, use the factory methods on NumberFormat such as getNumberInstance. These factories will return the most appropriate sub-class of NumberFormat for a given locale.

Exceptions
IllegalArgumentException if the given pattern is invalid.
See Also
getInstance, getNumberInstance, getCurrencyInstance, getPercentInstance

Syntax 3
public DecimalFormat( String pattern, DecimalFormatSymbols symbols )
Parameters
pattern
a non-localized pattern string
symbols
the set of symbols to be used
Description
Create a DecimalFormat from the given pattern and symbols. Use this constructor when you need to completely customize the behavior of the format.

To obtain standard formats for a given locale, use the factory methods on NumberFormat such as getInstance or getCurrencyInstance. If you need only minor adjustments to a standard format, you can modify the format returned by a NumberFormat factory method.

Exceptions
IllegalArgumentException if the given pattern is invalid
See Also
getInstance, getNumberInstance, getCurrencyInstance, getPercentInstance, DecimalFormatSymbols


 DecimalFormat.applyLocalizedPattern

DecimalFormat.applyLocalizedPattern

Class Overview | Class Members | This Package | All Packages

Syntax
public void applyLocalizedPattern( String pattern )
Description
Apply the given pattern to this Format object. The pattern is assumed to be in a localized notation. A pattern is a short-hand specification for the various formatting properties. These properties can also be changed individually through the various setter methods.

There is no limit to integer digits are set by this routine, since that is the typical end-user desire; use setMaximumInteger if you want to set a real value. For negative numbers, use a second pattern, separated by a semicolon

Example "#,#00.0#" -> 1,234.56

This means a minimum of 2 integer digits, 1 fraction digit, and a maximum of 2 fraction digits.

Example: "#,#00.0#;(#,#00.0#)" for negatives in parantheses.

In negative patterns, the minimum and maximum counts are ignored; these are presumed to be set in the positive pattern.


 DecimalFormat.applyPattern

DecimalFormat.applyPattern

Class Overview | Class Members | This Package | All Packages

Syntax
public void applyPattern( String pattern )
Description
Apply the given pattern to this Format object. A pattern is a short-hand specification for the various formatting properties. These properties can also be changed individually through the various setter methods.

There is no limit to integer digits are set by this routine, since that is the typical end-user desire; use setMaximumInteger if you want to set a real value. For negative numbers, use a second pattern, separated by a semicolon

Example "#,#00.0#" -> 1,234.56

This means a minimum of 2 integer digits, 1 fraction digit, and a maximum of 2 fraction digits.

Example: "#,#00.0#;(#,#00.0#)" for negatives in parantheses.

In negative patterns, the minimum and maximum counts are ignored; these are presumed to be set in the positive pattern.


 DecimalFormat.clone

DecimalFormat.clone

Class Overview | Class Members | This Package | All Packages

Syntax
public Object clone()
Description
Standard override; no change in semantics.

Overrides
clone in class NumberFormat


 DecimalFormat.equals

DecimalFormat.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Description
Overrides equals

Overrides
equals in class NumberFormat


 DecimalFormat.format

DecimalFormat.format

Class Overview | Class Members | This Package | All Packages

Syntax 1
public StringBuffer format( double number, StringBuffer result, FieldPosition fieldPosition )
Description
Specialization of format.

Overrides
format in class NumberFormat

Syntax 2
public StringBuffer format( long number, StringBuffer result, FieldPosition fieldPosition )
Description
Specialization of format.

Overrides
format in class NumberFormat


 DecimalFormat.getDecimalFormatSymbols

DecimalFormat.getDecimalFormatSymbols

Class Overview | Class Members | This Package | All Packages

Syntax
public DecimalFormatSymbols getDecimalFormatSymbols()
Returns
desired DecimalFormatSymbols
Description
Returns the decimal format symbols, which is generally not changed by the programmer or user.

See Also
DecimalFormatSymbols


 DecimalFormat.getGroupingSize

DecimalFormat.getGroupingSize

Class Overview | Class Members | This Package | All Packages

Syntax
public int getGroupingSize()
Description
Return the grouping size. Grouping size is the number of digits between grouping separators in the integer portion of a number. For example, in the number "123,456.78", the grouping size is 3.

See Also
setGroupingSize, isGroupingUsed, getGroupingSeparator


 DecimalFormat.getMultiplier

DecimalFormat.getMultiplier

Class Overview | Class Members | This Package | All Packages

Syntax
public int getMultiplier()
Description
Get the multiplier for use in percent, permill, etc. For a percentage, set the suffixes to have "%" and the multiplier to be 100. (For Arabic, use arabic percent symbol). For a permill, set the suffixes to have "?" and the multiplier to be 1000.

Examples: with 100, 1.23 -> "123", and "123" -> 1.23


 DecimalFormat.getNegativePrefix

DecimalFormat.getNegativePrefix

Class Overview | Class Members | This Package | All Packages

Syntax
public String getNegativePrefix()
Description
Get the negative prefix.

Examples: -123, ($123) (with negative suffix), sFr-123


 DecimalFormat.getNegativeSuffix

DecimalFormat.getNegativeSuffix

Class Overview | Class Members | This Package | All Packages

Syntax
public String getNegativeSuffix()
Description
Get the negative suffix.

Examples: -123%, ($123) (with positive suffixes)


 DecimalFormat.getPositivePrefix

DecimalFormat.getPositivePrefix

Class Overview | Class Members | This Package | All Packages

Syntax
public String getPositivePrefix()
Description
Get the positive prefix.

Examples: +123, $123, sFr123


 DecimalFormat.getPositiveSuffix

DecimalFormat.getPositiveSuffix

Class Overview | Class Members | This Package | All Packages

Syntax
public String getPositiveSuffix()
Description
Get the positive suffix.

Example: 123%


 DecimalFormat.hashCode

DecimalFormat.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int hashCode()
Description
Overrides hashCode

Overrides
hashCode in class NumberFormat


 DecimalFormat.isDecimalSeparatorAlwaysShown

DecimalFormat.isDecimalSeparatorAlwaysShown

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isDecimalSeparatorAlwaysShown()
Description
Allows you to get the behavior of the decimal separator with integers. (The decimal separator will always appear with decimals.)

Example: Decimal ON: 12345 -> 12345.; OFF: 12345 -> 12345


 DecimalFormat.parse

DecimalFormat.parse

Class Overview | Class Members | This Package | All Packages

Syntax
public Number parse( String text, ParsePosition status )
Description
Returns a Long if possible (e.g.

Overrides
parse in class NumberFormat


 DecimalFormat.setDecimalFormatSymbols

DecimalFormat.setDecimalFormatSymbols

Class Overview | Class Members | This Package | All Packages

Syntax
public void setDecimalFormatSymbols( DecimalFormatSymbols newSymbols )
Parameters
newSymbols
desired DecimalFormatSymbols
Description
Sets the decimal format symbols, which is generally not changed by the programmer or user.

See Also
DecimalFormatSymbols


 DecimalFormat.setDecimalSeparatorAlwaysShown

DecimalFormat.setDecimalSeparatorAlwaysShown

Class Overview | Class Members | This Package | All Packages

Syntax
public void setDecimalSeparatorAlwaysShown( boolean newValue )
Description
Allows you to set the behavior of the decimal separator with integers. (The decimal separator will always appear with decimals.)

Example: Decimal ON: 12345 -> 12345.; OFF: 12345 -> 12345


 DecimalFormat.setGroupingSize

DecimalFormat.setGroupingSize

Class Overview | Class Members | This Package | All Packages

Syntax
public void setGroupingSize( int newValue )
Description
Set the grouping size. Grouping size is the number of digits between grouping separators in the integer portion of a number. For example, in the number "123,456.78", the grouping size is 3.

See Also
getGroupingSize, setGroupingUsed, setGroupingSeparator


 DecimalFormat.setMultiplier

DecimalFormat.setMultiplier

Class Overview | Class Members | This Package | All Packages

Syntax
public void setMultiplier( int newValue )
Description
Set the multiplier for use in percent, permill, etc. For a percentage, set the suffixes to have "%" and the multiplier to be 100. (For Arabic, use arabic percent symbol). For a permill, set the suffixes to have "?" and the multiplier to be 1000.

Examples: with 100, 1.23 -> "123", and "123" -> 1.23


 DecimalFormat.setNegativePrefix

DecimalFormat.setNegativePrefix

Class Overview | Class Members | This Package | All Packages

Syntax
public void setNegativePrefix( String newValue )
Description
Set the negative prefix.

Examples: -123, ($123) (with negative suffix), sFr-123


 DecimalFormat.setNegativeSuffix

DecimalFormat.setNegativeSuffix

Class Overview | Class Members | This Package | All Packages

Syntax
public void setNegativeSuffix( String newValue )
Description
Set the positive suffix.

Examples: 123%


 DecimalFormat.setPositivePrefix

DecimalFormat.setPositivePrefix

Class Overview | Class Members | This Package | All Packages

Syntax
public void setPositivePrefix( String newValue )
Description
Set the positive prefix.

Examples: +123, $123, sFr123


 DecimalFormat.setPositiveSuffix

DecimalFormat.setPositiveSuffix

Class Overview | Class Members | This Package | All Packages

Syntax
public void setPositiveSuffix( String newValue )
Description
Set the positive suffix.

Example: 123%


 DecimalFormat.toLocalizedPattern

DecimalFormat.toLocalizedPattern

Class Overview | Class Members | This Package | All Packages

Syntax
public String toLocalizedPattern()
Description
Synthesizes a localized pattern string that represents the current state of this Format object.

See Also
applyPattern


 DecimalFormat.toPattern

DecimalFormat.toPattern

Class Overview | Class Members | This Package | All Packages

Syntax
public String toPattern()
Description
Synthesizes a pattern string that represents the current state of this Format object.

See Also
applyPattern


 Class DecimalFormatSymbols

Class java.text.DecimalFormatSymbols

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.text.DecimalFormatSymbols

public final class DecimalFormatSymbols
extends Object
implements Cloneable, Serializable

This class represents the set of symbols (such as the decimal separator, the grouping separator, and so on) needed by DecimalFormat to format numbers. DecimalFormat creates for itself an instance of DecimalFormatSymbols from its locale data. If you need to change any of these symbols, you can get the DecimalFormatSymbols object from your DecimalFormat and modify it.

See Also:
Locale, DecimalFormat


 DecimalFormatSymbols Members

DecimalFormatSymbols Members

Class Overview | This Package | All Packages

Constructors
Name | Description
DecimalFormatSymbols() | Create a DecimalFormatSymbols object for the default locale.
DecimalFormatSymbols(Locale) | Create a DecimalFormatSymbols object for the given locale.

Methods
Name | Description
clone() | Standard override.
equals(Object) | Override equals
getDecimalSeparator() | character used for decimal sign.
getDigit() | character used for a digit in a pattern.
getGroupingSeparator() | character used for thousands separator.
getInfinity() | character used to represent infinity.
getMinusSign() | character used to represent minus sign.
getNaN() | character used to represent NaN.
getPatternSeparator() | character used to separate positive and negative subpatterns in a pattern.
getPercent() | character used for percent sign.
getPerMill() | character used for mille percent sign.
getZeroDigit() | character used for zero.
hashCode() | Override hashCode
setDecimalSeparator(char) |
setDigit(char) |
setGroupingSeparator(char) |
setInfinity(String) |
setMinusSign(char) |
setNaN(String) |
setPatternSeparator(char) |
setPercent(char) |
setPerMill(char) |
setZeroDigit(char) |


 DecimalFormatSymbols.DecimalFormatSymbols

DecimalFormatSymbols.DecimalFormatSymbols

Class Overview | Class Members | This Package | All Packages

Syntax 1
public DecimalFormatSymbols()
Description
Create a DecimalFormatSymbols object for the default locale.

Syntax 2
public DecimalFormatSymbols( Locale locale )
Description
Create a DecimalFormatSymbols object for the given locale.


 DecimalFormatSymbols.clone

DecimalFormatSymbols.clone

Class Overview | Class Members | This Package | All Packages

Syntax
public Object clone()
Description
Standard override.

Overrides
clone in class Object


 DecimalFormatSymbols.equals

DecimalFormatSymbols.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Description
Override equals

Overrides
equals in class Object


 DecimalFormatSymbols.getDecimalSeparator

DecimalFormatSymbols.getDecimalSeparator

Class Overview | Class Members | This Package | All Packages

Syntax
public char getDecimalSeparator()
Description
character used for decimal sign. Different for French, etc.


 DecimalFormatSymbols.getDigit

DecimalFormatSymbols.getDigit

Class Overview | Class Members | This Package | All Packages

Syntax
public char getDigit()
Description
character used for a digit in a pattern.


 DecimalFormatSymbols.getGroupingSeparator

DecimalFormatSymbols.getGroupingSeparator

Class Overview | Class Members | This Package | All Packages

Syntax
public char getGroupingSeparator()
Description
character used for thousands separator. Different for French, etc.


 DecimalFormatSymbols.getInfinity

DecimalFormatSymbols.getInfinity

Class Overview | Class Members | This Package | All Packages

Syntax
public String getInfinity()
Description
character used to represent infinity. Almost always left unchanged.


 DecimalFormatSymbols.getMinusSign

DecimalFormatSymbols.getMinusSign

Class Overview | Class Members | This Package | All Packages

Syntax
public char getMinusSign()
Description
character used to represent minus sign. If no explicit negative format is specified, one is formed by prefixing minusSign to the positive format.


 DecimalFormatSymbols.getNaN

DecimalFormatSymbols.getNaN

Class Overview | Class Members | This Package | All Packages

Syntax
public String getNaN()
Description
character used to represent NaN. Almost always left unchanged.


 DecimalFormatSymbols.getPatternSeparator

DecimalFormatSymbols.getPatternSeparator

Class Overview | Class Members | This Package | All Packages

Syntax
public char getPatternSeparator()
Description
character used to separate positive and negative subpatterns in a pattern.


 DecimalFormatSymbols.getPercent

DecimalFormatSymbols.getPercent

Class Overview | Class Members | This Package | All Packages

Syntax
public char getPercent()
Description
character used for percent sign. Different for Arabic, etc.


 DecimalFormatSymbols.getPerMill

DecimalFormatSymbols.getPerMill

Class Overview | Class Members | This Package | All Packages

Syntax
public char getPerMill()
Description
character used for mille percent sign. Different for Arabic, etc.


 DecimalFormatSymbols.getZeroDigit

DecimalFormatSymbols.getZeroDigit

Class Overview | Class Members | This Package | All Packages

Syntax
public char getZeroDigit()
Description
character used for zero. Different for Arabic, etc.


 DecimalFormatSymbols.hashCode

DecimalFormatSymbols.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int hashCode()
Description
Override hashCode

Overrides
hashCode in class Object


 DecimalFormatSymbols.setDecimalSeparator

DecimalFormatSymbols.setDecimalSeparator

Class Overview | Class Members | This Package | All Packages

Syntax
public void setDecimalSeparator( char decimalSeparator )


 DecimalFormatSymbols.setDigit

DecimalFormatSymbols.setDigit

Class Overview | Class Members | This Package | All Packages

Syntax
public void setDigit( char digit )


 DecimalFormatSymbols.setGroupingSeparator

DecimalFormatSymbols.setGroupingSeparator

Class Overview | Class Members | This Package | All Packages

Syntax
public void setGroupingSeparator( char groupingSeparator )


 DecimalFormatSymbols.setInfinity

DecimalFormatSymbols.setInfinity

Class Overview | Class Members | This Package | All Packages

Syntax
public void setInfinity( String infinity )


 DecimalFormatSymbols.setMinusSign

DecimalFormatSymbols.setMinusSign

Class Overview | Class Members | This Package | All Packages

Syntax
public void setMinusSign( char minusSign )


 DecimalFormatSymbols.setNaN

DecimalFormatSymbols.setNaN

Class Overview | Class Members | This Package | All Packages

Syntax
public void setNaN( String NaN )


 DecimalFormatSymbols.setPatternSeparator

DecimalFormatSymbols.setPatternSeparator

Class Overview | Class Members | This Package | All Packages

Syntax
public void setPatternSeparator( char patternSeparator )


 DecimalFormatSymbols.setPercent

DecimalFormatSymbols.setPercent

Class Overview | Class Members | This Package | All Packages

Syntax
public void setPercent( char percent )


 DecimalFormatSymbols.setPerMill

DecimalFormatSymbols.setPerMill

Class Overview | Class Members | This Package | All Packages

Syntax
public void setPerMill( char perMill )


 DecimalFormatSymbols.setZeroDigit

DecimalFormatSymbols.setZeroDigit

Class Overview | Class Members | This Package | All Packages

Syntax
public void setZeroDigit( char zeroDigit )


 Class FieldPosition

Class java.text.FieldPosition

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.text.FieldPosition

public class FieldPosition
extends Object

FieldPosition is a simple class used by Format and its subclasses to identify fields in formatted output. Fields are identified by constants, whose names typically end with _FIELD, defined in the various subclasses of Format. See ERA_FIELD and its friends in DateFormat for an example.

FieldPosition keeps track of the position of the field within the formatted output with two indices: the index of the first character of the field and the index of the last character of the field.

One version of the format method in the various Format classes requires a FieldPosition object as an argument. You use this format method to perform partial formatting or to get information about the formatted output (such as the position of a field).

See Also:
Format


 FieldPosition Members

FieldPosition Members

Class Overview | This Package | All Packages

Constructors
Name | Description
FieldPosition(int) | Creates a FieldPosition object for the given field.

Methods
Name | Description
getBeginIndex() | Retrieve the index of the first character in the requested field.
getEndIndex() | Retrieve the index of the character following the last character in the requested field.
getField() | Retrieve the field identifier.


 FieldPosition.FieldPosition

FieldPosition.FieldPosition

Class Overview | Class Members | This Package | All Packages

Syntax
public FieldPosition( int field )
Description
Creates a FieldPosition object for the given field. Fields are identified by constants, whose names typically end with _FIELD, in the various subclasses of Format.

See Also
INTEGER_FIELD, FRACTION_FIELD, YEAR_FIELD, MONTH_FIELD


 FieldPosition.getBeginIndex

FieldPosition.getBeginIndex

Class Overview | Class Members | This Package | All Packages

Syntax
public int getBeginIndex()
Description
Retrieve the index of the first character in the requested field.


 FieldPosition.getEndIndex

FieldPosition.getEndIndex

Class Overview | Class Members | This Package | All Packages

Syntax
public int getEndIndex()
Description
Retrieve the index of the character following the last character in the requested field.


 FieldPosition.getField

FieldPosition.getField

Class Overview | Class Members | This Package | All Packages

Syntax
public int getField()
Description
Retrieve the field identifier.


 Class Format

Class java.text.Format

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.text.Format

public abstract class Format
extends Object
implements Serializable, Cloneable

Format is an abstract base class for formatting locale-sensitive information such as dates, messages, and numbers.

Format defines the programming interface for formatting locale-sensitive objects into Strings (the format method) and for parsing Strings back into objects (the parseObject method). Any String formatted by format is guaranteed to be parseable by parseObject.

If formatting is unsuccessful because the Format object cannot format the type of object specified, format throws an IllegalArgumentException. Otherwise, if there is something illformed about the object, format returns the Unicode replacement character \\uFFFD.

If there is no match when parsing, parseObject(String) throws a ParseException, and parseObject(String, ParsePosition) leaves the ParsePosition index member unchanged and returns null.

Subclassing: The JDK provides three concrete subclasses of Format-- DateFormat, MessageFormat, and NumberFormat--for formatting dates, messages, and numbers, respectively.

Concrete subclasses must implement these two methods:

  1. format(Object obj, StringBuffer toAppendTo, FieldPosition pos)
  2. parseObject (String source, ParsePosition pos)

Most subclasses will also implement the following two methods:

  1. getInstance for getting a useful format object appropriate for the current locale
  2. getInstance(Locale) for getting a useful format object appropriate for the specified locale
In addition, some subclasses may also choose to implement other getXxxxInstance methods for more specialized control. For example, the NumberFormat class provides getPercentInstance and getCurrencyInstance methods for getting specialized number formatters.

Subclasses of Format that allow programmers to create objects for locales (with getInstance(Locale) for example) must also implement the following class method:

 public static Locale[] getAvailableLocales()

And finally subclasses may define a set of constants to identify the various fields in the formatted output. These constants are used to create a FieldPosition object which identifies what information is contained in the field and its position in the formatted result. These constants should be named item_FIELD where item identifies the field. For examples of these constants, see ERA_FIELD and its friends in DateFormat.

See Also:
ParsePosition, FieldPosition, NumberFormat, DateFormat, MessageFormat


 Format Members

Format Members

Class Overview | This Package | All Packages

Constructors
Name | Description
Format() |

Methods
Name | Description
clone() | Creates a new object of the same class as this object.
format(Object) | Formats an object to produce a string.
format(Object, StringBuffer, FieldPosition) | Formats an object to produce a string.
parseObject(String) | Parses a string to produce an object.
parseObject(String, ParsePosition) | Parses a string to produce an object.


 Format.Format

Format.Format

Class Overview | Class Members | This Package | All Packages

Syntax
public Format()


 Format.clone

Format.clone

Class Overview | Class Members | This Package | All Packages

Syntax
public Object clone()
Description
Creates a new object of the same class as this object.

Overrides
clone in class Object


 Format.format

Format.format

Class Overview | Class Members | This Package | All Packages

Syntax 1
public final String format( Object obj )
Parameters
obj
The object to format
Returns
Formatted string.
Description
Formats an object to produce a string.

Subclasses will override the StringBuffer version of format.

Exceptions
IllegalArgumentException when the Format cannot format the type of object.
See Also
MessageFormat, format

Syntax 2
public abstract StringBuffer format( Object obj, StringBuffer toAppendTo, FieldPosition pos )
Parameters
obj
The object to format
toAppendTo
where the text is to be appended
status
On input: an alignment field, if desired. On output: the offsets of the alignment field.
Returns
the value passed in as toAppendTo (this allows chaining, as with StringBuffer.append())
Description
Formats an object to produce a string. Subclasses will implement for particular object, such as:
 StringBuffer format (Number obj, StringBuffer toAppendTo)
 Number parse (String str)
These general routines allow polymorphic parsing and formatting for objects such as the MessageFormat.

Exceptions
IllegalArgumentException when the Format cannot format the given object.
See Also
MessageFormat, FieldPosition


 Format.parseObject

Format.parseObject

Class Overview | Class Members | This Package | All Packages

Syntax 1
public abstract Object parseObject( String source, ParsePosition status )
Parameters
ParsePosition
Input-Output parameter.

Before calling, set status.index to the offset you want to start parsing at in the source. After calling, status.index is the end of the text you parsed. If error occurs, index is unchanged.

When parsing, leading whitespace is discarded (with successful parse), while trailing whitespace is left as is.

Example: Parsing "_12_xy" (where _ represents a space) for a number, with index == 0 will result in the number 12, with status.index updated to 3 (just before the second space). Parsing a second time will result in a ParseException since "xy" is not a number, and leave index at 3.

Subclasses will typically supply specific parse methods that return different types of values. Since methods can't overload on return types, these will typically be named "parse", while this polymorphic method will always be called parseObject. Any parse method that does not take a status should throw ParseException when no text in the required format is at the start position.

Returns
Object parsed from string. In case of error, returns null.
Description
Parses a string to produce an object. Subclasses will typically implement for particular object, such as:
       String format (Number obj);
       String format (long obj);
       String format (double obj);
       Number parse (String str);

See Also
ParsePosition

Syntax 2
public Object parseObject( String source ) throws ParseException
Description
Parses a string to produce an object.

Exceptions
ParseException if the specified string is invalid.


 Class MessageFormat

Class java.text.MessageFormat

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.text.Format
           |
           +----java.text.MessageFormat

public class MessageFormat
extends Format

MessageFormat provides a means to produce concatenated messages in language-neutral way. Use this to construct messages displayed for end users.

MessageFormat takes a set of objects, formats them, then inserts the formatted strings into the pattern at the appropriate places.

Note: MessageFormat differs from the other Format classes in that you create a MessageFormat object with one of its constructors (not with a getInstance style factory method). The factory methods aren't necessary because MessageFormat doesn't require any complex setup for a given locale. In fact, MessageFormat doesn't implement any locale specific behavior at all. It just needs to be set up on a sentence by sentence basis.

Here are some examples of usage:

 Object[] arguments = {
     new Integer(7),
     new Date(System.currentTimeMillis()),
     "a disturbance in the Force"
 };
 String result = MessageFormat.format(
     "At {1,time} on {1,date}, there was {2} on planet {0,number,integer}.",
     arguments);
 : At 12:30 PM on Jul 3, 2053, there was a disturbance
           in the Force on planet 7.
Typically, the message format will come from resources, and the arguments will be dynamically set at runtime.

Example 2:

 Object[] testArgs = {new Long(3), "MyDisk"};
 MessageFormat form = new MessageFormat(
     "The disk \"{1}\" contains {0} file(s).");
 System.out.println(form.format(testArgs));
 // output, with different testArgs
 : The disk "MyDisk" contains 0 file(s).
 : The disk "MyDisk" contains 1 file(s).
 : The disk "MyDisk" contains 1,273 file(s).

The pattern is of the form:

 messageFormatPattern := string ( "{" messageFormatElement "}" string )*
 messageFormatElement := argument { "," elementFormat }
 elementFormat := "time" { "," datetimeStyle }
                | "date" { "," datetimeStyle }
                | "number" { "," numberStyle }
                | "choice" { "," choiceStyle }
 datetimeStyle := "short"
                  | "medium"
                  | "long"
                  | "full"
                  | dateFormatPattern
 numberStyle := "currency"
               | "percent"
               | "integer"
               | numberFormatPattern
 choiceStyle := choiceFormatPattern
If there is no elementFormat, then the argument must be a string, which is substituted. If there is no dateTimeStyle or numberStyle, then the default format is used (for example, NumberFormat.getInstance, DateFormat.getTimeInstance, or DateFormat.getInstance).

In strings, single quotes can be used to quote the "{" (curly brace) if necessary. A real single quote is represented by ''. Inside a messageFormatElement, quotes are not removed. For example, {1,number,$'#',##} will produce a number format with the pound-sign quoted, with a result such as: "$#31,45".

If a pattern is used, then unquoted braces in the pattern, if any, must match: that is, "ab {0} de" and "ab '}' de" are ok, but "ab {0'}' de" and "ab } de" are not.

The argument is a number from 0 to 9, which corresponds to the arguments presented in an array to be formatted.

It is ok to have unused arguments in the array. With missing arguments or arguments that are not of the right class for the specified format, a ParseException is thrown. First, format checks to see if a Format object has been specified for the argument with the setFormats method. If so, then format uses that Format object to format the argument. Otherwise, the argument is formatted based on the object's type. If the argument is a Number, then format uses NumberFormat.getInstance to format the argument; if the argument is a Date, then format uses DateFormat.getDateTimeInstance to format the argument. Otherwise, it uses the toString method.

For more sophisticated patterns, you can use a ChoiceFormat to get output such as:

 MessageFormat form = new MessageFormat("The disk \"{1}\" contains {0}.");
 double[] filelimits = {0,1,2};
 String[] filepart = {"no files","one file","{0,number} files"};
 ChoiceFormat fileform = new ChoiceFormat(filelimits, filepart);
 form.setFormat(1,fileform); // NOT zero, see below
 Object[] testArgs = {new Long(12373), "MyDisk"};
 System.out.println(form.format(testArgs));
 // output, with different testArgs
 output: The disk "MyDisk" contains no files.
 output: The disk "MyDisk" contains one file.
 output: The disk "MyDisk" contains 1,273 files.
You can either do this programmatically, as in the above example, or by using a pattern (see ChoiceFormat for more information) as in:
 form.applyPattern(
    "There {0,choice,0#are no files|1#is one file|1#are {0,number,integer} files}.");

Note: As we see above, the string produced by a ChoiceFormat in MessageFormat is treated specially; occurances of '{' are used to indicated subformats, and cause recursion. If you create both a MessageFormat and ChoiceFormat programmatically (instead of using the string patterns), then be careful not to produce a format that recurses on itself, which will cause an infinite loop.

Note: formats are numbered by order of variable in the string. This is not the same as the argument numbering! For example: with "abc{2}def{3}ghi{0}...",

  • format0 affects the first variable {2}
  • format1 affects the second variable {3}
  • format2 affects the second variable {0}
  • and so on.

See Also:
Locale, Format, NumberFormat, DecimalFormat, ChoiceFormat


 MessageFormat Members

MessageFormat Members

Class Overview | This Package | All Packages

Constructors
Name | Description
MessageFormat(String) | Constructs with the specified pattern.

Methods
Name | Description
applyPattern(String) | Sets the pattern.
clone() | Overrides Cloneable
equals(Object) | Equality comparision between two message format objects
format(Object, StringBuffer, FieldPosition) | Formats an object to produce a string.
format(Object[], StringBuffer, FieldPosition) | Returns pattern with formatted objects.
format(String, Object[]) | Convenience routine.
getFormats() | Gets formats that were set with setFormats.
getLocale() | Gets the locale.
hashCode() | Generates a hash code for the message format object.
parse(String) | Parses the string.
parse(String, ParsePosition) | Parses the string.
parseObject(String, ParsePosition) | Parses the string.
setFormat(int, Format) | Sets formats individually to use on parameters.
setFormats(Format[]) | Sets formats to use on parameters.
setLocale(Locale) | Constructs with the specified pattern and formats for the arguments in that pattern.
toPattern() | Gets the pattern.


 MessageFormat.MessageFormat

MessageFormat.MessageFormat

Class Overview | Class Members | This Package | All Packages

Syntax
public MessageFormat( String pattern )
Description
Constructs with the specified pattern.

See Also
applyPattern


 MessageFormat.applyPattern

MessageFormat.applyPattern

Class Overview | Class Members | This Package | All Packages

Syntax
public void applyPattern( String newPattern )
Description
Sets the pattern. See the class description.


 MessageFormat.clone

MessageFormat.clone

Class Overview | Class Members | This Package | All Packages

Syntax
public Object clone()
Description
Overrides Cloneable

Overrides
clone in class Format


 MessageFormat.equals

MessageFormat.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Description
Equality comparision between two message format objects

Overrides
equals in class Object


 MessageFormat.format

MessageFormat.format

Class Overview | Class Members | This Package | All Packages

Syntax 1
public final StringBuffer format( Object source[], StringBuffer result, FieldPosition ignore )
Parameters
source
an array of objects to be formatted & substituted.
result
where text is appended.
ignore
no useful status is returned.
Description
Returns pattern with formatted objects.

Syntax 2
public static String format( String pattern, Object arguments[] )
Description
Convenience routine. Avoids explicit creation of MessageFormat, but doesn't allow future optimizations.

Syntax 3
public final StringBuffer format( Object source, StringBuffer result, FieldPosition ignore )
Description
Formats an object to produce a string.

Overrides
format in class Format


 MessageFormat.getFormats

MessageFormat.getFormats

Class Overview | Class Members | This Package | All Packages

Syntax
public Format[] getFormats()
Description
Gets formats that were set with setFormats. See the class description about format numbering.


 MessageFormat.getLocale

MessageFormat.getLocale

Class Overview | Class Members | This Package | All Packages

Syntax
public Locale getLocale()
Description
Gets the locale. This locale is used for fetching default number or date format information.


 MessageFormat.hashCode

MessageFormat.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int hashCode()
Description
Generates a hash code for the message format object.

Overrides
hashCode in class Object


 MessageFormat.parse

MessageFormat.parse

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Object[] parse( String source, ParsePosition status )
Description
Parses the string.

Caveats: The parse may fail in a number of circumstances. For example:

  • If one of the arguments does not occur in the pattern.
  • If the format of an argument is loses information, such as with a choice format where a large number formats to "many".
  • Does not yet handle recursion (where the substituted strings contain {n} references.)
  • Will not always find a match (or the correct match) if some part of the parse is ambiguous. For example, if the pattern "{1},{2}" is used with the string arguments {"a,b", "c"}, it will format as "a,b,c". When the result is parsed, it will return {"a", "b,c"}.
  • If a single argument is formatted twice in the string, then the later parse wins.

Syntax 2
public Object[] parse( String source ) throws ParseException
Description
Parses the string. Does not yet handle recursion (where the substituted strings contain {n} references.)

Exceptions
ParseException if the string can't be parsed.


 MessageFormat.parseObject

MessageFormat.parseObject

Class Overview | Class Members | This Package | All Packages

Syntax
public Object parseObject( String text, ParsePosition status )
Description
Parses the string. Does not yet handle recursion (where the substituted strings contain %n references.)

Overrides
parseObject in class Format


 MessageFormat.setFormat

MessageFormat.setFormat

Class Overview | Class Members | This Package | All Packages

Syntax
public void setFormat( int variable, Format newFormat )
Description
Sets formats individually to use on parameters. See the class description about format numbering.


 MessageFormat.setFormats

MessageFormat.setFormats

Class Overview | Class Members | This Package | All Packages

Syntax
public void setFormats( Format newFormats[] )
Description
Sets formats to use on parameters. See the class description about format numbering.


 MessageFormat.setLocale

MessageFormat.setLocale

Class Overview | Class Members | This Package | All Packages

Syntax
public void setLocale( Locale theLocale )
Description
Constructs with the specified pattern and formats for the arguments in that pattern.

See Also
applyPattern


 MessageFormat.toPattern

MessageFormat.toPattern

Class Overview | Class Members | This Package | All Packages

Syntax
public String toPattern()
Description
Gets the pattern. See the class description.


 Class NumberFormat

Class java.text.NumberFormat

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.text.Format
           |
           +----java.text.NumberFormat

public abstract class NumberFormat
extends Format
implements Cloneable

NumberFormat is the abstract base class for all number formats. This class provides the interface for formatting and parsing numbers. NumberFormat also provides methods for determining which locales have number formats, and what their names are.

NumberFormat helps you to format and parse numbers for any locale. Your code can be completely independent of the locale conventions for decimal points, thousands-separators, or even the particular decimal digits used, or whether the number format is even decimal.

To format a number for the current Locale, use one of the factory class methods:

  myString = NumberFormat.getInstance().format(myNumber);
If you are formatting multiple numbers, it is more efficient to get the format and use it multiple times so that the system doesn't have to fetch the information about the local language and country conventions multiple times.
 NumberFormat nf = NumberFormat.getInstance();
 for (int i = 0; i < a.length; ++i) {
     output.println(nf.format(myNumber[i]) + "; ");
 }
To format a number for a different Locale, specify it in the call to getInstance.
 NumberFormat nf = NumberFormat.getInstance(Locale.FRENCH);
You can also use a NumberFormat to parse numbers:
 myNumber = nf.parse(myString);
Use getInstance or getNumberInstance to get the normal number format. Use getCurrencyInstance to get the currency number format. And use getPercentInstance to get a format for displaying percentages. With this format, a fraction like 0.53 is displayed as 53%.

You can also control the display of numbers with such methods as setMinimumFractionDigits. If you want even more control over the format or parsing, or want to give your users more control, you can try casting the NumberFormat you get from the factory methods to a DecimalNumberFormat. This will work for the vast majority of locales; just remember to put it in a try block in case you encounter an unusual one.

You can also use forms of the parse and format methods with ParsePosition and FieldPosition to allow you to:

  • progressively parse through pieces of a string
  • align the decimal point and other areas
For example, you can align numbers in two ways:
  1. If you are using a monospaced font with spacing for alignment, you can pass the FieldPosition in your format call, with field = INTEGER_FIELD. On output, getEndIndex will be set to the offset between the last character of the integer and the decimal. Add (desiredSpaceCount - getEndIndex) spaces at the front of the string.
  2. If you are using proportional fonts, instead of padding with spaces, measure the width of the string in pixels from the start to getEndIndex. Then move the pen by (desiredPixelWidth - widthToAlignmentPoint) before drawing the text. It also works where there is no decimal, but possibly additional characters at the end, e.g. with parentheses in negative numbers: "(12)" for -12.

See Also:
DecimalFormat, ChoiceFormat


 NumberFormat Members

NumberFormat Members

Class Overview | This Package | All Packages

Fields
Name | Description
FRACTION_FIELD | Field constant used to construct a FieldPosition object.
INTEGER_FIELD | Field constant used to construct a FieldPosition object.

Constructors
Name | Description
NumberFormat() |

Methods
Name | Description
clone() | Overrides Cloneable
equals(Object) | Overrides equals
format(double) | Specialization of format.
format(double, StringBuffer, FieldPosition) | Specialization of format.
format(long) | Specialization of format.
format(long, StringBuffer, FieldPosition) | Specialization of format.
format(Object, StringBuffer, FieldPosition) | Formats an object to produce a string.
getAvailableLocales() | Get the set of Locales for which NumberFormats are installed
getCurrencyInstance() | Returns a currency format for the current default locale.
getCurrencyInstance(Locale) | Returns a currency format for the specified locale.
getInstance() | Returns the default number format for the current default locale.
getInstance(Locale) | Returns the default number format for the specified locale.
getMaximumFractionDigits() | Returns the maximum number of digits allowed in the fraction portion of a number.
getMaximumIntegerDigits() | Returns the maximum number of digits allowed in the integer portion of a number.
getMinimumFractionDigits() | Returns the minimum number of digits allowed in the fraction portion of a number.
getMinimumIntegerDigits() | Returns the minimum number of digits allowed in the integer portion of a number.
getNumberInstance() | Returns a general-purpose number format for the current default locale.
getNumberInstance(Locale) | Returns a general-purpose number format for the specified locale.
getPercentInstance() | Returns a percentage format for the current default locale.
getPercentInstance(Locale) | Returns a percentage format for the specified locale.
hashCode() | Overrides hashCode
isGroupingUsed() | Returns true if grouping is used in this format.
isParseIntegerOnly() | Returns true if this format will parse numbers as integers only.
parse(String) | Convenience method.
parse(String, ParsePosition) | Returns a Long if possible (e.g.
parseObject(String, ParsePosition) | Parses a string to produce an object.
setGroupingUsed(boolean) | Set whether or not grouping will be used in this format.
setMaximumFractionDigits(int) | Sets the maximum number of digits allowed in the fraction portion of a number.
setMaximumIntegerDigits(int) | Sets the maximum number of digits allowed in the integer portion of a number.
setMinimumFractionDigits(int) | Sets the minimum number of digits allowed in the fraction portion of a number.
setMinimumIntegerDigits(int) | Sets the minimum number of digits allowed in the integer portion of a number.
setParseIntegerOnly(boolean) | Sets whether or not numbers should be parsed as integers only.


 NumberFormat.FRACTION_FIELD

NumberFormat.FRACTION_FIELD

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int FRACTION_FIELD
Description
Field constant used to construct a FieldPosition object. Signifies that the position of the fraction part of a formatted number should be returned.

See Also
FieldPosition


 NumberFormat.INTEGER_FIELD

NumberFormat.INTEGER_FIELD

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int INTEGER_FIELD
Description
Field constant used to construct a FieldPosition object. Signifies that the position of the integer part of a formatted number should be returned.

See Also
FieldPosition


 NumberFormat.NumberFormat

NumberFormat.NumberFormat

Class Overview | Class Members | This Package | All Packages

Syntax
public NumberFormat()


 NumberFormat.clone

NumberFormat.clone

Class Overview | Class Members | This Package | All Packages

Syntax
public Object clone()
Description
Overrides Cloneable

Overrides
clone in class Format


 NumberFormat.equals

NumberFormat.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Description
Overrides equals

Overrides
equals in class Object


 NumberFormat.format

NumberFormat.format

Class Overview | Class Members | This Package | All Packages

Syntax
public final StringBuffer format( Object number, StringBuffer toAppendTo, FieldPosition pos )
Description
Formats an object to produce a string.

Overrides
format in class Format


 NumberFormat.format

NumberFormat.format

Class Overview | Class Members | This Package | All Packages

Syntax 1
public final String format( double number )
Description
Specialization of format.

See Also
format

Syntax 2
public final String format( long number )
Description
Specialization of format.

See Also
format

Syntax 3
public abstract StringBuffer format( double number, StringBuffer toAppendTo, FieldPosition pos )
Description
Specialization of format.

See Also
format

Syntax 4
public abstract StringBuffer format( long number, StringBuffer toAppendTo, FieldPosition pos )
Description
Specialization of format.

See Also
format


 NumberFormat.getAvailableLocales

NumberFormat.getAvailableLocales

Class Overview | Class Members | This Package | All Packages

Syntax
public static Locale[] getAvailableLocales()
Returns
available locales
Description
Get the set of Locales for which NumberFormats are installed


 NumberFormat.getCurrencyInstance

NumberFormat.getCurrencyInstance

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static final NumberFormat getCurrencyInstance()
Description
Returns a currency format for the current default locale.

Syntax 2
public static NumberFormat getCurrencyInstance( Locale inLocale )
Description
Returns a currency format for the specified locale.


 NumberFormat.getInstance

NumberFormat.getInstance

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static final NumberFormat getInstance()
Description
Returns the default number format for the current default locale. The default format is one of the styles provided by the other factory methods: getNumberInstance, getCurrencyInstance or getPercentInstance. Exactly which one is locale dependant.

Syntax 2
public static NumberFormat getInstance( Locale inLocale )
Description
Returns the default number format for the specified locale. The default format is one of the styles provided by the other factory methods: getNumberInstance, getCurrencyInstance or getPercentInstance. Exactly which one is locale dependant.


 NumberFormat.getMaximumFractionDigits

NumberFormat.getMaximumFractionDigits

Class Overview | Class Members | This Package | All Packages

Syntax
public int getMaximumFractionDigits()
Description
Returns the maximum number of digits allowed in the fraction portion of a number.

See Also
setMaximumFractionDigits


 NumberFormat.getMaximumIntegerDigits

NumberFormat.getMaximumIntegerDigits

Class Overview | Class Members | This Package | All Packages

Syntax
public int getMaximumIntegerDigits()
Description
Returns the maximum number of digits allowed in the integer portion of a number.

See Also
setMaximumIntegerDigits


 NumberFormat.getMinimumFractionDigits

NumberFormat.getMinimumFractionDigits

Class Overview | Class Members | This Package | All Packages

Syntax
public int getMinimumFractionDigits()
Description
Returns the minimum number of digits allowed in the fraction portion of a number.

See Also
setMinimumFractionDigits


 NumberFormat.getMinimumIntegerDigits

NumberFormat.getMinimumIntegerDigits

Class Overview | Class Members | This Package | All Packages

Syntax
public int getMinimumIntegerDigits()
Description
Returns the minimum number of digits allowed in the integer portion of a number.

See Also
setMinimumIntegerDigits


 NumberFormat.getNumberInstance

NumberFormat.getNumberInstance

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static final NumberFormat getNumberInstance()
Description
Returns a general-purpose number format for the current default locale.

Syntax 2
public static NumberFormat getNumberInstance( Locale inLocale )
Description
Returns a general-purpose number format for the specified locale.


 NumberFormat.getPercentInstance

NumberFormat.getPercentInstance

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static final NumberFormat getPercentInstance()
Description
Returns a percentage format for the current default locale.

Syntax 2
public static NumberFormat getPercentInstance( Locale inLocale )
Description
Returns a percentage format for the specified locale.


 NumberFormat.hashCode

NumberFormat.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int hashCode()
Description
Overrides hashCode

Overrides
hashCode in class Object


 NumberFormat.isGroupingUsed

NumberFormat.isGroupingUsed

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isGroupingUsed()
Description
Returns true if grouping is used in this format. For example, in the English locale, with grouping on, the number 1234567 might be formatted as "1,234,567". The grouping separator as well as the size of each group is locale dependant and is determined by sub-classes of NumberFormat.

See Also
setGroupingUsed


 NumberFormat.isParseIntegerOnly

NumberFormat.isParseIntegerOnly

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isParseIntegerOnly()
Description
Returns true if this format will parse numbers as integers only. For example in the English locale, with ParseIntegerOnly true, the string "1234." would be parsed as the integer value 1234 and parsing would stop at the "." character. Of course, the exact format accepted by the parse operation is locale dependant and determined by sub-classes of NumberFormat.


 NumberFormat.parse

NumberFormat.parse

Class Overview | Class Members | This Package | All Packages

Syntax 1
public abstract Number parse( String text, ParsePosition parsePosition )
Description
Returns a Long if possible (e.g. within range [Long.MIN_VALUE, Long.MAX_VALUE], and with no decimals), otherwise a Double. If IntegerOnly is set, will stop at a decimal point (or equivalent; e.g. for rational numbers "1 2/3", will stop after the 1). Does not throw an exception; if no object can be parsed, index is unchanged!

See Also
isParseIntegerOnly, parseObject

Syntax 2
public Number parse( String text ) throws ParseException
Description
Convenience method.

Exceptions
ParseException if the specified string is invalid.
See Also
format


 NumberFormat.parseObject

NumberFormat.parseObject

Class Overview | Class Members | This Package | All Packages

Syntax
public final Object parseObject( String source, ParsePosition parsePosition )
Description
Parses a string to produce an object.

Overrides
parseObject in class Format


 NumberFormat.setGroupingUsed

NumberFormat.setGroupingUsed

Class Overview | Class Members | This Package | All Packages

Syntax
public void setGroupingUsed( boolean newValue )
Description
Set whether or not grouping will be used in this format.

See Also
isGroupingUsed


 NumberFormat.setMaximumFractionDigits

NumberFormat.setMaximumFractionDigits

Class Overview | Class Members | This Package | All Packages

Syntax
public void setMaximumFractionDigits( int newValue )
Description
Sets the maximum number of digits allowed in the fraction portion of a number. maximumFractionDigits must be >= minimumFractionDigits. If the new value for maximumFractionDigits is less than the current value of minimumFractionDigits, then minimumFractionDigits will also be set to the new value.

See Also
getMaximumFractionDigits


 NumberFormat.setMaximumIntegerDigits

NumberFormat.setMaximumIntegerDigits

Class Overview | Class Members | This Package | All Packages

Syntax
public void setMaximumIntegerDigits( int newValue )
Description
Sets the maximum number of digits allowed in the integer portion of a number. maximumIntegerDigits must be >= minimumIntegerDigits. If the new value for maximumIntegerDigits is less than the current value of minimumIntegerDigits, then minimumIntegerDigits will also be set to the new value.

See Also
getMaximumIntegerDigits


 NumberFormat.setMinimumFractionDigits

NumberFormat.setMinimumFractionDigits

Class Overview | Class Members | This Package | All Packages

Syntax
public void setMinimumFractionDigits( int newValue )
Description
Sets the minimum number of digits allowed in the fraction portion of a number. minimumFractionDigits must be <= maximumFractionDigits. If the new value for minimumFractionDigits exceeds the current value of maximumFractionDigits, then maximumIntegerDigits will also be set to the new value

See Also
getMinimumFractionDigits


 NumberFormat.setMinimumIntegerDigits

NumberFormat.setMinimumIntegerDigits

Class Overview | Class Members | This Package | All Packages

Syntax
public void setMinimumIntegerDigits( int newValue )
Description
Sets the minimum number of digits allowed in the integer portion of a number. minimumIntegerDigits must be <= maximumIntegerDigits. If the new value for minimumIntegerDigits exceeds the current value of maximumIntegerDigits, then maximumIntegerDigits will also be set to the new value

See Also
getMinimumIntegerDigits


 NumberFormat.setParseIntegerOnly

NumberFormat.setParseIntegerOnly

Class Overview | Class Members | This Package | All Packages

Syntax
public void setParseIntegerOnly( boolean value )
Description
Sets whether or not numbers should be parsed as integers only.

See Also
isParseIntegerOnly


 Class ParseException

Class java.text.ParseException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.text.ParseException

public class ParseException
extends Exception

Signals that an error has been has been reached unexpectedly while parsing.

See Also:
Exception, Format, FieldPosition


 ParseException Members

ParseException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
ParseException(String, int) | Constructs a ParseException with the specified detail message and offset.

Methods
Name | Description
getErrorOffset() | Returns the position where the error was found.


 ParseException.ParseException

ParseException.ParseException

Class Overview | Class Members | This Package | All Packages

Syntax
public ParseException( String s, int errorOffset )
Parameters
s
the detail message
errorOffset
the position where the error is found while parsing.
Description
Constructs a ParseException with the specified detail message and offset. A detail message is a String that describes this particular exception.


 ParseException.getErrorOffset

ParseException.getErrorOffset

Class Overview | Class Members | This Package | All Packages

Syntax
public int getErrorOffset()
Description
Returns the position where the error was found.


 Class ParsePosition

Class java.text.ParsePosition

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.text.ParsePosition

public class ParsePosition
extends Object

ParsePosition is a simple class used by Format and its subclasses to keep track of the current position during parsing. The parseObject method in the various Format classes requires a ParsePosition object as an argument.

By design, as you parse through a string with different formats, you can use the same ParsePosition, since the index parameter records the current position.

See Also:
Format


 ParsePosition Members

ParsePosition Members

Class Overview | This Package | All Packages

Constructors
Name | Description
ParsePosition(int) | Create a new ParsePosition with the given initial index.

Methods
Name | Description
getIndex() | Retrieve the current parse position.
setIndex(int) | Set the current parse position.


 ParsePosition.ParsePosition

ParsePosition.ParsePosition

Class Overview | Class Members | This Package | All Packages

Syntax
public ParsePosition( int index )
Description
Create a new ParsePosition with the given initial index.


 ParsePosition.getIndex

ParsePosition.getIndex

Class Overview | Class Members | This Package | All Packages

Syntax
public int getIndex()
Description
Retrieve the current parse position. On input to a parse method, this is the index of the character at which parsing will begin; on output, it is the index of the character following the last character parsed.


 ParsePosition.setIndex

ParsePosition.setIndex

Class Overview | Class Members | This Package | All Packages

Syntax
public void setIndex( int index )
Description
Set the current parse position.


 Class RuleBasedCollator

Class java.text.RuleBasedCollator

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.text.Collator
           |
           +----java.text.RuleBasedCollator

public class RuleBasedCollator
extends Collator

The RuleBasedCollator class is a concrete subclass of Collator that provides a simple, data-driven, table collator. With this class you can create a customized table-based Collator. RuleBasedCollator maps characters to sort keys.

RuleBasedCollator has the following restrictions for efficiency (other subclasses may be used for more complex languages) :

  1. The French secondary ordering is applied to the whole collator object.
  2. All non-mentioned Unicode characters are at the end of the collation order.
  3. Private use characters are treated as identical. The private use area in Unicode is 0xE800-0xF8FF.

The collation table is composed of a list of collation rules, where each rule is of three forms:

    < modifier >
    < relation > < text-argument >
    < reset > < text-argument >
The following demonstrates how to create your own collation rules:
  • Text-Argument: A text-argument is any sequence of characters, excluding special characters (that is, whitespace characters and the characters used in modifier, relation and reset). If those characters are desired, you can put them in single quotes (e.g. ampersand => '&').
  • Modifier: There is a single modifier which is used to specify that all accents (secondary differences) are backwards.

    '@' : Indicates that accents are sorted backwards, as in French.

  • Relation: The relations are the following:
    • '<' : Greater, as a letter difference (primary)
    • ';' : Greater, as an accent difference (secondary)
    • ',' : Greater, as a case difference (tertiary)
    • '=' : Equal
  • Reset: There is a single reset which is used primarily for contractions and expansions, but which can also be used to add a modification at the end of a set of rules.

    '&' : Indicates that the next rule follows the position to where the reset text-argument would be sorted.

This sounds more complicated than it is in practice. For example, the following are equivalent ways of expressing the same thing:

 a < b < c
 a < b & b < c
 a < c & a < b
Notice that the order is important, as the subsequent item goes immediately after the text-argument. The following are not equivalent:
 a < b & a < c
 a < c & a < b
Either the text-argument must already be present in the sequence, or some initial substring of the text-argument must be present. (e.g. "a < b & ae < e" is valid since "a" is present in the sequence before "ae" is reset). In this latter case, "ae" is not entered and treated as a single character; instead, "e" is sorted as if it were expanded to two characters: "a" followed by an "e". This difference appears in natural languages: in traditional Spanish "ch" is treated as though it contracts to a single character (expressed as "c < ch < d"), while in traditional German "ä" (a-umlaut) is treated as though it expands to two characters (expressed as "a & ae ; ä < b").

Ignorable Characters

For ignorable characters, the first rule must start with a relation (the examples we have used above are really fragments; "a < b" really should be "< a < b"). If, however, the first relation is not "<", then all the text-arguments up to the first "<" are ignorable. For example, ", - < a < b" makes "-" an ignorable character, as we saw earlier in the word "black-birds". In the samples for different languages, you see that most accents are ignorable.

Normalization and Accents

The Collator object automatically normalizes text internally to separate accents from base characters where possible. This is done both when processing the rules, and when comparing two strings. Collator also uses the Unicode canonical mapping to ensure that combining sequences are sorted properly (for more information, see The Unicode Standard, Version 2.0.)

Errors

The following are errors:

  • A text-argument not preceded by either a reset or relation character (e.g. "a < b c < d").
  • A relation or reset character not followed by a text-argument (e.g. "a < , b").
  • A reset where the text-argument (or an initial substring of the text-argument) is not already in the sequence. (e.g. "a < b & e < f")
If you produce one of these errors, a RuleBasedCollator throws a ParseException.

Examples

Simple: "< a < b < c < d"

Norwegian: "< a,A< b,B< c,C< d,D< e,E< f,F< g,G< h,H< i,I< j,J < k,K< l,L< m,M< n,N< o,O< p,P< q,Q< r,R< s,S< t,T < u,U< v,V< w,W< x,X< y,Y< z,Z < å=a?,Å=A? ;aa,AA< æ,Æ< ø,Ø"

Normally, to create a rule-based Collator object, you will use Collator's factory method getInstance. However, to create a rule-based Collator object with specialized rules tailored to your needs, you construct the RuleBasedCollator with the rules contained in a String object. For example:

 String Simple = "< a < b < c < d";
 RuleBasedCollator mySimple = new RuleBasedCollator(Simple);
Or:
 String Norwegian = "< a,A< b,B< c,C< d,D< e,E< f,F< g,G< h,H< i,I< j,J" +
                 "< k,K< l,L< m,M< n,N< o,O< p,P< q,Q< r,R< s,S< t,T" +
                 "< u,U< v,V< w,W< x,X< y,Y< z,Z" +
                 "< å=a?,Å=A?" +
                 ";aa,AA< æ,Æ< ø,Ø";
 RuleBasedCollator myNorwegian = new RuleBasedCollator(Norwegian);

Combining Collators is as simple as concatenating strings. Here's an example that combines two Collators from two different locales:

 // Create an en_US Collator object
 RuleBasedCollator en_USCollator = (RuleBasedCollator)
     Collator.getInstance(new Locale("en", "US", ""));
 // Create a da_DK Collator object
 RuleBasedCollator da_DKCollator = (RuleBasedCollator)
     Collator.getInstance(new Locale("da", "DK", ""));
 // Combine the two
 // First, get the collation rules from en_USCollator
 String en_USRules = en_USCollator.getRules();
 // Second, get the collation rules from da_DKCollator
 String da_DKRules = da_DKCollator.getRules();
 RuleBasedCollator newCollator =
     new RuleBasedCollator(en_USRules + da_DKRules);
 // newCollator has the combined rules

Another more interesting example would be to make changes on an existing table to create a new Collator object. For example, add "& C < ch, cH, Ch, CH" to the en_USCollator object to create your own:

 // Create a new Collator object with additional rules
 String addRules = "& C < ch, cH, Ch, CH";
 RuleBasedCollator myCollator =
     new RuleBasedCollator(en_USCollator + addRules);
 // myCollator contains the new rules

The following example demonstrates how to change the order of non-spacing accents,

 // old rule
 String oldRules = "=?;?;?;?"    // main accents
                 + ";?;?;?;?"    // main accents
                 + ";?;?;?;?"    // main accents
                 + ";?;?;?;?"    // main accents
                 + ";?;?;?;?"    // main accents
                 + "< a , A ; ae, AE ; æ , Æ"
                 + "< b , B < c, C < e, E & C < d, D";
 // change the order of accent characters
 String addOn = "& ? ; ? ; ?";
 RuleBasedCollator myCollator = new RuleBasedCollator(oldRules + addOn);

The last example shows how to put new primary ordering in before the default setting. For example, in Japanese Collator, you can either sort English characters before or after Japanese characters,

 // get en_US Collator rules
 RuleBasedCollator en_USCollator = (RuleBasedCollator)Collator.getInstance(Locale.US);
 // add a few Japanese character to sort before English characters
 // suppose the last character before the first base letter 'a' in
 // the English collation rule is ?
 String jaString = "& ? < ?, ? < ?, ?";
 RuleBasedCollator myJapaneseCollator = new
     RuleBasedCollator(en_USCollator.getRules() + jaString);

See Also:
Collator, CollationElementIterator


 RuleBasedCollator Members

RuleBasedCollator Members

Class Overview | This Package | All Packages

Constructors
Name | Description
RuleBasedCollator(String) | RuleBasedCollator constructor.

Methods
Name | Description
clone() | Standard override; no change in semantics.
compare(String, String) | Compares the character data stored in two different strings based on the collation rules.
equals(Object) | Compares the equality of two collation objects.
getCollationElementIterator(String) | Return a CollationElementIterator for the given String.
getCollationKey(String) | Transforms the string into a series of characters that can be compared with CollationKey.compareTo.
getRules() | Gets the table-based rules for the collation object.
hashCode() | Generates the hash code for the table-based collation object


 RuleBasedCollator.RuleBasedCollator

RuleBasedCollator.RuleBasedCollator

Class Overview | Class Members | This Package | All Packages

Syntax
public RuleBasedCollator( String rules ) throws ParseException
Parameters
rules
the collation rules to build the collation table from.
Description
RuleBasedCollator constructor. This takes the table rules and builds a collation table out of them. Please see RuleBasedCollator class description for more details on the collation rule syntax.

Exceptions
ParseException A format exception will be thrown if the build process of the rules fails. For example, build rule "a < b c < d" will cause the constructor to throw the ParseException.
See Also
Locale


 RuleBasedCollator.clone

RuleBasedCollator.clone

Class Overview | Class Members | This Package | All Packages

Syntax
public Object clone()
Description
Standard override; no change in semantics.

Overrides
clone in class Collator


 RuleBasedCollator.compare

RuleBasedCollator.compare

Class Overview | Class Members | This Package | All Packages

Syntax
public int compare( String source, String target )
Description
Compares the character data stored in two different strings based on the collation rules. Returns information about whether a string is less than, greater than or equal to another string in a language. This can be overriden in a subclass.

Overrides
compare in class Collator


 RuleBasedCollator.equals

RuleBasedCollator.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Parameters
obj
the table-based collation object to be compared with this.
Returns
true if the current table-based collation object is the same as the table-based collation object obj; false otherwise.
Description
Compares the equality of two collation objects.

Overrides
equals in class Collator


 RuleBasedCollator.getCollationElementIterator

RuleBasedCollator.getCollationElementIterator

Class Overview | Class Members | This Package | All Packages

Syntax
public CollationElementIterator getCollationElementIterator( String source )
Description
Return a CollationElementIterator for the given String.

See Also
CollationElementIterator


 RuleBasedCollator.getCollationKey

RuleBasedCollator.getCollationKey

Class Overview | Class Members | This Package | All Packages

Syntax
public CollationKey getCollationKey( String source )
Description
Transforms the string into a series of characters that can be compared with CollationKey.compareTo. This overrides java.text.Collator.getCollationKey. It can be overriden in a subclass.

Overrides
getCollationKey in class Collator


 RuleBasedCollator.getRules

RuleBasedCollator.getRules

Class Overview | Class Members | This Package | All Packages

Syntax
public String getRules()
Returns
returns the collation rules that the table collation object was created from.
Description
Gets the table-based rules for the collation object.


 RuleBasedCollator.hashCode

RuleBasedCollator.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int hashCode()
Description
Generates the hash code for the table-based collation object

Overrides
hashCode in class Collator


 Class SimpleDateFormat

Class java.text.SimpleDateFormat

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.text.Format
           |
           +----java.text.DateFormat
                   |
                   +----java.text.SimpleDateFormat

public class SimpleDateFormat
extends DateFormat

SimpleDateFormat is a concrete class for formatting and parsing dates in a locale-sensitive manner. It allows for formatting (millis -> text), parsing (text -> millis), and normalization.

SimpleDateFormat allows you to start by choosing any user-defined patterns for date-time formatting. However, you are encouraged to create a date-time formatter with either getTimeInstance, getDateInstance, or getDateTimeInstance in DateFormat. Each of these class methods can return a date/time formatter initialized with a default format pattern. You may modify the format pattern using the applyPattern methods as desired. For more information on using these methods, see DateFormat.

Time Format Syntax:

To specify the time format use a time pattern string. In this pattern, all ASCII letters are reserved as pattern letters, which are defined as the following:

 Symbol   Meaning                 Presentation        Example
 ------   -------                 ------------        -------
 G        era designator          (Text)              AD
 y        year                    (Number)            1996
 M        month in year           (Text & Number)     July & 07
 d        day in month            (Number)            10
 h        hour in am/pm (1~12)    (Number)            12
 H        hour in day (0~23)      (Number)            0
 m        minute in hour          (Number)            30
 s        second in minute        (Number)            55
 S        millisecond             (Number)            978
 E        day in week             (Text)              Tuesday
 D        day in year             (Number)            189
 F        day of week in month    (Number)            2 (2nd Wed in July)
 w        week in year            (Number)            27
 W        week in month           (Number)            2
 a        am/pm marker            (Text)              PM
 k        hour in day (1~24)      (Number)            24
 K        hour in am/pm (0~11)    (Number)            0
 z        time zone               (Text)              Pacific Standard Time
 '        escape for text
 ''        single quote                              '
The count of pattern letters determine the format.

(Text): 4 or more pattern letters--use full form, < 4--use short or abbreviated form if one exists.

(Number): the minimum number of digits. Shorter numbers are zero-padded to this amount. Year is handled specially; that is, if the count of 'y' is 2, the Year will be truncated to 2 digits.

(Text & Number): 3 or over, use text, otherwise use number.

Any characters in the pattern that are not in the ranges of ['a'..'z'] and ['A'..'Z'] will be treated as quoted text. For instance, characters like ':', '.', ' ', '#' and '@' will appear in the resulting time text even they are not embraced within single quotes.

A pattern containing any invalid pattern letter will result in a thrown exception during formatting or parsing.

Examples Using the US Locale:

 Format Pattern                         Result
 --------------                         -------
 "yyyy.MM.dd G 'at' hh:mm:ss z"    ->>  1996.07.10 AD at 15:08:56 PDT
 "EEE, MMM d, ''yy"                ->>  Wed, July 10, '96
 "h:mm a"                          ->>  12:08 PM
 "hh 'o''''clock' a, zzzz"         ->>  12 o'clock PM, Pacific Daylight Time
 "K:mm a, z"                       ->>  0:00 PM, PST
 "yyyyy.MMMMM.dd GGG hh:mm aaa"    ->>  1996.July.10 AD 12:08 PM
Code Sample:

 SimpleTimeZone pdt = new SimpleTimeZone(-8 * 60 * 60 * 1000, "PST");
 pdt.setStartRule(DateFields.APRIL, 1, DateFields.SUNDAY, 2*60*60*1000);
 pdt.setEndRule(DateFields.OCTOBER, -1, DateFields.SUNDAY, 2*60*60*1000);
 // Format the current time.
 SimpleDateFormat formatter
     = new SimpleDateFormat ("yyyy.mm.dd e 'at' hh:mm:ss a zzz");
 Date currentTime_1 = new Date();
 String dateString = formatter.format(currentTime_1);
 // Parse the previous string back into a Date.
 ParsePosition pos = new ParsePosition(0);
 Date currentTime_2 = formatter.parse(dateString, pos);
In the example, the time value currentTime_2 obtained from parsing will be equal to currentTime_1. However, they may not be equal if the am/pm marker 'a' is left out from the format pattern while the "hour in am/pm" pattern symbol is used. This information loss can happen when formatting the time in PM.

For time zones that have no names, use strings GMT+hours:minutes or GMT-hours:minutes.

The calendar defines what is the first day of the week, the first week of the year, whether hours are zero based or not (0 vs 12 or 24), and the time zone. There is one common decimal format to handle all the numbers; the digit count is handled programmatically according to the pattern.

See Also:
Calendar, GregorianCalendar, TimeZone, DateFormat, DateFormatSymbols, DecimalFormat


 SimpleDateFormat Members

SimpleDateFormat Members

Class Overview | This Package | All Packages

Constructors
Name | Description
SimpleDateFormat() | Construct a SimpleDateFormat using the default pattern for the default locale.
SimpleDateFormat(String) | Construct a SimpleDateFormat using the given pattern in the default locale.
SimpleDateFormat(String, DateFormatSymbols) | Construct a SimpleDateFormat using the given pattern and locale-specific symbol data.
SimpleDateFormat(String, Locale) | Construct a SimpleDateFormat using the given pattern and locale.

Methods
Name | Description
applyLocalizedPattern(String) | Apply the given localized pattern string to this date format.
applyPattern(String) | Apply the given unlocalized pattern string to this date format.
clone() | Overrides Cloneable
equals(Object) | Override equals.
format(Date, StringBuffer, FieldPosition) | Overrides DateFormat Formats a date or time, which is the standard millis since 24:00 GMT, Jan 1, 1970.
getDateFormatSymbols() | Gets the date/time formatting data.
hashCode() | Override hashCode.
parse(String, ParsePosition) | Overrides DateFormat
setDateFormatSymbols(DateFormatSymbols) | Allows you to set the date/time formatting data.
toLocalizedPattern() | Return a localized pattern string describing this date format.
toPattern() | Return a pattern string describing this date format.


 SimpleDateFormat.SimpleDateFormat

SimpleDateFormat.SimpleDateFormat

Class Overview | Class Members | This Package | All Packages

Syntax 1
public SimpleDateFormat()
Description
Construct a SimpleDateFormat using the default pattern for the default locale. Note: Not all locales support SimpleDateFormat; for full generality, use the factory methods in the DateFormat class.

See Also
DateFormat

Syntax 2
public SimpleDateFormat( String pattern )
Description
Construct a SimpleDateFormat using the given pattern in the default locale. Note: Not all locales support SimpleDateFormat; for full generality, use the factory methods in the DateFormat class.

Syntax 3
public SimpleDateFormat( String pattern, Locale loc )
Description
Construct a SimpleDateFormat using the given pattern and locale. Note: Not all locales support SimpleDateFormat; for full generality, use the factory methods in the DateFormat class.

Syntax 4
public SimpleDateFormat( String pattern, DateFormatSymbols formatData )
Description
Construct a SimpleDateFormat using the given pattern and locale-specific symbol data.


 SimpleDateFormat.applyLocalizedPattern

SimpleDateFormat.applyLocalizedPattern

Class Overview | Class Members | This Package | All Packages

Syntax
public void applyLocalizedPattern( String pattern )
Description
Apply the given localized pattern string to this date format.


 SimpleDateFormat.applyPattern

SimpleDateFormat.applyPattern

Class Overview | Class Members | This Package | All Packages

Syntax
public void applyPattern( String pattern )
Description
Apply the given unlocalized pattern string to this date format.


 SimpleDateFormat.clone

SimpleDateFormat.clone

Class Overview | Class Members | This Package | All Packages

Syntax
public Object clone()
Description
Overrides Cloneable

Overrides
clone in class DateFormat


 SimpleDateFormat.equals

SimpleDateFormat.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Description
Override equals.

Overrides
equals in class DateFormat


 SimpleDateFormat.format

SimpleDateFormat.format

Class Overview | Class Members | This Package | All Packages

Syntax
public StringBuffer format( Date date, StringBuffer toAppendTo, FieldPosition pos )
Parameters
date
the date-time value to be formatted into a date-time string.
toAppendTo
where the new date-time text is to be appended.
pos
the formatting position. On input: an alignment field, if desired. On output: the offsets of the alignment field.
Returns
the formatted date-time string.
Description
Overrides DateFormat

Formats a date or time, which is the standard millis since 24:00 GMT, Jan 1, 1970.

Example: using the US locale: "yyyy.MM.dd e 'at' HH:mm:ss zzz" ->> 1996.07.10 AD at 15:08:56 PDT

Overrides
format in class DateFormat
See Also
DateFormat


 SimpleDateFormat.getDateFormatSymbols

SimpleDateFormat.getDateFormatSymbols

Class Overview | Class Members | This Package | All Packages

Syntax
public DateFormatSymbols getDateFormatSymbols()
Returns
a copy of the date-time formatting data associated with this date-time formatter.
Description
Gets the date/time formatting data.


 SimpleDateFormat.hashCode

SimpleDateFormat.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int hashCode()
Description
Override hashCode. Generates the hash code for the SimpleDateFormat object

Overrides
hashCode in class DateFormat


 SimpleDateFormat.parse

SimpleDateFormat.parse

Class Overview | Class Members | This Package | All Packages

Syntax
public Date parse( String text, ParsePosition pos )
Description
Overrides DateFormat

Overrides
parse in class DateFormat
See Also
DateFormat


 SimpleDateFormat.setDateFormatSymbols

SimpleDateFormat.setDateFormatSymbols

Class Overview | Class Members | This Package | All Packages

Syntax
public void setDateFormatSymbols( DateFormatSymbols newFormatSymbols )
Parameters
newFormatData
the given date-time formatting data.
Description
Allows you to set the date/time formatting data.


 SimpleDateFormat.toLocalizedPattern

SimpleDateFormat.toLocalizedPattern

Class Overview | Class Members | This Package | All Packages

Syntax
public String toLocalizedPattern()
Description
Return a localized pattern string describing this date format.


 SimpleDateFormat.toPattern

SimpleDateFormat.toPattern

Class Overview | Class Members | This Package | All Packages

Syntax
public String toPattern()
Description
Return a pattern string describing this date format.


 Class StringCharacterIterator

Class java.text.StringCharacterIterator

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.text.StringCharacterIterator

public final class StringCharacterIterator
extends Object
implements CharacterIterator

StringCharacterIterator implements the CharacterIterater protocol for a String. The StringCharacterIterator class iterates over the entire String.

Examples:

Traverse the text from start to finish

 public void traverseForward(CharacterIterator iter) {
     for (char c = iter.first(); c != CharacterIterator.DONE; c = iter.next()) {
         processChar(c);
     }
 }
Traverse the text backwards, from end to start
 public void traverseBackward(CharacterIterator iter) {
     for (char c = iter.last(); c != CharacterIterator.DONE; c = iter.prev()) {
         processChar(c);
     }
 }
Traverse both forward and backward from a given position in the text.
 public void traverseOut(CharacterIterator iter, int pos) {
     for (char c = iter.setIndex(pos);
          c != CharacterIterator.DONE && notBoundary(c);
          c = iter.next()) {}
     int end = iter.getIndex();
     for (char c = iter.setIndex(pos);
          c != CharacterIterator.DONE && notBoundary(c);
          c = iter.prev()) {}
     int start = iter.getIndex();
     processSection(iter.getText.subString(start,end);
 }


 StringCharacterIterator Members

StringCharacterIterator Members

Class Overview | This Package | All Packages

Constructors
Name | Description
StringCharacterIterator(String) | Construct an iterator with an initial index of 0.
StringCharacterIterator(String, int) | Construct an iterator with the specified initial index.
StringCharacterIterator(String, int, int, int) | Construct an iterator over the given range of the given string, with the index set at the specified position.

Methods
Name | Description
clone() | Create a copy of this boundary
current() | Get the character at the current position (as returned by getIndex()).
equals(Object) | Compares the equality of two StringCharacterIterator objects.
first() | Set the position to getBeginIndex() and return the character at that position.
getBeginIndex() | Return the start index of the text.
getEndIndex() | Return the end index of the text.
getIndex() | Return the current index.
hashCode() | Compute a hashcode for this enumeration
last() | Set the position to getEndIndex() and return the character at that position.
next() | Increment the iterator's index by one and return the character at the new index.
previous() | Decrement the iterator's index by one and return the character at the new index.
setIndex(int) | Set the position to specified position in the text and return that character.


 StringCharacterIterator.StringCharacterIterator

StringCharacterIterator.StringCharacterIterator

Class Overview | Class Members | This Package | All Packages

Syntax 1
public StringCharacterIterator( String text )
Description
Construct an iterator with an initial index of 0.

Syntax 2
public StringCharacterIterator( String text, int pos )
Parameters
text
The String to be iterated over
pos
Initial iterator position
Description
Construct an iterator with the specified initial index.

Syntax 3
public StringCharacterIterator( String text, int begin, int end, int pos )
Parameters
text
The String to be iterated over
begin
Index of the first character
end
Index of the character following the last character
pos
Initial iterator position
Description
Construct an iterator over the given range of the given string, with the index set at the specified position.


 StringCharacterIterator.clone

StringCharacterIterator.clone

Class Overview | Class Members | This Package | All Packages

Syntax
public Object clone()
Returns
A copy of this
Description
Create a copy of this boundary

Overrides
clone in class Object


 StringCharacterIterator.current

StringCharacterIterator.current

Class Overview | Class Members | This Package | All Packages

Syntax
public char current()
Returns
the character at the current position or DONE if the current position is off the end of the text.
Description
Get the character at the current position (as returned by getIndex()).


 StringCharacterIterator.equals

StringCharacterIterator.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Parameters
obj
the StringCharacterIterator object to be compared with.
Returns
true if the given obj is the same as this StringCharacterIterator object; false otherwise.
Description
Compares the equality of two StringCharacterIterator objects.

Overrides
equals in class Object


 StringCharacterIterator.first

StringCharacterIterator.first

Class Overview | Class Members | This Package | All Packages

Syntax
public char first()
Description
Set the position to getBeginIndex() and return the character at that position.


 StringCharacterIterator.getBeginIndex

StringCharacterIterator.getBeginIndex

Class Overview | Class Members | This Package | All Packages

Syntax
public int getBeginIndex()
Returns
the index at which the text begins.
Description
Return the start index of the text.


 StringCharacterIterator.getEndIndex

StringCharacterIterator.getEndIndex

Class Overview | Class Members | This Package | All Packages

Syntax
public int getEndIndex()
Returns
the index at which the text end.
Description
Return the end index of the text. This index is the index of the first character following the end of the text.


 StringCharacterIterator.getIndex

StringCharacterIterator.getIndex

Class Overview | Class Members | This Package | All Packages

Syntax
public int getIndex()
Returns
the current index.
Description
Return the current index.


 StringCharacterIterator.hashCode

StringCharacterIterator.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int hashCode()
Returns
A hash code
Description
Compute a hashcode for this enumeration

Overrides
hashCode in class Object


 StringCharacterIterator.last

StringCharacterIterator.last

Class Overview | Class Members | This Package | All Packages

Syntax
public char last()
Description
Set the position to getEndIndex() and return the character at that position.


 StringCharacterIterator.next

StringCharacterIterator.next

Class Overview | Class Members | This Package | All Packages

Syntax
public char next()
Returns
the character at the new position or DONE if the current position is off the end of the text.
Description
Increment the iterator's index by one and return the character at the new index. If the resulting index is greater or equal to getEndIndex(), the current index is reset to getEndIndex() and a value of DONE is returned.


 StringCharacterIterator.previous

StringCharacterIterator.previous

Class Overview | Class Members | This Package | All Packages

Syntax
public char previous()
Returns
the character at the new position or DONE if the current position is off the end of the text.
Description
Decrement the iterator's index by one and return the character at the new index. If the resulting index is less than getBeginIndex(), the current index is reset to getBeginIndex() and a value of DONE is returned.


 StringCharacterIterator.setIndex

StringCharacterIterator.setIndex

Class Overview | Class Members | This Package | All Packages

Syntax
public char setIndex( int p )
Description
Set the position to specified position in the text and return that character.


 Package java.util

Package java.util

All Packages

Interfaces

  • Enumeration
  • EventListener
  • Observer

    • Classes

  • BitSet
  • Calendar
  • Date
  • Dictionary
  • EventObject
  • GregorianCalendar
  • Hashtable
  • ListResourceBundle
  • Locale
  • Observable
  • Properties
  • PropertyResourceBundle
  • Random
  • ResourceBundle
  • SimpleTimeZone
  • Stack
  • StringTokenizer
  • TimeZone
  • Vector

    • Exceptions

  • EmptyStackException
  • MissingResourceException
  • NoSuchElementException
  • TooManyListenersException


 Class BitSet

Class java.util.BitSet

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.BitSet

public final class BitSet
extends Object
implements Cloneable, Serializable

A set of bits. The set automatically grows as more bits are needed.


 BitSet Members

BitSet Members

Class Overview | This Package | All Packages

Constructors
Name | Description
BitSet() | Creates an empty set.
BitSet(int) | Creates an empty set with the specified size.

Methods
Name | Description
and(BitSet) | Logically ANDs this bit set with the specified set of bits.
clear(int) | Clears a bit.
clone() | Clones the BitSet.
equals(Object) | Compares this object against the specified object.
get(int) | Gets a bit.
hashCode() | Gets the hashcode.
or(BitSet) | Logically ORs this bit set with the specified set of bits.
set(int) | Sets a bit.
size() | Calculates and returns the set's size in bits.
toString() | Converts the BitSet to a String.
xor(BitSet) | Logically XORs this bit set with the specified set of bits.


 BitSet.BitSet

BitSet.BitSet

Class Overview | Class Members | This Package | All Packages

Syntax 1
public BitSet()
Description
Creates an empty set.

Syntax 2
public BitSet( int nbits )
Parameters
nbits
the size of the set
Description
Creates an empty set with the specified size.


 BitSet.and

BitSet.and

Class Overview | Class Members | This Package | All Packages

Syntax
public void and( BitSet set )
Parameters
set
the bit set to be ANDed with
Description
Logically ANDs this bit set with the specified set of bits.


 BitSet.clear

BitSet.clear

Class Overview | Class Members | This Package | All Packages

Syntax
public void clear( int bit )
Parameters
bit
the bit to be cleared
Description
Clears a bit.


 BitSet.clone

BitSet.clone

Class Overview | Class Members | This Package | All Packages

Syntax
public Object clone()
Description
Clones the BitSet.

Overrides
clone in class Object


 BitSet.equals

BitSet.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Parameters
obj
the object to compare with
Returns
true if the objects are the same; false otherwise.
Description
Compares this object against the specified object.

Overrides
equals in class Object


 BitSet.get

BitSet.get

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean get( int bit )
Parameters
bit
the bit to be gotten
Description
Gets a bit.


 BitSet.hashCode

BitSet.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int hashCode()
Description
Gets the hashcode.

Overrides
hashCode in class Object


 BitSet.or

BitSet.or

Class Overview | Class Members | This Package | All Packages

Syntax
public void or( BitSet set )
Parameters
set
the bit set to be ORed with
Description
Logically ORs this bit set with the specified set of bits.


 BitSet.set

BitSet.set

Class Overview | Class Members | This Package | All Packages

Syntax
public void set( int bit )
Parameters
bit
the bit to be set
Description
Sets a bit.


 BitSet.size

BitSet.size

Class Overview | Class Members | This Package | All Packages

Syntax
public int size()
Description
Calculates and returns the set's size in bits. The maximum element in the set is the size - 1st element.


 BitSet.toString

BitSet.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Description
Converts the BitSet to a String.

Overrides
toString in class Object


 BitSet.xor

BitSet.xor

Class Overview | Class Members | This Package | All Packages

Syntax
public void xor( BitSet set )
Parameters
set
the bit set to be XORed with
Description
Logically XORs this bit set with the specified set of bits.


 Class Calendar

Class java.util.Calendar

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.Calendar

public abstract class Calendar
extends Object
implements Serializable, Cloneable

Calendar is an abstract base class for converting between a Date object and a set of integer fields such as YEAR, MONTH, DAY, HOUR, and so on. (A Date object represents a specific instant in time with millisecond precision. See java.util.Date for information about the Date class.)

Subclasses of Calendar interpret a Date according to the rules of a specific calendar system. The JDK provides one concrete subclass of Calendar: GregorianCalendar. Future subclasses could represent the various types of lunar calendars in use in many parts of the world.

Like other locale-sensitive classes, Calendar provides a class method, getInstance, for getting a generally useful object of this type. Calendar's getInstance method returns a GregorianCalendar object whose time fields have been initialized with the current date and time:

 Calendar rightNow = Calendar.getInstance();

A Calendar object can produce all the time field values needed to implement the date-time formatting for a particular language and calendar style (for example, Japanese-Gregorian, Japanese-Traditional).

When computing a Date from time fields, two special circumstances may arise: there may be insufficient information to compute the Date (such as only year and month but no day in the month), or there may be inconsistent information (such as "Tuesday, July 15, 1996" -- July 15, 1996 is actually a Monday).

Insufficient information. The calendar will use default information to specify the missing fields. This may vary by calendar; for the Gregorian calendar, the default for a field is the same as that of the start of the epoch: i.e., YEAR = 1970, MONTH = JANUARY, DATE = 1, etc.

Inconsistent information. The calendar will give preference to the combinations of fields in the following order (and disregard other inconsistent information).

 month + day-of-month
 month + week-of-month + day-of-week
 month + day-of-week-of-month + day-of-week
 day-of-year
 day-of-week + week-of-year
 hour-of-day
 ampm + hour-of-ampm

Note: for some non-Gregorian calendars, different fields may be necessary for complete disambiguation. For example, a full specification of the historial Arabic astronomical calendar requires year, month, day-of-month and day-of-week in some cases.

Note: There are certain possible ambiguities in interpretation of certain singular times, which are resolved in the following ways:

  1. 24:00:00 "belongs" to the following day. That is, 23:59 on Dec 31, 1969 < 24:00 on Jan 1, 1970 < 24:01:00 on Jan 1, 1970
  2. Although historically not precise, midnight also belongs to "am", and noon belongs to "pm", so on the same day, 12:00 am (midnight) < 12:01 am, and 12:00 pm (noon) < 12:01 pm

The date or time format strings are not part of the definition of a calendar, as those must be modifiable or overridable by the user at runtime. Use java.text.DateFormat to format dates.

Calendar provides an API for field "rolling", where fields can be incremented or decremented, but wrap around. For example, rolling the month up in the date "September 12, 1996" results in "October 12, 1996".

Calendar also provides a date arithmetic function for adding the specified (signed) amount of time to a particular time field. For example, subtracting 5 days from the date "September 12, 1996" results in "September 7, 1996".

See Also:
Date, GregorianCalendar, TimeZone, DateFormat


 Calendar Members

Calendar Members

Class Overview | This Package | All Packages

Fields
Name | Description
AM | Useful constant for hour in 12-hour clock.
AM_PM | Useful constant for date and time.
APRIL | Useful constant for month.
areFieldsSet | The flag which tells if the time fields are set for the calendar.
AUGUST | Useful constant for month.
DATE | Useful constant for date and time.
DAY_OF_MONTH | Useful constant for date and time.
DAY_OF_WEEK | Useful constant for date and time.
DAY_OF_WEEK_IN_MONTH | Useful constant for date and time.
DAY_OF_YEAR | Useful constant for date and time.
DECEMBER | Useful constant for month.
DST_OFFSET | Useful constant for date and time.
ERA | Useful constant for date and time.
FEBRUARY | Useful constant for month.
FIELD_COUNT | Useful constant for date and time.
fields | The time fields containing values into which the millis is computed.
FRIDAY | Useful constant for days of week.
HOUR | Useful constant for date and time.
HOUR_OF_DAY | Useful constant for date and time.
isSet | The flags which tell if a specified time field for the calendar is set.
isTimeSet | The flag which indicates if the current time is set for the calendar.
JANUARY | Useful constant for month.
JULY | Useful constant for month.
JUNE | Useful constant for month.
MARCH | Useful constant for month.
MAY | Useful constant for month.
MILLISECOND | Useful constant for date and time.
MINUTE | Useful constant for date and time.
MONDAY | Useful constant for days of week.
MONTH | Useful constant for date and time.
NOVEMBER | Useful constant for month.
OCTOBER | Useful constant for month.
PM | Useful constant for hour in 12-hour clock.
SATURDAY | Useful constant for days of week.
SECOND | Useful constant for date and time.
SEPTEMBER | Useful constant for month.
SUNDAY | Useful constant for days of week.
THURSDAY | Useful constant for days of week.
time | The current time set for the calendar.
TUESDAY | Useful constant for days of week.
UNDECIMBER | Useful constant for month.
WEDNESDAY | Useful constant for days of week.
WEEK_OF_MONTH | Useful constant for date and time.
WEEK_OF_YEAR | Useful constant for date and time.
YEAR | Useful constant for date and time.
ZONE_OFFSET | Useful constant for date and time.

Constructors
Name | Description
Calendar() | Constructs a Calendar with the default time zone as returned by TimeZone.getDefault(), and the default locale.
Calendar(TimeZone, Locale) | Constructs a Calendar with the given time zone and locale.

Methods
Name | Description
add(int, int) | Date Arithmetic function.
after(Object) | Compares the time field records.
before(Object) | Compares the time field records.
clear() | Clears the values of all the time fields.
clear(int) | Clears the value in the given time field.
clone() | Overrides Cloneable
complete() | Fills in any unset fields in the time field list.
computeFields() | Converts UTC as milliseconds to time field values.
computeTime() | Converts Calendar's time field values to UTC as milliseconds.
equals(Object) | Compares the time field records.
get(int) | Gets the value for a given time field.
getAvailableLocales() | Gets the set of locales for which Calendars are installed.
getFirstDayOfWeek() | Gets what the first day of the week is; e.g., Sunday in US, Monday in France.
getGreatestMinimum(int) | Gets the highest minimum value for the given field if varies.
getInstance() | Gets a Calendar using the default timezone and locale.
getInstance(Locale) | Gets a Calendar using the default timezone and given locale.
getInstance(TimeZone) | Gets a Calendar using the given timezone and default locale.
getInstance(TimeZone, Locale) | Gets a Calendar using the given timezone and given locale.
getLeastMaximum(int) | Gets the lowest maximum value for the given field if varies.
getMaximum(int) | Gets the maximum value for the given time field.
getMinimalDaysInFirstWeek() | Gets what the minimal days required in the first week of the year are; e.g., if the first week is defined as one that contains the first day of the first month of a year, getMinimalDaysInFirstWeek returns 1.
getMinimum(int) | Gets the minimum value for the given time field.
getTime() | Gets this Calendar's current time.
getTimeInMillis() | Gets this Calendar's current time as a long.
getTimeZone() | Gets the time zone.
internalGet(int) | Gets the value for a given time field.
isLenient() | Tell whether date/time interpretation is to be lenient.
isSet(int) | Determines if the given time field has a value set.
roll(int, boolean) | Time Field Rolling function.
set(int, int) | Sets the time field with the given value.
set(int, int, int) | Sets the values for the fields year, month, and date.
set(int, int, int, int, int) | Sets the values for the fields year, month, date, hour, and minute.
set(int, int, int, int, int, int) | Sets the values for the fields year, month, date, hour, minute, and second.
setFirstDayOfWeek(int) | Sets what the first day of the week is; e.g., Sunday in US, Monday in France.
setLenient(boolean) | Specify whether or not date/time interpretation is to be lenient.
setMinimalDaysInFirstWeek(int) | Sets what the minimal days required in the first week of the year are; For example, if the first week is defined as one that contains the first day of the first month of a year, call the method with value 1.
setTime(Date) | Sets this Calendar's current time with the given Date.
setTimeInMillis(long) | Sets this Calendar's current time from the given long value.
setTimeZone(TimeZone) | Sets the time zone with the given time zone value.


 Calendar.AM

Calendar.AM

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int AM
Description
Useful constant for hour in 12-hour clock. Used in GregorianCalendar.


 Calendar.AM_PM

Calendar.AM_PM

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int AM_PM
Description
Useful constant for date and time. Used in time fields.


 Calendar.APRIL

Calendar.APRIL

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int APRIL
Description
Useful constant for month. Used in GregorianCalendar.


 Calendar.areFieldsSet

Calendar.areFieldsSet

Class Overview | Class Members | This Package | All Packages

Syntax
protected boolean areFieldsSet
Description
The flag which tells if the time fields are set for the calendar.


 Calendar.AUGUST

Calendar.AUGUST

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int AUGUST
Description
Useful constant for month. Used in GregorianCalendar.


 Calendar.DATE

Calendar.DATE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int DATE
Description
Useful constant for date and time. Used in time fields. DATE is the time field name for day-of-month.


 Calendar.DAY_OF_MONTH

Calendar.DAY_OF_MONTH

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int DAY_OF_MONTH
Description
Useful constant for date and time. Used in time fields. This is a synonym for DATE.


 Calendar.DAY_OF_WEEK

Calendar.DAY_OF_WEEK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int DAY_OF_WEEK
Description
Useful constant for date and time. Used in time fields.


 Calendar.DAY_OF_WEEK_IN_MONTH

Calendar.DAY_OF_WEEK_IN_MONTH

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int DAY_OF_WEEK_IN_MONTH
Description
Useful constant for date and time. Used in time fields.


 Calendar.DAY_OF_YEAR

Calendar.DAY_OF_YEAR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int DAY_OF_YEAR
Description
Useful constant for date and time. Used in time fields.


 Calendar.DECEMBER

Calendar.DECEMBER

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int DECEMBER
Description
Useful constant for month. Used in GregorianCalendar.


 Calendar.DST_OFFSET

Calendar.DST_OFFSET

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int DST_OFFSET
Description
Useful constant for date and time. Used in time fields.


 Calendar.ERA

Calendar.ERA

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int ERA
Description
Useful constant for date and time. Used in time fields. ERA is calendar specific.


 Calendar.FEBRUARY

Calendar.FEBRUARY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int FEBRUARY
Description
Useful constant for month. Used in GregorianCalendar.


 Calendar.FIELD_COUNT

Calendar.FIELD_COUNT

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int FIELD_COUNT
Description
Useful constant for date and time. FIELD_COUNT is used for the time field array creation.


 Calendar.fields

Calendar.fields

Class Overview | Class Members | This Package | All Packages

Syntax
protected int fields[]
Description
The time fields containing values into which the millis is computed.


 Calendar.FRIDAY

Calendar.FRIDAY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int FRIDAY
Description
Useful constant for days of week. Used in GregorianCalendar.


 Calendar.HOUR

Calendar.HOUR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HOUR
Description
Useful constant for date and time. Used in time fields. HOUR is used for the 12-hour clock.


 Calendar.HOUR_OF_DAY

Calendar.HOUR_OF_DAY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HOUR_OF_DAY
Description
Useful constant for date and time. Used in time fields. HOUR_OF_DAY is used for the 24-hour clock.


 Calendar.isSet

Calendar.isSet

Class Overview | Class Members | This Package | All Packages

Syntax
protected boolean isSet[]
Description
The flags which tell if a specified time field for the calendar is set.


 Calendar.isTimeSet

Calendar.isTimeSet

Class Overview | Class Members | This Package | All Packages

Syntax
protected boolean isTimeSet
Description
The flag which indicates if the current time is set for the calendar.


 Calendar.JANUARY

Calendar.JANUARY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int JANUARY
Description
Useful constant for month. Used in GregorianCalendar. Note: Calendar month is now 0-based.


 Calendar.JULY

Calendar.JULY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int JULY
Description
Useful constant for month. Used in GregorianCalendar.


 Calendar.JUNE

Calendar.JUNE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int JUNE
Description
Useful constant for month. Used in GregorianCalendar.


 Calendar.MARCH

Calendar.MARCH

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int MARCH
Description
Useful constant for month. Used in GregorianCalendar.


 Calendar.MAY

Calendar.MAY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int MAY
Description
Useful constant for month. Used in GregorianCalendar.


 Calendar.MILLISECOND

Calendar.MILLISECOND

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int MILLISECOND
Description
Useful constant for date and time. Used in time fields.


 Calendar.MINUTE

Calendar.MINUTE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int MINUTE
Description
Useful constant for date and time. Used in time fields.


 Calendar.MONDAY

Calendar.MONDAY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int MONDAY
Description
Useful constant for days of week. Used in GregorianCalendar.


 Calendar.MONTH

Calendar.MONTH

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int MONTH
Description
Useful constant for date and time. Used in time fields.


 Calendar.NOVEMBER

Calendar.NOVEMBER

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int NOVEMBER
Description
Useful constant for month. Used in GregorianCalendar.


 Calendar.OCTOBER

Calendar.OCTOBER

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int OCTOBER
Description
Useful constant for month. Used in GregorianCalendar.


 Calendar.PM

Calendar.PM

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int PM
Description
Useful constant for hour in 12-hour clock. Used in GregorianCalendar.


 Calendar.SATURDAY

Calendar.SATURDAY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SATURDAY
Description
Useful constant for days of week. Used in GregorianCalendar.


 Calendar.SECOND

Calendar.SECOND

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SECOND
Description
Useful constant for date and time. Used in time fields.


 Calendar.SEPTEMBER

Calendar.SEPTEMBER

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SEPTEMBER
Description
Useful constant for month. Used in GregorianCalendar.


 Calendar.SUNDAY

Calendar.SUNDAY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int SUNDAY
Description
Useful constant for days of week. Used in GregorianCalendar.


 Calendar.THURSDAY

Calendar.THURSDAY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int THURSDAY
Description
Useful constant for days of week. Used in GregorianCalendar.


 Calendar.time

Calendar.time

Class Overview | Class Members | This Package | All Packages

Syntax
protected long time
Description
The current time set for the calendar.


 Calendar.TUESDAY

Calendar.TUESDAY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int TUESDAY
Description
Useful constant for days of week. Used in GregorianCalendar.


 Calendar.UNDECIMBER

Calendar.UNDECIMBER

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int UNDECIMBER
Description
Useful constant for month. Used in GregorianCalendar. UNDECIMBER is an artifical name. This 13th month is for lunar calendars.


 Calendar.WEDNESDAY

Calendar.WEDNESDAY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int WEDNESDAY
Description
Useful constant for days of week. Used in GregorianCalendar.


 Calendar.WEEK_OF_MONTH

Calendar.WEEK_OF_MONTH

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int WEEK_OF_MONTH
Description
Useful constant for date and time. Used in time fields.


 Calendar.WEEK_OF_YEAR

Calendar.WEEK_OF_YEAR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int WEEK_OF_YEAR
Description
Useful constant for date and time. Used in time fields.


 Calendar.YEAR

Calendar.YEAR

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int YEAR
Description
Useful constant for date and time. Used in time fields.


 Calendar.ZONE_OFFSET

Calendar.ZONE_OFFSET

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int ZONE_OFFSET
Description
Useful constant for date and time. Used in time fields.


 Calendar.Calendar

Calendar.Calendar

Class Overview | Class Members | This Package | All Packages

Syntax 1
protected Calendar()
Description
Constructs a Calendar with the default time zone as returned by TimeZone.getDefault(), and the default locale.

See Also
getDefault

Syntax 2
protected Calendar( TimeZone zone, Locale aLocale )
Parameters
zone
the given time zone.
Description
Constructs a Calendar with the given time zone and locale.


 Calendar.add

Calendar.add

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void add( int field, int amount )
Parameters
field
the time field.
amount
the amount of date or time to be added to the field.
Description
Date Arithmetic function. Adds the specified (signed) amount of time to the given time field, based on the calendar's rules. For example, to subtract 5 days from the current time of the calendar, you can achieve it by calling:

add(Calendar.DATE, -5).


 Calendar.after

Calendar.after

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract boolean after( Object when )
Parameters
when
the Calendar to be compared with this Calendar.
Returns
true if the current time of this Calendar is after the time of Calendar when; false otherwise.
Description
Compares the time field records. Equivalent to comparing result of conversion to UTC.


 Calendar.before

Calendar.before

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract boolean before( Object when )
Parameters
when
the Calendar to be compared with this Calendar.
Returns
true if the current time of this Calendar is before the time of Calendar when; false otherwise.
Description
Compares the time field records. Equivalent to comparing result of conversion to UTC.


 Calendar.clear

Calendar.clear

Class Overview | Class Members | This Package | All Packages

Syntax 1
public final void clear()
Description
Clears the values of all the time fields.

Syntax 2
public final void clear( int field )
Parameters
field
the time field to be cleared.
Description
Clears the value in the given time field.


 Calendar.clone

Calendar.clone

Class Overview | Class Members | This Package | All Packages

Syntax
public Object clone()
Description
Overrides Cloneable

Overrides
clone in class Object


 Calendar.complete

Calendar.complete

Class Overview | Class Members | This Package | All Packages

Syntax
protected void complete()
Description
Fills in any unset fields in the time field list.


 Calendar.computeFields

Calendar.computeFields

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract void computeFields()
Description
Converts UTC as milliseconds to time field values. This allows you to sync up the time field values with a new time that is set for the calendar.


 Calendar.computeTime

Calendar.computeTime

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract void computeTime()
Description
Converts Calendar's time field values to UTC as milliseconds.


 Calendar.equals

Calendar.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract boolean equals( Object when )
Parameters
when
the Calendar to be compared with this Calendar.
Returns
true if the current time of this Calendar is equal to the time of Calendar when; false otherwise.
Description
Compares the time field records. Equivalent to comparing result of conversion to UTC.

Overrides
equals in class Object


 Calendar.get

Calendar.get

Class Overview | Class Members | This Package | All Packages

Syntax
public final int get( int field )
Parameters
field
the given time field.
Returns
the value for the given time field.
Description
Gets the value for a given time field.


 Calendar.getAvailableLocales

Calendar.getAvailableLocales

Class Overview | Class Members | This Package | All Packages

Syntax
public static synchronized Locale[] getAvailableLocales()
Returns
the set of locales for which Calendars are installed.
Description
Gets the set of locales for which Calendars are installed.


 Calendar.getFirstDayOfWeek

Calendar.getFirstDayOfWeek

Class Overview | Class Members | This Package | All Packages

Syntax
public int getFirstDayOfWeek()
Returns
the first day of the week.
Description
Gets what the first day of the week is; e.g., Sunday in US, Monday in France.


 Calendar.getGreatestMinimum

Calendar.getGreatestMinimum

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract int getGreatestMinimum( int field )
Parameters
field
the given time field.
Returns
the highest minimum value for the given time field.
Description
Gets the highest minimum value for the given field if varies. Otherwise same as getMinimum(). For Gregorian, no difference.


 Calendar.getInstance

Calendar.getInstance

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static synchronized Calendar getInstance()
Returns
a Calendar.
Description
Gets a Calendar using the default timezone and locale.

Syntax 2
public static synchronized Calendar getInstance( TimeZone zone )
Parameters
zone
the given timezone.
Returns
a Calendar.
Description
Gets a Calendar using the given timezone and default locale.

Syntax 3
public static synchronized Calendar getInstance( Locale aLocale )
Parameters
aLocale
the given locale.
Returns
a Calendar.
Description
Gets a Calendar using the default timezone and given locale.

Syntax 4
public static synchronized Calendar getInstance( TimeZone zone, Locale aLocale )
Parameters
zone
the given timezone.
aLocale
the given locale.
Returns
a Calendar.
Description
Gets a Calendar using the given timezone and given locale.


 Calendar.getLeastMaximum

Calendar.getLeastMaximum

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract int getLeastMaximum( int field )
Parameters
field
the given time field.
Returns
the lowest maximum value for the given time field.
Description
Gets the lowest maximum value for the given field if varies. Otherwise same as getMaximum(). e.g., for Gregorian DAY_OF_MONTH, 28.


 Calendar.getMaximum

Calendar.getMaximum

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract int getMaximum( int field )
Parameters
field
the given time field.
Returns
the maximum value for the given time field.
Description
Gets the maximum value for the given time field. e.g. for Gregorian DAY_OF_MONTH, 31.


 Calendar.getMinimalDaysInFirstWeek

Calendar.getMinimalDaysInFirstWeek

Class Overview | Class Members | This Package | All Packages

Syntax
public int getMinimalDaysInFirstWeek()
Returns
the minimal days required in the first week of the year.
Description
Gets what the minimal days required in the first week of the year are; e.g., if the first week is defined as one that contains the first day of the first month of a year, getMinimalDaysInFirstWeek returns 1. If the minimal days required must be a full week, getMinimalDaysInFirstWeek returns 7.


 Calendar.getMinimum

Calendar.getMinimum

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract int getMinimum( int field )
Parameters
field
the given time field.
Returns
the minimum value for the given time field.
Description
Gets the minimum value for the given time field. e.g., for Gregorian DAY_OF_MONTH, 1.


 Calendar.getTime

Calendar.getTime

Class Overview | Class Members | This Package | All Packages

Syntax
public final Date getTime()
Returns
the current time.
Description
Gets this Calendar's current time.


 Calendar.getTimeInMillis

Calendar.getTimeInMillis

Class Overview | Class Members | This Package | All Packages

Syntax
protected long getTimeInMillis()
Returns
the current time as milliseconds from the epoch.
Description
Gets this Calendar's current time as a long.


 Calendar.getTimeZone

Calendar.getTimeZone

Class Overview | Class Members | This Package | All Packages

Syntax
public TimeZone getTimeZone()
Returns
the time zone object associated with this calendar.
Description
Gets the time zone.


 Calendar.internalGet

Calendar.internalGet

Class Overview | Class Members | This Package | All Packages

Syntax
protected final int internalGet( int field )
Parameters
field
the given time field.
Returns
the value for the given time field.
Description
Gets the value for a given time field. This is an internal fast time field value getter for the subclasses.


 Calendar.isLenient

Calendar.isLenient

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isLenient()
Description
Tell whether date/time interpretation is to be lenient.


 Calendar.isSet

Calendar.isSet

Class Overview | Class Members | This Package | All Packages

Syntax
public final boolean isSet( int field )
Returns
true if the given time field has a value set; false otherwise.
Description
Determines if the given time field has a value set.


 Calendar.roll

Calendar.roll

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void roll( int field, boolean up )
Parameters
field
the time field.
up
indicates if the value of the specified time field is to be rolled up or rolled down. Use true if rolling up, false otherwise.
Description
Time Field Rolling function. Rolls (up/down) a single unit of time on the given time field. For example, to roll the current date up by one day, you can achieve it by calling:

roll(Calendar.DATE, true). When rolling on the year or Calendar.YEAR field, it will roll the year value in the range between 1 and the value returned by calling getMaximum(Calendar.YEAR). When rolling on the month or Calendar.MONTH field, other fields like date might conflict and, need to be changed. For instance, rolling the month on the date 01/31/96 will result in 03/02/96. When rolling on the hour-in-day or Calendar.HOUR_OF_DAY field, it will roll the hour value in the range between 0 and 23, which is zero-based.


 Calendar.set

Calendar.set

Class Overview | Class Members | This Package | All Packages

Syntax 1
public final void set( int field, int value )
Parameters
field
the given time field.
value
the value to be set for the given time field.
Description
Sets the time field with the given value.

Syntax 2
public final void set( int year, int month, int date )
Parameters
year
the value used to set the YEAR time field.
month
the value used to set the MONTH time field. Month value is 0-based. e.g., 0 for January.
date
the value used to set the DATE time field.
Description
Sets the values for the fields year, month, and date.

Syntax 3
public final void set( int year, int month, int date, int hour, int minute )
Parameters
year
the value used to set the YEAR time field.
month
the value used to set the MONTH time field. Month value is 0-based. e.g., 0 for January.
date
the value used to set the DATE time field.
hour
the value used to set the HOUR_OF_DAY time field.
minute
the value used to set the MINUTE time field.
Description
Sets the values for the fields year, month, date, hour, and minute.

Syntax 4
public final void set( int year, int month, int date, int hour, int minute, int second )
Parameters
year
the value used to set the YEAR time field.
month
the value used to set the MONTH time field. Month value is 0-based. e.g., 0 for January.
date
the value used to set the DATE time field.
hour
the value used to set the HOUR_OF_DAY time field.
minute
the value used to set the MINUTE time field.
second
the value used to set the SECOND time field.
Description
Sets the values for the fields year, month, date, hour, minute, and second.


 Calendar.setFirstDayOfWeek

Calendar.setFirstDayOfWeek

Class Overview | Class Members | This Package | All Packages

Syntax
public void setFirstDayOfWeek( int value )
Parameters
value
the given first day of the week.
Description
Sets what the first day of the week is; e.g., Sunday in US, Monday in France.


 Calendar.setLenient

Calendar.setLenient

Class Overview | Class Members | This Package | All Packages

Syntax
public void setLenient( boolean lenient )
Description
Specify whether or not date/time interpretation is to be lenient. With lenient interpretation, a date such as "February 942, 1996" will be treated as being equivalent to the 941st day after February 1, 1996. With strict interpretation, such dates will cause an exception to be thrown.

See Also
setLenient


 Calendar.setMinimalDaysInFirstWeek

Calendar.setMinimalDaysInFirstWeek

Class Overview | Class Members | This Package | All Packages

Syntax
public void setMinimalDaysInFirstWeek( int value )
Parameters
value
the given minimal days required in the first week of the year.
Description
Sets what the minimal days required in the first week of the year are; For example, if the first week is defined as one that contains the first day of the first month of a year, call the method with value 1. If it must be a full week, use value 7.


 Calendar.setTime

Calendar.setTime

Class Overview | Class Members | This Package | All Packages

Syntax
public final void setTime( Date date )
Parameters
date
the given Date.
Description
Sets this Calendar's current time with the given Date.


 Calendar.setTimeInMillis

Calendar.setTimeInMillis

Class Overview | Class Members | This Package | All Packages

Syntax
protected void setTimeInMillis( long millis )
Parameters
date
the new time in milliseconds from the epoch.
Description
Sets this Calendar's current time from the given long value.


 Calendar.setTimeZone

Calendar.setTimeZone

Class Overview | Class Members | This Package | All Packages

Syntax
public void setTimeZone( TimeZone value )
Parameters
value
the given time zone.
Description
Sets the time zone with the given time zone value.


 Class Date

Class java.util.Date

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.Date

public class Date
extends Object
implements Serializable, Cloneable

The class Date represents a specific instant in time, with millisecond precision.

Prior to JDK 1.1, the class Date had two additional functions. It allowed the interpretation of dates as year, month, day, hour, minute, and second values. It also allowed the formatting and parsing of date strings. Unfortunately, the API for these functions was not amenable to internationalization. As of JDK 1.1, the Calendar class should be used to convert between dates and time fields and the DateFormat class should be used to format and parse date strings. The corresponding methods in Date are deprecated.

Although the Date class is intended to reflect coordinated universal time (UTC), it may not do so exactly, depending on the host environment of the Java Virtual Machine. Nearly all modern operating systems assume that 1 day = 24 × 60 × 60 = 86400 seconds in all cases. In UTC, however, about once every year or two there is an extra second, called a "leap second." The leap second is always added as the last second of the day, and always on December 31 or June 30. For example, the last minute of the year 1995 was 61 seconds long, thanks to an added leap second. Most computer clocks are not accurate enough to be able to reflect the leap-second distinction.

Some computer standards are defined in terms of Greenwich mean time (GMT), which is equivalent to universal time (UT). GMT is the "civil" name for the standard; UT is the "scientific" name for the same standard. The distinction between UTC and UT is that UTC is based on an atomic clock and UT is based on astronomical observations, which for all practical purposes is an invisibly fine hair to split. Because the earth's rotation is not uniform (it slows down and speeds up in complicated ways), UT does not always flow uniformly. Leap seconds are introduced as needed into UTC so as to keep UTC within 0.9 seconds of UT1, which is a version of UT with certain corrections applied. There are other time and date systems as well; for example, the time scale used by the satellite-based global positioning system (GPS) is synchronized to UTC but is not adjusted for leap seconds. An interesting source of further information is the U.S. Naval Observatory, particularly the Directorate of Time at:

    http://tycho.usno.navy.mil

and their definitions of "Systems of Time" at:

    http://tycho.usno.navy.mil/systime.html

In all methods of class Date that accept or return year, month, date, hours, minutes, and seconds values, the following representations are used:

  • A year y is represented by the integer y - 1900.
  • A month is represented by an integer form 0 to 11; 0 is January, 1 is February, and so forth; thus 11 is December.
  • A date (day of month) is represented by an integer from 1 to 31 in the usual manner.
  • An hour is represented by an integer from 0 to 23. Thus, the hour from midnight to 1 a.m. is hour 0, and the hour from noon to 1 p.m. is hour 12.
  • A minute is represented by an integer from 0 to 59 in the usual manner.
  • A second is represented by an integer from 0 to 60; the value 60 occurs only for leap seconds and even then only in Java implementations that actually track leap seconds correctly.

In all cases, arguments given to methods for these purposes need not fall within the indicated ranges; for example, a date may be specified as January 32 and is interpreted as meaning February 1.

See Also:
DateFormat, Calendar, TimeZone


 Date Members

Date Members

Class Overview | This Package | All Packages

Constructors
Name | Description
Date() | Allocates a Date object and initializes it so that it represents the time at which it was allocated measured to the nearest millisecond.
Date(int, int, int) | Allocates a Date object and initializes it so that it represents midnight, local time, at the beginning of the day specified by the year, month, and date arguments. Deprecated.
Date(int, int, int, int, int) | Allocates a Date object and initializes it so that it represents the specified hour and minute, local time, of the date specified by the year, month, date, hrs, and min arguments. Deprecated.
Date(int, int, int, int, int, int) | Allocates a Date object and initializes it so that it represents the specified hour, minute, and second, local time of the date specified by the year, month, date, hrs, min, and sec arguments. Deprecated.
Date(long) | Allocates a Date object and initializes it to represent the specified number of milliseconds since January 1, 1970, 00:00:00 GMT.
Date(String) | Allocates a Date object and initializes it so that it represents the date and time indicated by the string s, which is interpreted as if by the parse method. Deprecated.

Methods
Name | Description
after(Date) | Tests if this date is after the specified date.
before(Date) | Tests if this date is before the specified date.
equals(Object) | Compares two dates.
getDate() | Returns the day of the month represented by this date. Deprecated.
getDay() | Returns the day of the week represented by this date. Deprecated.
getHours() | Returns the hour represented by this date. Deprecated.
getMinutes() | Returns the number of minutes past the hour represented by this date. Deprecated.
getMonth() | Returns the month represented by this date. Deprecated.
getSeconds() | Returns the number of seconds past the minute represented by this date. Deprecated.
getTime() | Returns the number of milliseconds since January 1, 1970, 00:00:00 GMT represented by this date.
getTimezoneOffset() | Returns the local time-zone offset. Deprecated.
getYear() | Returns the year represented by this date, minus 1900. Deprecated.
hashCode() | Returns a hash code value for this object.
parse(String) | Given a string representing a time, parse it and return the time value. Deprecated.
setDate(int) | Sets the day of the month of this date to the specified value. Deprecated.
setHours(int) | Sets the hour of this date to the specified value. Deprecated.
setMinutes(int) | Sets the minutes of this date to the specified value. Deprecated.
setMonth(int) | Sets the month of this date to the specified value. Deprecated.
setSeconds(int) | Sets the seconds of this date to the specified value. Deprecated.
setTime(long) | Sets this date to represent the specified number of milliseconds since January 1, 1970 00:00:00 GMT.
setYear(int) | Sets the year of this date to be the specified value plus 1900. Deprecated.
toGMTString() | Creates a string representation of this date. Deprecated.
toLocaleString() | Creates a string representation of this date in an implementation-dependent form. Deprecated.
toString() | Creates a canonical string representation of the date.
UTC(int, int, int, int, int, int) | Determines the date and time based on the arguments. Deprecated.


 Date.Date

Date.Date

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Date()
Description
Allocates a Date object and initializes it so that it represents the time at which it was allocated measured to the nearest millisecond.

See Also
currentTimeMillis

Syntax 2
public Date( long date )
Parameters
date
the milliseconds since January 1, 1970, 00:00:00 GMT.
Description
Allocates a Date object and initializes it to represent the specified number of milliseconds since January 1, 1970, 00:00:00 GMT.

See Also
currentTimeMillis

Syntax 3
public Date( int year, int month, int date )
Parameters
year
the year minus 1900.
month
the month between 0-11.
date
the day of the month between 1-31.
Description
Note: Date() is deprecated.

Allocates a Date object and initializes it so that it represents midnight, local time, at the beginning of the day specified by the year, month, and date arguments.

See Also
Calendar

Syntax 4
public Date( int year, int month, int date, int hrs, int min )
Parameters
year
the year minus 1900.
month
the month between 0-11.
date
the day of the month between 1-31.
hrs
the hours between 0-23.
min
the minutes between 0-59.
Description
Note: Date() is deprecated.

Allocates a Date object and initializes it so that it represents the specified hour and minute, local time, of the date specified by the year, month, date, hrs, and min arguments.

See Also
Calendar

Syntax 5
public Date( int year, int month, int date, int hrs, int min, int sec )
Parameters
year
the year minus 1900.
month
the month between 0-11.
date
the day of the month between 1-31.
hrs
the hours between 0-23.
min
the minutes between 0-59.
sec
the seconds between 0-59.
Description
Note: Date() is deprecated.

Allocates a Date object and initializes it so that it represents the specified hour, minute, and second, local time of the date specified by the year, month, date, hrs, min, and sec arguments.

See Also
Calendar

Syntax 6
public Date( String s )
Parameters
s
a string representation of the date.
Description
Note: Date() is deprecated.

Allocates a Date object and initializes it so that it represents the date and time indicated by the string s, which is interpreted as if by the parse method.

See Also
DateFormat, parse


 Date.after

Date.after

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean after( Date when )
Parameters
when
a date.
Returns
true if this date is after the argument date; false otherwise.
Description
Tests if this date is after the specified date.


 Date.before

Date.before

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean before( Date when )
Parameters
when
a date.
Returns
true if this date is before the argument date; false otherwise.
Description
Tests if this date is before the specified date.


 Date.equals

Date.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Parameters
obj
the object to compare with.
Returns
true if the objects are the same; false otherwise.
Description
Compares two dates. The result is true if and only if the argument is not null and is a Date object that represents the same point in time, to the millisecond, as this object.

Thus, two Date objects are equal if and only if the getTime method returns the same long value for both.

Overrides
equals in class Object
See Also
getTime


 Date.getDate

Date.getDate

Class Overview | Class Members | This Package | All Packages

Syntax
public int getDate()
Returns
the day of the month represented by this date.
Description
Note: getDate() is deprecated.

Returns the day of the month represented by this date. The value returned is between 1 and 31.

See Also
Calendar


 Date.getDay

Date.getDay

Class Overview | Class Members | This Package | All Packages

Syntax
public int getDay()
Returns
the day of the week represented by this date.
Description
Note: getDay() is deprecated.

Returns the day of the week represented by this date. The value returned is between 0 and 6, where 0 represents Sunday.

See Also
Calendar


 Date.getHours

Date.getHours

Class Overview | Class Members | This Package | All Packages

Syntax
public int getHours()
Returns
the hour represented by this date.
Description
Note: getHours() is deprecated.

Returns the hour represented by this date. The value returned is between 0 and 23, where 0 represents midnight.

See Also
Calendar


 Date.getMinutes

Date.getMinutes

Class Overview | Class Members | This Package | All Packages

Syntax
public int getMinutes()
Returns
the number of minutes past the hour represented by this date.
Description
Note: getMinutes() is deprecated.

Returns the number of minutes past the hour represented by this date. The value returned is between 0 and 59.

See Also
Calendar


 Date.getMonth

Date.getMonth

Class Overview | Class Members | This Package | All Packages

Syntax
public int getMonth()
Returns
the month represented by this date.
Description
Note: getMonth() is deprecated.

Returns the month represented by this date. The value returned is between 0 and 11, with the value 0 representing January.

See Also
Calendar


 Date.getSeconds

Date.getSeconds

Class Overview | Class Members | This Package | All Packages

Syntax
public int getSeconds()
Returns
the number of seconds past the minute represented by this date.
Description
Note: getSeconds() is deprecated.

Returns the number of seconds past the minute represented by this date. The value returned is between 0 and 60. The value 60 can only occur on those Java Virtual Machines that take leap seconds into account.

See Also
Calendar


 Date.getTime

Date.getTime

Class Overview | Class Members | This Package | All Packages

Syntax
public long getTime()
Returns
the number of milliseconds since January 1, 1970, 00:00:00 GMT represented by this date.
Description
Returns the number of milliseconds since January 1, 1970, 00:00:00 GMT represented by this date.


 Date.getTimezoneOffset

Date.getTimezoneOffset

Class Overview | Class Members | This Package | All Packages

Syntax
public int getTimezoneOffset()
Returns
the time-zone offset, in minutes, for the current locale.
Description
Note: getTimezoneOffset() is deprecated.

Returns the local time-zone offset. The time-zone offset is the number of minutes that must be added to GMT to give the local time zone. This value includes the correction, if necessary, for daylight saving time.

See Also
Calendar, TimeZone


 Date.getYear

Date.getYear

Class Overview | Class Members | This Package | All Packages

Syntax
public int getYear()
Returns
the year represented by this date, minus 1900.
Description
Note: getYear() is deprecated.

Returns the year represented by this date, minus 1900.

See Also
Calendar


 Date.hashCode

Date.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public int hashCode()
Returns
a hash code value for this object.
Description
Returns a hash code value for this object.

Overrides
hashCode in class Object


 Date.parse

Date.parse

Class Overview | Class Members | This Package | All Packages

Syntax
public static long parse( String s )
Parameters
s
a string to be parsed as a date.
Returns
the number of milliseconds since January 1, 1970, 00:00:00 GMT represented by the string argument.
Description
Note: parse() is deprecated.

Given a string representing a time, parse it and return the time value. This method recognizes most standard syntaxes.

It accepts many syntaxes; in particular, it recognizes the IETF standard date syntax: "Sat, 12 Aug 1995 13:30:00 GMT". It also understands the continental U.S. time-zone abbreviations, but for general use, a time-zone offset should be used: "Sat, 12 Aug 1995 13:30:00 GMT+0430" (4 hours, 30 minutes west of the Greenwich meridian). If no time zone is specified, the local time zone is assumed. GMT and UTC are considered equivalent.

See Also
DateFormat


 Date.setDate

Date.setDate

Class Overview | Class Members | This Package | All Packages

Syntax
public void setDate( int date )
Parameters
date
the day of the month value between 1-31.
Description
Note: setDate() is deprecated.

Sets the day of the month of this date to the specified value.

See Also
Calendar


 Date.setHours

Date.setHours

Class Overview | Class Members | This Package | All Packages

Syntax
public void setHours( int hours )
Parameters
hours
the hour value.
Description
Note: setHours() is deprecated.

Sets the hour of this date to the specified value.

See Also
Calendar


 Date.setMinutes

Date.setMinutes

Class Overview | Class Members | This Package | All Packages

Syntax
public void setMinutes( int minutes )
Parameters
minutes
the value of the minutes.
Description
Note: setMinutes() is deprecated.

Sets the minutes of this date to the specified value.

See Also
Calendar


 Date.setMonth

Date.setMonth

Class Overview | Class Members | This Package | All Packages

Syntax
public void setMonth( int month )
Parameters
month
the month value between 0-11.
Description
Note: setMonth() is deprecated.

Sets the month of this date to the specified value.

See Also
Calendar


 Date.setSeconds

Date.setSeconds

Class Overview | Class Members | This Package | All Packages

Syntax
public void setSeconds( int seconds )
Parameters
seconds
the seconds value.
Description
Note: setSeconds() is deprecated.

Sets the seconds of this date to the specified value.

See Also
Calendar


 Date.setTime

Date.setTime

Class Overview | Class Members | This Package | All Packages

Syntax
public void setTime( long time )
Parameters
time
the number of milliseconds.
Description
Sets this date to represent the specified number of milliseconds since January 1, 1970 00:00:00 GMT.


 Date.setYear

Date.setYear

Class Overview | Class Members | This Package | All Packages

Syntax
public void setYear( int year )
Parameters
year
the year value.
Description
Note: setYear() is deprecated.

Sets the year of this date to be the specified value plus 1900.

See Also
Calendar


 Date.toGMTString

Date.toGMTString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toGMTString()
Returns
a string representation of this date, using the Internet GMT conventions.
Description
Note: toGMTString() is deprecated.

Creates a string representation of this date. The result is of the form:

    "12 Aug 1995 02:30:00 GMT"

in which the day of the month is always one or two digits. The other fields have exactly the width shown. The time zone is always given as "GMT".

See Also
DateFormat


 Date.toLocaleString

Date.toLocaleString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toLocaleString()
Returns
a string representation of this date, using the locale conventions.
Description
Note: toLocaleString() is deprecated.

Creates a string representation of this date in an implementation-dependent form. The intent is that the form should be familiar to the user of the Java application, wherever it may happen to be running. The intent is comparable to that of the "%c" format supported by the strftime() function of ISO C.

See Also
DateFormat


 Date.toString

Date.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Returns
a string representation of this date.
Description
Creates a canonical string representation of the date. The result is of the form "Sat Aug 12 02:30:00 PDT 1995".

Overrides
toString in class Object


 Date.UTC

Date.UTC

Class Overview | Class Members | This Package | All Packages

Syntax
public static long UTC( int year, int month, int date, int hrs, int min, int sec )
Parameters
year
the year minus 1900.
month
the month between 0-11.
date
the day of the month between 1-31.
hrs
the hours between 0-23.
min
the minutes between 0-59.
sec
the seconds between 0-59.
Returns
the number of seconds since January 1, 1970, 00:00:00 GMT for the date and time specified by the arguments.
Description
Note: UTC() is deprecated.

Determines the date and time based on the arguments. The arguments are interpreted in UTC, not in the local time zone

See Also
Calendar


 Class Dictionary

Class java.util.Dictionary

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.Dictionary

public abstract class Dictionary
extends Object

The Dictionary class is the abstract parent of any class, such as Hashtable, which maps keys to values. Any non-null object can be used as a key and as a value.

As a rule, the equals method should be used by implementations of this class to decide if two keys are the same.

See Also:
equals, hashCode, Hashtable


 Dictionary Members

Dictionary Members

Class Overview | This Package | All Packages

Constructors
Name | Description
Dictionary() |

Methods
Name | Description
elements() | Returns an enumeration of the values in this dictionary.
get(Object) | Returns the value to which the key is mapped in this dictionary.
isEmpty() | Tests if this dictionary maps no keys to value.
keys() | Returns an enumeration of the keys in this dictionary.
put(Object, Object) | Maps the specified key to the specified value in this dictionary.
remove(Object) | Removes the key (and its corresponding value) from this dictionary.
size() | Returns the number of keys in this dictionary.


 Dictionary.Dictionary

Dictionary.Dictionary

Class Overview | Class Members | This Package | All Packages

Syntax
public Dictionary()


 Dictionary.elements

Dictionary.elements

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract Enumeration elements()
Returns
an enumeration of the values in this dictionary.
Description
Returns an enumeration of the values in this dictionary. the Enumeration methods on the returned object to fetch the elements sequentially.

See Also
keys, Enumeration


 Dictionary.get

Dictionary.get

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract Object get( Object key )
Parameters
key
a key in this dictionary. null if the key is not mapped to any value in this dictionary.
Returns
the value to which the key is mapped in this dictionary;
Description
Returns the value to which the key is mapped in this dictionary.

See Also
put


 Dictionary.isEmpty

Dictionary.isEmpty

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract boolean isEmpty()
Returns
true if this dictionary maps no keys to values; false otherwise.
Description
Tests if this dictionary maps no keys to value.


 Dictionary.keys

Dictionary.keys

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract Enumeration keys()
Returns
an enumeration of the keys in this dictionary.
Description
Returns an enumeration of the keys in this dictionary.

See Also
elements, Enumeration


 Dictionary.put

Dictionary.put

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract Object put( Object key, Object value )
Parameters
key
the hashtable key.
value
the value.
Returns
the previous value to which the key was mapped in this dictionary, or null if the key did not have a previous mapping.
Description
Maps the specified key to the specified value in this dictionary. Neither the key nor the value can be null.

The value can be retrieved by calling the get method with a key that is equal to the original key.

Exceptions
NullPointerException if the key or value is null.
See Also
equals, get


 Dictionary.remove

Dictionary.remove

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract Object remove( Object key )
Parameters
key
the key that needs to be removed.
Returns
the value to which the key had been mapped in this dictionary, or null if the key did not have a mapping.
Description
Removes the key (and its corresponding value) from this dictionary. This method does nothing if the key is not in this dictionary.


 Dictionary.size

Dictionary.size

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract int size()
Returns
the number of keys in this dictionary.
Description
Returns the number of keys in this dictionary.


 Class EmptyStackException

Class java.util.EmptyStackException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.lang.RuntimeException
                           |
                           +----java.util.EmptyStackException

public class EmptyStackException
extends RuntimeException

Thrown by methods in the Stack class to indicate that the stack is empty.

See Also:
Stack


 EmptyStackException Members

EmptyStackException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
EmptyStackException() | Constructs a new EmptyStackException with no detail message.


 EmptyStackException.EmptyStackException

EmptyStackException.EmptyStackException

Class Overview | Class Members | This Package | All Packages

Syntax
public EmptyStackException()
Description
Constructs a new EmptyStackException with no detail message.


 Interface Enumeration

Interface java.util.Enumeration

Interface Members | This Package | All Packages

public interface Enumeration

An object that implements the Enumeration interface generates a series of elements, one at a time. Successive calls to the nextElement method return successive elements of the series.

For example, to print all elements of a vector v:

     for (Enumeration e = v.elements() ; e.hasMoreElements() ;) {
         System.out.println(e.nextElement());

     }

Methods are provided to enumerate through the elements of a vector, the keys of a hashtable, and the values in a hashtable. Enumerations are also used to specify the input streams to a SequenceInputStream.

See Also:
SequenceInputStream, nextElement, Hashtable, elements, keys, Vector, elements


 Enumeration Members

Enumeration Members

Interface Overview | This Package | All Packages

Methods
Name | Description
hasMoreElements() | Tests if this enumeration contains more elements.
nextElement() | Returns the next element of this enumeration.


 Enumeration.hasMoreElements

Enumeration.hasMoreElements

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract boolean hasMoreElements()
Returns
true if this enumeration contains more elements; false otherwise.
Description
Tests if this enumeration contains more elements.


 Enumeration.nextElement

Enumeration.nextElement

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract Object nextElement()
Returns
the next element of this enumeration.
Description
Returns the next element of this enumeration.

Exceptions
NoSuchElementException if no more elements exist.


 Interface EventListener

Interface java.util.EventListener

This Package | All Packages

public interface EventListener

A tagging interface that all event listener interfaces must extend


 Class EventObject

Class java.util.EventObject

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.EventObject

public class EventObject
extends Object
implements Serializable


 EventObject Members

EventObject Members

Class Overview | This Package | All Packages

Fields
Name | Description
source |

Constructors
Name | Description
EventObject(Object) |

Methods
Name | Description
getSource() |
toString() | Returns a string representation of the object.


 EventObject.source

EventObject.source

Class Overview | Class Members | This Package | All Packages

Syntax
protected transient Object source


 EventObject.EventObject

EventObject.EventObject

Class Overview | Class Members | This Package | All Packages

Syntax
public EventObject( Object source )


 EventObject.getSource

EventObject.getSource

Class Overview | Class Members | This Package | All Packages

Syntax
public Object getSource()


 EventObject.toString

EventObject.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Description
Returns a string representation of the object.

Overrides
toString in class Object


 Class GregorianCalendar

Class java.util.GregorianCalendar

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.Calendar
           |
           +----java.util.GregorianCalendar

public class GregorianCalendar
extends Calendar

GregorianCalendar is a concrete subclass of Calendar and provides the standard calendar used by most of the world.

The standard (Gregorian) calendar has 2 eras, BC and AD.

This implementation handles a single discontinuity, which corresponds by default to the date the Gregorian calendar was instituted (October 15, 1582 in some countries, later in others). This cutover date may be changed by the caller.

Prior to the institution of the Gregorian calendar, New Year's Day was March 25. To avoid confusion, this calendar always uses January 1. A manual adjustment may be made if desired for dates that are prior to the Gregorian changeover and which fall between January 1 and March 24.

Example:

     // get the supported ids for GMT-08:00 (Pacific Standard Time)
 String[] ids = TimeZone.getAvailableIDs(-8 * 60 * 60 * 1000);
     // if no ids were returned, something is wrong. get out.
 if (ids.length == 0)
     System.exit(0);
     // begin output
 System.out.println("Current Time");
     // create a Pacific Standard Time time zone
 SimpleTimeZone pdt = new SimpleTimeZone(-8 * 60 * 60 * 1000, ids[0]);
     // set up rules for daylight savings time
 pdt.setStartRule(Calendar.APRIL, 1, Calendar.SUNDAY, 2 * 60 * 60 * 1000);
 pdt.setEndRule(Calendar.OCTOBER, -1, Calendar.SUNDAY, 2 * 60 * 60 * 1000);
     // create a GregorianCalendar with the Pacific Daylight time zone
    // and the current date and time
 Calendar calendar = new GregorianCalendar(pdt);
 Date trialTime = new Date();
 calendar.setTime(trialTime);
    // print out a bunch of interesting things
 System.out.println("ERA: " + calendar.get(Calendar.ERA));
 System.out.println("YEAR: " + calendar.get(Calendar.YEAR));
 System.out.println("MONTH: " + calendar.get(Calendar.MONTH));
 System.out.println("WEEK_OF_YEAR: " + calendar.get(Calendar.WEEK_OF_YEAR));
 System.out.println("WEEK_OF_MONTH: " + calendar.get(Calendar.WEEK_OF_MONTH));
 System.out.println("DATE: " + calendar.get(Calendar.DATE));
 System.out.println("DAY_OF_MONTH: " + calendar.get(Calendar.DAY_OF_MONTH));
 System.out.println("DAY_OF_YEAR: " + calendar.get(Calendar.DAY_OF_YEAR));
 System.out.println("DAY_OF_WEEK: " + calendar.get(Calendar.DAY_OF_WEEK));
 System.out.println("DAY_OF_WEEK_IN_MONTH: "
                    + calendar.get(Calendar.DAY_OF_WEEK_IN_MONTH));
 System.out.println("AM_PM: " + calendar.get(Calendar.AM_PM));
 System.out.println("HOUR: " + calendar.get(Calendar.HOUR));
 System.out.println("HOUR_OF_DAY: " + calendar.get(Calendar.HOUR_OF_DAY));
 System.out.println("MINUTE: " + calendar.get(Calendar.MINUTE));
 System.out.println("SECOND: " + calendar.get(Calendar.SECOND));
 System.out.println("MILLISECOND: " + calendar.get(Calendar.MILLISECOND));
 System.out.println("ZONE_OFFSET: "
                    + (calendar.get(Calendar.ZONE_OFFSET)/(60*60*1000)));
 System.out.println("DST_OFFSET: "
                    + (calendar.get(Calendar.DST_OFFSET)/(60*60*1000)));
 System.out.println("Current Time, with hour reset to 3");
 calendar.clear(Calendar.HOUR_OF_DAY); // so doesn't override
 calendar.set(Calendar.HOUR, 3);
 System.out.println("ERA: " + calendar.get(Calendar.ERA));
 System.out.println("YEAR: " + calendar.get(Calendar.YEAR));
 System.out.println("MONTH: " + calendar.get(Calendar.MONTH));
 System.out.println("WEEK_OF_YEAR: " + calendar.get(Calendar.WEEK_OF_YEAR));
 System.out.println("WEEK_OF_MONTH: " + calendar.get(Calendar.WEEK_OF_MONTH));
 System.out.println("DATE: " + calendar.get(Calendar.DATE));
 System.out.println("DAY_OF_MONTH: " + calendar.get(Calendar.DAY_OF_MONTH));
 System.out.println("DAY_OF_YEAR: " + calendar.get(Calendar.DAY_OF_YEAR));
 System.out.println("DAY_OF_WEEK: " + calendar.get(Calendar.DAY_OF_WEEK));
 System.out.println("DAY_OF_WEEK_IN_MONTH: "
                    + calendar.get(Calendar.DAY_OF_WEEK_IN_MONTH));
 System.out.println("AM_PM: " + calendar.get(Calendar.AM_PM));
 System.out.println("HOUR: " + calendar.get(Calendar.HOUR));
 System.out.println("HOUR_OF_DAY: " + calendar.get(Calendar.HOUR_OF_DAY));
 System.out.println("MINUTE: " + calendar.get(Calendar.MINUTE));
 System.out.println("SECOND: " + calendar.get(Calendar.SECOND));
 System.out.println("MILLISECOND: " + calendar.get(Calendar.MILLISECOND));
 System.out.println("ZONE_OFFSET: "
        + (calendar.get(Calendar.ZONE_OFFSET)/(60*60*1000))); // in hours
 System.out.println("DST_OFFSET: "
        + (calendar.get(Calendar.DST_OFFSET)/(60*60*1000))); // in hours

See Also:
Calendar, TimeZone


 GregorianCalendar Members

GregorianCalendar Members

Class Overview | This Package | All Packages

Fields
Name | Description
AD | Useful constant for GregorianCalendar.
BC | Useful constant for GregorianCalendar.

Constructors
Name | Description
GregorianCalendar() | Constructs a default GregorianCalendar using the current time in the default time zone with the default locale.
GregorianCalendar(int, int, int) | Constructs a GregorianCalendar with the given date set in the default time zone with the default locale.
GregorianCalendar(int, int, int, int, int) | Constructs a GregorianCalendar with the given date and time set for the default time zone with the default locale.
GregorianCalendar(int, int, int, int, int, int) | Constructs a GregorianCalendar with the given date and time set for the default time zone with the default locale.
GregorianCalendar(Locale) | Constructs a GregorianCalendar based on the current time in the default time zone with the given locale.
GregorianCalendar(TimeZone) | Constructs a GregorianCalendar based on the current time in the given time zone with the default locale.
GregorianCalendar(TimeZone, Locale) | Constructs a GregorianCalendar based on the current time in the given time zone with the given locale.

Methods
Name | Description
add(int, int) | Overrides Calendar Date Arithmetic function.
after(Object) | Overrides Calendar Compares the time field records.
before(Object) | Overrides Calendar Compares the time field records.
clone() | Overrides Cloneable
computeFields() | Overrides Calendar Converts UTC as milliseconds to time field values.
computeTime() | Overrides Calendar Converts time field values to UTC as milliseconds.
equals(Object) | Overrides Calendar Compares the time field records.
getGreatestMinimum(int) | Returns highest minimum value for the given field if varies.
getGregorianChange() | Gets the Gregorian Calendar change date.
getLeastMaximum(int) | Returns lowest maximum value for the given field if varies.
getMaximum(int) | Returns maximum value for the given field.
getMinimum(int) | Returns minimum value for the given field.
hashCode() | Override hashCode.
isLeapYear(int) | Determines if the given year is a leap year.
roll(int, boolean) | Overrides Calendar Time Field Rolling function.
setGregorianChange(Date) | Sets the GregorianCalendar change date.


 GregorianCalendar.AD

GregorianCalendar.AD

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int AD
Description
Useful constant for GregorianCalendar.


 GregorianCalendar.BC

GregorianCalendar.BC

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int BC
Description
Useful constant for GregorianCalendar.


 GregorianCalendar.GregorianCalendar

GregorianCalendar.GregorianCalendar

Class Overview | Class Members | This Package | All Packages

Syntax 1
public GregorianCalendar()
Description
Constructs a default GregorianCalendar using the current time in the default time zone with the default locale.

Syntax 2
public GregorianCalendar( TimeZone zone )
Parameters
zone
the given time zone.
Description
Constructs a GregorianCalendar based on the current time in the given time zone with the default locale.

Syntax 3
public GregorianCalendar( Locale aLocale )
Parameters
aLocale
the given locale.
Description
Constructs a GregorianCalendar based on the current time in the default time zone with the given locale.

Syntax 4
public GregorianCalendar( TimeZone zone, Locale aLocale )
Parameters
zone
the given time zone.
aLocale
the given locale.
Description
Constructs a GregorianCalendar based on the current time in the given time zone with the given locale.

Syntax 5
public GregorianCalendar( int year, int month, int date )
Parameters
year
the value used to set the YEAR time field in the calendar.
month
the value used to set the MONTH time field in the calendar. Month value is 0-based. e.g., 0 for January.
date
the value used to set the DATE time field in the calendar.
Description
Constructs a GregorianCalendar with the given date set in the default time zone with the default locale.

Syntax 6
public GregorianCalendar( int year, int month, int date, int hour, int minute )
Parameters
year
the value used to set the YEAR time field in the calendar.
month
the value used to set the MONTH time field in the calendar. Month value is 0-based. e.g., 0 for January.
date
the value used to set the DATE time field in the calendar.
hour
the value used to set the HOUR_OF_DAY time field in the calendar.
minute
the value used to set the MINUTE time field in the calendar.
Description
Constructs a GregorianCalendar with the given date and time set for the default time zone with the default locale.

Syntax 7
public GregorianCalendar( int year, int month, int date, int hour, int minute, int second )
Parameters
year
the value used to set the YEAR time field in the calendar.
month
the value used to set the MONTH time field in the calendar. Month value is 0-based. e.g., 0 for January.
date
the value used to set the DATE time field in the calendar.
hour
the value used to set the HOUR_OF_DAY time field in the calendar.
minute
the value used to set the MINUTE time field in the calendar.
second
the value used to set the SECOND time field in the calendar.
Description
Constructs a GregorianCalendar with the given date and time set for the default time zone with the default locale.


 GregorianCalendar.add

GregorianCalendar.add

Class Overview | Class Members | This Package | All Packages

Syntax
public void add( int field, int amount )
Parameters
field
the time field.
amount
the amount of date or time to be added to the field.
Description
Overrides Calendar Date Arithmetic function. Adds the specified (signed) amount of time to the given time field, based on the calendar's rules.

Exceptions
IllegalArgumentException if an unknown field is given.
Overrides
add in class Calendar


 GregorianCalendar.after

GregorianCalendar.after

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean after( Object when )
Description
Overrides Calendar Compares the time field records. Equivalent to comparing result of conversion to UTC. Please see Calendar.after for descriptions on parameters and the return value.

Overrides
after in class Calendar


 GregorianCalendar.before

GregorianCalendar.before

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean before( Object when )
Description
Overrides Calendar Compares the time field records. Equivalent to comparing result of conversion to UTC. Please see Calendar.before for descriptions on parameters and the return value.

Overrides
before in class Calendar


 GregorianCalendar.clone

GregorianCalendar.clone

Class Overview | Class Members | This Package | All Packages

Syntax
public Object clone()
Description
Overrides Cloneable

Overrides
clone in class Calendar


 GregorianCalendar.computeFields

GregorianCalendar.computeFields

Class Overview | Class Members | This Package | All Packages

Syntax
protected void computeFields()
Description
Overrides Calendar Converts UTC as milliseconds to time field values.

Overrides
computeFields in class Calendar


 GregorianCalendar.computeTime

GregorianCalendar.computeTime

Class Overview | Class Members | This Package | All Packages

Syntax
protected void computeTime()
Description
Overrides Calendar Converts time field values to UTC as milliseconds.

Exceptions
IllegalArgumentException if an unknown field is given.
Overrides
computeTime in class Calendar


 GregorianCalendar.equals

GregorianCalendar.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Description
Overrides Calendar Compares the time field records. Equivalent to comparing result of conversion to UTC. Please see Calendar.equals for descriptions on parameters and the return value.

Overrides
equals in class Calendar


 GregorianCalendar.getGreatestMinimum

GregorianCalendar.getGreatestMinimum

Class Overview | Class Members | This Package | All Packages

Syntax
public int getGreatestMinimum( int field )
Description
Returns highest minimum value for the given field if varies. Otherwise same as getMinimum(). For Gregorian, no difference. Please see Calendar.getGreatestMinimum for descriptions on parameters and the return value.

Overrides
getGreatestMinimum in class Calendar


 GregorianCalendar.getGregorianChange

GregorianCalendar.getGregorianChange

Class Overview | Class Members | This Package | All Packages

Syntax
public final Date getGregorianChange()
Returns
the Gregorian cutover time for this calendar.
Description
Gets the Gregorian Calendar change date. This is the point when the switch from Julian dates to Gregorian dates occurred. Default is 00:00:00 local time, October 15, 1582. Previous to this time and date will be Julian dates.


 GregorianCalendar.getLeastMaximum

GregorianCalendar.getLeastMaximum

Class Overview | Class Members | This Package | All Packages

Syntax
public int getLeastMaximum( int field )
Description
Returns lowest maximum value for the given field if varies. Otherwise same as getMaximum(). For Gregorian DAY_OF_MONTH, 28 Please see Calendar.getLeastMaximum for descriptions on parameters and the return value.

Overrides
getLeastMaximum in class Calendar


 GregorianCalendar.getMaximum

GregorianCalendar.getMaximum

Class Overview | Class Members | This Package | All Packages

Syntax
public int getMaximum( int field )
Description
Returns maximum value for the given field. e.g. for Gregorian DAY_OF_MONTH, 31 Please see Calendar.getMaximum for descriptions on parameters and the return value.

Overrides
getMaximum in class Calendar


 GregorianCalendar.getMinimum

GregorianCalendar.getMinimum

Class Overview | Class Members | This Package | All Packages

Syntax
public int getMinimum( int field )
Description
Returns minimum value for the given field. e.g. for Gregorian DAY_OF_MONTH, 1 Please see Calendar.getMinimum for descriptions on parameters and the return value.

Overrides
getMinimum in class Calendar


 GregorianCalendar.hashCode

GregorianCalendar.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized int hashCode()
Description
Override hashCode. Generates the hash code for the GregorianCalendar object

Overrides
hashCode in class Object


 GregorianCalendar.isLeapYear

GregorianCalendar.isLeapYear

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isLeapYear( int year )
Parameters
year
the given year.
Returns
true if the given year is a leap year; false otherwise.
Description
Determines if the given year is a leap year. Returns true if the given year is a leap year.


 GregorianCalendar.roll

GregorianCalendar.roll

Class Overview | Class Members | This Package | All Packages

Syntax
public void roll( int field, boolean up )
Parameters
field
the time field.
up
Indicates if rolling up or rolling down the field value.
Description
Overrides Calendar Time Field Rolling function. Rolls (up/down) a single unit of time on the given time field.

Exceptions
IllegalArgumentException if an unknown field value is given.
Overrides
roll in class Calendar


 GregorianCalendar.setGregorianChange

GregorianCalendar.setGregorianChange

Class Overview | Class Members | This Package | All Packages

Syntax
public void setGregorianChange( Date date )
Parameters
date
the given Gregorian cutover date.
Description
Sets the GregorianCalendar change date. This is the point when the switch from Julian dates to Gregorian dates occurred. Default is 00:00:00 local time, October 15, 1582. Previous to this time and date will be Julian dates.


 Class Hashtable

Class java.util.Hashtable

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.Dictionary
           |
           +----java.util.Hashtable

public class Hashtable
extends Dictionary
implements Cloneable, Serializable

This class implements a hashtable, which maps keys to values. Any non-null object can be used as a key or as a value.

To successfully store and retrieve objects from a hashtable, the objects used as keys must implement the hashCode method and the equals method.

An instance of Hashtable has two parameters that affect its efficiency: its capacity and its load factor. The load factor should be between 0.0 and 1.0. When the number of entries in the hashtable exceeds the product of the load factor and the current capacity, the capacity is increased by calling the rehash method. Larger load factors use memory more efficiently, at the expense of larger expected time per lookup.

If many entries are to be made into a Hashtable, creating it with a sufficiently large capacity may allow the entries to be inserted more efficiently than letting it perform automatic rehashing as needed to grow the table.

This example creates a hashtable of numbers. It uses the names of the numbers as keys:

     Hashtable numbers = new Hashtable();
     numbers.put("one", new Integer(1));
     numbers.put("two", new Integer(2));
     numbers.put("three", new Integer(3));

To retrieve a number, use the following code:

     Integer n = (Integer)numbers.get("two");
     if (n != null) {
         System.out.println("two = " + n);
     }

See Also:
equals, hashCode, rehash


 Hashtable Members

Hashtable Members

Class Overview | This Package | All Packages

Constructors
Name | Description
Hashtable() | Constructs a new, empty hashtable with a default capacity and load factor.
Hashtable(int) | Constructs a new, empty hashtable with the specified initial capacity and default load factor.
Hashtable(int, float) | Constructs a new, empty hashtable with the specified initial capacity and the specified load factor.

Methods
Name | Description
clear() | Clears this hashtable so that it contains no keys.
clone() | Creates a shallow copy of this hashtable.
contains(Object) | Tests if some key maps into the specified value in this hashtable.
containsKey(Object) | Tests if the specified object is a key in this hashtable.
elements() | Returns an enumeration of the values in this hashtable.
get(Object) | Returns the value to which the specified key is mapped in this hashtable.
isEmpty() | Tests if this hashtable maps no keys to values.
keys() | Returns an enumeration of the keys in this hashtable.
put(Object, Object) | Maps the specified key to the specified value in this hashtable.
rehash() | Rehashes the contents of the hashtable into a hashtable with a larger capacity.
remove(Object) | Removes the key (and its corresponding value) from this hashtable.
size() | Returns the number of keys in this hashtable.
toString() | Returns a rather long string representation of this hashtable.


 Hashtable.Hashtable

Hashtable.Hashtable

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Hashtable( int initialCapacity, float loadFactor )
Parameters
initialCapacity
the initial capacity of the hashtable.
loadFactor
a number between 0.0 and 1.0.
Description
Constructs a new, empty hashtable with the specified initial capacity and the specified load factor.

Exceptions
IllegalArgumentException if the initial capacity is less than or equal to zero, or if the load factor is less than or equal to zero.

Syntax 2
public Hashtable( int initialCapacity )
Parameters
initialCapacity
the initial capacity of the hashtable.
Description
Constructs a new, empty hashtable with the specified initial capacity and default load factor.

Syntax 3
public Hashtable()
Description
Constructs a new, empty hashtable with a default capacity and load factor.


 Hashtable.clear

Hashtable.clear

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void clear()
Description
Clears this hashtable so that it contains no keys.


 Hashtable.clone

Hashtable.clone

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized Object clone()
Returns
a clone of the hashtable.
Description
Creates a shallow copy of this hashtable. The keys and values themselves are not cloned. This is a relatively expensive operation.

Overrides
clone in class Object


 Hashtable.contains

Hashtable.contains

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized boolean contains( Object value )
Parameters
value
a value to search for.
Returns
true if some key maps to the value argument in this hashtable; false otherwise.
Description
Tests if some key maps into the specified value in this hashtable. This operation is more expensive than the containsKey method.

Exceptions
NullPointerException if the value is null.
See Also
containsKey


 Hashtable.containsKey

Hashtable.containsKey

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized boolean containsKey( Object key )
Parameters
key
possible key.
Returns
true if the specified object is a key in this hashtable; false otherwise.
Description
Tests if the specified object is a key in this hashtable.

See Also
contains


 Hashtable.elements

Hashtable.elements

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized Enumeration elements()
Returns
an enumeration of the values in this hashtable.
Description
Returns an enumeration of the values in this hashtable. Use the Enumeration methods on the returned object to fetch the elements sequentially.

Overrides
elements in class Dictionary
See Also
Enumeration, keys


 Hashtable.get

Hashtable.get

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized Object get( Object key )
Parameters
key
a key in the hashtable.
Returns
the value to which the key is mapped in this hashtable; null if the key is not mapped to any value in this hashtable.
Description
Returns the value to which the specified key is mapped in this hashtable.

Overrides
get in class Dictionary
See Also
put


 Hashtable.isEmpty

Hashtable.isEmpty

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isEmpty()
Returns
true if this hashtable maps no keys to values; false otherwise.
Description
Tests if this hashtable maps no keys to values.

Overrides
isEmpty in class Dictionary


 Hashtable.keys

Hashtable.keys

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized Enumeration keys()
Returns
an enumeration of the keys in this hashtable.
Description
Returns an enumeration of the keys in this hashtable.

Overrides
keys in class Dictionary
See Also
Enumeration, elements


 Hashtable.put

Hashtable.put

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized Object put( Object key, Object value )
Parameters
key
the hashtable key.
value
the value.
Returns
the previous value of the specified key in this hashtable, or null if it did not have one.
Description
Maps the specified key to the specified value in this hashtable. Neither the key nor the value can be null.

The value can be retrieved by calling the get method with a key that is equal to the original key.

Exceptions
NullPointerException if the key or value is null.
Overrides
put in class Dictionary
See Also
equals, get


 Hashtable.rehash

Hashtable.rehash

Class Overview | Class Members | This Package | All Packages

Syntax
protected void rehash()
Description
Rehashes the contents of the hashtable into a hashtable with a larger capacity. This method is called automatically when the number of keys in the hashtable exceeds this hashtable's capacity and load factor.


 Hashtable.remove

Hashtable.remove

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized Object remove( Object key )
Parameters
key
the key that needs to be removed.
Returns
the value to which the key had been mapped in this hashtable, or null if the key did not have a mapping.
Description
Removes the key (and its corresponding value) from this hashtable. This method does nothing if the key is not in the hashtable.

Overrides
remove in class Dictionary


 Hashtable.size

Hashtable.size

Class Overview | Class Members | This Package | All Packages

Syntax
public int size()
Returns
the number of keys in this hashtable.
Description
Returns the number of keys in this hashtable.

Overrides
size in class Dictionary


 Hashtable.toString

Hashtable.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized String toString()
Returns
a string representation of this hashtable.
Description
Returns a rather long string representation of this hashtable.

Overrides
toString in class Object


 Class ListResourceBundle

Class java.util.ListResourceBundle

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.ResourceBundle
           |
           +----java.util.ListResourceBundle

public abstract class ListResourceBundle
extends ResourceBundle

ListResourceBundle is a abstract subclass of ResourceBundle that manages resources for a locale in a convenient and easy to use list. See ResourceBundle for more information about resource bundles in general.

Subclasses must override getContents and provide an array, where each item in the array is a pair of objects. The first element of each pair is a String key, and the second is the value associated with that key.

In the following example, the keys are of the form "s1"... The actual keys are entirely up to your choice, so long as they are the same as the keys you use in your program to retrieve the objects from the bundle. Keys are case-sensitive. MyResource is the default version of the bundle family, and MyResource_fr is the french version:

 //====================
 class MyResource extends ListResourceBundle {
     public Object[][] getContents() {
         return contents;
     }
     static final Object[][] contents = {
     // LOCALIZE THIS
         {"s1", "3"},		// starting value in choice field
         {"s2", "MyDisk"},	// starting value in string field
         {"s3", "3 Mar 96"},	// starting value in date field
         {"s4", "The disk '{1}' contained {0} on {2}."},	// initial pattern
         {"s5", "0"},		// first choice number
         {"s6", "no files"},	// first choice value
         {"s7", "1"},		// second choice number
         {"s8", "one file"},	// second choice value
         {"s9", "2"},		// third choice number
         {"s10", "{0}|3 files"},	// third choice value
         {"s11", "format threw an exception: {0}"},	// generic exception message
         {"s12", "ERROR"},	// what to show in field in case of error
         {"s14", "Result"},	// label for formatted stuff
         {"s13", "Dialog"},	// standard font
         {"s15", "Pattern"},	// label for standard pattern
         {"s16", new Dimension(1,5)}	// real object, not just string
     // END OF MATERIAL TO LOCALIZE
     };
 }
 //====================
 class MyResource_fr  extends ListResourceBundle {
     public Object[][] getContents() {
         return contents;
}
     static final Object[][] contents = {
     // LOCALIZE THIS
         {"s1", "3"},		// starting value in choice field
         {"s2", "MonDisk"},	// starting value in string field
         {"s3", "3 Mar 96"},	// starting value in date field
         {"s4", "Le disk '{1}' a {0} a {2}."},	// initial pattern
         {"s5", "0"},		// first choice number
         {"s6", "pas de files"},	// first choice value
         {"s7", "1"},		// second choice number
         {"s8", "une file"},	// second choice value
         {"s9", "2"},		// third choice number
         {"s10", "{0}|3 files"},	// third choice value
         {"s11", "Le format a jete une exception: {0}"},	// generic exception message
         {"s12", "ERROR"},	// what to show in field in case of error
         {"s14", "Resulte"},	// label for formatted stuff
         {"s13", "Dialogue"},	// standard font
         {"s15", "Pattern"},	// label for standard pattern
         {"s16", new Dimension(1,3)}	// real object, not just string
     // END OF MATERIAL TO LOCALIZE
     };
 }

See Also:
ResourceBundle, PropertyResourceBundle


 ListResourceBundle Members

ListResourceBundle Members

Class Overview | This Package | All Packages

Constructors
Name | Description
ListResourceBundle() |

Methods
Name | Description
getContents() | See class description.
getKeys() | Implementation of ResourceBundle.getKeys.
handleGetObject(String) | Override of ResourceBundle, same semantics


 ListResourceBundle.ListResourceBundle

ListResourceBundle.ListResourceBundle

Class Overview | Class Members | This Package | All Packages

Syntax
public ListResourceBundle()


 ListResourceBundle.getContents

ListResourceBundle.getContents

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract Object[][] getContents()
Description
See class description.


 ListResourceBundle.getKeys

ListResourceBundle.getKeys

Class Overview | Class Members | This Package | All Packages

Syntax
public Enumeration getKeys()
Description
Implementation of ResourceBundle.getKeys.

Overrides
getKeys in class ResourceBundle


 ListResourceBundle.handleGetObject

ListResourceBundle.handleGetObject

Class Overview | Class Members | This Package | All Packages

Syntax
public final Object handleGetObject( String key )
Description
Override of ResourceBundle, same semantics

Overrides
handleGetObject in class ResourceBundle


 Class Locale

Class java.util.Locale

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.Locale

public final class Locale
extends Object
implements Cloneable, Serializable

A Locale object represents a specific geographical, political, or cultural region. An operation that requires a Locale to perform its task is called locale-sensitive and uses the Locale to tailor information for the user. For example, displaying a number is a locale-sensitive operation--the number should be formatted according to the customs/conventions of the user's native country, region, or culture.

You create a Locale object using one of the two constructors in this class:

 Locale(String language, String country)
 Locale(String language, String country, String variant)
The first argument to both constructors is a valid ISO Language Code. These codes are the lower-case two-letter codes as defined by ISO-639. You can find a full list of these codes at a number of sites, such as:
http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt

The second argument to both constructors is a valid ISO Country Code. These codes are the upper-case two-letter codes as defined by ISO-3166. You can find a full list of these codes at a number of sites, such as:
http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html

The second constructor requires a third argument--the Variant. The Variant codes are vendor and browser-specific. For example, use WIN for Windows, MAC for Macintosh, and POSIX for POSIX. Where there are two variants, separate them with an underscore, and put the most important one first. For example, a Traditional Spanish collation might be referenced, with "ES", "ES", "Traditional_WIN".

Because a Locale object is just an identifier for a region, no validity check is performed when you construct a Locale. If you want to see whether particular resources are available for the Locale you construct, you must query those resources. For example, ask the NumberFormat for the locales it supports using its getAvailableLocales method.
Note: When you ask for a resource for a particular locale, you get back the best available match, not necessarily precisely what you asked for. For more information, look at ResourceBundle.

The Locale class provides a number of convenient constants that you can use to create Locale objects for commonly used locales. For example, the following creates a Locale object for the United States:

 Locale.US

Once you've created a Locale you can query it for information about itself. Use getCountry to get the ISO Country Code and getLanguage to get the ISO Language Code. You can use getDisplayCountry to get the name of the country suitable for displaying to the user. Similarly, you can use getDisplayLanguage to get the name of the language suitable for displaying to the user. Interestingly, the getDisplayXXX methods are themselves locale-sensitive and have two versions: one that uses the default locale and one that uses the locale specified as an argument.

The JDK provides a number of classes that perform locale-sensitive operations. For example, the NumberFormat class formats numbers, currency, or percentages in a locale-sensitive manner. Classes such as NumberFormat have a number of convenience methods for creating a default object of that type. For example, the NumberFormat class provides these three convenience methods for creating a default NumberFormat object:

 NumberFormat.getInstance()
 NumberFormat.getCurrencyInstance()
 NumberFormat.getPercentInstance()
These methods have two variants; one with an explicit locale and one without; the latter using the default locale.
 NumberFormat.getInstance(myLocale)
 NumberFormat.getCurrencyInstance(myLocale)
 NumberFormat.getPercentInstance(myLocale)
A Locale is the mechanism for identifying the kind of object (NumberFormat) that you would like to get. The locale is just a mechanism for identifying objects, not a container for the objects themselves.

Each class that performs locale-sensitive operations allows you to get all the available objects of that type. You can sift through these objects by language, country, or variant, and use the display names to present a menu to the user. For example, you can create a menu of all the collation objects suitable for a given language. Such classes must implement these three class methods:

 public static Locale[] getAvailableLocales()
 public static String getDisplayName(Locale objectLocale,
                                     Locale displayLocale)
 public static final String getDisplayName(Locale objectLocale)
     // getDisplayName will throw MissingResourceException if the locale
     // is not one of the available locales.

See Also:
ResourceBundle, Format, NumberFormat, Collation


 Locale Members

Locale Members

Class Overview | This Package | All Packages

Fields
Name | Description
CANADA | Useful constant for country.
CANADA_FRENCH | Useful constant for country.
CHINA | Useful constant for country.
CHINESE | Useful constant for language.
ENGLISH | Useful constant for language.
FRANCE | Useful constant for country.
FRENCH | Useful constant for language.
GERMAN | Useful constant for language.
GERMANY | Useful constant for country.
ITALIAN | Useful constant for language.
ITALY | Useful constant for country.
JAPAN | Useful constant for country.
JAPANESE | Useful constant for language.
KOREA | Useful constant for country.
KOREAN | Useful constant for language.
PRC | Useful constant for country.
SIMPLIFIED_CHINESE | Useful constant for language.
TAIWAN | Useful constant for region.
TRADITIONAL_CHINESE | Useful constant for language.
UK | Useful constant for country.
US | Useful constant for country.

Constructors
Name | Description
Locale(String, String) | Construct a locale from language, country.
Locale(String, String, String) | Construct a locale from language, country, variant.

Methods
Name | Description
clone() | Overrides Cloneable
equals(Object) | Compares two Objects for equality.
getCountry() | Getter for programmatic name of field, an uppercased two-letter ISO-3166 code.
getDefault() | Common method of getting the current default Locale.
getDisplayCountry() | Getter for display of field to user.
getDisplayCountry(Locale) | Getter for display of field to user.
getDisplayLanguage() | Getter for display of field to user.
getDisplayLanguage(Locale) | Getter for display of field to user.
getDisplayName() | Getter for display of the entire locale to user.
getDisplayName(Locale) | Getter for display of the entire locale to user.
getDisplayVariant() | Getter for display of field to user.
getDisplayVariant(Locale) | Getter for display of field to user If the localized name is not found, returns the variant code.
getISO3Country() | Getter for the three-letter ISO country abbreviation of the locale.
getISO3Language() | Getter for the three-letter ISO language abbreviation of the locale.
getLanguage() | Getter for programmatic name of field, an lowercased two-letter ISO-639 code.
getVariant() | Getter for programmatic name of field.
hashCode() | Override hashCode.
setDefault(Locale) | Sets the default.
toString() | Getter for the programmatic name of the entire locale, with the language, country and variant separated by underbars.


 Locale.CANADA

Locale.CANADA

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Locale CANADA
Description
Useful constant for country.


 Locale.CANADA_FRENCH

Locale.CANADA_FRENCH

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Locale CANADA_FRENCH
Description
Useful constant for country.


 Locale.CHINA

Locale.CHINA

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Locale CHINA
Description
Useful constant for country.


 Locale.CHINESE

Locale.CHINESE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Locale CHINESE
Description
Useful constant for language.


 Locale.ENGLISH

Locale.ENGLISH

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Locale ENGLISH
Description
Useful constant for language.


 Locale.FRANCE

Locale.FRANCE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Locale FRANCE
Description
Useful constant for country.


 Locale.FRENCH

Locale.FRENCH

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Locale FRENCH
Description
Useful constant for language.


 Locale.GERMAN

Locale.GERMAN

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Locale GERMAN
Description
Useful constant for language.


 Locale.GERMANY

Locale.GERMANY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Locale GERMANY
Description
Useful constant for country.


 Locale.ITALIAN

Locale.ITALIAN

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Locale ITALIAN
Description
Useful constant for language.


 Locale.ITALY

Locale.ITALY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Locale ITALY
Description
Useful constant for country.


 Locale.JAPAN

Locale.JAPAN

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Locale JAPAN
Description
Useful constant for country.


 Locale.JAPANESE

Locale.JAPANESE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Locale JAPANESE
Description
Useful constant for language.


 Locale.KOREA

Locale.KOREA

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Locale KOREA
Description
Useful constant for country.


 Locale.KOREAN

Locale.KOREAN

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Locale KOREAN
Description
Useful constant for language.


 Locale.PRC

Locale.PRC

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Locale PRC
Description
Useful constant for country.


 Locale.SIMPLIFIED_CHINESE

Locale.SIMPLIFIED_CHINESE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Locale SIMPLIFIED_CHINESE
Description
Useful constant for language.


 Locale.TAIWAN

Locale.TAIWAN

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Locale TAIWAN
Description
Useful constant for region.


 Locale.TRADITIONAL_CHINESE

Locale.TRADITIONAL_CHINESE

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Locale TRADITIONAL_CHINESE
Description
Useful constant for language.


 Locale.UK

Locale.UK

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Locale UK
Description
Useful constant for country.


 Locale.US

Locale.US

Class Overview | Class Members | This Package | All Packages

Syntax
public static final Locale US
Description
Useful constant for country.


 Locale.Locale

Locale.Locale

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Locale( String language, String country, String variant )
Parameters
language
lowercase two-letter ISO-639 code.
country
uppercase two-letter ISO-3166 code.
variant
vendor and browser specific code. See class description.
Description
Construct a locale from language, country, variant.

Syntax 2
public Locale( String language, String country )
Parameters
language
lowercase two-letter ISO-639 code.
country
uppercase two-letter ISO-3166 code.
Description
Construct a locale from language, country.


 Locale.clone

Locale.clone

Class Overview | Class Members | This Package | All Packages

Syntax
public Object clone()
Description
Overrides Cloneable

Overrides
clone in class Object


 Locale.equals

Locale.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Description
Compares two Objects for equality.

Overrides
equals in class Object


 Locale.getCountry

Locale.getCountry

Class Overview | Class Members | This Package | All Packages

Syntax
public String getCountry()
Description
Getter for programmatic name of field, an uppercased two-letter ISO-3166 code.

See Also
getDisplayCountry


 Locale.getDefault

Locale.getDefault

Class Overview | Class Members | This Package | All Packages

Syntax
public static synchronized Locale getDefault()
Description
Common method of getting the current default Locale. Used for the presentation: menus, dialogs, etc. Generally set once when your applet or application is initialized, then never reset. (If you do reset the default locale, you probably want to reload your GUI, so that the change is reflected in your interface.)

More advanced programs will allow users to use different locales for different fields, e.g. in a spreadsheet.
Note that the initial setting will match the host system.


 Locale.getDisplayCountry

Locale.getDisplayCountry

Class Overview | Class Members | This Package | All Packages

Syntax 1
public final String getDisplayCountry()
Description
Getter for display of field to user. If the localized name is not found, returns the ISO code. The default locale is used for the presentation language.

Syntax 2
public String getDisplayCountry( Locale inLocale )
Parameters
inLocale
specifies the desired user language.
Description
Getter for display of field to user. If the localized name is not found, returns the ISO code.


 Locale.getDisplayLanguage

Locale.getDisplayLanguage

Class Overview | Class Members | This Package | All Packages

Syntax 1
public final String getDisplayLanguage()
Description
Getter for display of field to user. If the localized name is not found, returns the ISO code. The desired user language is from the default locale.

Syntax 2
public String getDisplayLanguage( Locale inLocale )
Parameters
inLocale
specifies the desired user language.
Description
Getter for display of field to user. If the localized name is not found, returns the ISO codes. Example: "English (UK)", "Deutch", "Germany"


 Locale.getDisplayName

Locale.getDisplayName

Class Overview | Class Members | This Package | All Packages

Syntax 1
public final String getDisplayName()
Description
Getter for display of the entire locale to user. If the localized name is not found, uses the ISO codes. The default locale is used for the presentation language.

Syntax 2
public String getDisplayName( Locale inLocale )
Parameters
inLocale
specifies the desired user language.
Description
Getter for display of the entire locale to user. If the localized name is not found, uses the ISO codes


 Locale.getDisplayVariant

Locale.getDisplayVariant

Class Overview | Class Members | This Package | All Packages

Syntax 1
public final String getDisplayVariant()
Description
Getter for display of field to user. If the localized name is not found, returns the variant code. The default locale is used for the presentation language.

Syntax 2
public String getDisplayVariant( Locale inLocale )
Parameters
inLocale
specifies the desired user language.
Description
Getter for display of field to user If the localized name is not found, returns the variant code.


 Locale.getISO3Country

Locale.getISO3Country

Class Overview | Class Members | This Package | All Packages

Syntax
public String getISO3Country() throws MissingResourceException
Description
Getter for the three-letter ISO country abbreviation of the locale.

Exceptions
MissingResourceException Throws MissingResourceException if the three-letter language abbreviation is not available for this locale.


 Locale.getISO3Language

Locale.getISO3Language

Class Overview | Class Members | This Package | All Packages

Syntax
public String getISO3Language() throws MissingResourceException
Description
Getter for the three-letter ISO language abbreviation of the locale.

Exceptions
MissingResourceException Throws MissingResourceException if the three-letter language abbreviation is not available for this locale.


 Locale.getLanguage

Locale.getLanguage

Class Overview | Class Members | This Package | All Packages

Syntax
public String getLanguage()
Description
Getter for programmatic name of field, an lowercased two-letter ISO-639 code.

See Also
getDisplayLanguage


 Locale.getVariant

Locale.getVariant

Class Overview | Class Members | This Package | All Packages

Syntax
public String getVariant()
Description
Getter for programmatic name of field.

See Also
getDisplayVariant


 Locale.hashCode

Locale.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized int hashCode()
Description
Override hashCode. Since Locales are often used in hashtables, caches the value for speed.

Overrides
hashCode in class Object


 Locale.setDefault

Locale.setDefault

Class Overview | Class Members | This Package | All Packages

Syntax
public static synchronized void setDefault( Locale newLocale )
Parameters
newLocale
Locale to set to.
Description
Sets the default. Normally set once at the beginning of applet or application, then never reset. setDefault does not reset the host locale.


 Locale.toString

Locale.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public final String toString()
Description
Getter for the programmatic name of the entire locale, with the language, country and variant separated by underbars. If a field is missing, at most one underbar will occur. Example: "EN", "DE_DE", "EN_US_WIN", "DE_POSIX", "FR_MAC"

Overrides
toString in class Object
See Also
getDisplayName


 Class MissingResourceException

Class java.util.MissingResourceException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.lang.RuntimeException
                           |
                           +----java.util.MissingResourceException

public class MissingResourceException
extends RuntimeException

Signals that a resource is missing.

See Also:
Exception, ResourceBundle


 MissingResourceException Members

MissingResourceException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
MissingResourceException(String, String, String) | Constructs a MissingResourceException with the specified information.

Methods
Name | Description
getClassName() | Gets parameter passed by constructor.
getKey() | Gets parameter passed by constructor.


 MissingResourceException.MissingResourceException

MissingResourceException.MissingResourceException

Class Overview | Class Members | This Package | All Packages

Syntax
public MissingResourceException( String s, String className, String key )
Parameters
s
the detail message
classname
the name of the resource class
key
the key for the missing resource.
Description
Constructs a MissingResourceException with the specified information. A detail message is a String that describes this particular exception.


 MissingResourceException.getClassName

MissingResourceException.getClassName

Class Overview | Class Members | This Package | All Packages

Syntax
public String getClassName()
Description
Gets parameter passed by constructor.


 MissingResourceException.getKey

MissingResourceException.getKey

Class Overview | Class Members | This Package | All Packages

Syntax
public String getKey()
Description
Gets parameter passed by constructor.


 Class NoSuchElementException

Class java.util.NoSuchElementException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.lang.RuntimeException
                           |
                           +----java.util.NoSuchElementException

public class NoSuchElementException
extends RuntimeException

Thrown by the nextElement method of an Enumeration to indicate that there are no more elements in the enumeration.

See Also:
Enumeration, nextElement


 NoSuchElementException Members

NoSuchElementException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
NoSuchElementException() | Constructs a NoSuchElementException with no detail message.
NoSuchElementException(String) | Constructs a NoSuchElementException with the specified detail message.


 NoSuchElementException.NoSuchElementException

NoSuchElementException.NoSuchElementException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public NoSuchElementException()
Description
Constructs a NoSuchElementException with no detail message.

Syntax 2
public NoSuchElementException( String s )
Parameters
s
the detail message.
Description
Constructs a NoSuchElementException with the specified detail message.


 Class Observable

Class java.util.Observable

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.Observable

public class Observable
extends Object

This class represents an observable object, or "data" in the model-view paradigm. It can be subclassed to represent an object that the application wants to have observed.

An observable object can have one or more observers. After an observable instance changes, an application calling the Observable's notifyObservers method causes all of its observers to be notified of the change by a call to their update method.

See Also:
notifyObservers, notifyObservers, Observer, update


 Observable Members

Observable Members

Class Overview | This Package | All Packages

Constructors
Name | Description
Observable() | Construct an Observable with zero Observers

Methods
Name | Description
addObserver(Observer) | Adds an observer to the set of observers for this object.
clearChanged() | Indicates that this object has no longer changed, or that it has already notified all of its observers of its most recent change.
countObservers() | Returns the number of observers of this object.
deleteObserver(Observer) | Deletes an observer from the set of observers of this object.
deleteObservers() | Clears the observer list so that this object no longer has any observers.
hasChanged() | Tests if this object has changed.
notifyObservers() | If this object has changed, as indicated by the hasChanged method, then notify all of its observers and then call the clearChanged method to indicate that this object has no longer changed.
notifyObservers(Object) | If this object has changed, as indicated by the hasChanged method, then notify all of its observers and then call the clearChanged method to indicate that this object has no longer changed.
setChanged() | Indicates that this object has changed.


 Observable.Observable

Observable.Observable

Class Overview | Class Members | This Package | All Packages

Syntax
public Observable()
Description
Construct an Observable with zero Observers


 Observable.addObserver

Observable.addObserver

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void addObserver( Observer o )
Parameters
o
an observer to be added.
Description
Adds an observer to the set of observers for this object.


 Observable.clearChanged

Observable.clearChanged

Class Overview | Class Members | This Package | All Packages

Syntax
protected synchronized void clearChanged()
Description
Indicates that this object has no longer changed, or that it has already notified all of its observers of its most recent change. This method is called automatically by the notifyObservers methods.

See Also
notifyObservers, notifyObservers


 Observable.countObservers

Observable.countObservers

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized int countObservers()
Returns
the number of observers of this object.
Description
Returns the number of observers of this object.


 Observable.deleteObserver

Observable.deleteObserver

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void deleteObserver( Observer o )
Parameters
o
the observer to be deleted.
Description
Deletes an observer from the set of observers of this object.


 Observable.deleteObservers

Observable.deleteObservers

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void deleteObservers()
Description
Clears the observer list so that this object no longer has any observers.


 Observable.hasChanged

Observable.hasChanged

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized boolean hasChanged()
Returns
true if the setChanged method has been called more recently than the clearChanged method on this object; false otherwise.
Description
Tests if this object has changed.

See Also
clearChanged, setChanged


 Observable.notifyObservers

Observable.notifyObservers

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void notifyObservers()
Description
If this object has changed, as indicated by the hasChanged method, then notify all of its observers and then call the clearChanged method to indicate that this object has no longer changed.

Each observer has its update method called with two arguments: this observable object and null.

See Also
clearChanged, hasChanged, update

Syntax 2
public void notifyObservers( Object arg )
Parameters
arg
any object.
Description
If this object has changed, as indicated by the hasChanged method, then notify all of its observers and then call the clearChanged method to indicate that this object has no longer changed.

Each observer has its update method called with two arguments: this observable object and the arg argument.

See Also
clearChanged, hasChanged, update


 Observable.setChanged

Observable.setChanged

Class Overview | Class Members | This Package | All Packages

Syntax
protected synchronized void setChanged()
Description
Indicates that this object has changed.


 Interface Observer

Interface java.util.Observer

Interface Members | This Package | All Packages

public interface Observer

A class can implement the Observer interface when it wants to be informed of changes in observable objects.

See Also:
Observable


 Observer Members

Observer Members

Interface Overview | This Package | All Packages

Methods
Name | Description
update(Observable, Object) | This method is called whenever the observed object is changed.


 Observer.update

Observer.update

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void update( Observable o, Object arg )
Parameters
o
the observable object.
arg
an argument passed to the notifyObservers method.
Description
This method is called whenever the observed object is changed. An application calls an observable object's notifyObservers method to have all the object's observers notified of the change.


 Class Properties

Class java.util.Properties

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.Dictionary
           |
           +----java.util.Hashtable
                   |
                   +----java.util.Properties

public class Properties
extends Hashtable

The Properties class represents a persistent set of properties. The Properties can be saved to a stream or loaded from a stream. Each key and its corresponding value in the property list is a string.

A property list can contain another property list as its "defaults"; this second property list is searched if the property key is not found in the original property list.


 Properties Members

Properties Members

Class Overview | This Package | All Packages

Fields
Name | Description
defaults | A property list that contains default values for any keys not found in this property list.

Constructors
Name | Description
Properties() | Creates an empty property list with no default values.
Properties(Properties) | Creates an empty property list with the specified defaults.

Methods
Name | Description
getProperty(String) | Searches for the property with the specified key in this property list.
getProperty(String, String) | Searches for the property with the specified key in this property list.
list(PrintStream) | Prints this property list out to the specified output stream.
list(PrintWriter) | Prints this property list out to the specified output stream.
load(InputStream) | Reads a property list from an input stream.
propertyNames() | Returns an enumeration of all the keys in this property list, including the keys in the default property list.
save(OutputStream, String) | Stores this property list to the specified output stream.


 Properties.defaults

Properties.defaults

Class Overview | Class Members | This Package | All Packages

Syntax
protected Properties defaults
Description
A property list that contains default values for any keys not found in this property list.


 Properties.Properties

Properties.Properties

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Properties()
Description
Creates an empty property list with no default values.

Syntax 2
public Properties( Properties defaults )
Parameters
defaults
the defaults.
Description
Creates an empty property list with the specified defaults.


 Properties.getProperty

Properties.getProperty

Class Overview | Class Members | This Package | All Packages

Syntax 1
public String getProperty( String key )
Parameters
key
the property key.
Returns
the value in this property list with the specified key value.
Description
Searches for the property with the specified key in this property list. If the key is not found in this property list, the default property list, and its defaults, recursively, are then checked. The method returns null if the property is not found.

See Also
defaults

Syntax 2
public String getProperty( String key, String defaultValue )
Parameters
key
the hashtable key.
defaultValue
a default value.
Returns
the value in this property list with the specified key value.
Description
Searches for the property with the specified key in this property list. If the key is not found in this property list, the default property list, and its defaults, recursively, are then checked. The method returns the default value argument if the property is not found.

See Also
defaults


 Properties.list

Properties.list

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void list( PrintStream out )
Parameters
out
an output stream.
Description
Prints this property list out to the specified output stream. This method is useful for debugging.

Syntax 2
public void list( PrintWriter out )
Parameters
out
an output stream.
Description
Prints this property list out to the specified output stream. This method is useful for debugging.


 Properties.load

Properties.load

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void load( InputStream in ) throws IOException
Parameters
in
the input stream.
Description
Reads a property list from an input stream.

Exceptions
IOException if an error occurred when reading from the input stream.


 Properties.propertyNames

Properties.propertyNames

Class Overview | Class Members | This Package | All Packages

Syntax
public Enumeration propertyNames()
Returns
an enumeration of all the keys in this property list, including the keys in the default property list.
Description
Returns an enumeration of all the keys in this property list, including the keys in the default property list.

See Also
Enumeration, defaults


 Properties.save

Properties.save

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void save( OutputStream out, String header )
Parameters
out
an output stream.
header
a description of the property list.
Description
Stores this property list to the specified output stream. The string header is printed as a comment at the beginning of the stream.


 Class PropertyResourceBundle

Class java.util.PropertyResourceBundle

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.ResourceBundle
           |
           +----java.util.PropertyResourceBundle

public class PropertyResourceBundle
extends ResourceBundle

PropertyResourceBundle is an abstract subclass of ResourceBundle that manages resources for a locale using a set of static strings from a property file. See ResourceBundle for more information about resource bundles in general.

The property file contains the keys that you use in your source code in calls to ResourceBundle.getString and similar methods, and their corresponding values, etc. The name of the property file indicates the resource bundle's family and locale.

In the following example, the keys are of the form "s1"... The actual keys are entirely up to your choice, so long as they are the same as the keys you use in your program to retrieve the objects from the bundle. Keys are case-sensitive.

 s1=3
 s2=MeinDisk
 s3=3 Mar 96
 s4=Der disk '{1}' a {0} a {2}.
 s5=0
 s6=keine Datein
 s7=1
 s8=ein Datei
 s9=2
 s10={0}|3 Datein
 s11=Der Format worf ein Exception: {0}
 s12=ERROR
 s14=Resulte
 s13=Dialogue
 s15=Pattern
 s16=1,3

See Also:
ResourceBundle, ListResourceBundle


 PropertyResourceBundle Members

PropertyResourceBundle Members

Class Overview | This Package | All Packages

Constructors
Name | Description
PropertyResourceBundle(InputStream) | Creates a property resource

Methods
Name | Description
getKeys() | Implementation of ResourceBundle.getKeys.
handleGetObject(String) | Override of ResourceBundle, same semantics


 PropertyResourceBundle.PropertyResourceBundle

PropertyResourceBundle.PropertyResourceBundle

Class Overview | Class Members | This Package | All Packages

Syntax
public PropertyResourceBundle( InputStream stream ) throws IOException
Parameters
file
property file to read from.
Description
Creates a property resource


 PropertyResourceBundle.getKeys

PropertyResourceBundle.getKeys

Class Overview | Class Members | This Package | All Packages

Syntax
public Enumeration getKeys()
Description
Implementation of ResourceBundle.getKeys.

Overrides
getKeys in class ResourceBundle


 PropertyResourceBundle.handleGetObject

PropertyResourceBundle.handleGetObject

Class Overview | Class Members | This Package | All Packages

Syntax
public Object handleGetObject( String key )
Description
Override of ResourceBundle, same semantics

Overrides
handleGetObject in class ResourceBundle


 Class Random

Class java.util.Random

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.Random

public class Random
extends Object
implements Serializable

An instance of this class is used to generate a stream of pseudorandom numbers. The class uses a 48-bit seed, which is modified using a linear congruential formula. (See Donald Knuth, The Art of Computer Programming, Volume 2, Section 3.2.1.)

If two instances of Random are created with the same seed, and the same sequence of method calls is made for each, they will generate and return identical sequences of numbers.

Many applications will find the random method in class Math simpler to use.

See Also:
random


 Random Members

Random Members

Class Overview | This Package | All Packages

Constructors
Name | Description
Random() | Creates a new random number generator.
Random(long) | Creates a new random number generator using a single long seed.

Methods
Name | Description
next(int) | Generates the next pseudorandom number.
nextBytes(byte[]) | Generates a user specified number of random bytes.
nextDouble() | Returns the next pseudorandom, uniformly distributed double value between 0.0 and 1.0 from this random number generator's sequence.
nextFloat() | Returns the next pseudorandom, uniformly distributed float value between 0.0 and 1.0 from this random number generator's sequence.
nextGaussian() | Returns the next pseudorandom, Gaussian ("normally") distributed double value with mean 0.0 and standard deviation 1.0 from this random number generator's sequence.
nextInt() | Returns the next pseudorandom, uniformly distributed int value from this random number generator's sequence.
nextLong() | Returns the next pseudorandom, uniformly distributed long value from this random number generator's sequence.
setSeed(long) | Sets the seed of this random number generator using a single long seed.


 Random.Random

Random.Random

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Random()
Description
Creates a new random number generator. Its seed is initialized to a value based on the current time.

See Also
currentTimeMillis

Syntax 2
public Random( long seed )
Parameters
seed
the initial seed.
Description
Creates a new random number generator using a single long seed.

See Also
setSeed


 Random.next

Random.next

Class Overview | Class Members | This Package | All Packages

Syntax
protected synchronized int next( int bits )
Parameters
bits
random bits
Returns
the next pseudorandom value from this random number generator's sequence.
Description
Generates the next pseudorandom number. Subclass should override this, as this is used by all other methods.


 Random.nextBytes

Random.nextBytes

Class Overview | Class Members | This Package | All Packages

Syntax
public void nextBytes( byte bytes[] )
Description
Generates a user specified number of random bytes.


 Random.nextDouble

Random.nextDouble

Class Overview | Class Members | This Package | All Packages

Syntax
public double nextDouble()
Returns
the next pseudorandom, uniformly distributed double value between 0.0 and 1.0 from this random number generator's sequence.
Description
Returns the next pseudorandom, uniformly distributed double value between 0.0 and 1.0 from this random number generator's sequence.


 Random.nextFloat

Random.nextFloat

Class Overview | Class Members | This Package | All Packages

Syntax
public float nextFloat()
Returns
the next pseudorandom, uniformly distributed float value between 0.0 and 1.0 from this random number generator's sequence.
Description
Returns the next pseudorandom, uniformly distributed float value between 0.0 and 1.0 from this random number generator's sequence.


 Random.nextGaussian

Random.nextGaussian

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized double nextGaussian()
Returns
the next pseudorandom, Gaussian ("normally") distributed double value with mean 0.0 and standard deviation 1.0 from this random number generator's sequence.
Description
Returns the next pseudorandom, Gaussian ("normally") distributed double value with mean 0.0 and standard deviation 1.0 from this random number generator's sequence.


 Random.nextInt

Random.nextInt

Class Overview | Class Members | This Package | All Packages

Syntax
public int nextInt()
Returns
the next pseudorandom, uniformly distributed int value from this random number generator's sequence.
Description
Returns the next pseudorandom, uniformly distributed int value from this random number generator's sequence.


 Random.nextLong

Random.nextLong

Class Overview | Class Members | This Package | All Packages

Syntax
public long nextLong()
Returns
the next pseudorandom, uniformly distributed long value from this random number generator's sequence.
Description
Returns the next pseudorandom, uniformly distributed long value from this random number generator's sequence.


 Random.setSeed

Random.setSeed

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setSeed( long seed )
Parameters
seed
the initial seed.
Description
Sets the seed of this random number generator using a single long seed.


 Class ResourceBundle

Class java.util.ResourceBundle

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.ResourceBundle

public abstract class ResourceBundle
extends Object

Resource bundles contain locale-specific objects. When your program needs a locale-specific resource, a String for example, your program can load it from the resource bundle that is appropriate for the current user's locale. In this way, you can write program code that is largely independent of the user's locale isolating most, if not all, of the locale-specific information in resource bundles.

This allows you to write programs that can:

  • be easily localized, or translated, into different languages
  • handle multiple locales at once
  • be easily modified later to support even more locales

One resource bundle is, conceptually, a set of related classes that inherit from ResourceBundle. Each related subclass of ResourceBundle has the same base name plus an additional component that identifies its locale. For example, suppose your resource bundle is named MyResources. The first class you are likely to write is the default resource bundle which simply has the same name as its family--MyResources. You can also provide as many related locale-specific classes as you need: for example, perhaps you would provide a German one named MyResources_de.

Each related subclass of ResourceBundle contains the same items, but the items have been translated for the locale represented by that ResourceBundle subclass. For example, both MyResources and MyResources_de may have a String that's used on a button for confirming operations. In MyResources the String may contain OK and in MyResources_de it may contain Gut.

If there are different resources for different countries, you can make specializations: for example, MyResources_de_CH for Switzerland. If you want to only modify some of the resources in the specialization, you can do so.

When your program needs a locale-specific object, it loads the ResourceBundle class using the getBundle method:

 ResourceBundle myResources =
      ResourceBundle.getBundle("MyResources", currentLocale);
The first argument specifies the family name of the resource bundle that contains the object in question. The second argument indicates the desired locale. getBundle uses these two arguments to construct the name of the ResourceBundle subclass it should load as follows.

The resource bundle lookup searches for classes with various suffixes on the basis of (1) the desired locale and (2) the default locale (baseclass), in the following order from lower-level (more specific) to parent-level (less specific):

baseclass + "_" + language1 + "_" + country1 + "_" + variant1
baseclass + "_" + language1 + "_" + country1
baseclass + "_" + language1
baseclass
baseclass + "_" + language2 + "_" + country2 + "_" + variant2
baseclass + "_" + language2 + "_" + country2
baseclass + "_" + language2

The result of the lookup is a class, but that class may be backed by a property file on disk. If a lookup fails, getBundle() throws a MissingResourceException.

The baseclass must be fully qualified (for example, myPackage.MyResources, not just MyResources). It must also be accessable by your code; it cannot be a class that is private to the package where ResourceBundle.getBundle is called.

Note: ResourceBundle are used internally in accessing NumberFormats, Collations, and so on. The lookup strategy is the same.

Resource bundles contain key/value pairs. The keys uniquely identify a locale-specific object in the bundle. Here's an example of a ListResourceBundle that contains two key/value pairs:

 class MyResource extends ListResourceBundle {
      public Object[][] getContents() {
              return contents;
      }
      static final Object[][] contents = {
      // LOCALIZE THIS
              {"OkKey", "OK"},
              {"CancelKey", "Cancel"},
      // END OF MATERIAL TO LOCALIZE
      };
 }
Keys are always Strings. In this example, the keys are OkKey and CancelKey. In the above example, the values are also Strings--OK and Cancel--but they don't have to be. The values can be any type of object.

You retrieve an object from resource bundle using the appropriate getter method. Because OkKey and CancelKey are both strings, you would use getString to retrieve them:

 button1 = new Button(myResourceBundle.getString("OkKey"));
 button2 = new Button(myResourceBundle.getString("CancelKey"));
The getter methods all require the key as an argument and return the object if found. If the object is not found, the getter method throws a MissingResourceException.

Besides getString; ResourceBundle supports a number of other methods for getting different types of objects such as getStringArray. If you don't have an object that matches one of these methods, you can use getObject and cast the result to the appropriate type. For example:

 int[] myIntegers = (int[]) myResources.getObject("intList");

NOTE: You should always supply a baseclass with no suffixes. This will be the class of "last resort", if a locale is requested that does not exist. For example, below we have a class MyResources. It happens to contain US strings, so we don't have to have an explicit MyResource_en or MyResource_en_US.

The JDK provides two subclasses of ResourceBundle, ListResourceBundle and PropertyResourceBundle, that provide a fairly simple way to create resources. (Once serialization is fully integrated, we will provide another way.) As you saw briefly in a prevous example, ListResourceBundle manages its resource as a List of key/value pairs. PropertyResourceBundle uses a properties file to manage its resources.

If ListResourceBundle or PropertyResourceBundle do not suit your needs, you can write your own ResourceBundle subclass. Your subclasses must overrde two methods: handleGetObject and getKeys().

The following is a very simple example of a ResourceBundle subclass that manages only a few resources (for a larger number of resources you would probably use a Hashtable). Notice that if the key is not found, handleGetObject must return null. Notice also that you don't need to supply a value if a "parent-level" ResourceBundle handles the same key with the same value (look at uk below).

Example:

 abstract class MyResources extends ResourceBundle {
     public Object handleGetObject(String key) {
         if (key.equals("okKey")) return "Ok";
         if (key.equals("cancelKey")) return "Cancel";
        return null;
     }
 }
 abstract class MyResources_de extends MyResources {
     public Object handleGetObject(String key) {
         if (key.equals("okKey")) return "Gut";
         if (key.equals("cancelKey")) return "Vernichten";
         return null;
     }
 }
 abstract class MyResources_uk extends MyResources {
     public Object handleGetObject(String key) {
         // don't need okKey, since parent level handles it.
         if (key.equals("cancelKey")) return "Dispose";
            return null;
     }
 }
You do not have to restrict yourself to using a single family of ResourceBundles. For example, you could have a set of bundles for exception messages, ExceptionResources (ExceptionResources_fr, ExceptionResources_de, ...), and one for widgets, WidgetResource (WidgetResources_fr, WidgetResources_de, ...); breaking up the resources however you like.

See Also:
ListResourceBundle, PropertyResourceBundle, MissingResourceException


 ResourceBundle Members

ResourceBundle Members

Class Overview | This Package | All Packages

Fields
Name | Description
parent | The parent bundle is consulted by getObject when this bundle does not contain a particular resource.

Constructors
Name | Description
ResourceBundle() |

Methods
Name | Description
getBundle(String) | Get the appropriate ResourceBundle subclass.
getBundle(String, Locale) | Get the appropriate ResourceBundle subclass.
getKeys() | Return an enumeration of the keys.
getObject(String) | Get an object from a ResourceBundle.
getString(String) | Get an object from a ResourceBundle.
getStringArray(String) | Get an object from a ResourceBundle.
handleGetObject(String) | Get an object from a ResourceBundle.
setParent(ResourceBundle) | Set the parent bundle of this bundle.


 ResourceBundle.parent

ResourceBundle.parent

Class Overview | Class Members | This Package | All Packages

Syntax
protected ResourceBundle parent
Description
The parent bundle is consulted by getObject when this bundle does not contain a particular resource.


 ResourceBundle.ResourceBundle

ResourceBundle.ResourceBundle

Class Overview | Class Members | This Package | All Packages

Syntax
public ResourceBundle()


 ResourceBundle.getBundle

ResourceBundle.getBundle

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static final ResourceBundle getBundle( String baseName ) throws MissingResourceException
Parameters
baseName
see class description.
Description
Get the appropriate ResourceBundle subclass.

Syntax 2
public static final ResourceBundle getBundle( String baseName, Locale locale )
Parameters
baseName
see class description.
locale
see class description.
Description
Get the appropriate ResourceBundle subclass.


 ResourceBundle.getKeys

ResourceBundle.getKeys

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract Enumeration getKeys()
Description
Return an enumeration of the keys. NOTE: Subclasses must override.


 ResourceBundle.getObject

ResourceBundle.getObject

Class Overview | Class Members | This Package | All Packages

Syntax
public final Object getObject( String key ) throws MissingResourceException
Parameters
key
see class description.
Description
Get an object from a ResourceBundle.


 ResourceBundle.getString

ResourceBundle.getString

Class Overview | Class Members | This Package | All Packages

Syntax
public final String getString( String key ) throws MissingResourceException
Parameters
key
see class description.
Description
Get an object from a ResourceBundle.
Convenience method to save casting.


 ResourceBundle.getStringArray

ResourceBundle.getStringArray

Class Overview | Class Members | This Package | All Packages

Syntax
public final String[] getStringArray( String key ) throws MissingResourceException
Parameters
key
see class description.
Description
Get an object from a ResourceBundle.
Convenience method to save casting.


 ResourceBundle.handleGetObject

ResourceBundle.handleGetObject

Class Overview | Class Members | This Package | All Packages

Syntax
protected abstract Object handleGetObject( String key ) throws MissingResourceException
Parameters
key
see class description.
Description
Get an object from a ResourceBundle. NOTE: Subclasses must override.


 ResourceBundle.setParent

ResourceBundle.setParent

Class Overview | Class Members | This Package | All Packages

Syntax
protected void setParent( ResourceBundle parent )
Parameters
parent
this bundle's parent bundle.
Description
Set the parent bundle of this bundle. The parent bundle is searched by getObject when this bundle does not contain a particular resource.


 Class SimpleTimeZone

Class java.util.SimpleTimeZone

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.TimeZone
           |
           +----java.util.SimpleTimeZone

public class SimpleTimeZone
extends TimeZone

SimpleTimeZone is a concrete subclass of TimeZone that represents a time zone for use with a Gregorian calendar. This simple class does not handle historical changes, and has limited rules.

Use a negative value for dayOfWeekInMonth to indicate that SimpleTimeZone should count from the end of the month backwards. For example, Daylight Savings Time ends at the last (dayOfWeekInMonth = -1) Sunday in October, at 2 AM in standard time.

See Also:
Calendar, GregorianCalendar, TimeZone


 SimpleTimeZone Members

SimpleTimeZone Members

Class Overview | This Package | All Packages

Constructors
Name | Description
SimpleTimeZone(int, String) | Constructs a SimpleTimeZone with the given base time zone offset from GMT and time zone ID.
SimpleTimeZone(int, String, int, int, int, int, int, int, int, int) | Constructs a SimpleTimeZone with the given base time zone offset from GMT, time zone ID, time to start and end the daylight time.

Methods
Name | Description
clone() | Overrides Cloneable
equals(Object) | Compares the equality of two SimpleTimeZone objects.
getOffset(int, int, int, int, int, int) | Overrides TimeZone Gets offset, for current date, modified in case of daylight savings.
getRawOffset() | Overrides TimeZone Gets the GMT offset for this time zone.
hashCode() | Override hashCode.
inDaylightTime(Date) | Overrides TimeZone Queries if the given date is in Daylight Savings Time.
setEndRule(int, int, int, int) | Sets the daylight savings ending rule.
setRawOffset(int) | Overrides TimeZone Sets the base time zone offset to GMT.
setStartRule(int, int, int, int) | Sets the daylight savings starting rule.
setStartYear(int) | Sets the daylight savings starting year.
useDaylightTime() | Overrides TimeZone Queries if this time zone uses Daylight Savings Time.


 SimpleTimeZone.SimpleTimeZone

SimpleTimeZone.SimpleTimeZone

Class Overview | Class Members | This Package | All Packages

Syntax 1
public SimpleTimeZone( int rawOffset, String ID )
Parameters
rawOffset
the given base time zone offset to GMT.
ID
the time zone ID which is obtained from TimeZone.getAvailableIDs.
Description
Constructs a SimpleTimeZone with the given base time zone offset from GMT and time zone ID. Timezone IDs can be obtained from TimeZone.getAvailableIDs. Normally you should use TimeZone.getDefault to construct a TimeZone.

Syntax 2
public SimpleTimeZone( int rawOffset, String ID, int startMonth, int startDayOfWeekInMonth, int startDayOfWeek, int startTime, int endMonth, int endDayOfWeekInMonth, int endDayOfWeek, int endTime )
Parameters
rawOffset
the given base time zone offset to GMT.
ID
the time zone ID which is obtained from TimeZone.getAvailableIDs.
startMonth
the daylight savings starting month. Month is 0-based. eg, 0 for January.
startDayOfWeekInMonth
the daylight savings starting day-of-week-in-month. Please see the member description for an example.
startDayOfWeek
the daylight savings starting day-of-week. Please see the member description for an example.
startTime
the daylight savings starting time. Please see the member description for an example.
endMonth
the daylight savings ending month. Month is 0-based. eg, 0 for January.
endDayOfWeekInMonth
the daylight savings ending day-of-week-in-month. Please see the member description for an example.
endDayOfWeek
the daylight savings ending day-of-week. Please see the member description for an example.
endTime
the daylight savings ending time. Please see the member description for an example.
Description
Constructs a SimpleTimeZone with the given base time zone offset from GMT, time zone ID, time to start and end the daylight time. Timezone IDs can be obtained from TimeZone.getAvailableIDs. Normally you should use TimeZone.getDefault to create a TimeZone. For a time zone that does not use daylight saving time, do not use this constructor; instead you should use SimpleTimeZone(rawOffset, ID).


 SimpleTimeZone.clone

SimpleTimeZone.clone

Class Overview | Class Members | This Package | All Packages

Syntax
public Object clone()
Description
Overrides Cloneable

Overrides
clone in class TimeZone


 SimpleTimeZone.equals

SimpleTimeZone.equals

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean equals( Object obj )
Parameters
obj
the SimpleTimeZone object to be compared with.
Returns
true if the given obj is the same as this SimpleTimeZone object; false otherwise.
Description
Compares the equality of two SimpleTimeZone objects.

Overrides
equals in class Object


 SimpleTimeZone.getOffset

SimpleTimeZone.getOffset

Class Overview | Class Members | This Package | All Packages

Syntax
public int getOffset( int era, int year, int month, int day, int dayOfWeek, int millis )
Description
Overrides TimeZone Gets offset, for current date, modified in case of daylight savings. This is the offset to add *to* UTC to get local time. Please see TimeZone.getOffset for descriptions on parameters.

Overrides
getOffset in class TimeZone


 SimpleTimeZone.getRawOffset

SimpleTimeZone.getRawOffset

Class Overview | Class Members | This Package | All Packages

Syntax
public int getRawOffset()
Description
Overrides TimeZone Gets the GMT offset for this time zone.

Overrides
getRawOffset in class TimeZone


 SimpleTimeZone.hashCode

SimpleTimeZone.hashCode

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized int hashCode()
Description
Override hashCode. Generates the hash code for the SimpleDateFormat object

Overrides
hashCode in class Object


 SimpleTimeZone.inDaylightTime

SimpleTimeZone.inDaylightTime

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean inDaylightTime( Date date )
Description
Overrides TimeZone Queries if the given date is in Daylight Savings Time.

Overrides
inDaylightTime in class TimeZone


 SimpleTimeZone.setEndRule

SimpleTimeZone.setEndRule

Class Overview | Class Members | This Package | All Packages

Syntax
public void setEndRule( int month, int dayOfWeekInMonth, int dayOfWeek, int time )
Parameters
month
the daylight savings ending month. Month is 0-based. eg, 0 for January.
dayOfWeekInMonth
the daylight savings ending day-of-week-in-month. Please see the member description for an example.
dayOfWeek
the daylight savings ending day-of-week. Please see the member description for an example.
time
the daylight savings ending time. Please see the member description for an example.
Description
Sets the daylight savings ending rule. For example, Daylight Savings Time ends at the last (-1) Sunday in October, at 2 AM in standard time. Therefore, you can set the end rule by calling: setEndRule(TimeFields.OCTOBER, -1, TimeFields.SUNDAY, 2*60*60*1000);


 SimpleTimeZone.setRawOffset

SimpleTimeZone.setRawOffset

Class Overview | Class Members | This Package | All Packages

Syntax
public void setRawOffset( int offsetMillis )
Description
Overrides TimeZone Sets the base time zone offset to GMT. This is the offset to add *to* UTC to get local time. Please see TimeZone.setRawOffset for descriptions on the parameter.

Overrides
setRawOffset in class TimeZone


 SimpleTimeZone.setStartRule

SimpleTimeZone.setStartRule

Class Overview | Class Members | This Package | All Packages

Syntax
public void setStartRule( int month, int dayOfWeekInMonth, int dayOfWeek, int time )
Parameters
month
the daylight savings starting month. Month is 0-based. eg, 0 for January.
dayOfWeekInMonth
the daylight savings starting day-of-week-in-month. Please see the member description for an example.
dayOfWeek
the daylight savings starting day-of-week. Please see the member description for an example.
time
the daylight savings starting time. Please see the member description for an example.
Description
Sets the daylight savings starting rule. For example, Daylight Savings Time starts at the first Sunday in April, at 2 AM in standard time. Therefore, you can set the start rule by calling: setStartRule(TimeFields.APRIL, 1, TimeFields.SUNDAY, 2*60*60*1000);


 SimpleTimeZone.setStartYear

SimpleTimeZone.setStartYear

Class Overview | Class Members | This Package | All Packages

Syntax
public void setStartYear( int year )
Parameters
year
the daylight savings starting year.
Description
Sets the daylight savings starting year.


 SimpleTimeZone.useDaylightTime

SimpleTimeZone.useDaylightTime

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean useDaylightTime()
Description
Overrides TimeZone Queries if this time zone uses Daylight Savings Time.

Overrides
useDaylightTime in class TimeZone


 Class Stack

Class java.util.Stack

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.Vector
           |
           +----java.util.Stack

public class Stack
extends Vector

The Stack class represents a last-in-first-out (LIFO) stack of objects.


 Stack Members

Stack Members

Class Overview | This Package | All Packages

Constructors
Name | Description
Stack() |

Methods
Name | Description
empty() | Tests if this stack is empty.
peek() | Looks at the object at the top of this stack without removing it from the stack.
pop() | Removes the object at the top of this stack and returns that object as the value of this function.
push(Object) | Pushes an item onto the top of this stack.
search(Object) | Returns where an object is on this stack.


 Stack.Stack

Stack.Stack

Class Overview | Class Members | This Package | All Packages

Syntax
public Stack()


 Stack.empty

Stack.empty

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean empty()
Returns
true if this stack is empty; false otherwise.
Description
Tests if this stack is empty.


 Stack.peek

Stack.peek

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized Object peek()
Returns
the object at the top of this stack.
Description
Looks at the object at the top of this stack without removing it from the stack.

Exceptions
EmptyStackException if this stack is empty.


 Stack.pop

Stack.pop

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized Object pop()
Returns
The object at the top of this stack.
Description
Removes the object at the top of this stack and returns that object as the value of this function.

Exceptions
EmptyStackException if this stack is empty.


 Stack.push

Stack.push

Class Overview | Class Members | This Package | All Packages

Syntax
public Object push( Object item )
Parameters
item
the item to be pushed onto this stack.
Returns
the item argument.
Description
Pushes an item onto the top of this stack.


 Stack.search

Stack.search

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized int search( Object o )
Parameters
o
the desired object.
Returns
the distance from the top of the stack where the object is] located; the return value -1 indicates that the object is not on the stack.
Description
Returns where an object is on this stack.


 Class StringTokenizer

Class java.util.StringTokenizer

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.StringTokenizer

public class StringTokenizer
extends Object
implements Enumeration

The string tokenizer class allows an application to break a string into tokens. The tokenization method is much simpler than the one used by the StreamTokenizer class. The StringTokenizer methods do not distinguish among identifiers, numbers, and quoted strings, nor do they recognize and skip comments.

The set of delimiters (the characters that separate tokens) may be specified either at creation time or on a per-token basis.

An instance of StringTokenizer behaves in one of two ways, depending on whether it was created with the returnTokens flag having the value true or false:

  • If the flag is false, delimiter characters serve to separate tokens. A token is a maximal sequence of consecutive characters that are not delimiters.
  • If the flag is true, delimiter characters are considered to be tokens. A token is either one delimiter character, or a maximal sequence of consecutive characters that are not delimiters.

The following is one example of the use of the tokenizer. The code:

     StringTokenizer st = new StringTokenizer("this is a test");
     while (st.hasMoreTokens()) {
         println(st.nextToken());
     }

prints the following output:

     this
     is
     a
     test

See Also:
StreamTokenizer


 StringTokenizer Members

StringTokenizer Members

Class Overview | This Package | All Packages

Constructors
Name | Description
StringTokenizer(String) | Constructs a string tokenizer for the specified string.
StringTokenizer(String, String) | Constructs a string tokenizer for the specified string.
StringTokenizer(String, String, boolean) | Constructs a string tokenizer for the specified string.

Methods
Name | Description
countTokens() | Calculates the number of times that this tokenizer's nextToken method can be called before it generates an exception.
hasMoreElements() | Returns the same value as the hasMoreTokens method.
hasMoreTokens() | Tests if there are more tokens available from this tokenizer's string.
nextElement() | Returns the same value as the nextToken method, except that its declared return value is Object rather than String.
nextToken() | Returns the next token from this string tokenizer.
nextToken(String) | Returns the next token in this string tokenizer's string.


 StringTokenizer.StringTokenizer

StringTokenizer.StringTokenizer

Class Overview | Class Members | This Package | All Packages

Syntax 1
public StringTokenizer( String str, String delim, boolean returnTokens )
Parameters
str
a string to be parsed.
delim
the delimiters.
returnTokens
flag indicating whether to return the delimiters as tokens.
Description
Constructs a string tokenizer for the specified string. The characters in the delim argument are the delimiters for separating tokens.

If the returnTokens flag is true, then the delimiter characters are also returned as tokens. Each delimiter is returned as a string of length one. If the flag is false, the delimiter characters are skipped and only serve as separators between tokens.

Syntax 2
public StringTokenizer( String str, String delim )
Parameters
str
a string to be parsed.
delim
the delimiters.
Description
Constructs a string tokenizer for the specified string. The characters in the delim argument are the delimiters for separating tokens.

Syntax 3
public StringTokenizer( String str )
Parameters
str
a string to be parsed.
Description
Constructs a string tokenizer for the specified string. The tokenizer uses the default delimiter set, which is "\t\n\r": the space character, the tab character, the newline character, and the carriage-return character.


 StringTokenizer.countTokens

StringTokenizer.countTokens

Class Overview | Class Members | This Package | All Packages

Syntax
public int countTokens()
Returns
the number of tokens remaining in the string using the current delimiter set.
Description
Calculates the number of times that this tokenizer's nextToken method can be called before it generates an exception.

See Also
nextToken


 StringTokenizer.hasMoreElements

StringTokenizer.hasMoreElements

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean hasMoreElements()
Returns
true if there are more tokens; false otherwise.
Description
Returns the same value as the hasMoreTokens method. It exists so that this class can implement the Enumeration interface.

See Also
Enumeration, hasMoreTokens


 StringTokenizer.hasMoreTokens

StringTokenizer.hasMoreTokens

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean hasMoreTokens()
Returns
true if there are more tokens available from this tokenizer's string; false otherwise.
Description
Tests if there are more tokens available from this tokenizer's string.


 StringTokenizer.nextElement

StringTokenizer.nextElement

Class Overview | Class Members | This Package | All Packages

Syntax
public Object nextElement()
Returns
the next token in the string.
Description
Returns the same value as the nextToken method, except that its declared return value is Object rather than String. It exists so that this class can implement the Enumeration interface.

Exceptions
NoSuchElementException if there are no more tokens in this tokenizer's string.
See Also
Enumeration, nextToken


 StringTokenizer.nextToken

StringTokenizer.nextToken

Class Overview | Class Members | This Package | All Packages

Syntax 1
public String nextToken()
Returns
the next token from this string tokenizer.
Description
Returns the next token from this string tokenizer.

Exceptions
NoSuchElementException if there are no more tokens in this tokenizer's string.

Syntax 2
public String nextToken( String delim )
Parameters
delim
the new delimiters.
Returns
the next token, after switching to the new delimiter set.
Description
Returns the next token in this string tokenizer's string. The new delimiter set remains the default after this call.

Exceptions
NoSuchElementException if there are no more tokens in this tokenizer's string.


 Class TimeZone

Class java.util.TimeZone

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.TimeZone

public abstract class TimeZone
extends Object
implements Serializable, Cloneable

TimeZone represents a time zone offset, and also figures out daylight savings.

Typically, you get a TimeZone using getDefault which creates a TimeZone based on the time zone where the program is running. For example, for a program running in Japan, getDefault creates a TimeZone object based on Japanese Standard Time.

You can also get a TimeZone using getTimeZone along with a time zone ID. For instance, the time zone ID for the Pacific Standard Time zone is "PST". So, you can get a PST TimeZone object with:

 TimeZone tz = TimeZone.getTimeZone("PST");
You can use getAvailableIDs method to iterate through all the supported time zone IDs. You can then choose a supported ID to get a favorite TimeZone.

See Also:
Calendar, GregorianCalendar, SimpleTimeZone


 TimeZone Members

TimeZone Members

Class Overview | This Package | All Packages

Constructors
Name | Description
TimeZone() |

Methods
Name | Description
clone() | Overrides Cloneable
getAvailableIDs() | Gets all the available IDs supported.
getAvailableIDs(int) | Gets the available IDs according to the given time zone offset.
getDefault() | Gets the default TimeZone for this host.
getID() | Gets the ID of this time zone.
getOffset(int, int, int, int, int, int) | Gets the time zone offset, for current date, modified in case of daylight savings.
getRawOffset() | Gets unmodified offset, NOT modified in case of daylight savings.
getTimeZone(String) | Gets the TimeZone for the given ID.
inDaylightTime(Date) | Queries if the given date is in Daylight Savings Time in this time zone.
setDefault(TimeZone) | Sets time zone to using the given TimeZone.
setID(String) | Sets the time zone ID.
setRawOffset(int) | Sets the base time zone offset to GMT.
useDaylightTime() | Queries if this time zone uses Daylight Savings Time.


 TimeZone.TimeZone

TimeZone.TimeZone

Class Overview | Class Members | This Package | All Packages

Syntax
public TimeZone()


 TimeZone.clone

TimeZone.clone

Class Overview | Class Members | This Package | All Packages

Syntax
public Object clone()
Description
Overrides Cloneable

Overrides
clone in class Object


 TimeZone.getAvailableIDs

TimeZone.getAvailableIDs

Class Overview | Class Members | This Package | All Packages

Syntax 1
public static synchronized String[] getAvailableIDs( int rawOffset )
Parameters
rawOffset
the given time zone GMT offset.
Returns
an array of IDs, where the time zone for that ID has the specified GMT offset. For example, {"Phoenix", "Denver"}, since both have GMT-07:00, but differ in daylight savings behavior.
Description
Gets the available IDs according to the given time zone offset.

Syntax 2
public static synchronized String[] getAvailableIDs()
Returns
an array of IDs.
Description
Gets all the available IDs supported.


 TimeZone.getDefault

TimeZone.getDefault

Class Overview | Class Members | This Package | All Packages

Syntax
public static synchronized TimeZone getDefault()
Returns
a default TimeZone.
Description
Gets the default TimeZone for this host.


 TimeZone.getID

TimeZone.getID

Class Overview | Class Members | This Package | All Packages

Syntax
public String getID()
Returns
the ID of this time zone.
Description
Gets the ID of this time zone.


 TimeZone.getOffset

TimeZone.getOffset

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract int getOffset( int era, int year, int month, int day, int dayOfWeek, int milliseconds )
Parameters
era
the era of the given date.
year
the year in the given date.
month
the month in the given date. Month is 0-based. e.g., 0 for January.
day
the day-in-month of the given date.
dayOfWeek
the day-of-week of the given date.
milliseconds
the millis in day.
Returns
the offset to add *to* GMT to get local time.
Description
Gets the time zone offset, for current date, modified in case of daylight savings. This is the offset to add *to* UTC to get local time.


 TimeZone.getRawOffset

TimeZone.getRawOffset

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract int getRawOffset()
Returns
the unmodified offset to add *to* UTC to get local time.
Description
Gets unmodified offset, NOT modified in case of daylight savings. This is the offset to add *to* UTC to get local time.


 TimeZone.getTimeZone

TimeZone.getTimeZone

Class Overview | Class Members | This Package | All Packages

Syntax
public static synchronized TimeZone getTimeZone( String ID )
Parameters
ID
the given ID.
Returns
a TimeZone.
Description
Gets the TimeZone for the given ID.


 TimeZone.inDaylightTime

TimeZone.inDaylightTime

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract boolean inDaylightTime( Date date )
Parameters
date
the given Date.
Returns
true if the given date is in Daylight Savings Time, false, otherwise.
Description
Queries if the given date is in Daylight Savings Time in this time zone.


 TimeZone.setDefault

TimeZone.setDefault

Class Overview | Class Members | This Package | All Packages

Syntax
public static synchronized void setDefault( TimeZone zone )
Parameters
zone
the given time zone.
Description
Sets time zone to using the given TimeZone.


 TimeZone.setID

TimeZone.setID

Class Overview | Class Members | This Package | All Packages

Syntax
public void setID( String ID )
Parameters
ID
the new time zone ID.
Description
Sets the time zone ID. This does not change any other data in the time zone object.


 TimeZone.setRawOffset

TimeZone.setRawOffset

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract void setRawOffset( int offsetMillis )
Parameters
offsetMillis
the given base time zone offset to GMT.
Description
Sets the base time zone offset to GMT. This is the offset to add *to* UTC to get local time.


 TimeZone.useDaylightTime

TimeZone.useDaylightTime

Class Overview | Class Members | This Package | All Packages

Syntax
public abstract boolean useDaylightTime()
Returns
true if this time zone uses Daylight Savings Time, false, otherwise.
Description
Queries if this time zone uses Daylight Savings Time.


 Class TooManyListenersException

Class java.util.TooManyListenersException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.util.TooManyListenersException

public class TooManyListenersException
extends Exception

The TooManyListenersException Exception is used as part of the Java Event model to annotate and implement a unicast special case of a multicast Event Source.

The presence of a throws TooManyListenersException clause on any given concrete implementation of the normally multicast semantic void add < EventListenerType > () event listener registration pattern is used to annotate that interface as implementing a unicast Listener special case, that is, that one and only one Listener may be registered on the particular event listener source concurrently.

See Also:
EventObject, EventListener


 TooManyListenersException Members

TooManyListenersException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
TooManyListenersException() | Constructs a TooManyListenersException with no detail message.
TooManyListenersException(String) | Constructs a TooManyListenersException with the specified detail message.


 TooManyListenersException.TooManyListenersException

TooManyListenersException.TooManyListenersException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public TooManyListenersException()
Description
Constructs a TooManyListenersException with no detail message. A detail message is a String that describes this particular exception.

Syntax 2
public TooManyListenersException( String s )
Parameters
s
the detail message
Description
Constructs a TooManyListenersException with the specified detail message. A detail message is a String that describes this particular exception.


 Class Vector

Class java.util.Vector

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.Vector

public class Vector
extends Object
implements Cloneable, Serializable

The Vector class implements a growable array of objects. Like an array, it contains components that can be accessed using an integer index. However, the size of a Vector can grow or shrink as needed to accommodate adding and removing items after the Vector has been created.

Each vector tries to optimize storage management by maintaining a capacity and a capacityIncrement. The capacity is always at least as large as the vector size; it is usually larger because as components are added to the vector, the vector's storage increases in chunks the size of capacityIncrement. An application can increase the capacity of a vector before inserting a large number of components; this reduces the amount of incremental reallocation.


 Vector Members

Vector Members

Class Overview | This Package | All Packages

Fields
Name | Description
capacityIncrement | The amount by which the capacity of the vector is automatically incremented when its size becomes greater than its capacity.
elementCount | The number of valid components in the vector.
elementData | The array buffer into which the components of the vector are stored.

Constructors
Name | Description
Vector() | Constructs an empty vector.
Vector(int) | Constructs an empty vector with the specified initial capacity.
Vector(int, int) | Constructs an empty vector with the specified initial capacity and capacity increment.

Methods
Name | Description
addElement(Object) | Adds the specified component to the end of this vector, increasing its size by one.
capacity() | Returns the current capacity of this vector.
clone() | Returns a clone of this vector.
contains(Object) | Tests if the specified object is a component in this vector.
copyInto(Object[]) | Copies the components of this vector into the specified array.
elementAt(int) | Returns the component at the specified index.
elements() | Returns an enumeration of the components of this vector.
ensureCapacity(int) | Increases the capacity of this vector, if necessary, to ensure that it can hold at least the number of components specified by the minimum capacity argument.
firstElement() | Returns the first component of this vector.
indexOf(Object) | Searches for the first occurence of the given argument, testing for equality using the equals method.
indexOf(Object, int) | Searches for the first occurence of the given argument, beginning the search at index, and testing for equality using the equals method.
insertElementAt(Object, int) | Inserts the specified object as a component in this vector at the specified index.
isEmpty() | Tests if this vector has no components.
lastElement() | Returns the last component of the vector.
lastIndexOf(Object) | Returns the index of the last occurrence of the specified object in this vector.
lastIndexOf(Object, int) | Searches backwards for the specified object, starting from the specified index, and returns an index to it.
removeAllElements() | Removes all components from this vector and sets its size to zero.
removeElement(Object) | Removes the first occurrence of the argument from this vector.
removeElementAt(int) | Deletes the component at the specified index.
setElementAt(Object, int) | Sets the component at the specified index of this vector to be the specified object.
setSize(int) | Sets the size of this vector.
size() | Returns the number of components in this vector.
toString() | Returns a string representation of this vector.
trimToSize() | Trims the capacity of this vector to be the vector's current size.


 Vector.capacityIncrement

Vector.capacityIncrement

Class Overview | Class Members | This Package | All Packages

Syntax
protected int capacityIncrement
Description
The amount by which the capacity of the vector is automatically incremented when its size becomes greater than its capacity. If the capacity is 0, the capacity of the vector is doubled each time it needs to grow.


 Vector.elementCount

Vector.elementCount

Class Overview | Class Members | This Package | All Packages

Syntax
protected int elementCount
Description
The number of valid components in the vector.


 Vector.elementData

Vector.elementData

Class Overview | Class Members | This Package | All Packages

Syntax
protected Object elementData[]
Description
The array buffer into which the components of the vector are stored. The capacity of the vector is the length of this array buffer.


 Vector.Vector

Vector.Vector

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Vector( int initialCapacity, int capacityIncrement )
Parameters
initialCapacity
the initial capacity of the vector.
capacityIncrement
the amount by which the capacity is increased when the vector overflows.
Description
Constructs an empty vector with the specified initial capacity and capacity increment.

Syntax 2
public Vector( int initialCapacity )
Parameters
initialCapacity
the initial capacity of the vector.
Description
Constructs an empty vector with the specified initial capacity.

Syntax 3
public Vector()
Description
Constructs an empty vector.


 Vector.addElement

Vector.addElement

Class Overview | Class Members | This Package | All Packages

Syntax
public final synchronized void addElement( Object obj )
Parameters
obj
the component to be added.
Description
Adds the specified component to the end of this vector, increasing its size by one. The capacity of this vector is increased if its size becomes greater than its capacity.


 Vector.capacity

Vector.capacity

Class Overview | Class Members | This Package | All Packages

Syntax
public final int capacity()
Returns
the current capacity of this vector.
Description
Returns the current capacity of this vector.


 Vector.clone

Vector.clone

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized Object clone()
Returns
a clone of this vector.
Description
Returns a clone of this vector.

Overrides
clone in class Object


 Vector.contains

Vector.contains

Class Overview | Class Members | This Package | All Packages

Syntax
public final boolean contains( Object elem )
Parameters
elem
an object.
Returns
true if the specified object is a component in this vector; false otherwise.
Description
Tests if the specified object is a component in this vector.


 Vector.copyInto

Vector.copyInto

Class Overview | Class Members | This Package | All Packages

Syntax
public final synchronized void copyInto( Object anArray[] )
Parameters
anArray
the array into which the components get copied.
Description
Copies the components of this vector into the specified array. The array must be big enough to hold all the objects in this vector.


 Vector.elementAt

Vector.elementAt

Class Overview | Class Members | This Package | All Packages

Syntax
public final synchronized Object elementAt( int index )
Parameters
index
an index into this vector.
Returns
the component at the specified index.
Description
Returns the component at the specified index.

Exceptions
ArrayIndexOutOfBoundsException if an invalid index was given.


 Vector.elements

Vector.elements

Class Overview | Class Members | This Package | All Packages

Syntax
public final synchronized Enumeration elements()
Returns
an enumeration of the components of this vector.
Description
Returns an enumeration of the components of this vector.

See Also
Enumeration


 Vector.ensureCapacity

Vector.ensureCapacity

Class Overview | Class Members | This Package | All Packages

Syntax
public final synchronized void ensureCapacity( int minCapacity )
Parameters
minCapacity
the desired minimum capacity.
Description
Increases the capacity of this vector, if necessary, to ensure that it can hold at least the number of components specified by the minimum capacity argument.


 Vector.firstElement

Vector.firstElement

Class Overview | Class Members | This Package | All Packages

Syntax
public final synchronized Object firstElement()
Returns
the first component of this vector.
Description
Returns the first component of this vector.

Exceptions
NoSuchElementException if this vector has no components.


 Vector.indexOf

Vector.indexOf

Class Overview | Class Members | This Package | All Packages

Syntax 1
public final int indexOf( Object elem )
Parameters
elem
an object.
Returns
the index of the first occurrence of the argument in this vector; returns -1 if the object is not found.
Description
Searches for the first occurence of the given argument, testing for equality using the equals method.

See Also
equals

Syntax 2
public final synchronized int indexOf( Object elem, int index )
Parameters
elem
an object.
index
the index to start searching from.
Returns
the index of the first occurrence of the object argument in this vector at position index or later in the vector; returns -1 if the object is not found.
Description
Searches for the first occurence of the given argument, beginning the search at index, and testing for equality using the equals method.

See Also
equals


 Vector.insertElementAt

Vector.insertElementAt

Class Overview | Class Members | This Package | All Packages

Syntax
public final synchronized void insertElementAt( Object obj, int index )
Parameters
obj
the component to insert.
index
where to insert the new component.
Description
Inserts the specified object as a component in this vector at the specified index. Each component in this vector with an index greater or equal to the specified index is shifted upward to have an index one greater than the value it had previously.

The index must be a value greater than or equal to 0 and less than or equal to the current size of the vector.

Exceptions
ArrayIndexOutOfBoundsException if the index was invalid.
See Also
size


 Vector.isEmpty

Vector.isEmpty

Class Overview | Class Members | This Package | All Packages

Syntax
public final boolean isEmpty()
Returns
true if this vector has no components; false otherwise.
Description
Tests if this vector has no components.


 Vector.lastElement

Vector.lastElement

Class Overview | Class Members | This Package | All Packages

Syntax
public final synchronized Object lastElement()
Returns
the last component of the vector, i.e., the component at index size() - 1.
Description
Returns the last component of the vector.

Exceptions
NoSuchElementException if this vector is empty.


 Vector.lastIndexOf

Vector.lastIndexOf

Class Overview | Class Members | This Package | All Packages

Syntax 1
public final int lastIndexOf( Object elem )
Parameters
elem
the desired component.
Returns
the index of the last occurrence of the specified object in this vector; returns -1 if the object is not found.
Description
Returns the index of the last occurrence of the specified object in this vector.

Syntax 2
public final synchronized int lastIndexOf( Object elem, int index )
Parameters
elem
the desired component.
index
the index to start searching from.
Returns
the index of the last occurrence of the specified object in this vector at position less than index in the vector; -1 if the object is not found.
Description
Searches backwards for the specified object, starting from the specified index, and returns an index to it.


 Vector.removeAllElements

Vector.removeAllElements

Class Overview | Class Members | This Package | All Packages

Syntax
public final synchronized void removeAllElements()
Description
Removes all components from this vector and sets its size to zero.


 Vector.removeElement

Vector.removeElement

Class Overview | Class Members | This Package | All Packages

Syntax
public final synchronized boolean removeElement( Object obj )
Parameters
obj
the component to be removed.
Returns
true if the argument was a component of this vector; false otherwise.
Description
Removes the first occurrence of the argument from this vector. If the object is found in this vector, each component in the vector with an index greater or equal to the object's index is shifted downward to have an index one smaller than the value it had previously.


 Vector.removeElementAt

Vector.removeElementAt

Class Overview | Class Members | This Package | All Packages

Syntax
public final synchronized void removeElementAt( int index )
Parameters
index
the index of the object to remove.
Description
Deletes the component at the specified index. Each component in this vector with an index greater or equal to the specified index is shifted downward to have an index one smaller than the value it had previously.

The index must be a value greater than or equal to 0 and less than the current size of the vector.

Exceptions
ArrayIndexOutOfBoundsException if the index was invalid.
See Also
size


 Vector.setElementAt

Vector.setElementAt

Class Overview | Class Members | This Package | All Packages

Syntax
public final synchronized void setElementAt( Object obj, int index )
Parameters
obj
what the component is to be set to.
index
the specified index.
Description
Sets the component at the specified index of this vector to be the specified object. The previous component at that position is discarded.

The index must be a value greater than or equal to 0 and less than the current size of the vector.

Exceptions
ArrayIndexOutOfBoundsException if the index was invalid.
See Also
size


 Vector.setSize

Vector.setSize

Class Overview | Class Members | This Package | All Packages

Syntax
public final synchronized void setSize( int newSize )
Parameters
newSize
the new size of this vector.
Description
Sets the size of this vector. If the new size is greater than the current size, new null items are added to the end of the vector. If the new size is less than the current size, all components at index newSize and greater are discarded.


 Vector.size

Vector.size

Class Overview | Class Members | This Package | All Packages

Syntax
public final int size()
Returns
the number of components in this vector.
Description
Returns the number of components in this vector.


 Vector.toString

Vector.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public final synchronized String toString()
Returns
a string representation of this vector.
Description
Returns a string representation of this vector.

Overrides
toString in class Object


 Vector.trimToSize

Vector.trimToSize

Class Overview | Class Members | This Package | All Packages

Syntax
public final synchronized void trimToSize()
Description
Trims the capacity of this vector to be the vector's current size. An application can use this operation to minimize the storage of a vector.


 Package java.util.zip

Package java.util.zip

All Packages

Interfaces

  • Checksum

    • Classes

  • Adler32
  • CRC32
  • CheckedInputStream
  • CheckedOutputStream
  • Deflater
  • DeflaterOutputStream
  • GZIPInputStream
  • GZIPOutputStream
  • Inflater
  • InflaterInputStream
  • ZipEntry
  • ZipFile
  • ZipInputStream
  • ZipOutputStream

    • Exceptions

  • DataFormatException
  • ZipException


 Class Adler32

Class java.util.zip.Adler32

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.zip.Adler32

public class Adler32
extends Object
implements Checksum

A class that can be used to compute the Adler-32 checksum of a data stream. An Adler-32 checksum is almost as reliable as a CRC-32 but can be computed much faster.

See Also:
Checksum


 Adler32 Members

Adler32 Members

Class Overview | This Package | All Packages

Constructors
Name | Description
Adler32() |

Methods
Name | Description
getValue() | Returns checksum value.
reset() | Resets checksum to initial value.
update(byte[]) | Updates checksum with specified array of bytes.
update(byte[], int, int) | Updates checksum with specified array of bytes.
update(int) | Updates checksum with specified byte.


 Adler32.Adler32

Adler32.Adler32

Class Overview | Class Members | This Package | All Packages

Syntax
public Adler32()


 Adler32.getValue

Adler32.getValue

Class Overview | Class Members | This Package | All Packages

Syntax
public long getValue()
Description
Returns checksum value.


 Adler32.reset

Adler32.reset

Class Overview | Class Members | This Package | All Packages

Syntax
public void reset()
Description
Resets checksum to initial value.


 Adler32.update

Adler32.update

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void update( int b )
Description
Updates checksum with specified byte.

Syntax 2
public native void update( byte b[], int off, int len )
Description
Updates checksum with specified array of bytes.

Syntax 3
public void update( byte b[] )
Description
Updates checksum with specified array of bytes.


 Class CRC32

Class java.util.zip.CRC32

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.zip.CRC32

public class CRC32
extends Object
implements Checksum

A class that can be used to compute the CRC-32 of a data stream.

See Also:
Checksum


 CRC32 Members

CRC32 Members

Class Overview | This Package | All Packages

Constructors
Name | Description
CRC32() |

Methods
Name | Description
getValue() | Returns CRC-32 value.
reset() | Resets CRC-32 to initial value.
update(byte[]) | Updates CRC-32 with specified array of bytes.
update(byte[], int, int) | Updates CRC-32 with specified array of bytes.
update(int) | Updates CRC-32 with specified byte.


 CRC32.CRC32

CRC32.CRC32

Class Overview | Class Members | This Package | All Packages

Syntax
public CRC32()


 CRC32.getValue

CRC32.getValue

Class Overview | Class Members | This Package | All Packages

Syntax
public long getValue()
Description
Returns CRC-32 value.


 CRC32.reset

CRC32.reset

Class Overview | Class Members | This Package | All Packages

Syntax
public void reset()
Description
Resets CRC-32 to initial value.


 CRC32.update

CRC32.update

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void update( int b )
Description
Updates CRC-32 with specified byte.

Syntax 2
public native void update( byte b[], int off, int len )
Description
Updates CRC-32 with specified array of bytes.

Syntax 3
public void update( byte b[] )
Description
Updates CRC-32 with specified array of bytes.


 Class CheckedInputStream

Class java.util.zip.CheckedInputStream

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.InputStream
           |
           +----java.io.FilterInputStream
                   |
                   +----java.util.zip.CheckedInputStream

public class CheckedInputStream
extends FilterInputStream

An input stream that also maintains a checksum of the data being read. The checksum can then be used to verify the integrity of the input data.

See Also:
Checksum


 CheckedInputStream Members

CheckedInputStream Members

Class Overview | This Package | All Packages

Constructors
Name | Description
CheckedInputStream(InputStream, Checksum) | Creates an input stream using the specified Checksum.

Methods
Name | Description
getChecksum() | Returns the Checksum for this input stream.
read() | Reads a byte.
read(byte[], int, int) | Reads into an array of bytes.
skip(long) | Skips specified number of bytes of input.


 CheckedInputStream.CheckedInputStream

CheckedInputStream.CheckedInputStream

Class Overview | Class Members | This Package | All Packages

Syntax
public CheckedInputStream( InputStream in, Checksum cksum )
Parameters
in
the input stream
cksum
the Checksum
Description
Creates an input stream using the specified Checksum.


 CheckedInputStream.getChecksum

CheckedInputStream.getChecksum

Class Overview | Class Members | This Package | All Packages

Syntax
public Checksum getChecksum()
Description
Returns the Checksum for this input stream.


 CheckedInputStream.read

CheckedInputStream.read

Class Overview | Class Members | This Package | All Packages

Syntax 1
public int read() throws IOException
Returns
the byte read, or -1 if the end of the stream is reached.
Description
Reads a byte. Will block if no input is available.

Exceptions
IOException if an I/O error has occurred
Overrides
read in class FilterInputStream

Syntax 2
public int read( byte buf[], int off, int len ) throws IOException
Parameters
buf
the buffer into which the data is read
off
the start offset of the data
len
the maximum number of bytes read
Returns
the actual number of bytes read, or -1 if the end of the stream is reached.
Description
Reads into an array of bytes. Will block until some input is available.

Exceptions
IOException if an I/O error has occurred
Overrides
read in class FilterInputStream


 CheckedInputStream.skip

CheckedInputStream.skip

Class Overview | Class Members | This Package | All Packages

Syntax
public long skip( long n ) throws IOException
Parameters
n
the number of bytes to skip
Returns
the actual number of bytes skipped
Description
Skips specified number of bytes of input.

Exceptions
IOException if an I/O error has occurred
Overrides
skip in class FilterInputStream


 Class CheckedOutputStream

Class java.util.zip.CheckedOutputStream

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.OutputStream
           |
           +----java.io.FilterOutputStream
                   |
                   +----java.util.zip.CheckedOutputStream

public class CheckedOutputStream
extends FilterOutputStream

An output stream that also maintains a checksum of the data being written. The checksum can then be used to verify the integrity of the output data.

See Also:
Checksum


 CheckedOutputStream Members

CheckedOutputStream Members

Class Overview | This Package | All Packages

Constructors
Name | Description
CheckedOutputStream(OutputStream, Checksum) | Creates an output stream with the specified Checksum.

Methods
Name | Description
getChecksum() | Returns the Checksum for this output stream.
write(byte[], int, int) | Writes an array of bytes.
write(int) | Writes a byte.


 CheckedOutputStream.CheckedOutputStream

CheckedOutputStream.CheckedOutputStream

Class Overview | Class Members | This Package | All Packages

Syntax
public CheckedOutputStream( OutputStream out, Checksum cksum )
Parameters
out
the output stream
cksum
the checksum
Description
Creates an output stream with the specified Checksum.


 CheckedOutputStream.getChecksum

CheckedOutputStream.getChecksum

Class Overview | Class Members | This Package | All Packages

Syntax
public Checksum getChecksum()
Description
Returns the Checksum for this output stream.


 CheckedOutputStream.write

CheckedOutputStream.write

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void write( int b ) throws IOException
Parameters
b
the byte to be written
Description
Writes a byte. Will block until the byte is actually written.

Exceptions
IOException if an I/O error has occurred
Overrides
write in class FilterOutputStream

Syntax 2
public void write( byte b[], int off, int len ) throws IOException
Parameters
buf
the data to be written
off
the start offset of the data
len
the number of bytes to be written
Description
Writes an array of bytes. Will block until the bytes are actually written.

Exceptions
IOException if an I/O error has occurred
Overrides
write in class FilterOutputStream


 Interface Checksum

Interface java.util.zip.Checksum

Interface Members | This Package | All Packages

public interface Checksum

An interface representing a data checksum.


 Checksum Members

Checksum Members

Interface Overview | This Package | All Packages

Methods
Name | Description
getValue() | Returns the current checksum value.
reset() | Resets the checksum to its initial value.
update(byte[], int, int) | Updates the current checksum with the specified array of bytes.
update(int) | Updates the current checksum with the specified byte.


 Checksum.getValue

Checksum.getValue

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract long getValue()
Description
Returns the current checksum value.


 Checksum.reset

Checksum.reset

Interface Overview | Interface Members | This Package | All Packages

Syntax
public abstract void reset()
Description
Resets the checksum to its initial value.


 Checksum.update

Checksum.update

Interface Overview | Interface Members | This Package | All Packages

Syntax 1
public abstract void update( int b )
Description
Updates the current checksum with the specified byte.

Syntax 2
public abstract void update( byte b[], int off, int len )
Description
Updates the current checksum with the specified array of bytes.


 Class DataFormatException

Class java.util.zip.DataFormatException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.util.zip.DataFormatException

public class DataFormatException
extends Exception

Signals that a data format error has occurred.


 DataFormatException Members

DataFormatException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
DataFormatException() | Constructs a DataFormatException with no detail message.
DataFormatException(String) | Constructs a DataFormatException with the specified detail message.


 DataFormatException.DataFormatException

DataFormatException.DataFormatException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public DataFormatException()
Description
Constructs a DataFormatException with no detail message.

Syntax 2
public DataFormatException( String s )
Parameters
s
the String containing a detail message
Description
Constructs a DataFormatException with the specified detail message. A detail message is a String that describes this particular exception.


 Class Deflater

Class java.util.zip.Deflater

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.zip.Deflater

public class Deflater
extends Object

This class provides support for general purpose decompression using the popular ZLIB compression library. The ZLIB compression library was initially developed as part of the PNG graphics standard and is not protected by patents. It is fully described in RFCs 1950, 1951, and 1952, which can be found at ftp://ds.internic.net/rfc in the files rfc1950.txt (zlib format), rfc1951.txt (deflate format) and rfc1952.txt (gzip format).

See Also:
Inflater


 Deflater Members

Deflater Members

Class Overview | This Package | All Packages

Fields
Name | Description
BEST_COMPRESSION | Compression level for best compression.
BEST_SPEED | Compression level for fastest compression.
DEFAULT_COMPRESSION | Default compression level.
DEFAULT_STRATEGY | Default compression strategy.
DEFLATED | Compression method for the deflate algorithm (the only one currently supported).
FILTERED | Compression strategy best used for data consisting mostly of small values with a somewhat random distribution.
HUFFMAN_ONLY | Compression strategy for Huffman coding only.
NO_COMPRESSION | Compression level for no compression.

Constructors
Name | Description
Deflater() | Creates a new compressor with the default compression level.
Deflater(int) | Creates a new compressor using the specified compression level.
Deflater(int, boolean) | Creates a new compressor using the specified compression level.

Methods
Name | Description
deflate(byte[]) | Fills specified buffer with compressed data.
deflate(byte[], int, int) | Fills specified buffer with compressed data.
end() | Discards unprocessed input and frees internal data.
finalize() | Frees the compressor when garbage is collected.
finish() | When called, indicates that compression should end with the current contents of the input buffer.
finished() | Returns true if the end of the compressed data output stream has been reached.
getAdler() | Returns the ADLER-32 value of the uncompressed data.
getTotalIn() | Returns the total number of bytes input so far.
getTotalOut() | Returns the total number of bytes output so far.
needsInput() | Returns true if the input data buffer is empty and setInput() should be called in order to provide more input.
reset() | Resets deflater so that a new set of input data can be processed.
setDictionary(byte[]) | Sets preset dictionary for compression.
setDictionary(byte[], int, int) | Sets preset dictionary for compression.
setInput(byte[]) | Sets input data for compression.
setInput(byte[], int, int) | Sets input data for compression.
setLevel(int) | Sets the current compression level to the specified value.
setStrategy(int) | Sets the compression strategy to the specified value.


 Deflater.BEST_COMPRESSION

Deflater.BEST_COMPRESSION

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int BEST_COMPRESSION
Description
Compression level for best compression.


 Deflater.BEST_SPEED

Deflater.BEST_SPEED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int BEST_SPEED
Description
Compression level for fastest compression.


 Deflater.DEFAULT_COMPRESSION

Deflater.DEFAULT_COMPRESSION

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int DEFAULT_COMPRESSION
Description
Default compression level.


 Deflater.DEFAULT_STRATEGY

Deflater.DEFAULT_STRATEGY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int DEFAULT_STRATEGY
Description
Default compression strategy.


 Deflater.DEFLATED

Deflater.DEFLATED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int DEFLATED
Description
Compression method for the deflate algorithm (the only one currently supported).


 Deflater.FILTERED

Deflater.FILTERED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int FILTERED
Description
Compression strategy best used for data consisting mostly of small values with a somewhat random distribution. Forces more Huffman coding and less string matching.


 Deflater.HUFFMAN_ONLY

Deflater.HUFFMAN_ONLY

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int HUFFMAN_ONLY
Description
Compression strategy for Huffman coding only.


 Deflater.NO_COMPRESSION

Deflater.NO_COMPRESSION

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int NO_COMPRESSION
Description
Compression level for no compression.


 Deflater.Deflater

Deflater.Deflater

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Deflater( int level, boolean nowrap )
Parameters
level
the compression level (0-9)
nowrap
if true then use GZIP compatible compression
Description
Creates a new compressor using the specified compression level. If 'nowrap' is true then the ZLIB header and checksum fields will not be used in order to support the compression format used in both GZIP and PKZIP.

Syntax 2
public Deflater( int level )
Parameters
level
the compression level (0-9)
Description
Creates a new compressor using the specified compression level. Compressed data will be generated in ZLIB format.

Syntax 3
public Deflater()
Description
Creates a new compressor with the default compression level. Compressed data will be generated in ZLIB format.


 Deflater.deflate

Deflater.deflate

Class Overview | Class Members | This Package | All Packages

Syntax 1
public native synchronized int deflate( byte b[], int off, int len )
Parameters
b
the buffer for the compressed data
off
the start offset of the data
len
the maximum number of bytes of compressed data
Returns
the actual number of bytes of compressed data
Description
Fills specified buffer with compressed data. Returns actual number of bytes of compressed data. A return value of 0 indicates that needsInput() should be called in order to determine if more input data is required.

Syntax 2
public int deflate( byte b[] )
Parameters
b
the buffer for the compressed data
Returns
the actual number of bytes of compressed data
Description
Fills specified buffer with compressed data. Returns actual number of bytes of compressed data. A return value of 0 indicates that needsInput() should be called in order to determine if more input data is required.


 Deflater.end

Deflater.end

Class Overview | Class Members | This Package | All Packages

Syntax
public native synchronized void end()
Description
Discards unprocessed input and frees internal data.


 Deflater.finalize

Deflater.finalize

Class Overview | Class Members | This Package | All Packages

Syntax
protected void finalize()
Description
Frees the compressor when garbage is collected.

Overrides
finalize in class Object


 Deflater.finish

Deflater.finish

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void finish()
Description
When called, indicates that compression should end with the current contents of the input buffer.


 Deflater.finished

Deflater.finished

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized boolean finished()
Description
Returns true if the end of the compressed data output stream has been reached.


 Deflater.getAdler

Deflater.getAdler

Class Overview | Class Members | This Package | All Packages

Syntax
public native synchronized int getAdler()
Description
Returns the ADLER-32 value of the uncompressed data.


 Deflater.getTotalIn

Deflater.getTotalIn

Class Overview | Class Members | This Package | All Packages

Syntax
public native synchronized int getTotalIn()
Description
Returns the total number of bytes input so far.


 Deflater.getTotalOut

Deflater.getTotalOut

Class Overview | Class Members | This Package | All Packages

Syntax
public native synchronized int getTotalOut()
Description
Returns the total number of bytes output so far.


 Deflater.needsInput

Deflater.needsInput

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean needsInput()
Description
Returns true if the input data buffer is empty and setInput() should be called in order to provide more input.


 Deflater.reset

Deflater.reset

Class Overview | Class Members | This Package | All Packages

Syntax
public native synchronized void reset()
Description
Resets deflater so that a new set of input data can be processed. Keeps current compression level and strategy settings.


 Deflater.setDictionary

Deflater.setDictionary

Class Overview | Class Members | This Package | All Packages

Syntax 1
public native synchronized void setDictionary( byte b[], int off, int len )
Parameters
b
the dictionary data bytes
off
the start offset of the data
len
the length of the data
Description
Sets preset dictionary for compression. A preset dictionary is used when the history buffer can be predetermined. When the data is later uncompressed with Inflater.inflate(), Inflater.getAdler() can be called in order to get the Adler-32 value of the dictionary required for decompression.

See Also
inflate, getAdler

Syntax 2
public void setDictionary( byte b[] )
Parameters
b
the dictionary data bytes
Description
Sets preset dictionary for compression. A preset dictionary is used when the history buffer can be predetermined. When the data is later uncompressed with Inflater.inflate(), Inflater.getAdler() can be called in order to get the Adler-32 value of the dictionary required for decompression.

See Also
inflate, getAdler


 Deflater.setInput

Deflater.setInput

Class Overview | Class Members | This Package | All Packages

Syntax 1
public synchronized void setInput( byte b[], int off, int len )
Parameters
b
the input data bytes
off
the start offset of the data
len
the length of the data
Description
Sets input data for compression. This should be called whenever needsInput() returns true indicating that more input data is required.

See Also
needsInput

Syntax 2
public void setInput( byte b[] )
Parameters
b
the input data bytes
Description
Sets input data for compression. This should be called whenever needsInput() returns true indicating that more input data is required.

See Also
needsInput


 Deflater.setLevel

Deflater.setLevel

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setLevel( int Level )
Parameters
level
the new compression level (0-9)
Description
Sets the current compression level to the specified value.

Exceptions
IllegalArgumentException if the compression level is invalid


 Deflater.setStrategy

Deflater.setStrategy

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void setStrategy( int strategy )
Parameters
strategy
the new compression strategy
Description
Sets the compression strategy to the specified value.

Exceptions
IllegalArgumentException if the compression strategy is invalid


 Class DeflaterOutputStream

Class java.util.zip.DeflaterOutputStream

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.OutputStream
           |
           +----java.io.FilterOutputStream
                   |
                   +----java.util.zip.DeflaterOutputStream

public class DeflaterOutputStream
extends FilterOutputStream

This class implements an output stream filter for compressing data in the "deflate" compression format. It is also used as the basis for other types of compression filters, such as GZIPOutputStream.

See Also:
Deflater


 DeflaterOutputStream Members

DeflaterOutputStream Members

Class Overview | This Package | All Packages

Fields
Name | Description
buf | Output buffer for writing compressed data.
def | Compressor for this stream.

Constructors
Name | Description
DeflaterOutputStream(OutputStream) | Creates a new output stream with a defaul compressor and buffer size.
DeflaterOutputStream(OutputStream, Deflater) | Creates a new output stream with the specified compressor and a default buffer size.
DeflaterOutputStream(OutputStream, Deflater, int) | Creates a new output stream with the specified compressor and buffer size.

Methods
Name | Description
close() | Writes remaining compressed data to the output stream and closes the underlying stream.
deflate() | Writes next block of compressed data to the output stream.
finish() | Finishes writing compressed data to the output stream without closing the underlying stream.
write(byte[], int, int) | Writes an array of bytes to the compressed output stream.
write(int) | Writes a byte to the compressed output stream.


 DeflaterOutputStream.buf

DeflaterOutputStream.buf

Class Overview | Class Members | This Package | All Packages

Syntax
protected byte buf[]
Description
Output buffer for writing compressed data.


 DeflaterOutputStream.def

DeflaterOutputStream.def

Class Overview | Class Members | This Package | All Packages

Syntax
protected Deflater def
Description
Compressor for this stream.


 DeflaterOutputStream.DeflaterOutputStream

DeflaterOutputStream.DeflaterOutputStream

Class Overview | Class Members | This Package | All Packages

Syntax 1
public DeflaterOutputStream( OutputStream out, Deflater def, int size )
Parameters
out
the output stream
def
the compressor ("deflater")
len
the output buffer size
Description
Creates a new output stream with the specified compressor and buffer size.

Syntax 2
public DeflaterOutputStream( OutputStream out, Deflater def )
Parameters
out
the output stream
def
the compressor ("deflater")
Description
Creates a new output stream with the specified compressor and a default buffer size.

Syntax 3
public DeflaterOutputStream( OutputStream out )
Description
Creates a new output stream with a defaul compressor and buffer size.


 DeflaterOutputStream.close

DeflaterOutputStream.close

Class Overview | Class Members | This Package | All Packages

Syntax
public void close() throws IOException
Description
Writes remaining compressed data to the output stream and closes the underlying stream.

Exceptions
IOException if an I/O error has occurred
Overrides
close in class FilterOutputStream


 DeflaterOutputStream.deflate

DeflaterOutputStream.deflate

Class Overview | Class Members | This Package | All Packages

Syntax
protected void deflate() throws IOException
Description
Writes next block of compressed data to the output stream.


 DeflaterOutputStream.finish

DeflaterOutputStream.finish

Class Overview | Class Members | This Package | All Packages

Syntax
public void finish() throws IOException
Description
Finishes writing compressed data to the output stream without closing the underlying stream. Use this method when applying multiple filters in succession to the same output stream.

Exceptions
IOException if an I/O error has occurred


 DeflaterOutputStream.write

DeflaterOutputStream.write

Class Overview | Class Members | This Package | All Packages

Syntax 1
public void write( int b ) throws IOException
Parameters
b
the byte to be written
Description
Writes a byte to the compressed output stream. This method will block until the byte can be written.

Exceptions
IOException if an I/O error has occurred
Overrides
write in class FilterOutputStream

Syntax 2
public void write( byte b[], int off, int len ) throws IOException
Parameters
buf
the data to be written
off
the start offset of the data
len
the length of the data
Description
Writes an array of bytes to the compressed output stream. This method will block until all the bytes are written.

Exceptions
IOException if an I/O error has occurred
Overrides
write in class FilterOutputStream


 Class GZIPInputStream

Class java.util.zip.GZIPInputStream

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.InputStream
           |
           +----java.io.FilterInputStream
                   |
                   +----java.util.zip.InflaterInputStream
                           |
                           +----java.util.zip.GZIPInputStream

public class GZIPInputStream
extends InflaterInputStream

This class implements a stream filter for reading compressed data in the GZIP format.

See Also:
InflaterInputStream


 GZIPInputStream Members

GZIPInputStream Members

Class Overview | This Package | All Packages

Fields
Name | Description
crc | CRC-32 for uncompressed data.
eos | Indicates end of input stream.
GZIP_MAGIC | GZIP header magic number.

Constructors
Name | Description
GZIPInputStream(InputStream) | Creates a new input stream with a default buffer size.
GZIPInputStream(InputStream, int) | Creates a new input stream with the specified buffer size.

Methods
Name | Description
close() | Closes the input stream.
read(byte[], int, int) | Reads uncompressed data into an array of bytes.


 GZIPInputStream.crc

GZIPInputStream.crc

Class Overview | Class Members | This Package | All Packages

Syntax
protected CRC32 crc
Description
CRC-32 for uncompressed data.


 GZIPInputStream.eos

GZIPInputStream.eos

Class Overview | Class Members | This Package | All Packages

Syntax
protected boolean eos
Description
Indicates end of input stream.


 GZIPInputStream.GZIP_MAGIC

GZIPInputStream.GZIP_MAGIC

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int GZIP_MAGIC
Description
GZIP header magic number.


 GZIPInputStream.GZIPInputStream

GZIPInputStream.GZIPInputStream

Class Overview | Class Members | This Package | All Packages

Syntax 1
public GZIPInputStream( InputStream in, int size ) throws IOException
Parameters
in
the input stream
size
the input buffer size
Description
Creates a new input stream with the specified buffer size.

Exceptions
IOException if an I/O error has occurred

Syntax 2
public GZIPInputStream( InputStream in ) throws IOException
Parameters
in
the input stream
Description
Creates a new input stream with a default buffer size.

Exceptions
IOException if an I/O error has occurred


 GZIPInputStream.close

GZIPInputStream.close

Class Overview | Class Members | This Package | All Packages

Syntax
public void close() throws IOException
Description
Closes the input stream.

Exceptions
IOException if an I/O error has occurred
Overrides
close in class FilterInputStream


 GZIPInputStream.read

GZIPInputStream.read

Class Overview | Class Members | This Package | All Packages

Syntax
public int read( byte buf[], int off, int len ) throws IOException
Parameters
buf
the buffer into which the data is read
off
the start offset of the data
len
the maximum number of bytes read
Returns
the actual number of bytes read, or -1 if the end of the compressed input stream is reached
Description
Reads uncompressed data into an array of bytes. Blocks until enough input is available for decompression.

Exceptions
IOException if an I/O error has occurred or the compressed input data is corrupt
Overrides
read in class InflaterInputStream


 Class GZIPOutputStream

Class java.util.zip.GZIPOutputStream

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.OutputStream
           |
           +----java.io.FilterOutputStream
                   |
                   +----java.util.zip.DeflaterOutputStream
                           |
                           +----java.util.zip.GZIPOutputStream

public class GZIPOutputStream
extends DeflaterOutputStream

This class implements a stream filter for writing compressed data in the GZIP file format.


 GZIPOutputStream Members

GZIPOutputStream Members

Class Overview | This Package | All Packages

Fields
Name | Description
crc | CRC-32 of uncompressed data.

Constructors
Name | Description
GZIPOutputStream(OutputStream) | Creates a new output stream with a default buffer size.
GZIPOutputStream(OutputStream, int) | Creates a new output stream with the specified buffer size.

Methods
Name | Description
close() | Writes remaining compressed data to the output stream and closes the underlying stream.
finish() | Finishes writing compressed data to the output stream without closing the underlying stream.
write(byte[], int, int) | Writes array of bytes to the compressed output stream.


 GZIPOutputStream.crc

GZIPOutputStream.crc

Class Overview | Class Members | This Package | All Packages

Syntax
protected CRC32 crc
Description
CRC-32 of uncompressed data.


 GZIPOutputStream.GZIPOutputStream

GZIPOutputStream.GZIPOutputStream

Class Overview | Class Members | This Package | All Packages

Syntax 1
public GZIPOutputStream( OutputStream out, int size ) throws IOException
Parameters
out
the output stream
size
the output buffer size
Description
Creates a new output stream with the specified buffer size.

Exceptions
IOException If an I/O error has occurred.

Syntax 2
public GZIPOutputStream( OutputStream out ) throws IOException
Parameters
out
the output stream
Description
Creates a new output stream with a default buffer size.

Exceptions
IOException If an I/O error has occurred.


 GZIPOutputStream.close

GZIPOutputStream.close

Class Overview | Class Members | This Package | All Packages

Syntax
public void close() throws IOException
Description
Writes remaining compressed data to the output stream and closes the underlying stream.

Exceptions
IOException if an I/O error has occurred
Overrides
close in class DeflaterOutputStream


 GZIPOutputStream.finish

GZIPOutputStream.finish

Class Overview | Class Members | This Package | All Packages

Syntax
public void finish() throws IOException
Description
Finishes writing compressed data to the output stream without closing the underlying stream. Use this method when applying multiple filters in succession to the same output stream.

Exceptions
IOException if an I/O error has occurred
Overrides
finish in class DeflaterOutputStream


 GZIPOutputStream.write

GZIPOutputStream.write

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void write( byte buf[], int off, int len ) throws IOException
Parameters
buf
the data to be written
off
the start offset of the data
len
the length of the data
Description
Writes array of bytes to the compressed output stream. This method will block until all the bytes are written.

Exceptions
IOException If an I/O error has occurred.
Overrides
write in class DeflaterOutputStream


 Class Inflater

Class java.util.zip.Inflater

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.zip.Inflater

public class Inflater
extends Object

This class provides support for general purpose decompression using the popular ZLIB compression library. The ZLIB compression library was initially developed as part of the PNG graphics standard and is not protected by patents. It is fully described in RFCs 1950, 1951, and 1952, which can be found at ftp://ds.internic.net/rfc in the files rfc1950.txt (zlib format), rfc1951.txt (deflate format) and rfc1952.txt (gzip format).

See Also:
Deflater


 Inflater Members

Inflater Members

Class Overview | This Package | All Packages

Constructors
Name | Description
Inflater() | Creates a new decompressor.
Inflater(boolean) | Creates a new decompressor.

Methods
Name | Description
end() | Discards unprocessed input and frees internal data.
finalize() | Frees the decompressor when garbage is collected.
finished() | Return true if the end of the compressed data stream has been reached.
getAdler() | Returns the ADLER-32 value of the uncompressed data.
getRemaining() | Returns the total number of bytes remaining in the input buffer.
getTotalIn() | Returns the total number of bytes input so far.
getTotalOut() | Returns the total number of bytes output so far.
inflate(byte[]) | Uncompresses bytes into specified buffer.
inflate(byte[], int, int) | Uncompresses bytes into specified buffer.
needsDictionary() | Returns true if a preset dictionary is needed for decompression.
needsInput() | Returns true if no data remains in the input buffer.
reset() | Resets inflater so that a new set of input data can be processed.
setDictionary(byte[]) | Sets the preset dictionary to the given array of bytes.
setDictionary(byte[], int, int) | Sets the preset dictionary to the given array of bytes.
setInput(byte[]) | Sets input data for decompression.
setInput(byte[], int, int) | Sets input data for decompression.


 Inflater.Inflater

Inflater.Inflater

Class Overview | Class Members | This Package | All Packages

Syntax 1
public Inflater( boolean nowrap )
Parameters
nowrap
if true then support GZIP compatible compression
Description
Creates a new decompressor. If the parameter 'nowrap' is true then the ZLIB header and checksum fields will not be used in order to support the compression format used by both GZIP and PKZIP.

Syntax 2
public Inflater()
Description
Creates a new decompressor.


 Inflater.end

Inflater.end

Class Overview | Class Members | This Package | All Packages

Syntax
public native synchronized void end()
Description
Discards unprocessed input and frees internal data.


 Inflater.finalize

Inflater.finalize

Class Overview | Class Members | This Package | All Packages

Syntax
protected void finalize()
Description
Frees the decompressor when garbage is collected.

Overrides
finalize in class Object


 Inflater.finished

Inflater.finished

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized boolean finished()
Description
Return true if the end of the compressed data stream has been reached.


 Inflater.getAdler

Inflater.getAdler

Class Overview | Class Members | This Package | All Packages

Syntax
public native synchronized int getAdler()
Description
Returns the ADLER-32 value of the uncompressed data.


 Inflater.getRemaining

Inflater.getRemaining

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized int getRemaining()
Description
Returns the total number of bytes remaining in the input buffer. This can be used to find out what bytes still remain in the input buffer after decompression has finished.


 Inflater.getTotalIn

Inflater.getTotalIn

Class Overview | Class Members | This Package | All Packages

Syntax
public native synchronized int getTotalIn()
Description
Returns the total number of bytes input so far.


 Inflater.getTotalOut

Inflater.getTotalOut

Class Overview | Class Members | This Package | All Packages

Syntax
public native synchronized int getTotalOut()
Description
Returns the total number of bytes output so far.


 Inflater.inflate

Inflater.inflate

Class Overview | Class Members | This Package | All Packages

Syntax 1
public native synchronized int inflate( byte b[], int off, int len ) throws DataFormatException
Parameters
b
the buffer for the uncompressed data
off
the start offset of the data
len
the maximum number of uncompressed bytes
Returns
the actual number of uncompressed bytes
Description
Uncompresses bytes into specified buffer. Returns actual number of bytes uncompressed. A return value of 0 indicates that needsInput() or needsDictionary() should be called in order to determine if more input data or a preset dictionary is required. In the later case, getAdler() can be used to get the Adler-32 value of the dictionary required.

Exceptions
DataFormatException if the compressed data format is invalid
See Also
needsInput, needsDictionary

Syntax 2
public int inflate( byte b[] ) throws DataFormatException
Parameters
b
the buffer for the uncompressed data
Returns
the actual number of uncompressed bytes
Description
Uncompresses bytes into specified buffer. Returns actual number of bytes uncompressed. A return value of 0 indicates that needsInput() or needsDictionary() should be called in order to determine if more input data or a preset dictionary is required. In the later case, getAdler() can be used to get the Adler-32 value of the dictionary required.

Exceptions
DataFormatException if the compressed data format is invalid
See Also
needsInput, needsDictionary


 Inflater.needsDictionary

Inflater.needsDictionary

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized boolean needsDictionary()
Description
Returns true if a preset dictionary is needed for decompression.

See Also
InflatesetDictionary


 Inflater.needsInput

Inflater.needsInput

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized boolean needsInput()
Description
Returns true if no data remains in the input buffer. This can be used to determine if #setInput should be called in order to provide more input.


 Inflater.reset

Inflater.reset

Class Overview | Class Members | This Package | All Packages

Syntax
public native synchronized void reset()
Description
Resets inflater so that a new set of input data can be processed.


 Inflater.setDictionary

Inflater.setDictionary

Class Overview | Class Members | This Package | All Packages

Syntax 1
public native synchronized void setDictionary( byte b[], int off, int len )
Parameters
b
the dictionary data bytes
off
the start offset of the data
len
the length of the data
Description
Sets the preset dictionary to the given array of bytes. Should be called when inflate() returns 0 and needsDictionary() returns true indicating that a preset dictionary is required. The method getAdler() can be used to get the Adler-32 value of the dictionary needed.

See Also
needsDictionary, getAdler

Syntax 2
public void setDictionary( byte b[] )
Parameters
b
the dictionary data bytes
Description
Sets the preset dictionary to the given array of bytes. Should be called when inflate() returns 0 and needsDictionary() returns true indicating that a preset dictionary is required. The method getAdler() can be used to get the Adler-32 value of the dictionary needed.

See Also
needsDictionary, getAdler


 Inflater.setInput

Inflater.setInput

Class Overview | Class Members | This Package | All Packages

Syntax 1
public synchronized void setInput( byte b[], int off, int len )
Parameters
b
the input data bytes
off
the start offset of the input data
len
the length of the input data
Description
Sets input data for decompression. Should be called whenever needsInput() returns true indicating that more input data is required.

See Also
needsInput

Syntax 2
public void setInput( byte b[] )
Parameters
b
the input data bytes
Description
Sets input data for decompression. Should be called whenever needsInput() returns true indicating that more input data is required.

See Also
needsInput


 Class InflaterInputStream

Class java.util.zip.InflaterInputStream

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.InputStream
           |
           +----java.io.FilterInputStream
                   |
                   +----java.util.zip.InflaterInputStream

public class InflaterInputStream
extends FilterInputStream

This class implements a stream filter for uncompressing data in the "deflate" compression format. It is also used as the basis for other decompression filters, such as GZIPInputStream.

See Also:
Inflater


 InflaterInputStream Members

InflaterInputStream Members

Class Overview | This Package | All Packages

Fields
Name | Description
buf | Input buffer for decompression.
inf | Decompressor for this stream.
len | Length of input buffer.

Constructors
Name | Description
InflaterInputStream(InputStream) | Creates a new input stream with a default decompressor and buffer size.
InflaterInputStream(InputStream, Inflater) | Creates a new input stream with the specified decompressor and a default buffer size.
InflaterInputStream(InputStream, Inflater, int) | Creates a new input stream with the specified decompressor and buffer size.

Methods
Name | Description
fill() | Fills input buffer with more data to decompress.
read() | Reads a byte of uncompressed data.
read(byte[], int, int) | Reads uncompressed data into an array of bytes.
skip(long) | Skips specified number of bytes of uncompressed data.


 InflaterInputStream.buf

InflaterInputStream.buf

Class Overview | Class Members | This Package | All Packages

Syntax
protected byte buf[]
Description
Input buffer for decompression.


 InflaterInputStream.inf

InflaterInputStream.inf

Class Overview | Class Members | This Package | All Packages

Syntax
protected Inflater inf
Description
Decompressor for this stream.


 InflaterInputStream.len

InflaterInputStream.len

Class Overview | Class Members | This Package | All Packages

Syntax
protected int len
Description
Length of input buffer.


 InflaterInputStream.InflaterInputStream

InflaterInputStream.InflaterInputStream

Class Overview | Class Members | This Package | All Packages

Syntax 1
public InflaterInputStream( InputStream in, Inflater inf, int size )
Parameters
in
the input stream
inf
the decompressor ("inflater")
len
the input buffer size
Description
Creates a new input stream with the specified decompressor and buffer size.

Syntax 2
public InflaterInputStream( InputStream in, Inflater inf )
Parameters
in
the input stream
inf
the decompressor ("inflater")
Description
Creates a new input stream with the specified decompressor and a default buffer size.

Syntax 3
public InflaterInputStream( InputStream in )
Description
Creates a new input stream with a default decompressor and buffer size.


 InflaterInputStream.fill

InflaterInputStream.fill

Class Overview | Class Members | This Package | All Packages

Syntax
protected void fill() throws IOException
Description
Fills input buffer with more data to decompress.

Exceptions
IOException if an I/O error has occurred


 InflaterInputStream.read

InflaterInputStream.read

Class Overview | Class Members | This Package | All Packages

Syntax 1
public int read() throws IOException
Returns
the byte read, or -1 if end of compressed input is reached
Description
Reads a byte of uncompressed data. This method will block until enough input is available for decompression.

Exceptions
IOException if an I/O error has occurred
Overrides
read in class FilterInputStream

Syntax 2
public int read( byte b[], int off, int len ) throws IOException
Parameters
b
the buffer into which the data is read
off
the start offset of the data
len
the maximum number of bytes read
Returns
the actual number of bytes read, or -1 if the end of the compressed input is reached or a preset dictionary is needed
Description
Reads uncompressed data into an array of bytes. This method will block until some input can be decompressed.

Exceptions
ZipException if a ZIP format error has occurred
Exceptions
IOException if an I/O error has occurred
Overrides
read in class FilterInputStream


 InflaterInputStream.skip

InflaterInputStream.skip

Class Overview | Class Members | This Package | All Packages

Syntax
public long skip( long n ) throws IOException
Parameters
n
the number of bytes to skip
Returns
the actual number of bytes skipped.
Description
Skips specified number of bytes of uncompressed data.

Exceptions
IOException if an I/O error has occurred
Overrides
skip in class FilterInputStream


 Class ZipEntry

Class java.util.zip.ZipEntry

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.zip.ZipEntry

public class ZipEntry
extends Object
implements ZipConstants

This class is used to represent a ZIP file entry.


 ZipEntry Members

ZipEntry Members

Class Overview | This Package | All Packages

Fields
Name | Description
DEFLATED | Compression method for compressed (deflated) entries.
STORED | Compression method for uncompressed entries.

Constructors
Name | Description
ZipEntry(String) | Creates a new ZIP file entry with the specified name.

Methods
Name | Description
getComment() | Returns the comment string for the entry, or null if none.
getCompressedSize() | Returns the compressed size of the entry data, or -1 if not known.
getCrc() | Returns the CRC-32 checksum of the uncompressed entry data, or -1 if not known.
getExtra() | Returns the extra field data for the entry, or null if none.
getMethod() | Returns the compression method of the entry, or -1 if not specified.
getName() | Returns the name of the entry.
getSize() | Returns the uncompressed size of the entry data, or -1 if not known.
getTime() | Returns the modification time of the entry, or -1 if not specified.
isDirectory() | Returns true if this is a directory entry.
setComment(String) | Sets the optional comment string for the entry.
setCrc(long) | Sets the CRC-32 checksum of the uncompressed entry data.
setExtra(byte[]) | Sets the optional extra field data for the entry.
setMethod(int) | Sets the compression method for the entry.
setSize(long) | Sets the uncompressed size of the entry data.
setTime(long) | Sets the modification time of the entry.
toString() | Returns a string representation of the ZIP entry.


 ZipEntry.DEFLATED

ZipEntry.DEFLATED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int DEFLATED
Description
Compression method for compressed (deflated) entries.


 ZipEntry.STORED

ZipEntry.STORED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int STORED
Description
Compression method for uncompressed entries.


 ZipEntry.ZipEntry

ZipEntry.ZipEntry

Class Overview | Class Members | This Package | All Packages

Syntax
public ZipEntry( String name )
Parameters
name
the entry name
Description
Creates a new ZIP file entry with the specified name.

Exceptions
NullPointerException if the entry name is null
Exceptions
IllegalArgumentException if the entry name is longer than 0xFFFF bytes


 ZipEntry.getComment

ZipEntry.getComment

Class Overview | Class Members | This Package | All Packages

Syntax
public String getComment()
Description
Returns the comment string for the entry, or null if none.


 ZipEntry.getCompressedSize

ZipEntry.getCompressedSize

Class Overview | Class Members | This Package | All Packages

Syntax
public long getCompressedSize()
Description
Returns the compressed size of the entry data, or -1 if not known. In the case of a stored entry, the compressed size will be the same as the uncompressed size of the entry.


 ZipEntry.getCrc

ZipEntry.getCrc

Class Overview | Class Members | This Package | All Packages

Syntax
public long getCrc()
Description
Returns the CRC-32 checksum of the uncompressed entry data, or -1 if not known.


 ZipEntry.getExtra

ZipEntry.getExtra

Class Overview | Class Members | This Package | All Packages

Syntax
public byte[] getExtra()
Description
Returns the extra field data for the entry, or null if none.


 ZipEntry.getMethod

ZipEntry.getMethod

Class Overview | Class Members | This Package | All Packages

Syntax
public int getMethod()
Description
Returns the compression method of the entry, or -1 if not specified.


 ZipEntry.getName

ZipEntry.getName

Class Overview | Class Members | This Package | All Packages

Syntax
public String getName()
Description
Returns the name of the entry.


 ZipEntry.getSize

ZipEntry.getSize

Class Overview | Class Members | This Package | All Packages

Syntax
public long getSize()
Description
Returns the uncompressed size of the entry data, or -1 if not known.


 ZipEntry.getTime

ZipEntry.getTime

Class Overview | Class Members | This Package | All Packages

Syntax
public long getTime()
Description
Returns the modification time of the entry, or -1 if not specified.


 ZipEntry.isDirectory

ZipEntry.isDirectory

Class Overview | Class Members | This Package | All Packages

Syntax
public boolean isDirectory()
Description
Returns true if this is a directory entry. A directory entry is defined to be one whose name ends with a '/'.


 ZipEntry.setComment

ZipEntry.setComment

Class Overview | Class Members | This Package | All Packages

Syntax
public void setComment( String comment )
Parameters
comment
the comment string
Description
Sets the optional comment string for the entry.

Exceptions
IllegalArgumentException if the length of the specified comment string is greater than 0xFFFF bytes


 ZipEntry.setCrc

ZipEntry.setCrc

Class Overview | Class Members | This Package | All Packages

Syntax
public void setCrc( long crc )
Parameters
crc
the CRC-32 value
Description
Sets the CRC-32 checksum of the uncompressed entry data.

Exceptions
IllegalArgumentException if the specified CRC-32 value is less than 0 or greater than 0xFFFFFFFF


 ZipEntry.setExtra

ZipEntry.setExtra

Class Overview | Class Members | This Package | All Packages

Syntax
public void setExtra( byte extra[] )
Parameters
extra
the extra field data bytes
Description
Sets the optional extra field data for the entry.

Exceptions
IllegalArgumentException if the length of the specified extra field data is greater than 0xFFFFF bytes


 ZipEntry.setMethod

ZipEntry.setMethod

Class Overview | Class Members | This Package | All Packages

Syntax
public void setMethod( int method )
Parameters
method
the compression method, either STORED or DEFLATED
Description
Sets the compression method for the entry.

Exceptions
IllegalArgumentException if the specified compression method is invalid


 ZipEntry.setSize

ZipEntry.setSize

Class Overview | Class Members | This Package | All Packages

Syntax
public void setSize( long size )
Parameters
size
the uncompressed size in bytes
Description
Sets the uncompressed size of the entry data.

Exceptions
IllegalArgumentException if the specified size is less than 0 or greater than 0xFFFFFFFF bytes


 ZipEntry.setTime

ZipEntry.setTime

Class Overview | Class Members | This Package | All Packages

Syntax
public void setTime( long time )
Parameters
time
the entry modification time in number of milliseconds since the epoch
Description
Sets the modification time of the entry.


 ZipEntry.toString

ZipEntry.toString

Class Overview | Class Members | This Package | All Packages

Syntax
public String toString()
Description
Returns a string representation of the ZIP entry.

Overrides
toString in class Object


 Class ZipException

Class java.util.zip.ZipException

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.lang.Throwable
           |
           +----java.lang.Exception
                   |
                   +----java.io.IOException
                           |
                           +----java.util.zip.ZipException

public class ZipException
extends IOException


 ZipException Members

ZipException Members

Class Overview | This Package | All Packages

Constructors
Name | Description
ZipException() |
ZipException(String) |


 ZipException.ZipException

ZipException.ZipException

Class Overview | Class Members | This Package | All Packages

Syntax 1
public ZipException()

Syntax 2
public ZipException( String s )


 Class ZipFile

Class java.util.zip.ZipFile

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.util.zip.ZipFile

public class ZipFile
extends Object
implements ZipConstants

This class can be used to read the contents of a ZIP file. It uses RandomAccessFile for quick access to ZIP file entries, and supports both compressed and uncompressed entries.


 ZipFile Members

ZipFile Members

Class Overview | This Package | All Packages

Constructors
Name | Description
ZipFile(File) | Opens a ZIP file for reading given the specified File object.
ZipFile(String) | Opens a ZIP file for reading given the specified file name.

Methods
Name | Description
close() | Closes the ZIP file.
entries() | Returns an enumeration of the ZIP file entries.
getEntry(String) | Returns the ZIP file entry for the given path name.
getInputStream(ZipEntry) | Returns an input stream for reading the contents of the specified ZIP file entry.
getName() | Returns the path name of the ZIP file.


 ZipFile.ZipFile

ZipFile.ZipFile

Class Overview | Class Members | This Package | All Packages

Syntax 1
public ZipFile( String name ) throws IOException
Parameters
name
the name of the zip file
Description
Opens a ZIP file for reading given the specified file name.

Exceptions
ZipException if a ZIP format error has occurred
Exceptions
IOException if an I/O error has occurred

Syntax 2
public ZipFile( File file ) throws ZipException, IOException
Parameters
file
the ZIP file to be opened for reading
Description
Opens a ZIP file for reading given the specified File object.

Exceptions
ZipException if a ZIP error has occurred
Exceptions
IOException if an I/O error has occurred


 ZipFile.close

ZipFile.close

Class Overview | Class Members | This Package | All Packages

Syntax
public void close() throws IOException
Description
Closes the ZIP file.


 ZipFile.entries

ZipFile.entries

Class Overview | Class Members | This Package | All Packages

Syntax
public Enumeration entries()
Description
Returns an enumeration of the ZIP file entries.


 ZipFile.getEntry

ZipFile.getEntry

Class Overview | Class Members | This Package | All Packages

Syntax
public ZipEntry getEntry( String name )
Parameters
name
the name of the entry
Returns
the ZIP file entry
Description
Returns the ZIP file entry for the given path name. Returns null if there is no entry corresponding to the given name.


 ZipFile.getInputStream

ZipFile.getInputStream

Class Overview | Class Members | This Package | All Packages

Syntax
public InputStream getInputStream( ZipEntry ze ) throws IOException
Parameters
ze
the zip file entry
Description
Returns an input stream for reading the contents of the specified ZIP file entry.

Exceptions
ZipException if a ZIP format error has occurred
Exceptions
IOException if an I/O error has occurred


 ZipFile.getName

ZipFile.getName

Class Overview | Class Members | This Package | All Packages

Syntax
public String getName()
Description
Returns the path name of the ZIP file.


 Class ZipInputStream

Class java.util.zip.ZipInputStream

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.InputStream
           |
           +----java.io.FilterInputStream
                   |
                   +----java.util.zip.InflaterInputStream
                           |
                           +----java.util.zip.ZipInputStream

public class ZipInputStream
extends InflaterInputStream
implements ZipConstants

This class implements an input stream filter for reading files in the ZIP file format. Includes support for both compressed and uncompressed entries.


 ZipInputStream Members

ZipInputStream Members

Class Overview | This Package | All Packages

Constructors
Name | Description
ZipInputStream(InputStream) | Creates a new ZIP input stream.

Methods
Name | Description
close() | Closes the ZIP input stream.
closeEntry() | Closes the current ZIP entry and positions the stream for reading the next entry.
getNextEntry() | Reads the next ZIP file entry and positions stream at the beginning of the entry data.
read(byte[], int, int) | Reads from the current ZIP entry into an array of bytes.
skip(long) | Skips specified number of bytes in the current ZIP entry.


 ZipInputStream.ZipInputStream

ZipInputStream.ZipInputStream

Class Overview | Class Members | This Package | All Packages

Syntax
public ZipInputStream( InputStream in )
Parameters
in
the actual input stream
Description
Creates a new ZIP input stream.


 ZipInputStream.close

ZipInputStream.close

Class Overview | Class Members | This Package | All Packages

Syntax
public void close() throws IOException
Description
Closes the ZIP input stream.

Exceptions
IOException if an I/O error has occurred
Overrides
close in class FilterInputStream


 ZipInputStream.closeEntry

ZipInputStream.closeEntry

Class Overview | Class Members | This Package | All Packages

Syntax
public void closeEntry() throws IOException
Description
Closes the current ZIP entry and positions the stream for reading the next entry.

Exceptions
ZipException if a ZIP file error has occurred
Exceptions
IOException if an I/O error has occurred


 ZipInputStream.getNextEntry

ZipInputStream.getNextEntry

Class Overview | Class Members | This Package | All Packages

Syntax
public ZipEntry getNextEntry() throws IOException
Description
Reads the next ZIP file entry and positions stream at the beginning of the entry data.

Exceptions
ZipException if a ZIP file error has occurred
Exceptions
IOException if an I/O error has occurred


 ZipInputStream.read

ZipInputStream.read

Class Overview | Class Members | This Package | All Packages

Syntax
public int read( byte b[], int off, int len ) throws IOException
Parameters
b
the buffer into which the data is read
off
the start offset of the data
len
the maximum number of bytes read
Returns
the actual number of bytes read, or -1 if the end of the entry is reached
Description
Reads from the current ZIP entry into an array of bytes. Blocks until some input is available.

Exceptions
ZipException if a ZIP file error has occurred
Exceptions
IOException if an I/O error has occurred
Overrides
read in class InflaterInputStream


 ZipInputStream.skip

ZipInputStream.skip

Class Overview | Class Members | This Package | All Packages

Syntax
public long skip( long n ) throws IOException
Parameters
n
the number of bytes to skip
Returns
the actual number of bytes skipped
Description
Skips specified number of bytes in the current ZIP entry.

Exceptions
ZipException if a ZIP file error has occurred
Exceptions
IOException if an I/O error has occurred
Overrides
skip in class InflaterInputStream


 Class ZipOutputStream

Class java.util.zip.ZipOutputStream

Class Members | This Package | All Packages
java.lang.Object
   |
   +----java.io.OutputStream
           |
           +----java.io.FilterOutputStream
                   |
                   +----java.util.zip.DeflaterOutputStream
                           |
                           +----java.util.zip.ZipOutputStream

public class ZipOutputStream
extends DeflaterOutputStream
implements ZipConstants

This class implements an output stream filter for writing files in the ZIP file format. Includes support for both compressed and uncompressed entries.


 ZipOutputStream Members

ZipOutputStream Members

Class Overview | This Package | All Packages

Fields
Name | Description
DEFLATED | Compression method for compressed (DEFLATED) entries.
STORED | Compression method for uncompressed (STORED) entries.

Constructors
Name | Description
ZipOutputStream(OutputStream) | Creates a new ZIP output stream.

Methods
Name | Description
close() | Closes the ZIP output stream as well as the stream being filtered.
closeEntry() | Closes the current ZIP entry and positions the stream for writing the next entry.
finish() | Finishes writing the contents of the ZIP output stream without closing the underlying stream.
putNextEntry(ZipEntry) | Begins writing a new ZIP file entry and positions the stream to the start of the entry data.
setComment(String) | Sets the ZIP file comment.
setLevel(int) | Sets the compression level for subsequent entries which are DEFLATED.
setMethod(int) | Sets the default compression method for subsequent entries.
write(byte[], int, int) | Writes an array of bytes to the current ZIP entry data.


 ZipOutputStream.DEFLATED

ZipOutputStream.DEFLATED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int DEFLATED
Description
Compression method for compressed (DEFLATED) entries.


 ZipOutputStream.STORED

ZipOutputStream.STORED

Class Overview | Class Members | This Package | All Packages

Syntax
public static final int STORED
Description
Compression method for uncompressed (STORED) entries.


 ZipOutputStream.ZipOutputStream

ZipOutputStream.ZipOutputStream

Class Overview | Class Members | This Package | All Packages

Syntax
public ZipOutputStream( OutputStream out )
Parameters
out
the actual output stream
Description
Creates a new ZIP output stream.


 ZipOutputStream.close

ZipOutputStream.close

Class Overview | Class Members | This Package | All Packages

Syntax
public void close() throws IOException
Description
Closes the ZIP output stream as well as the stream being filtered.

Exceptions
ZipException if a ZIP file error has occurred
Exceptions
IOException if an I/O error has occurred
Overrides
close in class DeflaterOutputStream


 ZipOutputStream.closeEntry

ZipOutputStream.closeEntry

Class Overview | Class Members | This Package | All Packages

Syntax
public void closeEntry() throws IOException
Description
Closes the current ZIP entry and positions the stream for writing the next entry.

Exceptions
ZipException if a ZIP format error has occurred
Exceptions
IOException if an I/O error has occurred


 ZipOutputStream.finish

ZipOutputStream.finish

Class Overview | Class Members | This Package | All Packages

Syntax
public void finish() throws IOException
Description
Finishes writing the contents of the ZIP output stream without closing the underlying stream. Use this method when applying multiple filters in succession to the same output stream.

Exceptions
ZipException if a ZIP file error has occurred
Exceptions
IOException if an I/O exception has occurred
Overrides
finish in class DeflaterOutputStream


 ZipOutputStream.putNextEntry

ZipOutputStream.putNextEntry

Class Overview | Class Members | This Package | All Packages

Syntax
public void putNextEntry( ZipEntry e ) throws IOException
Parameters
e
the ZIP entry to be written
Description
Begins writing a new ZIP file entry and positions the stream to the start of the entry data. Closes the current entry if still active. The default compression method will be used if no compression method was specified for the entry, and the current time will be used if the entry has no set modification time.

Exceptions
ZipException if a ZIP format error has occurred
Exceptions
IOException if an I/O error has occurred


 ZipOutputStream.setComment

ZipOutputStream.setComment

Class Overview | Class Members | This Package | All Packages

Syntax
public void setComment( String comment )
Parameters
comment
the comment string
Description
Sets the ZIP file comment.

Exceptions
IllegalArgumentException if the length of the specified ZIP file comment is greater than 0xFFFF bytes


 ZipOutputStream.setLevel

ZipOutputStream.setLevel

Class Overview | Class Members | This Package | All Packages

Syntax
public void setLevel( int level )
Parameters
level
the compression level (0-9)
Description
Sets the compression level for subsequent entries which are DEFLATED. The default setting is DEFAULT_COMPRESSION.

Exceptions
IllegalArgumentException if the compression level is invalid


 ZipOutputStream.setMethod

ZipOutputStream.setMethod

Class Overview | Class Members | This Package | All Packages

Syntax
public void setMethod( int method )
Parameters
method
the default compression method
Description
Sets the default compression method for subsequent entries. This default will be used whenever the compression method is not specified for an individual ZIP file entry, and is initially set to DEFLATED.

Exceptions
IllegalArgumentException if the specified compression method is invalid


 ZipOutputStream.write

ZipOutputStream.write

Class Overview | Class Members | This Package | All Packages

Syntax
public synchronized void write( byte b[], int off, int len ) throws IOException
Parameters
b
the data to be written
off
the start offset in the data
len
the number of bytes that are written
Description
Writes an array of bytes to the current ZIP entry data. This method will block until all the bytes are written.

Exceptions
ZipException if a ZIP file error has occurred
Exceptions
IOException if an I/O error has occurred
Overrides
write in class DeflaterOutputStream


Java Language Specification

The Java Language Specification

Version 1.0

James Gosling
Bill Joy
Guy Steele

"When I use a word," Humpty Dumpty said,
in rather a scornful tone, "it means just what I
choose it to mean—neither more nor less."
"The question is," said Alice, "whether you
can make words mean so many different things."
"The question is," said Humpty Dumpty,
"which is to be master—that's all."
—Lewis Carroll, Through the Looking Glass


Copyright

RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the United States Government is subject to the restrictions set forth in DFARS 252.227-7013 (c)(1)(ii) and FAR 52.227-19.

The release described in this manual may be protected by one or more U.S. patents, foreign patents, or pending applications.

Sun Microsystems, Inc. (SUN) hereby grants to you a fully-paid, nonexclusive, nontransferable, perpetual, worldwide limited license (without the right to sublicense) under SUN's intellectual property rights that are essential to practice this specification. This license allows and is limited to the creation and distribution of clean room implementations of this specification that (i) include a complete implementation of the current version of this specification without subsetting or supersetting, (ii) implement all the interfaces and functionality of the standard java.* packages as defined by SUN, without subsetting or supersetting, (iii) do not add any additional packages, classes or methods to the java.* packages (iv) pass all test suites relating to the most recent published version of this specification that are available from SUN six (6) months prior to any beta release of the clean room implementation or upgrade thereto, (v) do not derive from SUN source code or binary materials, and (vi) do not include any SUN binary materials without an appropriate and separate license from SUN.

Sun, Sun Microsystems, Sun Microsystems Computer Corporation, the Sun logo, the Sun Microsystems Computer Corporation logo, Java, JavaSoft, JavaScript and HotJava are trademarks or registered trademarks of Sun Microsystems, Inc. UNIX® is a registered trademark in the United States and other countries, exclusively licensed through X/Open Company, Ltd. Apple and Dylan are trademarks of Apple Computer, Inc. All other product names mentioned herein are the trademarks of their respective owners.

THIS PUBLICATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.

THIS PUBLICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THE PUBLICATION. SUN MICROSYSTEMS, INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS PUBLICATION AT ANY TIME.

Credits and permissions for quoted material appear in a separate section on page 823.

ISBN 0-201-63451-1
1 2 3 4 5 6 7 8 9-MA-99989796
First printing, August 1996


Series Foreword

The Java Series books provide definitive reference documentation for Java programmers and end users. They are written by members of the Java team and published under the auspices of JavaSoft, a Sun Microsystems business. The World- Wide-Web allows Java documentation to be made available over the Internet, either by downloading or as hypertext. Nevertheless, the world-wide interest in Java technology led us to write and publish these books to supplement all of the documentation at our Web site

To learn the latest about the Java Platform and Environment or download the latest Java release, visit our World Wide Web site at http://java.sun.com/. For updated information about the Java Series, including sample code, errata, and previews of forthcoming books, visit http://java.sun.com/Series/.

We would like to thank the Corporate and Professional Publishing Group at Addison-Wesley for their partnership in putting together the Series. Our editor Mike Hendrickson and his team have done a superb job of navigating us through the world of publishing. Within Sun Microsystems, the support of James Gosling, Jon Kannegaard, and Bill Joy ensured that this series would have the resources it needed to be successful. In addition to the tremendous effort by individual authors, many members of the JavaSoft team have contributed behind the scenes to bring the highest level of quality and engineering to the books in the Series. A personal note of thanks to my children Christopher and James for putting a positive spin on the many trips to my office during the development of the Series.

Lisa Friendly
Series Editor


Preface

Java was originally called Oak, and designed for use in embedded consumer- electronic applications by James Gosling. After several years of experience with the language, and significant contributions by Ed Frank, Patrick Naughton, Jonathan Payne, and Chris Warth it was retargeted to the Internet, renamed Java, and substantially revised to be the language specified here. The final form of the language was defined by James Gosling, Bill Joy, Guy Steele, Richard Tuck, Frank Yellin, and Arthur van Hoff, with help from Graham Hamilton, Tim Lindholm and many other friends and colleagues.

Java is a general-purpose concurrent class-based object-oriented programming language, specifically designed to have as few implementation dependencies as possible. Java allows application developers to write a program once and then be able to run it everywhere on the Internet.

This book attempts a complete specification of the syntax and semantics of the Java language and the core packages java.lang, java.io, and java.util of its Application Programming Interface. We intend that the behavior of every language construct is specified here, so that all implementations of Java will accept the same programs. Except for timing dependencies or other non-determinisms and given sufficient time and sufficient memory space, a Java program should compute the same result on all machines and in all implementations.

We believe that Java is a mature language, ready for widespread use. Nevertheless, we expect some evolution of the language in the years to come. We intend to manage this evolution in a way that is completely compatible with existing applications. To do this, we intend to make relatively few new versions of the language, and to distinguish each new version with a different filename extension. Java compilers and systems will be able to support the several versions simultannously, with complete compatibility.

Much research and experimentation with Java is already underway. We encourage this work, and will continue to cooperate with external groups to explore improvements to Java. For example, we have already received several interesting proposals for parameterized types. In technically difficult areas, near the state of the art, this kind of research collaboration is essential.

We acknowledge and thank the many people who have contributed to this book through their excellent feedback, assistance and encouragement:

Particularly thorough, careful, and thoughtful reviews of drafts were provided by Tom Cargill, Peter Deutsch, Paul Hilfinger, Masayuki Ida, David Moon, Steven Muchnick, Charles L. Perkins, Chris Van Wyk, Steve Vinoski, Philip Wadler, Daniel Weinreb, and Kenneth Zadeck. We are very grateful for their extraordinary volunteer efforts.

We are also grateful for reviews, questions, comments, and suggestions from Stephen Adams, Bowen Alpern, Glenn Ammons, Leonid Arbuzov, Kim Bruce, Edwin Chan, David Chase, Pavel Curtis, Drew Dean, William Dietz, David Dill, Patrick Dussud, Ed Felten, John Giannandrea, John Gilmore, Charles Gust, Warren Harris, Lee Hasiuk, Mike Hendrickson, Mark Hill, Urs Hoelzle, Roger Hoover, Susan Flynn Hummel, Christopher Jang, Mick Jordan, Mukesh Kacker, Peter Kessler, James Larus, Derek Lieber, Bill McKeeman, Steve Naroff, Evi Nemeth, Robert O'Callahan, Dave Papay, Craig Partridge, Scott Pfeffer, Eric Raymond, Jim Roskind, Jim Russell, William Scherlis, Edith Schonberg, Anthony Scian, Matthew Self, Janice Shepherd, Kathy Stark, Barbara Steele, Rob Strom, William Waite, Greg Weeks, and Bob Wilson. (This list was generated semi-automatically from our e-mail records. We apologize if we have omitted anyone.)

The feedback from all these reviewers was invaluable to us in improving the definition of the Java language as well as the form of the presentation in this book. We thank them for their diligence. Any remaining errors in this book-we hope they are few-are our responsibility and not theirs.

We thank Francesca Freedman for assistance with matters of typography and layout. We thank Dan Mills of Adobe Systems Incorporated for assistance in exploring possible choices of typefaces.

Many of our colleagues at Sun Microsystems have helped us in one way or another. Lisa Friendly, our series editor, managed our relationship with Addison-Wesley. Susan Stambaugh managed the distribution of many hundreds of copies of drafts to reviewers. We received valuable assistance and technical advice from Ben Adida, Ole Agesen, Ken Arnold, Rick Cattell, Asmus Freytag, Norm Hardy, Steve Heller, David Hough, Doug Kramer, Nancy Lee, Marianne Mueller, Akira Tanaka, Greg Tarsy, David Ungar, Jim Waldo, Ann Wollrath, Geoff Wyant, and Derek White. We thank Alan Baratz, David Bowen, Mike Clary, John Doerr, Jon Kannegaard, Eric Schmidt, Bob Sproull, Bert Sutherland, and Scott McNealy for leadership and encouragement.

The on-line Bartleby Library of Columbia University, at URL:

http://www.cc.columbia.edu/acis/bartleby/

was invaluable to us during the process of researching and verifying many of the quotations that are scattered throughout this book. Here is one example:

They lard their lean books with the fat of others' works.
—Robert Burton (1576-1640)

We are grateful to those who have toiled on Project Bartleby, for saving us a great deal of effort and reawakening our appreciation for the works of Walt Whitman.

We are thankful for the tools and services we had at our disposal in writing this book: telephones, overnight delivery, desktop workstations, laser printers, photocopiers, text formatting and page layout software, fonts, electronic mail, the World Wide Web, and, of course, the Internet. We live in three different states, scattered across a continent, but collaboration with each other and with our reviewers has seemed almost effortless. Kudos to the thousands of people who have worked over the years to make these excellent tools and services work quickly and reliably.

Mike Hendrickson, Katie Duffy, Simone Payment, and Rosa Aimée González of Addison-Wesley were very helpful, encouraging, and patient during the long process of bringing this book to print. We also thank the copy editors.

Rosemary Simpson worked hard, on a very tight schedule, to create the index. We got into the act at the last minute, however; blame us and not her for any jokes you may find hidden therein.

Finally, we are grateful to our families and friends. Life has been a bit crazy for us these last few months and we thank these good people for their support.

In their book The C Programming Language, Brian Kernighan and Dennis Ritchie said that they felt that the C language "wears well as one's experience with it grows." If you like C, we think you will like Java. We hope that Java, too, wears well for you.

James Gosling
Cupertino, California

Bill Joy
Aspen, Colorado

Guy Steele
Chelmsford, Massachusetts

July, 1996


1. Introduction

CHAPTER 1

Introduction

If I have seen further it is by standing upon the shoulders of Giants.
—Sir Isaac Newton

Java is a general-purpose, concurrent, class-based, object-oriented language. It is designed to be simple enough that many programmers can achieve fluency in the language. Java is related to C and C++ but is organized rather differently, with a number of aspects of C and C++ omitted and a few ideas from other languages included. Java is intended to be a production language, not a research language, and so, as C. A. R. Hoare suggested in his classic paper on language design, the design of Java has avoided including new and untested features.

Java is strongly typed. This specification clearly distinguishes between the compile-time errors that can and must be detected, and those that occur at run time. Compile time normally consists of translating Java programs into a machine-independent byte-code representation. Run-time activities include loading and linking of the classes needed to execute a program, optional machine code generation and dynamic optimization of the program, and actual program execution.

Java is a relatively high-level language, in that details of the machine representation are not available through the language. It includes automatic storage management, typically using a garbage collector, to avoid the safety problems of explicit deallocation (as in C's free or C++'s delete). High-performance garbage-collected implementations of Java can have bounded pauses to support systems programming and real-time applications. Java does not include any unsafe constructs, such as array accesses without index checking, since such unsafe constructs would cause a program to behave in an unspecified way.

Java is normally compiled to a bytecoded instruction set and binary format defined in The Java Virtual Machine Specification (Addison-Wesley, 1996). Most implementations of Java for general-purpose programming will support the additional packages defined in the series of books under the general title The Java Application Programming Interface (Addison-Wesley).

This Java Language Specification is organized as follows:

Chapter 2 describes grammars and the notation used to present the lexical and syntactic grammars for Java.

Chapter 3 describes the lexical structure of Java, which is based on C and C++. Java is written in the Unicode character set. Java supports the writing of Unicode characters on systems that support only ASCII.

Chapter 4 describes Java's types, values, and variables. Java's types are the primitive types and reference types.

The primitive types are defined to be the same on all machines and in all implementations, and are various sizes of two's-complement integers, single- and double-precision IEEE 754 standard floating-point numbers, a boolean type, and a Unicode character char type. Values of the primitive types do not share state.

Java's reference types are the class types, the interface types, and the array types. The reference types are implemented by dynamically created objects that are either instances of classes or arrays. Many references to each object can exist. All objects (including arrays) support the methods of the standard class Object, which is the (single) root of the class hierarchy. A predefined String class supports Unicode character strings. Standard classes exist for wrapping primitive values inside of objects.

Variables are typed storage locations. A variable of a primitive type holds a value of that exact primitive type. A variable of a class type can hold a null reference or a reference to an object whose type is that class type or any subclass of that class type. A variable of an interface type can hold a null reference or a reference to an instance of any class that implements the interface. A variable of an array type can hold a null reference or a reference to an array. A variable of class type Object can hold a null reference or a reference to any object, whether class instance or array.

Chapter 5 describes Java's conversions and numeric promotions. Conversions change the compile-time type and, sometimes, the value of an expression. Numeric promotions are used to convert the operands of a numeric operator to a common type where an operation can be performed. There are no loopholes in the language; casts on reference types are checked at run time to ensure type safety.

Chapter 6 describes declarations and names, and how to determine what names mean (denote). Java does not require types or their members to be declared before they are used. Declaration order is significant only for local variables and the order of initializers of fields in a class or interface.

Java provides control over the scope of names and supports limitations on external access to members of packages, classes, and interfaces. This helps in writing large programs by distinguishing the implementation of a type from its users and those who extend it. Standard naming conventions that make for more readable programs are described here.

Chapter 7 describes the structure of a Java program, which is organized into packages similar to the modules of Modula. The members of a package are compilation units and subpackages. Compilation units contain type declarations and can import types from other packages to give them short names. Packages have names in a hierarchical namespace, and the Internet domain name system can be used to form unique package names.

Chapter 8 describes Java's classes. The members of classes are fields (variables) and methods. Class variables exist once per class. Class methods operate without reference to a specific object. Instance variables are dynamically created in objects that are instances of classes. Instance methods are invoked on instances of classes; such instances become the current object this during their execution, supporting the object-oriented programming style.

Classes support single implementation inheritance, in which the implementation of each class is derived from that of a single superclass, and ultimately from the class Object. Variables of a class type can reference an instance of that class or of any subclass of that class, allowing new types to be used with existing methods, polymorphically.

Classes support concurrent programming with synchronized methods. Methods declare the checked exceptions that can arise from their execution, which allows compile-time checking to ensure that exceptional conditions are handled. Objects can declare a finalize method that will be invoked before the objects are discarded by the garbage collector, allowing the objects to clean up their state.

For simplicity, Java has neither declaration "headers" separate from the implementation of a class nor separate type and class hierarchies.

Although Java does not include parameterized classes, the semantics of arrays are those of a parameterized class with some syntactic sugar. Like the programming language Beta, Java uses a run-time type check when storing references in arrays to ensure complete type safety.

Chapter 9 describes Java's interface types, which declare a set of abstract methods and constants. Classes that are otherwise unrelated can implement the same interface type. A variable of an interface type can contain a reference to any object that implements the interface. Multiple interface inheritance is supported.

Chapter 10 describes Java arrays. Array accesses include bounds checking. Arrays are dynamically created objects and may be assigned to variables of type Object. Java supports arrays of arrays, rather than multidimensional arrays.

Chapter 11 describes Java's exceptions, which are nonresuming and fully integrated with the language semantics and concurrency mechanisms. There are three kinds of exceptions: checked exceptions, run-time exceptions, and errors. The compiler ensures that checked exceptions are properly handled by requiring that a method or constructor can result in a checked exception only if it declares it. This provides compile-time checking that exception handlers exist, and aids programming in the large. Most user-defined exceptions should be checked exceptions. Invalid operations in the program detected by the Java Virtual Machine result in run-time exceptions, such as NullPointerException. Errors result from failures detected by the virtual machine, such as OutOfMemoryError. Most simple programs do not try to handle errors.

Chapter 12 describes activities that occur during execution of a Java program. A Java program is normally stored as binary files representing compiled classes and interfaces. These binary files can be loaded into a Java Virtual Machine, linked to other classes and interfaces, and initialized.

After initialization, class methods and class variables may be used. Some classes may be instantiated to create new objects of the class type. Objects that are class instances also contain an instance of each superclass of the class, and object creation involves recursive creation of these superclass instances.

When an object is no longer referenced, it may be reclaimed by the garbage collector. If an object declares a finalizer, the finalizer is executed before the object is reclaimed to give the object a last chance to clean up resources that would not otherwise be released. When a class is no longer needed, it may be unloaded; if a class finalizer is declared, it is given a chance to clean up first. Objects and classes may be finalized on exit of the Java Virtual Machine.

Chapter 13 describes binary compatibility, specifying the impact of changes to types on other types that use the changed types but have not been recompiled. These considerations are of interest to developers of types that are to be widely distributed, in a continuing series of versions, often through the Internet. Good program development environments automatically recompile dependent code whenever a type is changed, so most programmers need not be concerned about these details.

Chapter 14 describes Java's blocks and statements, which are based on C and C++. Java has no goto, but includes labeled break and continue statements. Unlike C, Java requires boolean expressions in control-flow statements, and does not convert types to boolean implicitly, in the hope of catching more errors at compile time. A synchronized statement provides basic object-level monitor locking. A try statement can include catch and finally clauses to protect against non-local control transfers.

Chapter 15 describes Java's expressions. Java fully specifies the (apparent) order of evaluation of expressions, for increased determinism and portability. Overloaded methods and constructors are resolved at compile time by picking the most specific method or constructor from those which are applicable. Java chooses which method or constructor by using the same basic algorithm used in languages with richer dispatching, such as CLOS and Dylan, for the future.

Chapter 16 describes the precise way in which Java ensures that local variables are definitely set before use. While all other variables are automatically initialized to a default value, Java does not automatically initialize local variables in order to avoid masking programming errors.

Chapter 17 describes the semantics of Java threads and locks, which are based on the monitor-based concurrency originally introduced with the Mesa programming language. Java specifies a memory model for shared-memory multiprocessors that supports high-performance implementations.

Chapter 18 describes the facilities for automatically generating documentation from special comments in Java source code.

Chapter 19 presents a LALR(1) syntactic grammar for Java, and describes the differences between this grammar and the expository grammar used in the body of the language specification that precedes it.

Chapters 20 through 22 are the reference manual for the core of the standard Java Application Programming Interface. These packages must be included in all general purpose Java systems.

Chapter 20 describes the package java.lang. The types defined in java.lang are automatically imported to be available without qualification in all Java programs. They include the primordial class Object, which is a superclass of all other classes; classes such as Integer and Float, which wrap the primitive types inside objects; exceptions and errors defined by the language and the Java Virtual Machine; Thread support; metalinguistic classes such as Class and ClassLoader; and the class System, which abstracts the host system.

Chapter 21 describes the package java.util, which defines a few basic utility classes, such as a hashtable class and a pseudo-random number generator.

Chapter 22 describes the package java.io, which defines basic input/output facilities, including random access files and streams of values of primitive types.

The book concludes with two indexes: one for the types, methods, and fields defined and described in this specification, and the other a more traditional index.


1.1 Example Programs

Most of the example programs given in the text are ready to be executed by a Java system and are similar in form to:

class Test {
    public static void main(String[] args) {
        for (int i = 0; i < args.length; i++)
            System.out.print(i == 0 ? args[i] : " " + args[i]);
        System.out.println();
    }
}

On a Sun workstation, this class, stored in the file Test.java, can be compiled and executed by giving the commands:

javac Test.java
java Test Hello, world.

producing the output:

Hello, world.


1.2 References

Apple Computer. Dylan Reference Manual. Apple Computer Inc., Cupertino, California. September 29, 1995. See also http://www.cambridge.apple.com/.

Bobrow, Daniel G., Linda G. DeMichiel, Richard P. Gabriel, Sonya E. Keene, Gregor Kiczales, and David A. Moon. Common Lisp Object System Specification, X3J13 Document 88-002R, June 1988; appears as Chapter 28 of Steele, Guy. Common Lisp: The Language, 2nd ed. Digital Press, 1990, ISBN 1-55558-041-6, 770-864.

Ellis, Margaret A., and Bjarne Stroustrup. The Annotated C++ Reference Manual. Addison-Wesley, Reading, Massachusetts, 1990, reprinted with corrections October 1992, ISBN 0-201-51459-1.

Harbison, Samuel. Modula-3. Prentice Hall, Englewood Cliffs, New Jersey, 1992, ISBN 0-13-596396.

Hoare, C. A. R. Hints on Programming Language Design. Stanford University Computer Science Department Technical Report No. CS-73-403, December 1973. Reprinted in SIGACT/SIGPLAN Symposium on Principles of Programming Languages. Association for Computing Machinery, New York, October 1973.

IEEE Standard for Binary Floating-Point Arithmetic. ANSI/IEEE Std. 754-1985. Available from Global Engineering Documents, 15 Inverness Way East, Englewood, Colorado 80112-5704 USA; 800-854-7179.

Kernighan, Brian W., and Dennis M. Ritchie. The C Programming Language, 2nd ed. Prentice Hall, Englewood Cliffs, New Jersey, 1988, ISBN 0-13-110362-8.

Madsen, Ole Lehrmann, Birger Møller-Pedersen, and Kristen Nygaard. Object-Oriented Programming in the Beta Programming Language. Addison-Wesley, Reading, Massachusetts, 1993, ISBN 0-201-52430.

Mitchell, James G., William Maybury, and Richard Sweet. The Mesa Programming Language, Version 5.0. Xerox PARC, Palo Alto, California, CSL 79-3, April 1979.

Stroustrup, Bjarne. The C++ Progamming Language, 2nd ed. Addison-Wesley, Reading, Massachusetts, 1991, reprinted with corrections January 1994, ISBN 0-201-53992-6.

Unicode Consortium, The. The Unicode Standard: Worldwide Character Encoding, Version 1.0. Addison-Wesley, Reading, Massachusetts, Volume 1, 1991, ISBN 0-201-56788-1, and Volume 2, 1992, ISBN 0-201-60845-6. (Version 2, forthcoming, 1996.)


 2. Grammars

CHAPTER 2

Grammars

Grammar, which knows how to control even kings . . .
—Moliere, Les Femmes Savantes (1672), Act II, scene vi

This chapter describes the context-free grammars used in this specification to define the lexical and syntactic structure of a Java program.


2.1 Context-Free Grammars

A context-free grammar consists of a number of productions. Each production has an abstract symbol called a nonterminal as its left-hand side, and a sequence of one or more nonterminal and terminal symbols as its right-hand side. For each grammar, the terminal symbols are drawn from a specified alphabet.

Starting from a sentence consisting of a single distinguished nonterminal, called the goal symbol, a given context-free grammar specifies a language, namely, the infinite set of possible sequences of terminal symbols that can result from repeatedly replacing any nonterminal in the sequence with a right-hand side of a production for which the nonterminal is the left-hand side.


2.2 The Lexical Grammar

A lexical grammar for Java is given in §3. This grammar has as its terminal symbols the characters of the Unicode character set. It defines a set of productions, starting from the goal symbol Input (§3.5), that describe how sequences of Unicode characters (§3.1) are translated into a sequence of input elements (§3.5).

These input elements, with white space (§3.6) and comments (§3.7) discarded, form the terminal symbols for the syntactic grammar for Java and are called Java tokens (§3.5). These tokens are the identifiers (§3.8), keywords (§3.9), literals (§3.10), separators (§3.11), and operators (§3.12) of the Java language.


2.3 The Syntactic Grammar

The syntactic grammar for Java is given in Chapters 4, 6-10, 14, and 15. This grammar has Java tokens defined by the lexical grammar as its terminal symbols. It defines a set of productions, starting from the goal symbol CompilationUnit (§7.3), that describe how sequences of tokens can form syntactically correct Java programs.

A LALR(1) version of the syntactic grammar is presented in Chapter 19. The grammar in the body of this specification is very similar to the LALR(1) grammar but more readable.


2.4 Grammar Notation

Terminal symbols are shown in fixed width font in the productions of the lexical and syntactic grammars, and throughout this specification whenever the text is directly referring to such a terminal symbol. These are to appear in a program exactly as written.

Nonterminal symbols are shown in italic type. The definition of a nonterminal is introduced by the name of the nonterminal being defined followed by a colon. One or more alternative right-hand sides for the nonterminal then follow on succeeding lines. For example, the syntactic definition:

IfThenStatement:

    if ( Expression ) Statement

states that the nonterminal IfThenStatement represents the token if, followed by a left parenthesis token, followed by an Expression, followed by a right parenthesis token, followed by a Statement. As another example, the syntactic definition:

ArgumentList:

    Argument

    ArgumentList , Argument

states that an ArgumentList may represent either a single Argument or an ArgumentList, followed by a comma, followed by an Argument. This definition of ArgumentList is recursive, that is to say, it is defined in terms of itself. The result is that an ArgumentList may contain any positive number of arguments. Such recursive definitions of nonterminals are common.

The subscripted suffix "opt", which may appear after a terminal or nonterminal, indicates an optional symbol. The alternative containing the optional symbol actually specifies two right-hand sides, one that omits the optional element and one that includes it. This means that:

BreakStatement:

    break Identifieropt ;

is a convenient abbreviation for:

BreakStatement:

    break ;

    break Identifier ;

and that:

ForStatement:

    for ( ForInitopt ; Expressionopt ; ForUpdateopt ) Statement

is a convenient abbreviation for:

ForStatement:

    for ( ; Expressionopt ; ForUpdateopt ) Statement

    for ( ForInit ; Expressionopt ; ForUpdateopt ) Statement

which in turn is an abbreviation for:

ForStatement:

    for ( ; ; ForUpdateopt ) Statement

    for ( ; Expression ; ForUpdateopt ) Statement

    for ( ForInit ; ; ForUpdateopt ) Statement

    for ( ForInit ; Expression ; ForUpdateopt ) Statement

which in turn is an abbreviation for:

ForStatement:

    for ( ; ; ) Statement

    for ( ; ; ForUpdate ) Statement

    for ( ; Expression ; ) Statement

    for ( ; Expression ; ForUpdate ) Statement

    for ( ForInit ; ; ) Statement

    for ( ForInit ; ; ForUpdate ) Statement

    for ( ForInit ; Expression ; ) Statement

    for ( ForInit ; Expression ; ForUpdate ) Statement

so the nonterminal ForStatement actually has eight alternative right-hand sides.

A very long right-hand side may be continued on a second line by substantially indenting this second line, as in:

ConstructorDeclaration:

    ConstructorModifiersopt ConstructorDeclarator

        Throwsopt ConstructorBody

which defines one right-hand side for the nonterminal ConstructorDeclaration. (This right-hand side is an abbreviation for four alternative right-hand sides, because of the two occurrences of "opt".)

When the words "one of" follow the colon in a grammar definition, they signify that each of the terminal symbols on the following line or lines is an alternative definition. For example, the lexical grammar for Java contains the production:

ZeroToThree: one of

    0 1 2 3

which is merely a convenient abbreviation for:

ZeroToThree:

    0

    1

    2

    3

When an alternative in a lexical production appears to be a token, it represents the sequence of characters that would make up such a token. Thus, the definition:

BooleanLiteral: one of

    true false

in a lexical grammar production is shorthand for:

BooleanLiteral:

    t r u e

    f a l s e

The right-hand side of a lexical production may specify that certain expansions are not permitted by using the phrase "but not" and then indicating the expansions to be excluded, as in the productions for InputCharacter (§3.4) and Identifier (§3.8):

InputCharacter:

    UnicodeInputCharacter but not CR or LF

Identifier:

    IdentifierName but not a Keyword or BooleanLiteral or NullLiteral

Finally, a few nonterminal symbols are described by a descriptive phrase in roman type in cases where it would be impractical to list all the alternatives:

RawInputCharacter:

    any Unicode character


 3. Lexical Structure

CHAPTER 3

Lexical Structure

Lexicographer: A writer of dictionaries, a harmless drudge.
—Samuel Johnson, Dictionary (1755)

This chapter specifies the lexical structure of Java.

Java programs are written in Unicode (§3.1), but lexical translations are provided (§3.2) so that Unicode escapes (§3.3) can be used to include any Unicode character using only ASCII characters. Line terminators are defined (§3.4) to support the different conventions of existing host systems while maintaining consistent line numbers.

The Unicode characters resulting from the lexical translations are reduced to a sequence of input elements (§3.5), which are white space (§3.6), comments (§3.7), and tokens. The tokens are the identifiers (§3.8), keywords (§3.9), literals (§3.10), separators (§3.11), and operators (§3.12) of the Java syntactic grammar.


3.1 Unicode

Java programs are written using the Unicode character set, version 2.0. Information about this encoding may be found at:

http://www.unicode.org/ and ftp://unicode.org/

Versions of Java prior to 1.1 used Unicode version 1.1.5 (see The Unicode Standard: Worldwide Character Encoding (§1.2) and updates). See §20.5 for a discussion of the differences between Unicode version 1.1.5 and Unicode version 2.0.

Except for comments (§3.7), identifiers, and the contents of character and string literals (§3.10.4, §3.10.5), all input elements (§3.5) in a Java program are formed only from ASCII characters (or Unicode escapes (§3.3) which result in ASCII characters). ASCII (ANSI X3.4) is the American Standard Code for Information Interchange. The first 128 characters of the Unicode character encoding are the ASCII characters.


3.2 Lexical Translations

A raw Unicode character stream is translated into a sequence of Java tokens, using the following three lexical translation steps, which are applied in turn:

  • A translation of Unicode escapes (§3.3) in the raw stream of Unicode characters to the corresponding Unicode character. A Unicode escape of the form \u xxxx, where xxxx is a hexadecimal value, represents the Unicode character whose encoding is xxxx. This translation step allows any Java program to be expressed using only ASCII characters.
  • A translation of the Unicode stream resulting from step 1 into a stream of input characters and line terminators (§3.4).
  • A translation of the stream of input characters and line terminators resulting from step 2 into a sequence of Java input elements (§3.5) which, after white space (§3.6) and comments (§3.7) are discarded, comprise the tokens (§3.5) that are the terminal symbols of the syntactic grammar (§2.3) for Java.

Java always uses the longest possible translation at each step, even if the result does not ultimately make a correct Java program, while another lexical translation would. Thus the input characters a--b are tokenized (§3.5) as a, --, b, which is not part of any grammatically correct Java program, even though the tokenization a, -, -, b could be part of a grammatically correct Java program.


3.3 Unicode Escapes

Java implementations first recognize Unicode escapes in their input, translating the ASCII characters \u followed by four hexadecimal digits to the Unicode character with the indicated hexadecimal value, and passing all other characters unchanged. This translation step results in a sequence of Unicode input characters:

UnicodeInputCharacter:

    UnicodeEscape

    RawInputCharacter

UnicodeEscape:

    \ UnicodeMarker HexDigit HexDigit HexDigit HexDigit

UnicodeMarker:

    u

    UnicodeMarker u

RawInputCharacter:

    any Unicode character

HexDigit: one of

    0 1 2 3 4 5 6 7 8 9 a b c d e f A B C D E F

The \, u, and hexadecimal digits here are all ASCII characters.

In addition to the processing implied by the grammar, for each raw input character that is a backslash \, input processing must consider how many other \ characters contiguously precede it, separating it from a non-\ character or the start of the input stream. If this number is even, then the \ is eligible to begin a Unicode escape; if the number is odd, then the \ is not eligible to begin a Unicode escape. For example, the raw input "\\u2297=\u2297" results in the eleven characters " \ \ u 2 2 9 7 = [image] " (\u2297 is the Unicode encoding of the character " [image] ").

If an eligible \ is not followed by u, then it is treated as a RawInputCharacter and remains part of the escaped Unicode stream. If an eligible \ is followed by u, or more than one u, and the last u is not followed by four hexadecimal digits, then a compile-time error occurs.

The character produced by a Unicode escape does not participate in further Unicode escapes. For example, the raw input \u005cu005a results in the six characters \ u 0 0 5 a, because 005c is the Unicode value for \. It does not result in the character Z, which is Unicode character 005a, because the \ that resulted from the \u005c is not interpreted as the start of a further Unicode escape.

Java specifies a standard way of transforming a Unicode Java program into ASCII that changes a Java program into a form that can be processed by ASCII-based tools. The transformation involves converting any Unicode escapes in the source text of the program to ASCII by adding an extra u-for example, \u xxxx becomes \uu xxxx-while simultaneously converting non-ASCII characters in the source text to a \u xxxx escape containing a single u. This transformed version is equally acceptable to a Java compiler and represents the exact same program. The exact Unicode source can later be restored from this ASCII form by converting each escape sequence where multiple u's are present to a sequence of Unicode characters with one fewer u, while simultaneously converting each escape sequence with a single u to the corresponding single Unicode character.

Java systems should use the \u xxxx notation as an output format to display Unicode characters when a suitable font is not available.


3.4 Line Terminators

Java implementations next divide the sequence of Unicode input characters into lines by recognizing line terminators. This definition of lines determines the line numbers produced by a Java compiler or other Java system component. It also specifies the termination of the // form of a comment (§3.7).

LineTerminator:

    the ASCII LF character, also known as "newline"

    the ASCII CR character, also known as "return"

    the ASCII CR character followed by the ASCII LF character

InputCharacter:

    UnicodeInputCharacter but not CR or LF

Lines are terminated by the ASCII characters CR, or LF, or CR LF. The two characters CR immediately followed by LF are counted as one line terminator, not two. The result is a sequence of line terminators and input characters, which are the terminal symbols for the third step in the tokenization process.


3.5 Input Elements and Tokens

The input characters and line terminators that result from escape processing (§3.3) and then input line recognition (§3.4) are reduced to a sequence of input elements. Those input elements that are not white space (§3.6) or comments (§3.7) are tokens. The tokens are the terminal symbols of the Java syntactic grammar (§2.3).

This process is specified by the following productions:

Input:

    InputElementsopt Subopt

InputElements:

    InputElement

    InputElements InputElement

InputElement:

    WhiteSpace

    Comment

    Token

Token:

    Identifier

    Keyword

    Literal

    Separator

    Operator

Sub:

    the ASCII SUB character, also known as "control-Z"

White space (§3.6) and comments (§3.7) can serve to separate tokens that, if adjacent, might be tokenized in another manner. For example, the ASCII characters - and = in the input can form the operator token -= (§3.12) only if there is no intervening white space or comment.

As a special concession for compatibility with certain operating systems, the ASCII SUB character (\u001a, or control-Z) is ignored if it is the last character in the escaped input stream.

Consider two tokens x and y in the resulting input stream. If x precedes y, then we say that x is to the left of y and that y is to the right of x. For example, in this simple piece of Java code:

class Empty {
}

we say that the } token is to the right of the { token, even though it appears, in this two-dimensional representation on paper, downward and to the left of the { token. This convention about the use of the words left and right allows us to speak, for example, of the right-hand operand of a binary operator or of the left-hand side of an assignment.


3.6 White Space

White space is defined as the ASCII space, horizontal tab, and form feed characters, as well as line terminators (§3.4).

WhiteSpace:

    the ASCII SP character, also known as "space"

    the ASCII HT character, also known as "horizontal tab"

    the ASCII FF character, also known as "form feed"

    LineTerminator


3.7 Comments

Java defines three kinds of comments:

/* text */ A traditional comment: all the text from the ASCII characters /* to the ASCII characters */ is ignored (as in C and C++).

// text A single-line comment: all the text from the ASCII characters // to the end of the line is ignored (as in C++).

/** documentation */ A documentation comment: the text enclosed by the ASCII characters /** and */ can be processed by a separate tool to prepare automatically generated documentation of the following class, interface, constructor, or member (method or field) declaration. See §18 for a full description of how the supplied documentation is processed.

These comments are formally specified by the following productions:

Comment:

    TraditionalComment

    EndOfLineComment

    DocumentationComment

TraditionalComment:

    / * NotStar CommentTail

EndOfLineComment:

    / / CharactersInLineopt LineTerminator

DocumentationComment:

    / * * CommentTailStar

CommentTail:

    * CommentTailStar

    NotStar CommentTail

CommentTailStar:

    /

    * CommentTailStar

    NotStarNotSlash CommentTail

NotStar:

    InputCharacter but not *

    LineTerminator

NotStarNotSlash:

    InputCharacter but not * or /

    LineTerminator

CharactersInLine:

    InputCharacter

    CharactersInLine InputCharacter

These productions imply all of the following properties:

  • Comments do not nest.
  • /* and */ have no special meaning in comments that begin with //.
  • // has no special meaning in comments that begin with /* or /**.

As a result, the text:

/* this comment /* // /** ends here: */

is a single complete comment.

The lexical grammar implies that comments do not occur within character literals (§3.10.4) or string literals (§3.10.5).

Note that /**/ is considered to be a documentation comment, while /* */ (with a space between the asterisks) is a traditional comment.


3.8 Identifiers

An identifier is an unlimited-length sequence of Java letters and Java digits, the first of which must be a Java letter. An identifier cannot have the same spelling (Unicode character sequence) as a keyword (§3.9), Boolean literal (§3.10.3), or the null literal (§3.10.7).

Identifier:

    IdentifierChars but not a Keyword or BooleanLiteral or NullLiteral

IdentifierChars:

    JavaLetter

    IdentifierChars JavaLetterOrDigit

JavaLetter:

    any Unicode character that is a Java letter (see below)

JavaLetterOrDigit:

    any Unicode character that is a Java letter-or-digit (see below)

Letters and digits may be drawn from the entire Unicode character set, which supports most writing scripts in use in the world today, including the large sets for Chinese, Japanese, and Korean. This allows Java programmers to use identifiers in their programs that are written in their native languages.

A Java letter is a character for which the method Character.isJavaLetter (§20.5.17) returns true. A Java letter-or-digit is a character for which the method Character.isJavaLetterOrDigit (§20.5.18) returns true.

The Java letters include uppercase and lowercase ASCII Latin letters A-Z (\u0041-\u005a), and a-z (\u0061-\u007a), and, for historical reasons, the ASCII underscore (_, or \u005f) and dollar sign ($, or \u0024). The $ character should be used only in mechanically generated Java code or, rarely, to access preexisting names on legacy systems.

The Java digits include the ASCII digits 0-9 (\u0030-\u0039).

Two identifiers are the same only if they are identical, that is, have the same Unicode character for each letter or digit.

Identifiers that have the same external appearance may yet be different. For example, the identifiers consisting of the single letters LATIN CAPITAL LETTER A (A, \u0041), LATIN SMALL LETTER A (a, \u0061), GREEK CAPITAL LETTER ALPHA (A, \u0391), and CYRILLIC SMALL LETTER A (a, \u0430) are all different.

Unicode composite characters are different from the decomposed characters. For example, a LATIN CAPITAL LETTER A ACUTE (Á, \u00c1) could be considered to be the same as a LATIN CAPITAL LETTER A (A, \u0041) immediately followed by a NON-SPACING ACUTE (´, \u0301) when sorting, but these are different in Java identifiers. See The Unicode Standard, Volume 1, pages 412ff for details about decomposition, and see pages 626-627 of that work for details about sorting.

Examples of identifiers are:

    String			i3		          			MAX_VALUE				isLetterOrDigit


3.9 Keywords

The following character sequences, formed from ASCII letters, are reserved for use as keywords and cannot be used as identifiers (§3.8):

Keyword: one of

    abstract	default	if	private	throw

    boolean	do	implements	protected	throws

    break	double	import	public	transient

    byte	else	instanceof	return	try

    case	extends	int	short	void

    catch	final	interface	static	volatile

    char	finally	long	super	while

    class	float	native	switch

    const	for	new	synchronized

    continue	goto	package	this

The keywords const and goto are reserved by Java, even though they are not currently used in Java. This may allow a Java compiler to produce better error messages if these C++ keywords incorrectly appear in Java programs.

While true and false might appear to be keywords, they are technically Boolean literals (§3.10.3). Similarly, while null might appear to be a keyword, it is technically the null literal (§3.10.7).


3.10 Literals

A literal is the source code representation of a value of a primitive type (§4.2), the String type (§4.3.3, §20.12), or the null type (§4.1):

Literal:

    IntegerLiteral

    FloatingPointLiteral

    BooleanLiteral

    CharacterLiteral

    StringLiteral

    NullLiteral


3.10.1 Integer Literals

See §4.2.1 for a general discussion of the integer types and values.

An integer literal may be expressed in decimal (base 10), hexadecimal (base 16), or octal (base 8):

IntegerLiteral:

    DecimalIntegerLiteral

    HexIntegerLiteral

    OctalIntegerLiteral

DecimalIntegerLiteral:

    DecimalNumeral IntegerTypeSuffixopt

HexIntegerLiteral:

    HexNumeral IntegerTypeSuffixopt

OctalIntegerLiteral:

    OctalNumeral IntegerTypeSuffixopt

IntegerTypeSuffix: one of

    l L

An integer literal is of type long if it is suffixed with an ASCII letter L or l (ell); otherwise it is of type int (§4.2.1). The suffix L is preferred, because the letter l (ell) is often hard to distinguish from the digit 1 (one).

A decimal numeral is either the single ASCII character 0, representing the integer zero, or consists of an ASCII digit from 1 to 9, optionally followed by one or more ASCII digits from 0 to 9, representing a positive integer:

DecimalNumeral:

    0

    NonZeroDigit Digitsopt

Digits:

    Digit

    Digits Digit

Digit:

    0

    NonZeroDigit

NonZeroDigit: one of

    1 2 3 4 5 6 7 8 9

A hexadecimal numeral consists of the leading ASCII characters 0x or 0X followed by one or more ASCII hexadecimal digits and can represent a positive, zero, or negative integer. Hexadecimal digits with values 10 through 15 are represented by the ASCII letters a through f or A through F, respectively; each letter used as a hexadecimal digit may be uppercase or lowercase.

HexNumeral:

    0 x HexDigit

    0 X HexDigit

    HexNumeral HexDigit

The following production from §3.3 is repeated here for clarity:

HexDigit: one of

    0 1 2 3 4 5 6 7 8 9 a b c d e f A B C D E F

An octal numeral consists of an ASCII digit 0 followed by one or more of the ASCII digits 0 through 7 and can represent a positive, zero, or negative integer.

OctalNumeral:

    0 OctalDigit

    OctalNumeral OctalDigit

OctalDigit: one of

    0 1 2 3 4 5 6 7

Note that octal numerals are always consist of two or more digits; 0 is always considered to be a decimal numeral-not that it matters much in practice, for the numerals 0, 00, and 0x0 all represent exactly the same integer value.

The largest decimal literal of type int is 2147483648 ( [image]). All decimal literals from 0 to 2147483647 may appear anywhere an int literal may appear, but the literal 2147483648 may appear only as the operand of the unary negation operator -.

The largest positive hexadecimal and octal literals of type int are 0x7fffffff and 017777777777, respectively, which equal 2147483647 ( [image]). The most negative hexadecimal and octal literals of type int are 0x80000000 and 020000000000, respectively, each of which represents the decimal value -2147483648 ( [image]). The hexadecimal and octal literals 0xffffffff and 037777777777, respectively, represent the decimal value -1.

See also Integer.MIN_VALUE (§20.7.1) and Integer.MAX_VALUE (§20.7.2).

A compile-time error occurs if a decimal literal of type int is larger than 2147483648 ( [image]), or if the literal 2147483648 appears anywhere other than as the operand of the unary - operator, or if a hexadecimal or octal int literal does not fit in 32 bits.

Examples of int literals:

    0		2		0372			0xDadaCafe					1996		0x00FF00FF

The largest decimal literal of type long is 9223372036854775808L ( [image]). All decimal literals from 0L to 9223372036854775807L may appear anywhere a long literal may appear, but the literal 9223372036854775808L may appear only as the operand of the unary negation operator -.

The largest positive hexadecimal and octal literals of type long are 0x7fffffffffffffffL and 0777777777777777777777L, respectively, which equal 9223372036854775807L ( [image]). The literals 0x8000000000000000L and 01000000000000000000000L are the most negative long hexadecimal and octal literals, respectively. Each has the decimal value -9223372036854775808L ( [image]). The hexadecimal and octal literals 0xffffffffffffffffL and 01777777777777777777777L, respectively, represent the decimal value -1L.

See also Long.MIN_VALUE (§20.8.1) and Long.MAX_VALUE (§20.8.2).

A compile-time error occurs if a decimal literal of type long is larger than 9223372036854775808L ( [image]), or if the literal 9223372036854775808L appears anywhere other than as the operand of the unary - operator, or if a hexadecimal or octal long literal does not fit in 64 bits.

Examples of long literals:

    0l		0777L			0x100000000L					2147483648L				   0xC0B0L


3.10.2 Floating-Point Literals

See §4.2.3 for a general discussion of the floating-point types and values.

A floating-point literal has the following parts: a whole-number part, a decimal point (represented by an ASCII period character), a fractional part, an exponent, and a type suffix. The exponent, if present, is indicated by the ASCII letter e or E followed by an optionally signed integer.

At least one digit, in either the whole number or the fraction part, and either a decimal point, an exponent, or a float type suffix are required. All other parts are optional.

A floating-point literal is of type float if it is suffixed with an ASCII letter F or f; otherwise its type is double and it can optionally be suffixed with an ASCII letter D or d.

FloatingPointLiteral:

    Digits . Digitsopt ExponentPartopt FloatTypeSuffixopt

    . Digits ExponentPartopt FloatTypeSuffixopt

    Digits ExponentPart FloatTypeSuffixopt

    Digits ExponentPartopt FloatTypeSuffix

ExponentPart:

    ExponentIndicator SignedInteger

ExponentIndicator: one of

    e E

SignedInteger:

    Signopt Digits

Sign: one of

    + -

FloatTypeSuffix: one of

    f F d D

The Java types float and double are IEEE 754 32-bit single-precision and 64-bit double-precision binary floating-point values, respectively.

The details of proper input conversion from a Unicode string representation of a floating-point number to the internal IEEE 754 binary floating-point representation are described for the methods valueOf of class Float (§20.9.17) and class Double (§20.10.16) of the package java.lang.

The largest positive finite float literal is 3.40282347e+38f. The smallest positive finite nonzero literal of type float is 1.40239846e-45f. The largest positive finite double literal is 1.79769313486231570e+308. The smallest positive finite nonzero literal of type double is 4.94065645841246544e-324.

See Float.MIN_VALUE (§20.9.1) and Float.MAX_VALUE (§20.9.2); see also Double.MIN_VALUE (§20.10.1) and Double.MAX_VALUE (§20.10.2).

A compile-time error occurs if a nonzero floating-point literal is too large, so that on rounded conversion to its internal representation it becomes an IEEE 754 infinity. A Java program can represent infinities without producing a compile-time error by using constant expressions such as 1f/0f or -1d/0d or by using the predefined constants POSITIVE_INFINITY and NEGATIVE_INFINITY of the classes Float (§20.9) and Double (§20.10).

A compile-time error occurs if a nonzero floating-point literal is too small, so that, on rounded conversion to its internal representation, it becomes a zero. A compile-time error does not occur if a nonzero floating-point literal has a small value that, on rounded conversion to its internal representation, becomes a nonzero denormalized number.

Predefined constants representing Not-a-Number values are defined in the classes Float and Double as Float.NaN (§20.9.5) and Double.NaN (§20.10.5).

Examples of float literals:

    1e1f			2.f			.3f		0f		3.14f			6.022137e+23f

Examples of double literals:

    1e1			2.			.3		0.0		3.14			1e-9d		1e137

There is no provision for expressing floating-point literals in other than decimal radix. However, method intBitsToFloat (§20.9.23) of class Float and method longBitsToDouble (§20.10.22) of class Double provide a way to express floating-point values in terms of hexadecimal or octal integer literals. For example, the value of:

Double.longBitsToDouble(0x400921FB54442D18L)

is equal to the value of Math.PI (§20.11.2).


3.10.3 Boolean Literals

The boolean type has two values, represented by the literals true and false, formed from ASCII letters.

A boolean literal is always of type boolean.

BooleanLiteral: one of

    true false


3.10.4 Character Literals

A character literal is expressed as a character or an escape sequence, enclosed in ASCII single quotes. (The single-quote, or apostrophe, character is \u0027.)

A character literal is always of type char.

CharacterLiteral:

    ' SingleCharacter '

    ' EscapeSequence '

SingleCharacter:

    InputCharacter but not ' or \

The escape sequences are described in §3.10.6.

As specified in §3.4, the characters CR and LF are never an InputCharacter; they are recognized as constituting a LineTerminator.

It is a compile-time error for the character following the SingleCharacter or EscapeSequence to be other than a '.

It is a compile-time error for a line terminator to appear after the opening ' and before the closing '.

The following are examples of char literals:

'a'
'%'
'\t'
'\\'
'\''
'\u03a9'
'\uFFFF'
'\177'
'  '
'  '

Because Unicode escapes are processed very early, it is not correct to write '\u000a' for a character literal whose value is linefeed (LF); the Unicode escape \u000a is transformed into an actual linefeed in translation step 1 (§3.3) and the linefeed becomes a LineTerminator in step 2 (§3.4), and so the character literal is not valid in step 3. Instead, one should use the escape sequence '\n' (§3.10.6). Similarly, it is not correct to write '\u000d' for a character literal whose value is carriage return (CR). Instead, use '\r'.

In C and C++, a character literal may contain representations of more than one character, but the value of such a character literal is implementation-defined. In Java, a character literal always represents exactly one character.


3.10.5 String Literals

A string literal consists of zero or more characters enclosed in double quotes. Each character may be represented by an escape sequence.

A string literal is always of type String (§4.3.3, §20.12). A string literal always refers to the same instance (§4.3.1) of class String.

StringLiteral:

    " StringCharactersopt "

StringCharacters:

    StringCharacter

    StringCharacters StringCharacter

StringCharacter:

    InputCharacter but not " or \

    EscapeSequence

The escape sequences are described in §3.10.6.

As specified in §3.4, neither of the characters CR and LF is ever considered to be an InputCharacter; each is recognized as constituting a LineTerminator.

It is a compile-time error for a line terminator to appear after the opening " and before the closing matching ". A long string literal can always be broken up into shorter pieces and written as a (possibly parenthesized) expression using the string concatenation operator + (§15.17.1).

The following are examples of string literals:

"" 							// the empty string
"\""							// a string containing " alone
"This is a string"							// a string containing 16 characters

"This is a " +							// actually a string-valued constant expression,
    "two-line string"						//		formed from two string literals

Because Unicode escapes are processed very early, it is not correct to write "\u000a" for a string literal containing a single linefeed (LF); the Unicode escape \u000a is transformed into an actual linefeed in translation step 1 (§3.3) and the linefeed becomes a LineTerminator in step 2 (§3.4), and so the string literal is not valid in step 3. Instead, one should write "\n" (§3.10.6). Similarly, it is not correct to write "\u000d" for a string literal containing a single carriage return (CR). Instead use "\r".

Each string literal is a reference (§4.3) to an instance (§4.3.1, §12.5) of class String (§4.3.3,§20.12). String objects have a constant value. String literals-or, more generally, strings that are the values of constant expressions (§15.27)-are "interned" so as to share unique instances, using the method String.intern (§20.12.47).

Thus, the test program consisting of the compilation unit (§7.3):

package testPackage;

class Test {
    public static void main(String[] args) {
        String hello = "Hello", lo = "lo";
        System.out.print((hello == "Hello") + " ");
        System.out.print((Other.hello == hello) + " ");
        System.out.print((other.Other.hello == hello) + " ");
        System.out.print((hello == ("Hel"+"lo")) + " ");
        System.out.print((hello == ("Hel"+lo)) + " ");
        System.out.println(hello == ("Hel"+lo).intern());
    }
}

class Other { static String hello = "Hello"; }

and the compilation unit:

package other;

public class Other { static String hello = "Hello"; }

produces the output:

true true true true false true

This example illustrates six points:

  • Literal strings within the same class (§8) in the same package (§7) represent references to the same String object (§4.3.1).
  • Literal strings within different classes in the same package represent references to the same String object.
  • Literal strings within different classes in different packages likewise represent references to the same String object.
  • Strings computed by constant expressions (§15.27) are computed at compile time and then treated as if they were literals.
  • Strings computed at run time are newly created and therefore distinct.
  • The result of explicitly interning a computed string is the same string as any pre-existing literal string with the same contents.


3.10.6 Escape Sequences for Character and String Literals

The character and string escape sequences allow for the representation of some nongraphic characters as well as the single quote, double quote, and backslash characters in character literals (§3.10.4) and string literals (§3.10.5).

EscapeSequence:
\ b /* \u0008: backspace BS */
\ t /* \u0009: horizontal tab HT */
\ n /* \u000a: linefeed LF */
\ f /* \u000c: form feed FF */
\ r /* \u000d: carriage return CR */
\ " /* \u0022: double quote " */
\ ' /* \u0027: single quote ' */
\ \ /* \u005c: backslash \ */
OctalEscape /* \u0000 to \u00ff: from octal value */

OctalEscape:

    \ OctalDigit

    \ OctalDigit OctalDigit

    \ ZeroToThree OctalDigit OctalDigit

OctalDigit: one of

    0 1 2 3 4 5 6 7

ZeroToThree: one of

    0 1 2 3

It is a compile-time error if the character following a backslash in an escape is not an ASCII b, t, n, f, r, ", ', \, 0, 1, 2, 3, 4, 5, 6, or 7. The Unicode escape \u is processed earlier (§3.3). (Octal escapes are provided for compatibility with C, but can express only Unicode values \u0000 through \u00FF, so Unicode escapes are usually preferred.)


3.10.7 The Null Literal

The null type has one value, the null reference, represented by the literal null, which is formed from ASCII characters. A null literal is always of the null type.

NullLiteral:

    null


3.11 Separators

The following nine ASCII characters are the Java separators (punctuators):

Separator: one of
( ) { } [ ] ; , .


3.12 Operators

The following 37 tokens are the Java operators, formed from ASCII characters:

Operator: one of
= > < ! ~ ? :
== <= >= != && || ++ --
+ - * / & | ^ % << >> >>>
+= -= *= /= &= |= ^= %= <<= >>= >>>=

Give her no token but stones; for she's as hard as steel.
—William Shakespeare, Two Gentlemen of Verona, Act I, scene i

These lords are visited; you are not free;
For the Lord's tokens on you do I see.
—William Shakespeare, Love's Labour's Lost, Act V, scene ii

Thou, thou, Lysander, thou hast given her rhymes,
And interchanged love-tokens with my child.
—William Shakespeare, A Midsummer Night's Dream, Act I, scene i

Here is a letter from Queen Hecuba,
A token from her daughter . . .
—William Shakespeare, Troilus and Cressida, Act V, scene i

Are there no other tokens . . . ?
—William Shakespeare, Measure for Measure, Act IV, scene i


 4. Types, Values, and Variables

CHAPTER 4

Types, Values, and Variables

I send no agent or medium,
offer no representative of value,
but offer the value itself.
—Walt Whitman, Carol of Occupations (1855), in Leaves of Grass

Java is a strongly typed language, which means that every variable and every expression has a type that is known at compile time. Types limit the values that a variable (§4.5) can hold or that an expression can produce, limit the operations supported on those values, and determine the meaning of the operations. Strong typing helps detect errors at compile time.

The types of the Java language are divided into two categories: primitive types and reference types. The primitive types (§4.2) are the boolean type and the numeric types. The numeric types are the integral types byte, short, int, long, and char, and the floating-point types float and double. The reference types (§4.3) are class types, interface types, and array types. There is also a special null type. An object (§4.3.1) in Java is a dynamically created instance of a class type or a dynamically created array. The values of a reference type are references to objects. All objects, including arrays, support the methods of class Object (§4.3.2). String literals are represented by String objects (§4.3.3).

Types are the same (§4.3.4) if they have the same fully qualified names and are loaded by the same class loader. Names of types are used (§4.4) in declarations, in casts, in class instance creation expressions, in array creation expressions, and in instanceof operator expressions.

A variable (§4.5) is a storage location. A variable of a primitive type always holds a value of that exact type. A variable of a class type T can hold a null reference or a reference to an instance of class T or of any class that is a subclass of T. A variable of an interface type can hold a null reference or a reference to any instance of any class that implements the interface. If T is a primitive type, then a variable of type "array of T" can hold a null reference or a reference to any array of type "array of T"; if T is a reference type, then a variable of type "array of T" can hold a null reference or a reference to any array of type "array of S" such that type S is assignable (§5.2) to type T. A variable of type Object can hold a null reference or a reference to any object, whether class instance or array.


4.1 The Kinds of Types and Values

There are two kinds of types in Java: primitive types (§4.2) and reference types (§4.3). There are, correspondingly, two kinds of data values that can be stored in variables, passed as arguments, returned by methods, and operated on: primitive values (§4.2) and reference values (§4.3).

Type:

    PrimitiveType

    ReferenceType

There is also a special null type, the type of the expression null, which has no name. Because the null type has no name, it is impossible to declare a variable of the null type or to cast to the null type. The null reference is the only possible value of an expression of null type. The null reference can always be cast to any reference type. In practice, the Java programmer can ignore the null type and just pretend that null is merely a special literal that can be of any reference type.


4.2 Primitive Types and Values

A primitive type is predefined by the Java language and named by its reserved keyword (§3.9):

PrimitiveType:

    NumericType

    boolean

NumericType:

    IntegralType

    FloatingPointType

IntegralType: one of

    byte short int long char

FloatingPointType: one of

    float double

Primitive values do not share state with other primitive values. A variable whose type is a primitive type always holds a primitive value of that same type. The value of a variable of primitive type can be changed only by assignment operations on that variable.

The numeric types are the integral types and the floating-point types.

The integral types are byte, short, int, and long, whose values are 8-bit, 16-bit, 32-bit and 64-bit signed two's-complement integers, respectively, and char, whose values are 16-bit unsigned integers representing Unicode characters.

The floating-point types are float, whose values are 32-bit IEEE 754 floating-point numbers, and double, whose values are 64-bit IEEE 754 floating-point numbers.

The boolean type has exactly two values: true and false.


4.2.1 Integral Types and Values

The values of the integral types are integers in the following ranges:

  • For byte, from -128 to 127, inclusive
  • For short, from -32768 to 32767, inclusive
  • For int, from -2147483648 to 2147483647, inclusive
  • For long, from -9223372036854775808 to 9223372036854775807, inclusive
  • For char, from '\u0000' to '\uffff' inclusive, that is, from 0 to 65535


4.2.2 Integer Operations

Java provides a number of operators that act on integral values:

  • The comparison operators, which result in a value of type boolean:
    • The numerical comparison operators <, <=, >, and >= (§15.19.1)
    • The numerical equality operators == and != (§15.20.1)
  • The numerical operators, which result in a value of type int or long:
    • The unary plus and minus operators + and - (§15.14.3, §15.14.4)
    • The multiplicative operators *, /, and % (§15.16)
    • The additive operators + and - (§15.17.2)
    • The increment operator ++, both prefix (§15.14.1) and postfix (§15.13.2)
    • The decrement operator --, both prefix (§15.14.2) and postfix (§15.13.3)
    • The signed and unsigned shift operators <<, >>, and >>> (§15.18)
    • The bitwise complement operator ~ (§15.14.5)
    • The integer bitwise operators &, |, and ^ (§15.21.1)
  • The conditional operator ? : (§15.24)
  • The cast operator, which can convert from an integral value to a value of any specified numeric type (§5.4, §15.15)
  • The string concatenation operator + (§15.17.1), which, when given a String operand and an integral operand, will convert the integral operand to a String representing its value in decimal form, and then produce a newly created String that is the concatenation of the two strings

Other useful constructors, methods, and constants are predefined in the classes Integer (§20.7), Long (§20.8), and Character (§20.5).

If an integer operator other than a shift operator has at least one operand of type long, then the operation is carried out using 64-bit precision, and the result of the numerical operator is of type long. If the other operand is not long, it is first widened (§5.1.2) to type long by numeric promotion (§5.6). Otherwise, the operation is carried out using 32-bit precision, and the result of the numerical operator is of type int. If either operand is not an int, it is first widened to type int by numeric promotion.

The built-in integer operators do not indicate overflow or underflow in any way. The only numeric operators that can throw an exception (§11) are the integer divide operator / (§15.16.2) and the integer remainder operator % (§15.16.3), which throw an ArithmeticException if the right-hand operand is zero.

The example:

class Test {
    public static void main(String[] args) {
        int i = 1000000;
        System.out.println(i * i);
        long l = i;
        System.out.println(l * l);
        System.out.println(20296 / (l - i));
    }
}

produces the output:

-727379968
1000000000000

and then encounters an ArithmeticException in the division by l - i, because l - i is zero. The first multiplication is performed in 32-bit precision, whereas the second multiplication is a long multiplication. The value -727379968 is the decimal value of the low 32 bits of the mathematical result, 1000000000000, which is a value too large for type int.

Any value of any integral type may be cast to or from any numeric type. There are no casts between integral types and the type boolean.


4.2.3 Floating-Point Types and Values

The floating-point types are float and double, representing the single-precision 32-bit and double-precision 64-bit format IEEE 754 values and operations as specified in IEEE Standard for Binary Floating-Point Arithmetic, ANSI/IEEE Standard 754-1985 (IEEE, New York).

The IEEE 754 standard includes not only positive and negative sign-magnitude numbers, but also positive and negative zeros, positive and negative infinities, and a special Not-a-Number (hereafter abbreviated NaN). The NaN value is used to represent the result of certain operations such as dividing zero by zero. NaN constants of both float and double type are predefined as Float.NaN (§20.9.5) and Double.NaN (§20.10.5).

The finite nonzero values of type float are of the form [image], where s is +1 or -1, m is a positive integer less than [image], and e is an integer between -149 and 104, inclusive. Values of that form such that m is positive but less than [image] and e is equal to -149 are said to be denormalized.

The finite nonzero values of type double are of the form [image], where s is +1 or -1, m is a positive integer less than [image], and e is an integer between -1075 and 970, inclusive. Values of that form such that m is positive but less than [image] and e is equal to -1075 are said to be denormalized.

Except for NaN, floating-point values are ordered; arranged from smallest to largest, they are negative infinity, negative finite nonzero values, negative zero, positive zero, positive finite nonzero values, and positive infinity.

Positive zero and negative zero compare equal; thus the result of the expression 0.0==-0.0 is true and the result of 0.0>-0.0 is false. But other operations can distinguish positive and negative zero; for example, 1.0/0.0 has the value positive infinity, while the value of 1.0/-0.0 is negative infinity. The operations Math.min and Math.max also distinguish positive zero and negative zero.

NaN is unordered, so the numerical comparison operators <, <=, >, and >= return false if either or both operands are NaN (§15.19.1). The equality operator == returns false if either operand is NaN, and the inequality operator != returns true if either operand is NaN (§15.20.1). In particular, x!=x is true if and only if x is NaN, and (x<y) == !(x>=y) will be false if x or y is NaN.

Any value of a floating-point type may be cast to or from any numeric type. There are no casts between floating-point types and the type boolean.


4.2.4 Floating-Point Operations

Java provides a number of operators that act on floating-point values:

  • The comparison operators, which result in a value of type boolean:
    • The numerical comparison operators <, <=, >, and >= (§15.19.1)
    • The numerical equality operators == and != (§15.20.1)
  • The numerical operators, which result in a value of type float or double:
    • The unary plus and minus operators + and - (§15.14.3, §15.14.4)
    • The multiplicative operators *, /, and % (§15.16)
    • The additive operators + and - (§15.17.2)
    • The increment operator ++, both prefix (§15.14.1) and postfix (§15.13.2)
    • The decrement operator --, both prefix (§15.14.2) and postfix (§15.13.3)
  • The conditional operator ? : (§15.24)
  • The cast operator, which can convert from a floating-point value to a value of any specified numeric type (§5.4, §15.15)
  • The string concatenation operator + (§15.17.1), which, when given a String operand and a floating-point operand, will convert the floating-point operand to a String representing its value in decimal form (without information loss), and then produce a newly created String by concatenating the two strings

Other useful constructors, methods, and constants are predefined in the classes Float (§20.9), Double (§20.10), and Math (§20.11).

If at least one of the operands to a binary operator is of floating-point type, then the operation is a floating-point operation, even if the other is integral.

If at least one of the operands to a numerical operator is of type double, then the operation is carried out using 64-bit floating-point arithmetic, and the result of the numerical operator is a value of type double. (If the other operand is not a double, it is first widened to type double by numeric promotion (§5.6).) Otherwise, the operation is carried out using 32-bit floating-point arithmetic, and the result of the numerical operator is a value of type float. If the other operand is not a float, it is first widened to type float by numeric promotion.

Operators on floating-point numbers behave exactly as specified by IEEE 754. In particular, Java requires support of IEEE 754 denormalized floating-point numbers and gradual underflow, which make it easier to prove desirable properties of particular numerical algorithms. Floating-point operations in Java do not "flush to zero" if the calculated result is a denormalized number.

Java requires that floating-point arithmetic behave as if every floating-point operator rounded its floating-point result to the result precision. Inexact results must be rounded to the representable value nearest to the infinitely precise result; if the two nearest representable values are equally near, the one with its least significant bit zero is chosen. This is the IEEE 754 standard's default rounding mode known as round to nearest.

Java uses round toward zero when converting a floating value to an integer (§5.1.3), which acts, in this case, as though the number were truncated, discarding the mantissa bits. Rounding toward zero chooses at its result the format's value closest to and no greater in magnitude than the infinitely precise result.

Java floating-point operators produce no exceptions (§11). An operation that overflows produces a signed infinity, an operation that underflows produces a signed zero, and an operation that has no mathematically definite result produces NaN. All numeric operations with NaN as an operand produce NaN as a result. As has already been described, NaN is unordered, so a numeric comparison operation involving one or two NaNs returns false and any != comparison involving NaN returns true, including x!=x when x is NaN.

The example program:

class Test {

    public static void main(String[] args) {

        // An example of overflow:
        double d = 1e308;
        System.out.print("overflow produces infinity: ");
        System.out.println(d + "*10==" + d*10);

        // An example of gradual underflow:
        d = 1e-305 * Math.PI;
        System.out.print("gradual underflow: " + d + "\n      ");
        for (int i = 0; i < 4; i++)
            System.out.print(" " + (d /= 100000));
        System.out.println();

        // An example of NaN:
        System.out.print("0.0/0.0 is Not-a-Number: ");
        d = 0.0/0.0;
        System.out.println(d);

        // An example of inexact results and rounding:
        System.out.print("inexact results with float:");
        for (int i = 0; i < 100; i++) {
            float z = 1.0f / i;
            if (z * i != 1.0f)
                System.out.print(" " + i);
        }
        System.out.println();

        // Another example of inexact results and rounding:
        System.out.print("inexact results with double:");
        for (int i = 0; i < 100; i++) {
            double z = 1.0 / i;
            if (z * i != 1.0)
                System.out.print(" " + i);
        }
        System.out.println();

        // An example of cast to integer rounding:
        System.out.print("cast to int rounds toward 0: ");
        d = 12345.6;
        System.out.println((int)d + " " + (int)(-d));
    }
}

produces the output:

overflow produces infinity: 1.0e+308*10==Infinity
gradual underflow: 3.141592653589793E-305
    3.1415926535898E-310 3.141592653E-315 3.142E-320 0.0
0.0/0.0 is Not-a-Number: NaN
inexact results with float: 0 41 47 55 61 82 83 94 97
inexact results with double: 0 49 98
cast to int rounds toward 0: 12345 -12345

This example demonstrates, among other things, that gradual underflow can result in a gradual loss of precision.

The inexact results when i is 0 involve division by zero, so that z becomes positive infinity, and z * 0 is NaN, which is not equal to 1.0.


4.2.5 The boolean Type and boolean Values

The boolean type represents a logical quantity with two possible values, indicated by the literals true and false (§3.10.3). The boolean operators are:

  • The relational operators == and != (§15.20.2)
  • The logical-complement operator ! (§15.14.6)
  • The logical operators &, ^, and | (§15.21.2)
  • The conditional-and and conditional-or operators && (§15.22) and || (§15.23)
  • The conditional operator ? : (§15.24)
  • The string concatenation operator + (§15.17.1), which, when given a String operand and a boolean operand, will convert the boolean operand to a String (either "true" or "false"), and then produce a newly created String that is the concatenation of the two strings

Boolean expressions determine the control flow in several kinds of statements:

  • The if statement (§14.8)
  • The while statement (§14.10)
  • The do statement (§14.11)
  • The for statement (§14.12)

A boolean expression also determines which subexpression is evaluated in the conditional ? : operator (§15.24).

Only boolean expressions can be used in control flow statements and as the first operand of the conditional operator ? :. An integer x can be converted to a boolean, following the C language convention that any nonzero value is true, by the expression x!=0. An object reference obj can be converted to a boolean, following the C language convention that any reference other than null is true, by the expression obj!=null.

A cast of a boolean value to type boolean is allowed (§5.1.1); no other casts on type boolean are allowed. A boolean can be converted to a string by string conversion (§5.4).


4.3 Reference Types and Values

There are three kinds of reference types: class types (§8), interface types (§9), and array types (§10).

ReferenceType:

    ClassOrInterfaceType

    ArrayType

ClassOrInterfaceType:

    ClassType

    InterfaceType

ClassType:

    TypeName

InterfaceType:

    TypeName

ArrayType:

    Type [ ]

Names are described in §6; type names in §6.5 and, specifically, §6.5.4.

The sample code:

class Point { int[] metrics; }

interface Move { void move(int deltax, int deltay); }

declares a class type Point, an interface type Move, and uses an array type int[] (an array of int) to declare the field metrics of the class Point.


4.3.1 Objects

An object is a class instance or an array.

The reference values (often just references) are pointers to these objects, and a special null reference, which refers to no object.

A class instance is explicitly created by a class instance creation expression (§15.8), or by invoking the newInstance method of class Class (§20.3.8). An array is explicitly created by an array creation expression (§15.8).

A new class instance is implicitly created when the string concatenation operator + (§15.17.1) is used in an expression, resulting in a new object of type String (§4.3.3, §20.12). A new array object is implicitly created when an array initializer expression (§10.6) is evaluated; this can occur when a class or interface is initialized (§12.4), when a new instance of a class is created (§15.8), or when a local variable declaration statement is executed (§14.3).

Many of these cases are illustrated in the following example:

class Point {
    int x, y;
    Point() { System.out.println("default"); }
    Point(int x, int y) { this.x = x; this.y = y; }

    // A Point instance is explicitly created at class initialization time:
    static Point origin = new Point(0,0);

    // A String can be implicitly created by a + operator:
    public String toString() {

        return "(" + x + "," + y + ")";

    }
}

class Test {
    public static void main(String[] args) {
        // A Point is explicitly created using newInstance:
        Point p = null;
        try {
            p = (Point)Class.forName("Point").newInstance();
        } catch (Exception e) {
            System.out.println(e);
        }

        // An array is implicitly created by an array constructor:
        Point a[] = { new Point(0,0), new Point(1,1) };

        // Strings are implicitly created by + operators:
        System.out.println("p: " + p);
        System.out.println("a: { " + a[0] + ", "

                                           + a[1] + " }");

        // An array is explicitly created by an array creation expression:
        String sa[] = new String[2];
        sa[0] = "he"; sa[1] = "llo";
        System.out.println(sa[0] + sa[1]);
    }
}

which produces the output:

default
p: (0,0)
a: { (0,0), (1,1) }
hello

The operators on references to objects are:

  • Field access, using either a qualified name (§6.6) or a field access expression (§15.10)
  • Method invocation (§15.11)
  • The cast operator (§5.4, §15.15)
  • The string concatenation operator + (§15.17.1), which, when given a String operand and a reference, will convert the reference to a String by invoking the toString method (§20.1.2) of the referenced object (using "null" if either the reference or the result of toString is a null reference), and then will produce a newly created String that is the concatenation of the two strings
  • The instanceof operator (§15.19.2)
  • The reference equality operators == and != (§15.20.3)
  • The conditional operator ? : (§15.24).

There may be many references to the same object. Most objects have state, stored in the fields of objects that are instances of classes or in the variables that are the components of an array object. If two variables contain references to the same object, the state of the object can be modified using one variable's reference to the object, and then the altered state can be observed through the reference in the other variable.

The example program:

class Value { int val; }

class Test {
    public static void main(String[] args) {
        int i1 = 3;
        int i2 = i1;
        i2 = 4;
        System.out.print("i1==" + i1);
        System.out.println(" but i2==" + i2);
        Value v1 = new Value();
        v1.val = 5;
        Value v2 = v1;
        v2.val = 6;
        System.out.print("v1.val==" + v1.val);
        System.out.println(" and v2.val==" + v2.val);
    }
}

produces the output:

i1==3 but i2==4
v1.val==6 and v2.val==6

because v1.val and v2.val reference the same instance variable (§4.5.3) in the one Value object created by the only new expression, while i1 and i2 are different variables.

See §10 and §15.9 for examples of the creation and use of arrays.

Each object has an associated lock (§17.13), which is used by synchronized methods (§8.4.3) and the synchronized statement (§14.17) to provide control over concurrent access to state by multiple threads (§17.12, §20.20).


4.3.2 The Class Object

The standard class Object is a superclass (§8.1) of all other classes. A variable of type Object can hold a reference to any object, whether it is an instance of a class or an array (§10). All class and array types inherit the methods of class Object, which are summarized here and completely specified in §20.1:

package java.lang;

public class Object {
    public final Class getClass() { . . . }
    public String toString() { . . . }
    public boolean equals(Object obj) { . . . }
    public int hashCode() { . . . }
    protected Object clone()
        throws CloneNotSupportedException { . . . }
    public final void wait()

        throws IllegalMonitorStateException,

            InterruptedException { . . . }
    public final void wait(long millis)
        throws IllegalMonitorStateException,
            InterruptedException { . . . }
    public final void wait(long millis, int nanos) { . . . }
        throws IllegalMonitorStateException,
            InterruptedException { . . . }
    public final void notify() { . . . }
        throws IllegalMonitorStateException
    public final void notifyAll() { . . . }
        throws IllegalMonitorStateException
    protected void finalize()
        throws Throwable { . . . }
}

The members of Object are as follows:

  • The method getClass returns the Class (§20.3) object that represents the class of the object. A Class object exists for each reference type. It can be used, for example, to discover the fully qualified name of a class, its members, its immediate superclass, and any interfaces that it implements. A class method that is declared synchronized (§8.4.3.5) synchronizes on the lock associated with the Class object of the class.
  • The method toString returns a String representation of the object.
  • The methods equals and hashCode are declared for the benefit of hashtables such as java.util.Hashtable (§21.7). The method equals defines a notion of object equality, which is based on value, not reference, comparison.
  • The method clone is used to make a duplicate of an object.
  • The methods wait, notify, and notifyAll are used in concurrent programming using threads, as described in §17.
  • The method finalize is run just before an object is destroyed and is described in §12.6.


4.3.3 The Class String

Instances of class String (§20.12) represent sequences of Unicode characters. A String object has a constant (unchanging) value. String literals (§3.10.5) are references to instances of class String.

The string concatenation operator + (§15.17.1) implicitly creates a new String object.


4.3.4 When Reference Types Are the Same

Two reference types the same type if:

  • They are both class or both interface types, are loaded by the same class loader, and have the same fully-qualified name (§6.6), in which case they are sometimes said to be the same class or the same interface.
  • They are both array types, and have the same component type (§10).


4.4 Where Types Are Used

Types are used when they appear in declarations or in certain expressions.

The following code fragment contains one or more instances of each kind of usage of a type:

import java.util.Random;

class MiscMath {

    int divisor;

    MiscMath(int divisor) {
        this.divisor = divisor;
    }

    float ratio(long l) {
        try {
            l /= divisor;
        } catch (Exception e) {
            if (e instanceof ArithmeticException)
                l = Long.MAX_VALUE;
            else
                l = 0;
        }
        return (float)l;
    }

    double gausser() {
        Random r = new Random();
        double[] val = new double[2];
        val[0] = r.nextGaussian();
        val[1] = r.nextGaussian();
        return (val[0] + val[1]) / 2;
    }

}

In this example, types are used in declarations of the following:

  • Imported types (§7.5); here the type Random, imported from the type java.util.Random of the package java.util, is declared
  • Fields, which are the class variables and instance variables of classes (§8.3), and constants of interfaces (§9.3); here the field divisor in the class MiscMath is declared to be of type int
  • Method parameters (§8.4.1); here the parameter l of the method ratio is declared to be of type long
  • Method results (§8.4); here the result of the method ratio is declared to be of type float, and the result of the method gausser is declared to be of type double
  • Constructor parameters (§8.6.1); here the parameter of the constructor for MiscMath is declared to be of type int
  • Local variables (§14.3, §14.12); the local variables r and val of the method gausser are declared to be of types Random and double[] (array of double)
  • Exception handler parameters (§14.18); here the exception handler parameter e of the catch clause is declared to be of type Exception

and in expressions of the following kinds:

  • Class instance creations (§15.8); here a local variable r of method gausser is initialized by a class instance creation expression that uses the type Random
  • Array creations (§15.9); here the local variable val of method gausser is initialized by an array creation expression that creates an array of double with size 2
  • Casts (§15.15); here the return statement of the method ratio uses the float type in a cast
  • The instanceof operator (§15.19.2); here the instanceof operator tests whether e is assignment compatible with the type ArithmeticException


4.5 Variables

A variable is a storage location and has an associated type, sometimes called its compile-time type, that is either a primitive type (§4.2) or a reference type (§4.3). A variable always contains a value that is assignment compatible (§5.2) with its type. A variable's value is changed by an assignment (§15.25) or by a prefix or postfix ++ (increment) or -- (decrement) operator (§15.13.2, §15.13.3, §15.14.1, §15.14.2).

Compatibility of the value of a variable with its type is guaranteed by the design of the Java language. Default values are compatible (§4.5.4) and all assignments to a variable are checked for assignment compatibility (§5.2), usually at compile time, but, in a single case involving arrays, a run-time check is made (§10.10).


4.5.1 Variables of Primitive Type

A variable of a primitive type always holds a value of that exact primitive type.


4.5.2 Variables of Reference Type

A variable of reference type can hold either of the following:

  • A null reference
  • A reference to any object (§4.3) whose class (§4.5.5) is assignment compatible (§5.2) with the type of the variable


4.5.3 Kinds of Variables

There are seven kinds of variables:

  • A class variable is a field declared using the keyword static within a class declaration (§8.3.1.1), or with or without the keyword static within an interface declaration (§9.3). A class variable is created when its class or interface is loaded (§12.2) and is initialized to a default value (§4.5.4). The class variable effectively ceases to exist when its class or interface is unloaded (§12.8), after any necessary finalization of the class or interface (§12.6) has been completed.
  • An instance variable is a field declared within a class declaration without using the keyword static (§8.3.1.1). If a class T has a field a that is an instance variable, then a new instance variable a is created and initialized to a default value (§4.5.4) as part of each newly created object of class T or of any class that is a subclass of T (§8.1.3). The instance variable effectively ceases to exist when the object of which it is a field is no longer referenced, after any necessary finalization of the object (§12.6) has been completed.
  • Array components are unnamed variables that are created and initialized to default values (§4.5.4) whenever a new object that is an array is created (§15.9). The array components effectively cease to exist when the array is no longer referenced. See §10 for a description of arrays.
  • Method parameters (§8.4.1) name argument values passed to a method. For every parameter declared in a method declaration, a new parameter variable is created each time that method is invoked (§15.11). The new variable is initialized with the corresponding argument value from the method invocation. The method parameter effectively ceases to exist when the execution of the body of the method is complete.
  • Constructor parameters (§8.6.1) name argument values passed to a constructor. For every parameter declared in a constructor declaration, a new parameter variable is created each time a class instance creation expression (§15.8) or explicit constructor invocation (§8.6.5) invokes that constructor. The new variable is initialized with the corresponding argument value from the creation expression or constructor invocation. The constructor parameter effectively ceases to exist when the execution of the body of the constructor is complete.
  • An exception-handler parameter is created each time an exception is caught by a catch clause of a try statement (§14.18). The new variable is initialized with the actual object associated with the exception (§11.3, §14.16). The exception-handler parameter effectively ceases to exist when execution of the block associated with the catch clause is complete.
  • Local variables are declared by local variable declaration statements (§14.3). Whenever the flow of control enters a block (§14.2) or for statement (§14.12), a new variable is created for each local variable declared in a local variable declaration statement immediately contained within that block or for statement. A local variable declaration statement may contain an expression which initializes the variable. The local variable with an initializing expression is not initialized, however, until the local variable declaration statement that declares it is executed. (The rules of definite assignment (§16) prevent the value of a local variable from being used before it has been initialized or otherwise assigned a value.) The local variable effectively ceases to exist when the execution of the block or for statement is complete.

Were it not for one exceptional situation, a local variable could always be regarded as being created when its local variable declaration statement is executed. The exceptional situation involves the switch statement (§14.9), where it is possible for control to enter a block but bypass execution of a local variable declaration statement. Because of the restrictions imposed by the rules of definite assignment (§16), however, the local variable declared by such a bypassed local variable declaration statement cannot be used before it has been definitely assigned a value by an assignment expression (§15.25).

The following example contains several different kinds of variables:

class Point {
    static int numPoints;								// numPoints is a class variable
    int x, y;								// x and y are instance variables
    int[] w = new int[10];								// w[0] is an array component
    int setX(int x) {								// x is a method parameter
        int oldx = this.x;							// oldx is a local variable
        this.x = x;
        return oldx;
    }
}


4.5.4 Initial Values of Variables

Every variable in a Java program must have a value before its value is used:

  • Each class variable, instance variable, or array component is initialized with a default value when it is created (§15.8, §15.9, §20.3.6):
    • For type byte, the default value is zero, that is, the value of (byte)0.
    • For type short, the default value is zero, that is, the value of (short)0.
    • For type int, the default value is zero, that is, 0.
    • For type long, the default value is zero, that is, 0L.
    • For type float, the default value is positive zero, that is, 0.0f.
    • For type double, the default value is positive zero, that is, 0.0d.
    • For type char, the default value is the null character, that is, '\u0000'.
    • For type boolean, the default value is false.
    • For all reference types (§4.3), the default value is null.
  • Each method parameter (§8.4.1) is initialized to the corresponding argument value provided by the invoker of the method (§15.11).
  • Each constructor parameter (§8.6.1) is initialized to the corresponding argument value provided by a class instance creation expression (§15.8) or explicit constructor invocation (§8.6.5).
  • An exception-handler parameter (§14.18) is initialized to the thrown object representing the exception (§11.3, §14.16).
  • A local variable (§14.3, §14.12) must be explicitly given a value before it is used, by either initialization (§14.3) or assignment (§15.25), in a way that can be verified by the compiler using the rules for definite assignment (§16).

The example program:

class Point {
    static int npoints;
    int x, y;
    Point root;
}

class Test {
    public static void main(String[] args) {
        System.out.println("npoints=" + Point.npoints);
        Point p = new Point();
        System.out.println("p.x=" + p.x + ", p.y=" + p.y);
        System.out.println("p.root=" + p.root);
    }
}

prints:

npoints=0
p.x=0, p.y=0
p.root=null

illustrating the default initialization of npoints, which occurs when the class Point is prepared (§12.3.2), and the default initialization of x, y, and root, which occurs when a new Point is instantiated. See §12 for a full description of all aspects of loading, linking, and initialization of classes and interfaces, plus a description of the instantiation of classes to make new class instances.


4.5.5 Variables Have Types, Objects Have Classes

Every object belongs to some particular class: the class that was mentioned in the creation expression that produced the object, the class whose class object was used to invoke the newInstance method (§20.3.6) to produce the object, or the String class for objects implicitly created by the string concatenation operator + (§15.17.1). This class is called the class of the object. (Arrays also have a class, as described at the end of this section.) An object is said to be an instance of its class and of all superclasses of its class.

(Sometimes a variable or expression is said to have a "run-time type" but that is an abuse of terminology; it refers to the class of the object referred to by the value of the variable or expression at run time, assuming that the value is not null. Properly speaking, type is a compile-time notion. A variable or expression has a type; an object or array has no type, but belongs to a class.)

The type of a variable is always declared, and the type of an expression can be deduced at compile time. The type limits the possible values that the variable can hold or the expression can produce at run time. If a run-time value is a reference that is not null, it refers to an object or array that has a class (not a type), and that class will necessarily be compatible with the compile-time type.

Even though a variable or expression may have a compile-time type that is an interface type, there are no instances of interfaces. A variable or expression whose type is an interface type can reference any object whose class implements (§8.1.4) that interface.

Here is an example of creating new objects and of the distinction between the type of a variable and the class of an object:

public interface Colorable {
    void setColor(byte r, byte g, byte b);
}

class Point { int x, y; }

class ColoredPoint extends Point implements Colorable {

    byte r, g, b;

    public void setColor(byte rv, byte gv, byte bv) {
        r = rv; g = gv; b = bv;
    }

}

class Test {
    public static void main(String[] args) {
        Point p = new Point();
        ColoredPoint cp = new ColoredPoint();
        p = cp;
        Colorable c = cp;
    }
}

In this example:

  • The local variable p of the method main of class Test has type Point and is initially assigned a reference to a new instance of class Point.
  • The local variable cp similarly has as its type ColoredPoint, and is initially assigned a reference to a new instance of class ColoredPoint.
  • The assignment of the value of cp to the variable p causes p to hold a reference to a ColoredPoint object. This is permitted because ColoredPoint is a subclass of Point, so the class ColoredPoint is assignment compatible (§5.2) with the type Point. A ColoredPoint object includes support for all the methods of a Point. In addition to its particular fields r, g, and b, it has the fields of class Point, namely x and y.
  • The local variable c has as its type the interface type Colorable, so it can hold a reference to any object whose class implements Colorable; specifically, it can hold a reference to a ColoredPoint.
  • Note that an expression such as "new Colorable()" is not valid because it is not possible to create an instance of an interface, only of a class.

Every array also has a class; the method getClass (§20.1.1), when invoked for an array object, will return a class object (of class Class) that represents the class of the array. The classes for arrays have strange names that are not valid Java identifiers; for example, the class for an array of int components has the name "[I" and so the value of the expression:

new int[10].getClass().getName()

is the string "[I"; see §20.1.1 for details.

Oft on the dappled turf at ease
I sit, and play with similes,
Loose types of things through all degrees.
—William Wordsworth, To the Same Flower


 5. Conversions and Promotions

CHAPTER 5

Conversions and Promotions

Thou art not for the fashion of these times,
Where none will sweat but for promotion.
—William Shakespeare, As You Like It, Act II, scene iii

Every Java expression has a type that can be deduced from the structure of the expression and the types of the literals, variables, and methods mentioned in the expression. It is possible, however, to write an expression in a context where the type of the expression is not appropriate. In some cases, this leads to an error at compile time; for example, if the expression in an if statement (§14.8) has any type other than boolean, a compile-time error occurs. In other cases, the context may be able to accept a type that is related to the type of the expression; as a convenience, rather than requiring the programmer to indicate a type conversion explicitly, the Java language performs an implicit conversion from the type of the expression to a type acceptable for its surrounding context.

A specific conversion from type S to type T allows an expression of type S to be treated at compile time as if it had type T instead. In some cases this will require a corresponding action at run time to check the validity of the conversion or to translate the run-time value of the expression into a form appropriate for the new type T. For example:

  • A conversion from type Object (§20.1) to type Thread (§20.20) requires a run-time check to make sure that the run-time value is actually an instance of class Thread or one of its subclasses; if it is not, an exception is thrown.
  • A conversion from type Thread to type Object requires no run-time action; Thread is a subclass of Object, so any reference produced by an expression of type Thread is a valid reference value of type Object.
  • A conversion from type int to type long requires run-time sign-extension of a 32-bit integer value to the 64-bit long representation. No information is lost.
  • A conversion from type double to type long requires a nontrivial translation from a 64-bit floating-point value to the 64-bit integer representation. Depending on the actual run-time value, information may be lost.

In every conversion context, only certain specific conversions are permitted. The specific conversions that are possible in Java are grouped for convenience of description into several broad categories:

  • Identity conversions
  • Widening primitive conversions
  • Narrowing primitive conversions
  • Widening reference conversions
  • Narrowing reference conversions
  • String conversions

There are five conversion contexts in which conversion of Java expressions may occur. Each context allows conversions in some of the categories named above but not others. The term "conversion" is also used to describe the process of choosing a specific conversion for such a context. For example, we say that an expression that is an actual argument in a method invocation is subject to "method invocation conversion," meaning that a specific conversion will be implicitly chosen for that expression according to the rules for the method invocation argument context.

One conversion context is the operand of a numeric operator such as + or *. The conversion process for such operands is called numeric promotion. Promotion is special in that, in the case of binary operators, the conversion chosen for one operand may depend in part on the type of the other operand expression.

This chapter first describes the six categories of conversions (§5.1), including the special conversions to String allowed for the string concatenation operator +. Then the five conversion contexts are described:

  • Assignment conversion (§5.2, §15.25) converts the type of an expression to the type of a specified variable. The conversions permitted for assignment are limited in such a way that assignment conversion never causes an exception.
  • Method invocation conversion (§5.3, §15.8, §15.11) is applied to each argument in a method or constructor invocation and, except in one case, performs the same conversions that assignment conversion does. Method invocation conversion never causes an exception.
  • Casting conversion (§5.4) converts the type of an expression to a type explicitly specified by a cast operator (§15.15). It is more inclusive than assignment or method invocation conversion, allowing any specific conversion other than a string conversion, but certain casts to a reference type may cause an exception at run time.
  • String conversion (§5.4, §15.17.1) allows any type to be converted to type String.
  • Numeric promotion (§5.6) brings the operands of a numeric operator to a common type so that an operation can be performed.

Here are some examples of the various contexts for conversion:

class Test {

    public static void main(String[] args) {

        // Casting conversion (§5.4) of a float literal to
        // type int. Without the cast operator, this would
        // be a compile-time error, because this is a
        // narrowing conversion (§5.1.3):
        int i = (int)12.5f;

        // String conversion (§5.4) of i's int value:
        System.out.println("(int)12.5f==" + i);

        // Assignment conversion (§5.2) of i's value to type
        // float. This is a widening conversion (§5.1.2):
        float f = i;

        // String conversion of f's float value:
        System.out.println("after float widening: " + f);

        // Numeric promotion (§5.6) of i's value to type
        // float. This is a binary numeric promotion.
        // After promotion, the operation is float*float:
        System.out.print(f);
        f = f * i;

        // Two string conversions of i and f:
        System.out.println("*" + i + "==" + f);

        // Method invocation conversion (§5.3) of f's value
        // to type double, needed because the method Math.sin
        // accepts only a double argument:
        double d = Math.sin(f);

        // Two string conversions of f and d:
        System.out.println("Math.sin(" + f + ")==" + d);

    }

}

which produces the output:

(int)12.5f==12
after float widening: 12.0
12.0*12==144.0
Math.sin(144.0)==-0.49102159389846934


5.1 Kinds of Conversion

Specific type conversions in Java are divided into six categories.


5.1.1 Identity Conversions

A conversion from a type to that same type is permitted for any type. This may seem trivial, but it has two practical consequences. First, it is always permitted for an expression to have the desired type to begin with, thus allowing the simply stated rule that every expression is subject to conversion, if only a trivial identity conversion. Second, it implies that it is permitted for a program to include redundant cast operators for the sake of clarity.

The only permitted conversion that involves the type boolean is the identity conversion from boolean to boolean.


5.1.2 Widening Primitive Conversions

The following 19 specific conversions on primitive types are called the widening primitive conversions:

  • byte to short, int, long, float, or double
  • short to int, long, float, or double
  • char to int, long, float, or double
  • int to long, float, or double
  • long to float or double
  • float to double

Widening primitive conversions do not lose information about the overall magnitude of a numeric value. Indeed, conversions widening from an integral type to another integral type and from float to double do not lose any information at all; the numeric value is preserved exactly. Conversion of an int or a long value to float, or of a long value to double, may result in loss of precision-that is, the result may lose some of the least significant bits of the value. In this case, the resulting floating-point value will be a correctly rounded version of the integer value, using IEEE 754 round-to-nearest mode (§4.2.4).

A widening conversion of a signed integer value to an integral type T simply sign-extends the two's-complement representation of the integer value to fill the wider format. A widening conversion of a character to an integral type T zero-extends the representation of the character value to fill the wider format.

Despite the fact that loss of precision may occur, widening conversions among primitive types never result in a run-time exception (§11).

Here is an example of a widening conversion that loses precision:

class Test {
    public static void main(String[] args) {
        int big = 1234567890;
        float approx = big;
        System.out.println(big - (int)approx);
    }
}

which prints:

-46

thus indicating that information was lost during the conversion from type int to type float because values of type float are not precise to nine significant digits.


5.1.3 Narrowing Primitive Conversions

The following 23 specific conversions on primitive types are called the narrowing primitive conversions:

  • byte to char
  • short to byte or char
  • char to byte or short
  • int to byte, short, or char
  • long to byte, short, char, or int
  • float to byte, short, char, int, or long
  • double to byte, short, char, int, long, or float

Narrowing conversions may lose information about the overall magnitude of a numeric value and may also lose precision.

A narrowing conversion of a signed integer to an integral type T simply discards all but the n lowest order bits, where n is the number of bits used to represent type T. In addition to a possible loss of information about the magnitude of the numeric value, this may cause the sign of the resulting value to differ from the sign of the input value.

A narrowing conversion of a character to an integral type T likewise simply discards all but the n lowest order bits, where n is the number of bits used to represent type T. In addition to a possible loss of information about the magnitude of the numeric value, this may cause the resulting value to be a negative number, even though characters represent 16-bit unsigned integer values.

A narrowing conversion of a floating-point number to an integral type T takes two steps:

  • In the first step, the floating-point number is converted either to a long, if T is long, or to an int, if T is byte, short, char, or int, as follows:
    • If the floating-point number is NaN (§4.2.3), the result of the first step of the conversion is an int or long 0.
    • Otherwise, if the floating-point number is not an infinity, the floating-point value is rounded to an integer value V, rounding toward zero using IEEE 754 round-toward-zero mode (§4.2.3). Then there are two cases:
      • If T is long, and this integer value can be represented as a long, then the result of the first step is the long value V.
      • Otherwise, if this integer value can be represented as an int, then the result of the first step is the int value V.
    • Otherwise, one of the following two cases must be true:
      • The value must be too small (a negative value of large magnitude or negative infinity), and the result of the first step is the smallest representable value of type int or long.
      • The value must be too large (a positive value of large magnitude or positive infinity), and the result of the first step is the largest representable value of type int or long.
  • In the second step:
    • If T is int or long, the result of the conversion is the result of the first step.
    • If T is byte, char, or short, the result of the conversion is the result of a narrowing conversion to type T (§5.1.3) of the result of the first step.

The example:

class Test {
    public static void main(String[] args) {
        float fmin = Float.NEGATIVE_INFINITY;
        float fmax = Float.POSITIVE_INFINITY;
        System.out.println("long: " + (long)fmin +
                                ".." + (long)fmax);
        System.out.println("int: " + (int)fmin +
                                ".." + (int)fmax);
        System.out.println("short: " + (short)fmin +
                                ".." + (short)fmax);
        System.out.println("char: " + (int)(char)fmin +
                                ".." + (int)(char)fmax);
        System.out.println("byte: " + (byte)fmin +
                                ".." + (byte)fmax);
    }
}

produces the output:

long: -9223372036854775808..9223372036854775807
int: -2147483648..2147483647
short: 0..-1
char: 0..65535
byte: 0..-1

The results for char, int, and long are unsurprising, producing the minimum and maximum representable values of the type.

The results for byte and short lose information about the sign and magnitude of the numeric values and also lose precision. The results can be understood by examining the low order bits of the minimum and maximum int. The minimum int is, in hexadecimal, 0x80000000, and the maximum int is 0x7fffffff. This explains the short results, which are the low 16 bits of these values, namely, 0x0000 and 0xffff; it explains the char results, which also are the low 16 bits of these values, namely, '\u0000' and '\uffff'; and it explains the byte results, which are the low 8 bits of these values, namely, 0x00 and 0xff.

A narrowing conversion from double to float behaves in accordance with IEEE 754. The result is correctly rounded using IEEE 754 round-to-nearest mode. A value too small to be represented as a float is converted to positive or negative zero; a value too large to be represented as a float is converted to a (positive or negative) infinity. A double NaN is always converted to a float NaN.

Despite the fact that overflow, underflow, or other loss of information may occur, narrowing conversions among primitive types never result in a run-time exception (§11).

Here is a small test program that demonstrates a number of narrowing conversions that lose information:

class Test {

    public static void main(String[] args) {

        // A narrowing of int to short loses high bits:
        System.out.println("(short)0x12345678==0x" +
                    Integer.toHexString((short)0x12345678));

        // A int value not fitting in byte changes sign and magnitude:
        System.out.println("(byte)255==" + (byte)255);

        // A float value too big to fit gives largest int value:
        System.out.println("(int)1e20f==" + (int)1e20f);

        // A NaN converted to int yields zero:
        System.out.println("(int)NaN==" + (int)Float.NaN);

        // A double value too large for float yields infinity:
        System.out.println("(float)-1e100==" + (float)-1e100);

        // A double value too small for float underflows to zero:
        System.out.println("(float)1e-50==" + (float)1e-50);

    }

}

This test program produces the following output:

(short)0x12345678==0x5678
(byte)255==-1
(int)1e20f==2147483647
(int)NaN==0
(float)-1e100==-Infinity
(float)1e-50==0.0


5.1.4 Widening Reference Conversions

The following conversions are called the widening reference conversions:

  • From any class type S to any class type T, provided that S is a subclass of T. (An important special case is that there is a widening conversion to the class type Object from any other class type.)
  • From any class type S to any interface type K, provided that S implements K.
  • From the null type to any class type, interface type, or array type.
  • From any interface type J to any interface type K, provided that J is a subinterface of K.
  • From any interface type to type Object.
  • From any array type to type Object.
  • From any array type to type Cloneable.
  • From any array type SC[] to any array type TC[], provided that SC and TC are reference types and there is a widening conversion from SC to TC.

Such conversions never require a special action at run time and therefore never throw an exception at run time. They consist simply in regarding a reference as having some other type in a manner that can be proved correct at compile time.

See §8 for the detailed specifications for classes, §9 for interfaces, and §10 for arrays.


5.1.5 Narrowing Reference Conversions

The following conversions are called the narrowing reference conversions:

  • From any class type S to any class type T, provided that S is a superclass of T. (An important special case is that there is a narrowing conversion from the class type Object to any other class type.)
  • From any class type S to any interface type K, provided that S is not final and does not implement K. (An important special case is that there is a narrowing conversion from the class type Object to any interface type.)
  • From type Object to any array type.
  • From type Object to any interface type.
  • From any interface type J to any class type T that is not final.
  • From any interface type J to any class type T that is final, provided that T implements J.
  • From any interface type J to any interface type K, provided that J is not a subinterface of K and there is no method name m such that J and K both declare a method named m with the same signature but different return types.
  • From any array type SC[] to any array type TC[], provided that SC and TC are reference types and there is a narrowing conversion from SC to TC.

Such conversions require a test at run time to find out whether the actual reference value is a legitimate value of the new type. If not, then a ClassCastException is thrown.


5.1.6 String Conversions

There is a string conversion to type String from every other type, including the null type.


5.1.7 Forbidden Conversions

  • There is no permitted conversion from any reference type to any primitive type.
  • Except for the string conversions, there is no permitted conversion from any primitive type to any reference type.
  • There is no permitted conversion from the null type to any primitive type.
  • There is no permitted conversion to the null type other than the identity conversion.
  • There is no permitted conversion to the type boolean other than the identity conversion.
  • There is no permitted conversion from the type boolean other than the identity conversion and string conversion.
  • There is no permitted conversion other than string conversion from class type S to a different class type T if S is not a subclass of T and T is not a subclass of S.
  • There is no permitted conversion from class type S to interface type K if S is final and does not implement K.
  • There is no permitted conversion from class type S to any array type if S is not Object.
  • There is no permitted conversion other than string conversion from interface type J to class type T if T is final and does not implement J.
  • There is no permitted conversion from interface type J to interface type K if J and K declare methods with the same signature but different return types.
  • There is no permitted conversion from any array type to any class type other than Object or String.
  • There is no permitted conversion from any array type to any interface type, except to the interface type Cloneable, which is implemented by all arrays.
  • There is no permitted conversion from array type SC[] to array type TC[] if there is no permitted conversion other than a string conversion from SC to TC.


5.2 Assignment Conversion

Assignment conversion occurs when the value of an expression is assigned (§15.25) to a variable: the type of the expression must be converted to the type of the variable. Assignment contexts allow the use of an identity conversion (§5.1.1), a widening primitive conversion (§5.1.2), or a widening reference conversion (§5.1.4). In addition, a narrowing primitive conversion may be used if all of the following conditions are satisfied:

  • The expression is a constant expression of type int.
  • The type of the variable is byte, short, or char.
  • The value of the expression (which is known at compile time, because it is a constant expression) is representable in the type of the variable.

If the type of the expression cannot be converted to the type of the variable by a conversion permitted in an assignment context, then a compile-time error occurs.

If the type of an expression can be converted to the type a variable by assignment conversion, we say the expression (or its value) is assignable to the variable or, equivalently, that the type of the expression is assignment compatible with the type of the variable.

An assignment conversion never causes an exception. (Note, however, that an assignment may result in an exception in a special case involving array elements -see §10.10 and §15.25.1.)

The compile-time narrowing of constants means that code such as:

byte theAnswer = 42;

is allowed. Without the narrowing, the fact that the integer literal 42 has type int would mean that a cast to byte would be required:

byte theAnswer = (byte)42;									// cast is permitted but not required

A value of primitive type must not be assigned to a variable of reference type; an attempt to do so will result in a compile-time error. A value of type boolean can be assigned only to a variable of type boolean.

The following test program contains examples of assignment conversion of primitive values:

class Test {
    public static void main(String[] args) {
        short s = 12;							// narrow 12 to short
        float f = s;							// widen short to float
        System.out.println("f=" + f);

        char c = '\u0123';
        long l = c;							// widen char to long
        System.out.println("l=0x" + Long.toString(l,16));

        f = 1.23f;
        double d = f;							// widen float to double
        System.out.println("d=" + d);
    }
}

It produces the following output:

f=12.0
i=0x123
d=1.2300000190734863

The following test, however, produces compile-time errors:

class Test {
    public static void main(String[] args) {
        short s = 123;
        char c = s;							// error: would require cast
        s = c;							// error: would require cast
    }
}

because not all short values are char values, and neither are all char values short values.

A value of reference type must not be assigned to a variable of primitive type; an attempt to do so will result in a compile-time error.

A value of the null type (the null reference is the only such value) may be assigned to any reference type, resulting in a null reference of that type.

Here is a sample program illustrating assignments of references:

public class Point { int x, y; }

public class Point3D extends Point { int z; }

public interface Colorable {
    void setColor(int color);
}

public class ColoredPoint extends Point implements Colorable
{
    int color;
    public void setColor(int color) { this.color = color; }
}

class Test {

    public static void main(String[] args) {

        // Assignments to variables of class type:
        Point p = new Point();
        p = new Point3D();							// ok: because Point3d is a
                                    // subclass of Point

        Point3D p3d = p;							// error: will require a cast because a
                                    // Point might not be a Point3D
                                    // (even though it is, dynamically,
                                    // in this example.)

        // Assignments to variables of type Object:
        Object o = p;							// ok: any object to Object
        int[] a = new int[3];
        Object o2 = a;							// ok: an array to Object

        // Assignments to variables of interface type:
        ColoredPoint cp = new ColoredPoint();
        Colorable c = cp;							// ok: ColoredPoint implements
                                    // Colorable

        // Assignments to variables of array type:
        byte[] b = new byte[4];
        a = b;							// error: these are not arrays
                                    // of the same primitive type
        Point3D[] p3da = new Point3D[3];
        Point[] pa = p3da;							// ok: since we can assign a
                                    // Point3D to a Point
        p3da = pa;							// error: (cast needed) since a Point
                                    // can't be assigned to a Point3D

    }

}

Assignment of a value of compile-time reference type S (source) to a variable of compile-time reference type T (target) is checked as follows:

  • If S is a class type:
    • If T is a class type, then S must either be the same class as T, or S must be a subclass of T, or a compile-time error occurs.
    • If T is an interface type, then S must implement interface T, or a compile-time error occurs.
    • If T is an array type, then a compile-time error occurs.
  • If S is an interface type:
    • If T is a class type, then T must be Object, or a compile-time error occurs.
    • If T is an interface type, then T must be either the same interface as S or a superinterface of S, or a compile-time error occurs.
    • If T is an array type, then a compile-time error occurs.
  • If S is an array type SC[], that is, an array of components of type SC:
    • If T is a class type, then T must be Object, or a compile-time error occurs.
    • If T is an interface type, then a compile-time error occurs unless T is the interface type Cloneable, the only interface implemented by arrays.
    • If T is an array type TC[], that is, an array of components of type TC, then a compile-time error occurs unless one of the following is true:
      • TC and SC are the same primitive type.
      • TC and SC are both reference types and type SC is assignable to TC, as determined by a recursive application of these compile-time rules for assignability.

See §8 for the detailed specifications for classes, §9 for interfaces, and §10 for arrays.

The following test program illustrates assignment conversions on reference values, but fails to compile because it violates the preceding rules, as described in its comments. This example should be compared to the preceding one.

public class Point { int x, y; }

public interface Colorable { void setColor(int color); }

public class ColoredPoint extends Point implements Colorable
{
    int color;
    public void setColor(int color) { this.color = color; }
}

class Test {

    public static void main(String[] args) {

        Point p = new Point();

        ColoredPoint cp = new ColoredPoint();

        // Okay because ColoredPoint is a subclass of Point:
        p = cp;

        // Okay because ColoredPoint implements Colorable:
        Colorable c = cp;

        // The following cause compile-time errors because
        // we cannot be sure they will succeed, depending on
        // the run-time type of p; a run-time check will be
        // necessary for the needed narrowing conversion and
        // must be indicated by including a cast:
        cp = p;				// p might be neither a ColoredPoint
                        // nor a subclass of ColoredPoint
        c = p;				// p might not implement Colorable

    }

}

Here is another example involving assignment of array objects:

class Point { int x, y; }

class ColoredPoint extends Point { int color; }

class Test {
    public static void main(String[] args) {
        long[] veclong = new long[100];
        Object o = veclong;									// okay
        Long l = veclong;									// compile-time error
        short[] vecshort = veclong;									// compile-time error
        Point[] pvec = new Point[100];
        ColoredPoint[] cpvec = new ColoredPoint[100];
        pvec = cpvec;									// okay
        pvec[0] = new Point();									// okay at compile time,
                                            // but would throw an
                                            // exception at run time
        cpvec = pvec;									// compile-time error
    }
}

In this example:

  • The value of veclong cannot be assigned to a Long variable, because Long is a class type (§20.8) other than Object. An array can be assigned only to a variable of a compatible array type, or to a variable of type Object.
  • The value of veclong cannot be assigned to vecshort, because they are arrays of primitive type, and short and long are not the same primitive type.
  • The value of cpvec can be assigned to pvec, because any reference that could be the value of an expression of type ColoredPoint can be the value of a variable of type Point. The subsequent assignment of the new Point to a component of pvec then would throw an ArrayStoreException (if the program were otherwise corrected so that it could be compiled), because a ColoredPoint array can't have an instance of Point as the value of a component.
  • The value of pvec cannot be assigned to cpvec, because not every reference that could be the value of an expression of type ColoredPoint can correctly be the value of a variable of type Point. If the value of pvec at run time were a reference to an instance of Point[], and the assignment to cpvec were allowed, a simple reference to a component of cpvec, say, cpvec[0], could return a Point, and a Point is not a ColoredPoint. Thus to allow such an assignment would allow a violation of the type system. A cast may be used (§5.4, §15.15) to ensure that pvec references a ColoredPoint[]:

        cpvec = (ColoredPoint[])pvec;										// okay, but may throw an
                                                // exception at run time


5.3 Method Invocation Conversion

Method invocation conversion is applied to each argument value in a method or constructor invocation (§15.8, §15.11): the type of the argument expression must be converted to the type of the corresponding parameter. Method invocation contexts allow the use of an identity conversion (§5.1.1), a widening primitive conversion (§5.1.2), or a widening reference conversion (§5.1.4).

Method invocation conversions specifically do not include the implicit narrowing of integer constants which is part of assignment conversion (§5.2). The Java designers felt that including these implicit narrowing conversions would add additional complexity to the overloaded method matching resolution process (§15.11.2). Thus, the example:

class Test {

    static int m(byte a, int b) { return a+b; }

    static int m(short a, short b) { return a-b; }

    public static void main(String[] args) {
        System.out.println(m(12, 2));										// compile-time error
    }

}

causes a compile-time error because the integer literals 12 and 2 have type int, so neither method m matches under the rules of (§15.11.2). A language that included implicit narrowing of integer constants would need additional rules to resolve cases like this example.


5.4 String Conversion

String conversion applies only to the operands of the binary + operator when one of the arguments is a String. In this single special case, the other argument to the + is converted to a String, and a new String which is the concatenation of the two strings is the result of the +. String conversion is specified in detail within the description of the string concatenation + operator (§15.17.1).


5.5 Casting Conversion

Sing away sorrow, cast away care.

-Miguel de Cervantes (1547-1616),
Don Quixote (Lockhart's translation), Chapter viii

Casting conversion is applied to the operand of a cast operator (§15.15): the type of the operand expression must be converted to the type explicitly named by the cast operator. Casting contexts allow the use of an identity conversion (§5.1.1), a widening primitive conversion (§5.1.2), a narrowing primitive conversion (§5.1.3), a widening reference conversion (§5.1.4), or a narrowing reference conversion (§5.1.5). Thus casting conversions are more inclusive than assignment or method invocation conversions: a cast can do any permitted conversion other than a string conversion.

Some casts can be proven incorrect at compile time; such casts result in a compile-time error.

A value of a primitive type can be cast to another primitive type by identity conversion, if the types are the same, or by a widening primitive conversion or a narrowing primitive conversion.

A value of a primitive type cannot be cast to a reference type by casting conversion, nor can a value of a reference type be cast to a primitive type.

The remaining cases involve conversion between reference types. The detailed rules for compile-time correctness checking of a casting conversion of a value of compile-time reference type S (source) to a compile-time reference type T (target) are as follows:

  • If S is a class type:
    • If T is a class type, then S and T must be related classes-that is, S and T must be the same class, or S a subclass of T, or T a subclass of S; otherwise a compile-time error occurs.
    • If T is an interface type:
      • If S is not a final class (§8.1.2), then the cast is always correct at compile time (because even if S does not implement T, a subclass of S might).
      • If S is a final class (§8.1.2), then S must implement T, or a compile-time error occurs.
    • If T is an array type, then S must be the class Object, or a compile-time error occurs.
  • If S is an interface type:
    • If T is a class type that is not final (§8.1.2), then the cast is always correct at compile time (because even if T does not implement S, a subclass of T might).
    • If T is a class type that is final (§8.1.2), then T must implement S, or a compile-time error occurs.
    • If T is an interface type and if T and S contain methods with the same signature (§8.4.2) but different return types, then a compile-time error occurs.
  • If S is an array type SC[], that is, an array of components of type SC:
    • If T is a class type, then if T is not Object, then a compile-time error occurs (because Object is the only class type to which arrays can be assigned).
    • If T is an interface type, then a compile-time error occurs unless T is the interface type Cloneable, the only interface implemented by arrays.
    • If T is an array type TC[], that is, an array of components of type TC, then a compile-time error occurs unless one of the following is true:
      • TC and SC are the same primitive type.
      • TC and SC are reference types and type SC can be cast to TC by a recursive application of these compile-time rules for casting.

See §8 for the detailed specifications of classes, §9 for interfaces, and §10 for arrays.

If a cast to a reference type is not a compile-time error, there are two cases:

  • The cast can be determined to be correct at compile time. A cast from the compile-time type S to compile-time type T is correct at compile time if and only if S can be converted to T by assignment conversion (§5.2).
  • The cast requires a run-time validity check. If the value at run time is null, then the cast is allowed. Otherwise, let R be the class of the object referred to by the run-time reference value, and let T be the type named in the cast operator. A cast conversion must check, at run time, that the class R is assignment compatible with the type T, using the algorithm specified in §5.2 but using the class R instead of the compile-time type S as specified there. (Note that R cannot be an interface when these rules are first applied for any given cast, but R may be an interface if the rules are applied recursively because the run-time reference value refers to an array whose element type is an interface type.) This modified algorithm is shown here:
    • If R is an ordinary class (not an array class):
      • If T is a class type, then R must be either the same class (§4.3.4) as T or a subclass of T, or a run-time exception is thrown.
      • If T is an interface type, then R must implement (§8.1.4) interface T, or a run-time exception is thrown.
      • If T is an array type, then a run-time exception is thrown.
    • If R is an interface:
      • If T is a class type, then T must be Object (§4.3.2, §20.1), or a run-time exception is thrown.
      • If T is an interface type, then R must be either the same interface as T or a subinterface of T, or a run-time exception is thrown.
      • If T is an array type, then a run-time exception is thrown.
    • If R is a class representing an array type RC[]-that is, an array of components of type RC:
      • If T is a class type, then T must be Object (§4.3.2, §20.1), or a run-time exception is thrown.
      • If T is an interface type, then a run-time exception is thrown unless T is the interface type Cloneable, the only interface implemented by arrays (this case could slip past the compile-time checking if, for example, a reference to an array were stored in a variable of type Object).
      • If T is an array type TC[], that is, an array of components of type TC, then a run-time exception is thrown unless one of the following is true:
        • TC and RC are the same primitive type.
        • TC and RC are reference types and type RC can be cast to TC by a recursive application of these run-time rules for casting.

If a run-time exception is thrown, it is a ClassCastException (§11.5.1.1, §20.22).

Here are some examples of casting conversions of reference types, similar to the example in §5.2:

public class Point { int x, y; }

public interface Colorable { void setColor(int color); }

public class ColoredPoint extends Point implements Colorable
{
    int color;
    public void setColor(int color) { this.color = color; }
}

final class EndPoint extends Point { }

class Test {

    public static void main(String[] args) {
        Point p = new Point();
        ColoredPoint cp = new ColoredPoint();
        Colorable c;

        // The following may cause errors at run time because
        // we cannot be sure they will succeed; this possibility
        // is suggested by the casts:
        cp = (ColoredPoint)p;							// p might not reference an
                                    // object which is a ColoredPoint
                                    // or a subclass of ColoredPoint
        c = (Colorable)p;							// p might not be Colorable

        // The following are incorrect at compile time because
        // they can never succeed as explained in the text:
        Long l = (Long)p;							// compile-time error #1
        EndPoint e = new EndPoint();
        c = (Colorable)e;							// compile-time error #2

    }

}

Here the first compile-time error occurs because the class types Long and Point are unrelated (that is, they are not the same, and neither is a subclass of the other), so a cast between them will always fail.

The second compile-time error occurs because a variable of type EndPoint can never reference a value that implements the interface Colorable. This is because EndPoint is a final type, and a variable of a final type always holds a value of the same run-time type as its compile-time type. Therefore, the run-time type of variable e must be exactly the type EndPoint, and type EndPoint does not implement Colorable.

Here is an example involving arrays (§10):

class Point {

    int x, y;

    Point(int x, int y) { this.x = x; this.y = y; }

    public String toString() { return "("+x+","+y+")"; }

}

public interface Colorable { void setColor(int color); }

public class ColoredPoint extends Point implements Colorable
{

    int color;

    ColoredPoint(int x, int y, int color) {
        super(x, y); setColor(color);
    }

    public void setColor(int color) { this.color = color; }

    public String toString() {
        return super.toString() + "@" + color;
    }

}

class Test {

    public static void main(String[] args) {
        Point[] pa = new ColoredPoint[4];
        pa[0] = new ColoredPoint(2, 2, 12);
        pa[1] = new ColoredPoint(4, 5, 24);
        ColoredPoint[] cpa = (ColoredPoint[])pa;
        System.out.print("cpa: {");
        for (int i = 0; i < cpa.length; i++)
            System.out.print((i == 0 ? " " : ", ") + cpa[i]);
        System.out.println(" }");
    }

}

This example compiles without errors and produces the output:

cpa: { (2,2)@12, (4,5)@24, null, null }

The following example uses casts to compile, but it throws exceptions at run time, because the types are incompatible:

public class Point { int x, y; }

public interface Colorable { void setColor(int color); }

public class ColoredPoint extends Point implements Colorable
{

    int color;

    public void setColor(int color) { this.color = color; }

}

class Test {

    public static void main(String[] args) {

        Point[] pa = new Point[100];

        // The following line will throw a ClassCastException:
        ColoredPoint[] cpa = (ColoredPoint[])pa;

        System.out.println(cpa[0]);

        int[] shortvec = new int[2];

        Object o = shortvec;

        // The following line will throw a ClassCastException:
        Colorable c = (Colorable)o;

        c.setColor(0);

    }

}


5.6 Numeric Promotions

Numeric promotion is applied to the operands of an arithmetic operator. Numeric promotion contexts allow the use of an identity conversion (§5.1.1) or a widening primitive conversion (§5.1.2).

Numeric promotions are used to convert the operands of a numeric operator to a common type so that an operation can be performed. The two kinds of numeric promotion are unary numeric promotion (§5.6.1) and binary numeric promotion (§5.6.2). The analogous conversions in C are called "the usual unary conversions" and "the usual binary conversions."

Numeric promotion is not a general feature of Java, but rather a property of the specific definitions of the built-in operations.


5.6.1 Unary Numeric Promotion

Some operators apply unary numeric promotion to a single operand, which must produce a value of a numeric type:

  • If the operand is of compile-time type byte, short, or char, unary numeric promotion promotes it to a value of type int by a widening conversion (§5.1.2).
  • Otherwise, a unary numeric operand remains as is and is not converted.

Unary numeric promotion is performed on expressions in the following situations:

  • The dimension expression in array creations (§15.9)
  • The index expression in array access expressions (§15.12)
  • Operands of the unary operators plus + (§15.14.3) and minus - (§15.14.4)
  • The operand of the bitwise complement operator ~ (§15.14.5)
  • Each operand, separately, of the shift operators >>, >>>, and << (§15.18), so that a long shift distance (right operand) does not promote the value being shifted (left operand) to long

Here is a test program that includes examples of unary numeric promotion:

class Test {
    public static void main(String[] args) {
        byte b = 2;
        int a[] = new int[b];							// dimension expression promotion
        char c = '\u0001';
        a[c] = 1;							// index expression promotion
        a[0] = -c;							// unary - promotion
        System.out.println("a: " + a[0] + "," + a[1]);

        b = -1;
        int i = ~b;							// bitwise complement promotion
        System.out.println("~0x" + Integer.toHexString(b)
                            + "==0x" + Integer.toHexString(i));

        i = b << 4L;							// shift promotion (left operand)
        System.out.println("0x" + Integer.toHexString(b)
                     + "<<4L==0x" + Integer.toHexString(i));
    }
}

This test program produces the output:

a: -1,1
~0xffffffff==0x0
0xffffffff<<4L==0xfffffff0


5.6.2 Binary Numeric Promotion

When an operator applies binary numeric promotion to a pair of operands, each of which must denote a value of a numeric type, the following rules apply, in order, using widening conversion (§5.1.2) to convert operands as necessary:

  • If either operand is of type double, the other is converted to double.
  • Otherwise, if either operand is of type float, the other is converted to float.
  • Otherwise, if either operand is of type long, the other is converted to long.
  • Otherwise, both operands are converted to type int.

Binary numeric promotion is performed on the operands of certain operators:

  • The multiplicative operators *, / and % (§15.16)
  • The addition and subtraction operators for numeric types + and - (§15.17.2)
  • The numerical comparison operators <, <=, >, and >= (§15.19.1)
  • The numerical equality operators == and != (§15.20.1)
  • The integer bitwise operators &, ^, and | (§15.21.1)
  • In certain cases, the conditional operator ? : (§15.24)

An example of binary numeric promotion appears above in §5.1. Here is another:

class Test {
    public static void main(String[] args) {
        int i = 0;
        float f = 1.0f;
        double d = 2.0;

        // First i*f promoted to float*float, then
        // float==double is promoted to double==double:
        if (i * f == d)
            System.out.println("oops");

        // A char&byte is promoted to int&int:
        byte b = 0x1f;
        char c = 'G';
        int control = c & b;
        System.out.println(Integer.toHexString(control));

        // A int:float promoted to float:float:
        f = (b==0) ? f : 4.0f;
        System.out.println(1.0/f);

    }

}

which produces the output:

7
0.25

The example converts the ASCII character G to the ASCII control-G (BEL), by masking off all but the low 5 bits of the character. The 7 is the numeric value of this control character.

O suns! O grass of graves! O perpetual transfers and promotions!
—Walt Whitman, Walt Whitman (1855) in Leaves of Grass


 6. Names

CHAPTER 6

Names

The Tao that can be told is not the eternal Tao;
The name that can be named is not the eternal name.
The Nameless is the origin of Heaven and Earth;
The Named is the mother of all things.
—Lao-Tsu (c. 6th century BC)

Names are used to refer to entities declared in a Java program. A declared entity (§6.1) is a package, class type, interface type, member (field or method) of a reference type, parameter (to a method, constructor, or exception handler), or local variable.

Names in Java programs are either simple, consisting of a single identifier, or qualified, consisting of a sequence of identifiers separated by "." tokens (§6.2).

Every name introduced by a declaration has a scope (§6.3), which is the part of the Java program text within which the declared entity can be referred to by a simple name.

Packages and reference types (that is, class types, interface types, and array types) have members (§6.4). A member can be referred to using a qualified name N.x, where N is a simple or qualified name and x is an identifier. If N names a package, then x is a member of that package, which is either a class or interface type or a subpackage. If N names a reference type or a variable of a reference type, then x names a member of that type, which is either a field or a method.

In determining the meaning of a name (§6.5), Java uses the context of the occurrence to disambiguate among packages, types, variables, and methods with the same name.

Access control (§6.6) can be specified in a class, interface, method, or field declaration to control when access to a member is allowed. Access is a different concept from scope; access specifies the part of the Java program text within which the declared entity can be referred to by a qualified name, a field access expression (§15.10), or a method invocation expression (§15.11) in which the method is not specified by a simple name. The default access is that a member can be accessed anywhere within the package that contains its declaration; other possibilities are public, protected, and private.

Fully qualified names (§6.7) and naming conventions (§6.8) are also discussed in this chapter.

The name of a field, parameter, or local variable may be used as an expression (§15.13.1). The name of a method may appear in an expression only as part of a method invocation expression (§15.11). The name of a class or interface type may appear in an expression only as part of a class instance creation expression (§15.8), an array creation expression (§15.9), a cast expression (§15.15), or an instanceof expression (§15.19.2), or as part of a qualified name for a field or method. The name of a package may appear in an expression only as part of a qualified name for a class or interface type.


6.1 Declarations

A declaration introduces an entity into a Java program and includes an identifier (§3.8) that can be used in a name to refer to this entity. A declared entity is one of the following:

  • A package, declared in a package declaration (§7.4)
  • An imported type, declared in a single-type-import declaration (§7.5.1) or a type-import-on-demand declaration (§7.5.2)
  • A class, declared in a class type declaration (§8.1)
  • An interface, declared in an interface type declaration (§9.1)
  • A member of a reference type (§8.2, §9.2, §10.7), one of the following:
    • A field, one of the following:
      • A field declared in a class type (§8.3)
      • A constant field declared in an interface type (§9.3)
      • The field length, which is implicitly a member of every array type (§10.7)
    • A method, one of the following:
      • A method (abstract or otherwise) declared in a class type (§8.4)
      • A method (always abstract) declared in an interface type (§9.4)
  • A parameter, one of the following:
    • A parameter of a method or constructor of a class (§8.4.1, §8.6.1)
    • A parameter of an abstract method of an interface (§9.4)
    • A parameter of an exception handler declared in a catch clause of a try statement (§14.18)
  • A local variable, one of the following:
    • A local variable declared in a block (§14.3)
    • A local variable declared in a for statement (§14.12)

Constructors (§8.6) are also introduced by declarations, but use the name of the class in which they are declared rather than introducing a new name.


6.2 Names

A name is used to refer to an entity declared in a Java program.

There are two forms of names: simple names and qualified names. A simple name is a single identifier. A qualified name consists of a name, a "." token, and an identifier.

In determining the meaning of a name (§6.5), the Java language takes into account the context in which the name appears. It distinguishes among contexts where a name must denote (refer to) a package (§6.5.3), a type (§6.5.4), a variable or value in an expression (§6.5.5), or a method (§6.5.6).

Not all identifiers in Java programs are a part of a name. Identifiers are also used in the following situations:

  • In declarations (§6.1), where an identifier may occur to specify the name by which the declared entity will be known
  • In field access expressions (§15.10), where an identifier occurs after a "." token to indicate a member of an object that is the value of an expression or the keyword super that appears before the "." token
  • In some method invocation expressions (§15.11), where an identifier may occur after a "." token and before a "(" token to indicate a method to be invoked for an object that is the value of an expression or the keyword super that appears before the "." token
  • As labels in labeled statements (§14.6) and in break (§14.13) and continue (§14.14) statements that refer to statement labels

In the example:

class Test {
    public static void main(String[] args) {
        Class c = System.out.getClass();
        System.out.println(c.toString().length() +
                                args[0].length() + args.length);
    }
}

the identifiers Test, main, and the first occurrences of args and c are not names; rather, they are used in declarations to specify the names of the declared entities. The names String, Class, System.out.getClass, System.out.println, c.toString, args, and args.length appear in the example. The first occurrence of length is not a name, but rather an identifier appearing in a method invocation expression (§15.11). The second occurrence of length is not a name, but rather an identifier appearing in a method invocation expression (§15.11).

The identifiers used in labeled statements and their associated break and continue statements are completely separate from those used in declarations. Thus, the following code is valid:

class TestString {

    char[] value;

    int offset, count;

    int indexOf(TestString str, int fromIndex) {
        char[] v1 = value, v2 = str.value;
        int max = offset + (count - str.count);
        int start = offset + ((fromIndex < 0) ? 0 : fromIndex);
    i:
        for (int i = start; i <= max; i++)

        {
            int n = str.count, j = i, k = str.offset;
            while (n-- != 0) {
                if (v1[j++] != v2[k++])
                    continue i;
            }
            return i - offset;
        }
        return -1;
    }
}

This code was taken from a version of the class String and its method indexOf (§20.12.26), where the label was originally called test. Changing the label to have the same name as the local variable i does not hide the label in the scope of the declaration of i. The identifier max could also have been used as the statement label; the label would not hide the local variable max within the labeled statement.


6.3 Scope of a Simple Name

The scope of a declaration is the region of the program within which the entity declared by the declaration can be referred to using a simple name:

  • The scope of a package, as introduced by a package declaration, is determined by the host system (§7.4.3). All Java code is within the scope of the standard package named java, so the package java can always be referred to by Java code.
  • The scope of a type imported by a single-type-import declaration (§7.5.1) or type-import-on-demand declaration (§7.5.2) is all the class and interface type declarations (§7.6) in the compilation unit in which the import declaration appears.
  • The scope of a type introduced by a class type declaration (§8.1.1) or interface type declaration (§9.1.1) is the declarations of all class and interface types in all the compilation units (§7.3) of the package in which it is declared.
  • The scope of a member declared in or inherited by a class type (§8.2) or interface type (§9.2) is the entire declaration of the class or interface type. The declaration of a member needs to appear before it is used only when the use is in a field initialization expression (§8.3.2, §12.4.2, §12.5). This means that a compile-time error results from the test program:

    class Test {
        int i = j;				// compile-time error: incorrect forward reference
        int j = 1;
    }

    whereas the following example compiles without error:

    class Test {
        Test() { k = 2; }
        int j = 1;
        int i = j;
        int k;
    }

even though the constructor (§8.6) for Test refers to the field k that is declared three lines later.

  • The scope of a parameter of a method (§8.4.1) is the entire body of the method.
  • The scope of a parameter of a constructor (§8.6.1) is the entire body of the constructor.
  • The scope of a local variable declaration in a block (§14.3.2) is the rest of the block in which the declaration appears, starting with its own initializer (§14.3) and including any further declarators to the right in the local variable declaration statement.
  • The scope of a local variable declared in the ForInit part of a for statement (§14.12) includes all of the following:
    • Its own initializer
    • Any further declarators to the right in the ForInit part of the for statement
    • The Expression and ForUpdate parts of the for statement
    • The contained Statement
  • The scope of a parameter of an exception handler that is declared in a catch clause of a try statement (§14.18) is the entire block associated with the catch.

These rules imply that declarations of class and interface types need not appear before uses of the types.

In the example:

package points;

class Point {
    int x, y;
    PointList list;
    Point next;
}

class PointList {
    Point first;
}

the use of PointList in class Point is correct, because the scope of the class type name PointList includes both class Point and class PointList, as well as any other type declarations in other compilation units of package points.


6.3.1 Hiding Names

Some declarations may be hidden (§6.3.1) in part of their scope by another declaration of the same name, in which case a simple name cannot be used to refer to the declared entity.

The example:

class Test {
    static int x = 1;
    public static void main(String[] args) {
        int x = 0;
        System.out.print("x=" + x);
        System.out.println(", Test.x=" + Test.x);
    }
}

produces the output:

x=0, Test.x=1

This example declares:

  • a class Test
  • a class (static) variable x that is a member of the class Test
  • a class method main that is a member of the class Test
  • a parameter args of the main method
  • a local variable x of the main method

Since the scope of a class variable includes the entire body of the class (§8.2) the class variable x would normally be available throughout the entire body of the method main. In this example, however, the class variable x is hidden within the body of the method main by the declaration of the local variable x.

A local variable has as its scope the rest of the block in which it is declared (§14.3.2); in this case this is the rest of the body of the main method, namely its initializer "0" and the invocations of print and println.

This means that:

  • The expression "x" in the invocation of print refers to (denotes) the value of the local variable x.
  • The invocation of println uses a qualified name (§6.6) Test.x, which uses the class type name Test to access the class variable x, because the declaration of Test.x is hidden at this point and cannot be referred to by its simple name.

If the standard naming conventions (§6.8) are followed, then hiding that would make the identification of separate naming contexts matter should be rare. The following contrived example involves hiding because it does not follow the standard naming conventions:

class Point { int x, y; }

class Test {

    static Point Point(int x, int y) {
        Point p = new Point();
        p.x = x; p.y = y;
        return p;
    }

    public static void main(String[] args) {
        int Point;
        Point[] pa = new Point[2];
        for (Point = 0; Point < 2; Point++) {
            pa[Point] = new Point();
            pa[Point].x = Point;
            pa[Point].y = Point;
        }
        System.out.println(pa[0].x + "," + pa[0].y);
        System.out.println(pa[1].x + "," + pa[1].y);
        Point p = Point(3, 4);
        System.out.println(p.x + "," + p.y);
    }

}

This compiles without error and executes to produce the output:

0,0
1,1

3,4

Within the body of main, the lookups of Point find different declarations depending on the context of the use:

  • In the expression "new Point[2]", the two occurrences of the class instance creation expression "new Point()", and at the start of three different local variable declaration statements, the Point is a TypeName (§6.5.4) and denotes the class type Point in each case.
  • In the method invocation expression "Point(3, 4)" the occurrence of Point is a MethodName (§6.5.6) and denotes the class (static) method Point.
  • All other names are ExpressionNames (§6.5.5) and refer to the local variable Point.

The example:

import java.util.*;

class Vector {
    int val[] = { 1 , 2 };
}

class Test {
    public static void main(String[] args) {
        Vector v = new Vector();
        System.out.println(v.val[0]);
    }
}

compiles and prints:

1

using the class Vector declared here in preference to class java.util.Vector that might be imported on demand.


6.4 Members and Inheritance

Packages and reference types have members. The members of a package (§7) are subpackages (§7.1) and all the class (§8) and interface (§9) types declared in all the compilation units (§7.3) of the package. The members of a reference type (§4.3) are fields (§8.3, §9.3, §10.7) and methods (§8.4, §9.4). Members are either declared in the type, or inherited because they are accessible members of a superclass or superinterface which are neither hidden nor overridden (§8.4.6).

This section provides an overview of the members of packages and reference types here, as background for the discussion of qualified names and the determination of the meaning of names. For a complete description of membership, see §7.1, §8.2, §9.2, and §10.7.


6.4.1 The Members of a Package

A member of a package (§7) is a subpackage (§7.1), or a class (§8) or interface (§9) type declared in a compilation unit (§7.3) of the package.

In general, the subpackages of a package are determined by the host system (§7.2). However, the standard package java always includes the subpackages lang, util, io, and net and may include other subpackages. No two distinct members of the same package may have the same simple name (§7.1), but members of different packages may have the same simple name. For example, it is possible to declare a package:

package vector;
public class Vector { Object[] vec; }

that has as a member a public class named Vector, even though the standard package java.util also declares a class named Vector. These two class types are different, reflected by the fact that they have different fully qualified names (§6.7). The fully qualified name of this example Vector is vector.Vector, whereas java.util.Vector is the fully qualified name of the standard Vector class. Because the package vector contains a class named Vector, it cannot also have a subpackage named Vector.


6.4.2 The Members of a Class Type

The members of a class type (§8.2) are fields and methods. The members of a class type are all of the following:

  • Members inherited from its direct superclass (§8.1.3), if it has one (the class Object has no direct superclass)
  • Members inherited from any direct superinterfaces (§8.1.4)
  • Members declared in the body of the class (§8.1.5)

Constructors (§8.6) are not members.

There is no restriction against a field and a method of a class type having the same simple name.

A class may have two or more fields with the same simple name if they are declared in different interfaces and inherited. An attempt to refer to any of the fields by its simple name results in a compile-time error (§6.5.6.2, §8.2).

In the example:

interface Colors {
    int WHITE = 0, BLACK = 1;
}

interface Separates {
    int CYAN = 0, MAGENTA = 1, YELLOW = 2, BLACK = 3;
}

class Test implements Colors, Separates {
    public static void main(String[] args) {
        System.out.println(BLACK); // compile-time error: ambiguous
    }
}

the name BLACK in the method main is ambiguous, because class Test has two members named BLACK, one inherited from Colors and one from Separates.

A class type may have two or more methods with the same simple name if the methods have different signatures (§8.4.2), that is, if they have different numbers of parameters or different parameter types in at least one parameter position. Such a method member name is said to be overloaded.

A class type may contain a declaration for a method with the same name and the same signature as a method that would otherwise be inherited from a superclass or superinterface. In this case, the method of the superclass or superinterface is not inherited. If the method not inherited is abstract, then the new declaration is said to implement it; if the method not inherited is not abstract, then the new declaration is said to override it.

In the example:

class Point {
    float x, y;
    void move(int dx, int dy) { x += dx; y += dy; }
    void move(float dx, float dy) { x += dx; y += dy; }
    public String toString() { return "("+x+","+y+")"; }
}

the class Point has two members that are methods with the same name, move. The overloaded move method of class Point chosen for any particular method invocation is determined at compile time by the overloading resolution procedure given in §15.11.

In this example, the members of the class Point are the float instance variables x and y declared in Point, the two declared move methods, the declared toString method, and the members that Point inherits from its implicit direct superclass Object (§4.3.2), such as the method hashCode (§20.1.4). Note that Point does not inherit the toString method (§20.1.2) of class Object because that method is overridden by the declaration of the toString method in class Point.


6.4.3 The Members of an Interface Type

The members of an interface type (§9.2) are fields and methods. The members of an interface are all of the following:

  • Members inherited from any direct superinterfaces (§9.1.3)
  • Members declared in the body of the interface (§9.1.4)

An interface may have two or more fields with the same simple name if they are declared in different interfaces and inherited. An attempt to refer to any such field by its simple name results in a compile-time error (§6.5.5.1, §9.2).

In the example:

interface Colors {
    int WHITE = 0, BLACK = 1;
}

interface Separates {
    int CYAN = 0, MAGENTA = 1, YELLOW = 2, BLACK = 3;
}
interface ColorsAndSeparates extends Colors, Separates {

    int DEFAULT = BLACK;								 	// compile-time error: ambiguous

}

the members of the interface ColorsAndSeparates include those members inherited from Colors and those inherited from Separates, namely WHITE, BLACK (first of two), CYAN, MAGENTA, YELLOW, and BLACK (second of two). The member name BLACK is ambiguous in the interface ColorsAndSeparates.


6.4.4 The Members of an Array Type

The members of an array type (§10.7) are all of the following:

  • Members inherited from its implicit superclass Object (§4.3.2, §20.1)
  • The field length, which is a constant (final) field of every array; its type is int and it contains the number of components of the array

The example:

class Test {
    public static void main(String[] args) {
        int[] ia = new int[3];
        int[] ib = new int[6];
        System.out.println(ia.getClass() == ib.getClass());
        System.out.println("ia has length=" + ia.length);
    }
}

produces the output:

true
ia has length=3

This example uses the method getClass inherited from class Object and the field length. The result of the comparison of the Class objects in the second println demonstrates that all arrays whose components are of type int are instances of the same array type, which is int[].


6.5 Determining the Meaning of a Name

The meaning of a name in Java depends on the context in which it is used. The determination of the meaning of a name requires three steps. First, context causes a name syntactically to fall into one of five categories: PackageName, TypeName, ExpressionName, MethodName, or AmbiguousName. Second, a name that is initially classified by its context as an AmbiguousName is then reclassified by certain scoping rules to be a PackageName, TypeName, or ExpressionName. Third, the resulting category then dictates the final determination of the meaning of the name (or a compilation error if the name has no meaning).

PackageName:

    Identifier

    PackageName . Identifier

TypeName:

    Identifier

    PackageName . Identifier

ExpressionName:

    Identifier

    AmbiguousName . Identifier

MethodName:

    Identifier

    AmbiguousName . Identifier

AmbiguousName:

    Identifier

    AmbiguousName . Identifier

Java's use of context helps to minimize name conflicts between entities of different kinds. Such conflicts will be rare if the naming conventions described in §6.8 are followed. Nevertheless, conflicts may arise unintentionally as types developed by different programmers or different organizations evolve. For example, types, methods, and fields may have the same name. Java never has trouble distinguishing between a method and a field with the same name, since the context of a use always tells whether a method or a field is intended.


6.5.1 Syntactic Classification of a Name According to Context

A name is syntactically classified as a PackageName in these contexts:

  • In a package declaration (§7.4)
  • In a type-import-on-demand declaration (§7.5.2)
  • To the left of the "." in a qualified PackageName
  • To the left of the "." in a qualified TypeName

A name is syntactically classified as a TypeName in these contexts:

  • In a single-type-import declaration (§7.5.1)
  • In an extends clause in a class declaration (§8.1.3)
  • In an implements clause in a class declaration (§8.1.4)
  • In an extends clause in an interface declaration (§9.1.3)
  • As a Type (or the part of a Type that remains after all brackets are deleted) in any of the following contexts:
    • In a field declaration (§8.3, §9.3)
    • As the result type of a method (§8.4, §9.4)
    • As the type of a formal parameter of a method or constructor (§8.4.1, §8.6.1, §9.4)
    • As the type of an exception that can be thrown by a method or constructor (§8.4.4, §8.6.4, §9.4)
    • As the type of a local variable (§14.3)
    • As the type of an exception parameter in a catch clause of a try statement (§14.18)
    • As the class type of an instance that is to be created in a class instance creation expression (§15.8)
    • As the element type of an array to be created in an array creation expression (§15.9)
    • As the type mentioned in the cast operator of a cast expression (§15.15)
    • As the type that follows the instanceof relational operator (§15.19.2)

A name is syntactically classified as an ExpressionName in these contexts:

  • As the array reference expression in an array access expression (§15.12)
  • As a PostfixExpression (§15.13)
  • As the left-hand operand of an assignment operator (§15.25)

A name is syntactically classified as a MethodName in this context:

· Before the "(" in a method invocation expression (§15.11)

A name is syntactically classified as an AmbiguousName in these contexts:

  • To the left of the "." in a qualified ExpressionName
  • To the left of the "." in a qualified MethodName
  • To the left of the "." in a qualified AmbiguousName


6.5.2 Reclassification of Contextually Ambiguous Names

An AmbiguousName is then reclassified as follows:

  • If the AmbiguousName is a simple name, consisting of a single Identifier:
    • If the Identifier appears within the scope (§6.3) of a local variable declaration (§14.3) or parameter declaration (§8.4.1, §8.6.1, §14.18) with that name, then the AmbiguousName is reclassified as an ExpressionName.
    • Otherwise, consider the class or interface C within whose declaration the Identifier occurs. If C has one or more fields with that name, which may be either declared within it or inherited, then the AmbiguousName is reclassified as an ExpressionName.
    • Otherwise, if a type of that name is declared in the compilation unit (§7.3) containing the Identifier, either by a single-type-import declaration (§7.5.1) or by a class or interface type declaration (§7.6), then the AmbiguousName is reclassified as a TypeName.
    • Otherwise, if a type of that name is declared in another compilation unit (§7.3) of the package (§7.1) of the compilation unit containing the Identifier, then the AmbiguousName is reclassified as a TypeName.
    • Otherwise, if a type of that name is declared by exactly one type-import-on-demand declaration (§7.5.2) of the compilation unit containing the Identifier, then the AmbiguousName is reclassified as a TypeName.
    • Otherwise, if a type of that name is declared by more than one type-import-on-demand declaration of the compilation unit containing the Identifier, then a compile-time error results.
    • Otherwise, the AmbiguousName is reclassified as a PackageName. A later step determines whether or not a package of that name actually exists.
  • If the AmbiguousName is a qualified name, consisting of a name, a ".", and an Identifier, then the name to the left of the "." is first reclassified, for it is itself an AmbiguousName. There is then a choice:
    • If the name to the left of the "." is reclassified as a PackageName, then there is a further choice:
      • If there is a package whose name is the name to the left of the "." and that package contains a declaration of a type whose name is the same as the Identifier, then this AmbiguousName is reclassified as a TypeName.
      • Otherwise, this AmbiguousName is reclassified as a PackageName. A later step determines whether or not a package of that name actually exists.
    • If the name to the left of the "." is reclassified as a TypeName, then this AmbiguousName is reclassified as an ExpressionName. u If the name to the left of the "." is reclassified as an ExpressionName, then this AmbiguousName is reclassified as an ExpressionName.

As an example, consider the following contrived "library code":

package ORG.rpgpoet;

import java.util.Random;

interface Music { Random[] wizards = new Random[4]; }

and then consider this example code in another package:

package bazola;

class Gabriel {
    static int n = ORG.rpgpoet.Music.wizards.length;
}

First of all, the name ORG.rpgpoet.Music.wizards.length is classified as an ExpressionName because it functions as a PostfixExpression. Therefore, each of the names:

ORG.rpgpoet.Music.wizards
ORG.rpgpoet.Music
ORG.rpgpoet
ORG

is initially classified as an AmbiguousName. These are then reclassified:

  • Assuming that there is no class or interface named ORG in any other compilation unit of package bazola, then the simple name ORG is reclassified as a PackageName.
  • Next, assuming that there is no class or interface named rpgpoet in any compilation unit of package ORG (and we know that there is no such class or interface because package ORG has a subpackage named rpgpoet), the qualified name ORG.rpgpoet is reclassified as a PackageName.
  • Next, because package ORG.rpgpoet has an interface type named Music, the qualified name ORG.rpgpoet.Music is reclassified as a TypeName.
  • Finally, because the name ORG.rpgpoet.Music is a TypeName, the qualified name ORG.rpgpoet.Music.wizards is reclassified as an ExpressionName.


6.5.3 Meaning of Package Names

The meaning of a name classified as a PackageName is determined as follows.

6.5.3.1 Simple Package Names

If a package name consists of a single Identifier, then this identifier denotes a top- level package named by that identifier. If no package of that name is accessible, as determined by the host system (§7.4.3), then a compile-time error occurs.

6.5.3.2 Qualified Package Names

If a package name is of the form Q.Id, then Q must also be a package name. The package name Q.Id names a package that is the member named Id within the package named by Q. If Q does not name an accessible package or Id does not name an accessible subpackage of that package, then a compile-time error occurs.


6.5.4 Meaning of Type Names

The meaning of a name classified as a TypeName is determined as follows.

6.5.4.1 Simple Type Names

If a type name consists of a single Identifier, then the identifier must occur in the scope of a declaration of a type with this name, or a compile-time error occurs. It is possible that the identifier occurs within the scope of more than one type with that name, in which case the type denoted by the name is determined as follows:

  • If a type with that name is declared in the current compilation unit (§7.3), either by a single-type-import declaration (§7.5.1) or by a declaration of a class or interface type (§7.6), then the simple type name denotes that type.
  • Otherwise, if a type with that name is declared in another compilation unit (§7.3) of the package (§7.1) containing the identifier, then the identifier denotes that type. Note that, in systems that store compilation units in a file system, such a compilation unit must have a file name that is the name of the type (§7.6).
  • Otherwise, if a type of that name is declared by exactly one type-import-on-demand declaration (§7.5.2) of the compilation unit containing the identifier, then the simple type name denotes that type.
  • Otherwise, if a type of that name is declared by more than one type-import-on-demand declaration of the compilation unit, then the name is ambiguous as a type name; a compile-time error occurs.
  • Otherwise, the name is undefined as a type name; a compile-time error occurs.

This order for considering type declarations is designed to choose the most explicit of two or more applicable type declarations.

6.5.4.2 Qualified Type Names

If a type name is of the form Q.Id, then Q must be a package name. The type name Q.Id names a type that is the member named Id within the package named by Q. If Q does not name an accessible package, or Id does not name a type within that package, or the type named Id within that package is not accessible (§6.6), then a compile-time error occurs.

The example:

package wnj.test;

class Test {
    public static void main(String[] args) {
        java.util.Date date =
            new java.util.Date(System.currentTimeMillis());
        System.out.println(date.toLocaleString());
    }
}

produced the following output the first time it was run:

Sun Jan 21 22:56:29 1996

In this example:

  • The name wnj.test must name a package on the host system. It is resolved by first looking for the package wnj, using the procedure described in §6.5.3.1, and then making sure that the subpackage test of this package is accessible.
  • The name java.util.Date (§21.3) must denote a type, so we first use the procedure recursively to determine if java.util is an accessible package, which it is, and then look to see if the type Date is accessible in this package.


6.5.5 Meaning of Expression Names

The meaning of a name classified as an ExpressionName is determined as follows.

6.5.5.1 Simple Expression Names

If an expression name consists of a single Identifier, then:

  • If the Identifier appears within the scope (§6.3) of a local variable declaration (§14.3) or parameter declaration (§8.4.1, §8.6.1, §14.18) with that name, then the expression name denotes a variable, that is, that local variable or parameter. Local variables and parameters are never hidden (§6.3, §6.3.1, §14.3), so there is necessarily at most one such local variable or parameter. The type of the expression name is the declared type of the local variable or parameter.
  • Otherwise, if the Identifier appears within a class declaration (§8):
    • If there is not exactly one member of that class (§8.2) that is a field with that name, then a compile-time error results.
    • Otherwise, if the single member field with that name is declared final (§8.3.1.2), then the expression name denotes the value of the field. The type of the expression name is the declared type of the field. If the Identifier appears in a context that requires a variable and not a value, then a compile-time error occurs.
    • Otherwise, the expression name denotes a variable, the single member field with that name. The type of the expression name is the field's declared type.

If the field is an instance variable (§8.3.1.1), the expression name must appear within the declaration of an instance method (§8.4), constructor (§8.6), or instance variable initializer (§8.3.2.2). If it appears within a static method (§8.4.3.2), static initializer (§8.5), or initializer for a static variable (§8.3.1.1, §12.4.2), then a compile-time error occurs.

  • Otherwise, the identifier appears within an interface declaration (§9):
    • If there is not exactly one member of that interface (§9.2) that is a field with that name, then a compile-time error results.
    • Otherwise, the expression name denotes the value of the single member field of that name. The type of the expression name is the declared type of the field. If the Identifier appears in a context that requires a variable and not a value, then a compile-time error occurs.

In the example:

class Test {

    static int v;

    static final int f = 3;

    public static void main(String[] args) {
        int i;
        i = 1;
        v = 2;
        f = 33;										// compile-time error
        System.out.println(i + " " + v + " " + f);
    }

}

the names used as the left-hand-sides in the assignments to i, v, and f denote the local variable i, the field v, and the value of f (not the variable f, because f is a final variable). The example therefore produces an error at compile time because the last assignment does not have a variable as its left-hand side. If the erroneous assignment is removed, the modified code can be compiled and it will produce the output:

1 2 3

6.5.5.2 Qualified Expression Names

If an expression name is of the form Q.Id, then Q has already been classified as a package name, a type name, or an expression name:

  • If Q is a package name, then a compile-time error occurs.
  • If Q is a type name that names a class type (§8), then:
    • If there is not exactly one accessible (§6.6) member of the class type that is a field named Id, then a compile-time error occurs.
    • Otherwise, if the single accessible member field is not a class variable (that is, it is not declared static), then a compile-time error occurs.
    • Otherwise, if the class variable is declared final, then Q.Id denotes the value of the class variable. The type of the expression Q.Id is the declared type of the class variable. If Q.Id appears in a context that requires a variable and not a value, then a compile-time error occurs.
    • Otherwise, Q.Id denotes the class variable. The type of the expression Q.Id is the declared type of the class variable.
  • If Q is a type name that names an interface type (§9), then:
    • If there is not exactly one accessible (§6.6) member of the interface type that is a field named Id, then a compile-time error occurs.
    • Otherwise, Q.Id denotes the value of the field. The type of the expression Q.Id is the declared type of the field. If Q.Id appears in a context that requires a variable and not a value, then a compile-time error occurs.
  • If Q is an expression name, let T be the type of the expression Q:
    • If T is not a reference type, a compile-time error occurs.
    • If there is not exactly one accessible (§6.6) member of the type T that is a field named Id, then a compile-time error occurs.
    • Otherwise, if this field is any of the following:
      • A field of an interface type
      • A final field of a class type (which may be either a class variable or an instance variable)
      • The final field length of an array type then Q.Id denotes the value of the field. The type of the expression Q.Id is the declared type of the field. If Q.Id appears in a context that requires a variable and not a value, then a compile-time error occurs.

    • Otherwise, Q.Id denotes a variable, the field Id of class T, which may be either a class variable or an instance variable. The type of the expression Q.Id is the declared type of the field

The example:

class Point {
    int x, y;
    static int nPoints;
}

class Test {
    public static void main(String[] args) {
        int i = 0;
        i.x++;								// compile-time error
        Point p = new Point();
        p.nPoints();								// compile-time error
    }
}

encounters two compile-time errors, because the int variable i has no members, and because nPoints is not a method of class Point.


6.5.6 Meaning of Method Names

A MethodName can appear only in a method invocation expression (§15.11). The meaning of a name classified as a MethodName is determined as follows.

6.5.6.1 Simple Method Names

If a method name consists of a single Identifier, then Identifier is the method name to be used for method invocation. The Identifier must name at least one method of the class or interface within whose declaration the Identifier appears. See §15.11 for further discussion of the interpretation of simple method names in method invocation expressions.

6.5.6.2 Qualified Method Names

If a method name is of the form Q.Id, then Q has already been classified as a package name, a type name, or an expression name. If Q is a package name, then a compile-time error occurs. Otherwise, Id is the method name to be used for method invocation. If Q is a type name, then Id must name at least one static method of the type Q. If Q is an expression name, then let T be the type of the expression Q; Id must name at least one method of the type T. See §15.11 for further discussion of the interpretation of qualified method names in method invocation expressions.


6.6 Qualified Names and Access Control

Qualified names are a means of access to members of packages and reference types; related means of access include field access expressions (§15.10) and method invocation expressions (§15.11). All three are syntactically similar in that a "." token appears, preceded by some indication of a package, type, or expression having a type and followed by an Identifier that names a member of the package or type. These are collectively known as constructs for qualified access.

Java provides mechanisms for access control, to prevent the users of a package or class from depending on unnecessary details of the implementation of that package or class. Access control applies to qualified access and to the invocation of constructors by class instance creation expressions (§15.8), explicit constructor invocations (§8.6.5), and the method newInstance of class Class (§20.3.6).

If access is permitted, then the accessed entity is said to be accessible.


6.6.1 Determining Accessibility

  • Whether a package is accessible is determined by the host system (§7.2).
  • If a class or interface type is declared public, then it may be accessed by any Java code that can access the package in which it is declared. If a class or interface type is not declared public, then it may be accessed only from within the package in which it is declared.
  • A member (field or method) of a reference (class, interface, or array) type or a constructor of a class type is accessible only if the type is accessible and the member or constructor is declared to permit access:
    • If the member or constructor is declared public, then access is permitted. All members of interfaces are implicitly public.
    • Otherwise, if the member or constructor is declared protected, then access is permitted only when one of the following is true:
        • Access to the member or constructor occurs from within the package containing the class in which the protected member is declared.
        • Access occurs within a subclass of the class in which the protected member is declared, and the access is correct as described in §6.6.2.

    • Otherwise, if the member or constructor is declared private, then access is permitted only when it occurs from within the class in which it is declared.
    • Otherwise, we say there is default access, which is permitted only when the access occurs from within the package in which the type is declared.


6.6.2 Details on protected Access

A protected member or constructor of an object may be accessed from outside the package in which it is declared only by code that is responsible for the implementation of that object. Let C be the class in which a protected member or constructor is declared and let S be the subclass of C in whose declaration the use of the protected member or constructor occurs. Then:

  • If an access is of a protected member (field or method), let Id be its name. Consider then the means of qualified access:
    • If the access is by a field access expression of the form super.Id, then the access is permitted.
    • If the access is by a qualified name Q.Id, where Q is a TypeName, then the access is permitted if and only if Q is S or a subclass of S.
    • If the access is by a qualified name Q.Id, where Q is an ExpressionName, then the access is permitted if and only if the type of the expression Q is S or a subclass of S.
    • If the access is by a field access expression E.Id, where E is a Primary expression, or by a method invocation expression E.Id(. . .), where E is a Primary expression, then the access is permitted if and only if the type of E is S or a subclass of S.
  • Otherwise, if an access is of a protected constructor:
    • If the access is by a superclass constructor invocation super(. . .), then the access is permitted.
    • If the access is by a class instance creation expression new T(. . .), then the access is not permitted. (A protected constructor can be accessed by a class instance creation expression only from within the package in which it is defined.)
    • If the access is by an invocation of the method newInstance of class Class (§20.3.6), then the access is not permitted.


6.6.3 An Example of Access Control

For examples of access control, consider the two compilation units:

package points;

class PointVec { Point[] vec; }

and:

package points;

public class Point {
    protected int x, y;
    public void move(int dx, int dy) { x += dx; y += dy; }
    public int getX() { return x; }
    public int getY() { return y; }
}

which declare two class types in the package points:

  • The class type PointVec is not public and not part of the public interface of the package points, but rather can be used only by other classes in the package.
  • The class type Point is declared public and is available to other packages. It is part of the public interface of the package points.
  • The methods move, getX, and getY of the class Point are declared public and so are available to any Java code that uses an object of type Point.
  • The fields x and y are declared protected and are accessible outside the package points only in subclasses of class Point, and only when they are fields of objects that are being implemented by the code that is accessing them.

See §6.6.7 for an example of how the protected access modifier limits access.


6.6.4 Example: Access to public and Non-public Classes

If a class lacks the public modifier, access to the class declaration is limited to the package in which it is declared (§6.6). In the example:

package points;

public class Point {
    public int x, y;
    public void move(int dx, int dy) { x += dx; y += dy; }
}

class PointList {
    Point next, prev;
}

two classes are declared in the compilation unit. The class Point is available outside the package points, while the class PointList is available for access only within the package. Thus a compilation unit in another package can access points.Point, either by using its fully qualified name:

package pointsUser;

class Test {
    public static void main(String[] args) {
        points.Point p = new points.Point();
        System.out.println(p.x + " " + p.y);
    }
}

or by using a single-type-import declaration (§7.5.1) that mentions the fully qualfied name, so that the simple name may be used thereafter:

package pointsUser;

import points.Point;

class Test {
    public static void main(String[] args) {
        Point p = new Point();
        System.out.println(p.x + " " + p.y);
    }
}

However, this compilation unit cannot use or import points.PointList, which is not declared public and is therefore inaccessible outside package points.


6.6.5 Example: Default-Access Fields, Methods, and Constructors

If none of the access modifiers public, protected, or private are specified, a class member or constructor is accessible throughout the package that contains the declaration of the class in which the class member is declared, but the class member or constructor is not accessible in any other package. If a public class has a method or constructor with default access, then this method or constructor is not accessible to or inherited by a subclass declared outside this package.

For example, if we have:

package points;

public class Point {
    public int x, y;
    void move(int dx, int dy) { x += dx; y += dy; }
    public void moveAlso(int dx, int dy) { move(dx, dy); }
}

then a subclass in another package may declare an unrelated move method, with the same signature (§8.4.2) and return type, but because the original move method is not accessible from package morepoints super may not be used:

package morepoints;

public class PlusPoint extends points.Point {
    public void move(int dx, int dy) {
        super.move(dx, dy);								// compile-time error
        moveAlso(dx, dy);
    }
}

Because move of Point is not overridden by move in PlusPoint, the method moveAlso in Point never calls the method move in PlusPoint.

Thus if you delete the super.move call from PlusPoint and execute the test program:

import points.Point;

import morepoints.PlusPoint;

class Test {

    public static void main(String[] args) {
        PlusPoint pp = new PlusPoint();
        pp.move(1, 1);
    }

}

it terminates normally. If move of Point were overridden by move in PlusPoint, then this program would recurse infinitely, until a StackoverflowError occurred.


6.6.6 Example: public Fields, Methods, and Constructors

A public class member or constructor is accessible throughout the package where it is declared and from any other package that has access to the package in which it is declared (§7.4.4). For example, in the compilation unit:

package points;

public class Point {

    int x, y;

    public void move(int dx, int dy) {
        x += dx; y += dy;
        moves++;
    }

    public static int moves = 0;

}

the public class Point has as public members the move method and the moves field. These public members are accessible to any other package that has access to package points. The fields x and y are not public and therefore are accessible only from within the package points.


6.6.7 Example: protected Fields, Methods, and Constructors

Consider this example, where the point package declares:

package points;

public class Point {

    protected int x, y;

    void warp(threePoint.Point3d a) {
        if (a.z > 0)						// compile-time error: cannot access a.z
            a.delta(this);
    }

}

and the threePoint package declares:

package threePoint;

import points.Point;

public class Point3d extends Point {

    protected int z;

    public void delta(Point p) {
        p.x += this.x;						// compile-time error: cannot access p.x
        p.y += this.y;						// compile-time error: cannot access p.y
    }

    public void delta3d(Point3d q) {
        q.x += this.x;
        q.y += this.y;
        q.z += this.z;
    }

}

which defines a class Point3d. A compile-time error occurs in the method delta here: it cannot access the protected members x and y of its parameter p, because while Point3d (the class in which the references to fields x and y occur) is a subclass of Point (the class in which x and y are declared), it is not involved in the implementation of a Point (the type of the parameter p). The method delta3d can access the protected members of its parameter q, because the class Point3d is a subclass of Point and is involved in the implementation of a Point3d.

The method delta could try to cast (§5.4, §15.15) its parameter to be a Point3d, but this cast would fail, causing an exception, if the class of p at run time were not Point3d.

A compile-time error also occurs in the method warp: it cannot access the protected member z of its parameter a, because while the class Point (the class in which the reference to field z occurs) is involved in the implementation of a Point (the type of the parameter a), it is not a subclass of Point (the class in which z is declared).


6.6.8 Example: private Fields, Methods, and Constructors

A private class member or constructor is accessible only within the class body in which the member is declared and is not inherited by subclasses. In the example:

class Point {

    Point() { setMasterID(); }

    int x, y;
    private int ID;
    private static int masterID = 0;

    private void setMasterID() { ID = masterID++; }

}

the private members ID, masterID, and setMasterID may be used only within the body of class Point. They may not be accessed by qualified names, field access expressions, or method invocation expressions outside the body of the declaration of Point.

See §8.6.8 for an example that uses a private constructor.


6.7 Fully Qualified Names

Every package, class, interface, array type, and primitive type has a fully qualified name. It follows that every type except the null type has a fully qualified name.

  • The fully qualified name of a primitive type is the keyword for that primitive type, namely boolean, char, byte, short, int, long, float, or double.
  • The fully qualified name of a named package that is not a subpackage of a named package is its simple name.
  • The fully qualified name of a named package that is a subpackage of another named package consists of the fully qualified name of the containing package, followed by ".", followed by the simple (member) name of the subpackage.
  • The fully qualified name of a class or interface that is declared in an unnamed package is the simple name of the class or interface.
  • The fully qualified name of a class or interface that is declared in a named package consists of the fully qualified name of the package, followed by ".", followed by the simple name of the class or interface.
  • The fully qualified name of an array type consists of the fully qualified name of the component type of the array type followed by "[]".

Examples:

  • The fully qualified name of the type long is "long".
  • The fully qualified name of the standard package java.lang is "java.lang" because it is subpackage lang of package java.
  • The fully qualified name of the class Object, which is defined in the package java.lang, is "java.lang.Object".
  • The fully qualified name of the interface Enumeration, which is defined in the package java.util, is "java.util.Enumeration".
  • The fully qualified name of the type "array of double" is "double[]".
  • The fully qualified name of the type "array of array of array of array of String" is "java.lang.String[][][][]".

In the example:

package points;

class Point { int x, y; }

class PointVec {
    Point[] vec;
}

the fully qualified name of the type Point is "points.Point"; the fully qualified name of the type PointVec is "points.PointVec"; and the fully qualified name of the type of the field vec of class PointVec is "points.Point[]".


6.8 Naming Conventions

The Java system and standard classes attempt to use, whenever possible, names chosen according to the conventions presented here. These conventions help to make code more readable and avoid certain kinds of name conflicts.

We recommend these conventions for use in all Java programs. However, these conventions should not be followed slavishly if long-held conventional usage dictates otherwise. So, for example, the sin and cos methods of the class java.lang.Math have mathematically conventional names, even though these method names flout Java convention because they are short and are not verbs.


6.8.1 Package Names

Names of packages that are to be made widely available should be formed as described in §7.7. Such names are always qualified names whose first identifier consists of two or three uppercase letters that name an Internet domain, such as COM, EDU, GOV, MIL, NET, ORG, or a two-letter ISO country code such as UK or JP. Here are examples of hypothetical unique names that might be formed under this convention:

COM.JavaSoft.jag.Oak
ORG.NPR.pledge.driver
UK.ac.city.rugby.game

Names of packages intended only for local use should have a first identifier that begins with a lowercase letter, but that first identifier specifically should not be the identifier java; package names that start with the identifier java are reserved to JavaSoft for naming standard Java packages.

When package names occur in expressions:

  • If a package name is hidden by a field declaration, then import declarations (§7.5) can usually be used to make available the type names declared in that package.
  • If a package name is hidden by a declaration of a parameter or local variable, then the name of the parameter or local variable can be changed without affecting other Java code.
  • The first component of a package name is normally not easily mistaken for a type name, as a type name normally begins with a single uppercase letter. (The Java language does not actually rely on case distinctions to determine whether a name is a package name or a type name. It is not possible for a type name to hide a package name.)


6.8.2 Class and Interface Type Names

Names of class types should be descriptive nouns or noun phrases, not overly long, in mixed case with the first letter of each word capitalized. For example:

ClassLoader
SecurityManager
Thread
Dictionary
BufferedInputStream

Likewise, names of interface types should be short and descriptive, not overly long, in mixed case with the first letter of each word capitalized. The name may be a descriptive noun or noun phrase, which is appropriate when an interface is used as if it were an abstract superclass, such as interfaces java.io.DataInput and java.io.DataOutput; or it may be an adjective describing a behavior, as for the interfaces java.lang.Runnable and java.lang.Cloneable.

Hiding involving class and interface type names is rare. Names of fields, parameters, and local variables normally do not hide type names because they conventionally begin with a lowercase letter whereas type names conventionally begin with an uppercase letter.


6.8.3 Method Names

Method names should be verbs or verb phrases, in mixed case, with the first letter lowercase and the first letter of any subsequent words capitalized. Here are some additional specific conventions for method names:

  • Methods to get and set an attribute that might be thought of as a variable V should be named get V and set V. An example is the methods getPriority (§20.20.22) and setPriority (§20.20.23) of class java.lang.Thread.
  • A method that returns the length of something should be named length, as in class java.lang.String (§20.12.11).
  • A method that tests a boolean condition V about an object should be named is V. An example is the method isInterrupted of class java.lang.Thread (§20.20.32).
  • A method that converts its object to a particular format F should be named to F. Examples are the method toString of class java.lang.Object (§20.1.2) and the methods toLocaleString (§21.3.27) and toGMTString (§21.3.28) of class java.util.Date.

Whenever possible and appropriate, basing the names of methods in a new class on names in an existing class that is similar, especially a class from the standard Java Application Programming Interface classes, will make it easier to use.

Method names cannot hide or be hidden by other names (§6.5.6).


6.8.4 Field Names

Names of fields that are not final should be in mixed case with a lowercase first letter and the first letters of subsequent words capitalized. Note that well-designed Java classes have very few public or protected fields, except for fields that are constants (final static fields) (§6.8.5).

Fields should have names that are nouns, noun phrases, or abbreviations for nouns. Examples of this convention are the fields buf, pos, and count of the class java.io.ByteArrayInputStream (§22.6) and the field bytesTransferred of the class java.io.InterruptedIOException (§22.30.1).

Hiding involving field names is rare.

  • If a field name hides a package name, then an import declaration (§7.5) can usually be used to make available the type names declared in that package.
  • If a field name hides a type name, then a fully qualified name for the type can be used.
  • Field names cannot hide method names.
  • If a field name is hidden by a declaration of a parameter or local variable, then the name of the parameter or local variable can be changed without affecting other Java code.


6.8.5 Constant Names

The names of constants in interface types should be, and final variables of class types may conventionally be, a sequence of one or more words, acronyms, or abbreviations, all uppercase, with components separated by underscore "_" characters. Constant names should be descriptive and not unnecessarily abbreviated. Conventionally they may be any appropriate part of speech. Examples of names for constants include MIN_VALUE, MAX_VALUE, MIN_RADIX, and MAX_RADIX of the class java.lang.Character.

A group of constants that represent alternative values of a set, or, less frequently, masking bits in an integer value, are sometimes usefully specified with a common acronym as a name prefix, as in:

interface ProcessStates {
    int PS_RUNNING = 0;
    int PS_SUSPENDED = 1;
}

Hiding involving constant names is rare:

  • Constant names should be longer than three letters, so that they do not hide the initial component of a unique package name.
  • Constant names normally have no lowercase letters, so they will not normally hide names of packages, types, or fields, whose names normally contain at least one lowercase letter.
  • Constant names cannot hide method names, because they are distinguished syntactically.


6.8.6 Local Variable and Parameter Names

Local variable and parameter names should be short, yet meaningful. They are often short sequences of lowercase letters that are not words. For example:

  • Acronyms, that is the first letter of a series of words, as in cp for a variable holding a reference to a ColoredPoint
  • Abbreviations, as in buf holding a pointer to a buffer of some kind
  • Mnemonic terms, organized in some way to aid memory and understanding, typically by using a set of local variables with conventional names patterned after the names of parameters to widely used classes. For example:
    • in and out, whenever some kind of input and output are involved, patterned after the fields of java.lang.System
    • off and len, whenever an offset and length are involved, patterned after the parameters to the read and write methods of the interfaces DataInput and DataOutput of java.io

One-character local variable or parameter names should be avoided, except for temporary and looping variables, or where a variable holds an undistinguished value of a type. Conventional one-character names are:

  • b for a byte
  • c for a char
  • d for a double
  • e for an Exception
  • f for a float
  • i, j, and k for integers
  • l for a long
  • o for an Object
  • s for a String
  • v for an arbitrary value of some type

Local variable or parameter names that consist of only two or three uppercase letters should be avoided to avoid potential conflicts with the initial country codes and domain names that are the first component of unique package names (§7.7).

What's in a name? That which we call a rose
By any other name would smell as sweet.
—William Shakespeare, Romeo and Juliet (c. 1594), Act II, scene ii

Rose is a rose is a rose is a rose.
—Gertrude Stein, "Sacred Emily" (1913), in Geographies and Plays

. . . stat rosa pristina nomine, nomina nuda tenemus.
—Bernard of Morlay, De contemptu mundi (12th century),
quoted in Umberto Eco, The Name of the Rose (1980)


 7. Packages

CHAPTER 7

Packages

Good things come in small packages.
—Traditional proverb

Java programs are organized as sets of packages. Each package has its own set of names for types, which helps to prevent name conflicts. A type is accessible (§6.6) outside the package that declares it only if the type is declared public.

The naming structure for packages is hierarchical (§7.1). The members of a package are class and interface types (§7.6), which are declared in compilation units of the package, and subpackages, which may contain compilation units and subpackages of their own.

A package can be stored in a file system (§7.2.1) or in a database (§7.2.2). Packages that are stored in a file system have certain constraints on the organization of their compilation units to allow a simple implementation to find classes easily. In either case, the set of packages available to a Java program is determined by the host system, but must always include at least the three standard packages java.lang, java.util, and java.io as specified in Chapters 20, 21, and 22. In most host environments, the standard packages java.applet, java.awt, and java.net, which are not described in this specification, are also available to Java programs.

A package consists of a number of compilation units (§7.3). A compilation unit automatically has access to all types declared in its package and also automatically imports each of the types declared in the predefined package java.lang.

A compilation unit has three parts, each of which is optional:

  • A package declaration (§7.4), giving the fully qualified name (§6.7) of the package to which the compilation unit belongs
  • import declarations (§7.5) that allow types from other packages to be referred to using their simple names
  • Type declarations (§7.6) of class and interface types

For small programs and casual development, a package can be unnamed (§7.4.2) or have a simple name, but if Java code is to be widely distributed, unique package names should be chosen (§7.7). This can prevent the conflicts that would otherwise occur if two development groups happened to pick the same package name and these packages were later to be used in a single program.


7.1 Package Members

A package can have members of either or both of the following kinds:

  • Subpackages of the package
  • Types declared in the compilation units (§7.3) of the package

For example, in the standard Java Application Programming Interface:

  • The package java has subpackages awt, applet, io, lang, net, and util, but no compilation units.
  • The package java.awt has a subpackage named image, as well as a number of compilation units containing declarations of class and interface types.

If the fully qualified name (§6.7) of a package is P, and Q is a subpackage of P, then P.Q is the fully qualified name of the subpackage.

The subpackages of package java named lang, util, and io (whose fully qualified package names are therefore java.lang, java.util, and java.io) are a standard part of every Java implementation and are specified in Chapters 20, 21, and 22. Many Java implementations will include the entire set of java packages defined in the series of books The Java Application Programming Interface.

A package may not contain a type declaration and a subpackage of the same name, or a compile-time error results. Here are some examples:

  • Because the package java.awt has a subpackage image, it cannot (and does not) contain a declaration of a class or interface type named image.
  • If there is a package named mouse and a type Button in that package (which then might be referred to as mouse.Button), then there cannot be any package with the fully qualified name mouse.Button or mouse.Button.Click.
  • If COM.Sun.java.jag is the fully qualified name of a type, then there cannot be any package whose fully qualified name is either COM.Sun.java.jag or COM.Sun.java.jag.scrabble.

The hierarchical naming structure for packages is intended to be convenient for organizing related packages in a conventional manner, but has no significance in the Java language itself other than the prohibition against a package having a subpackage with the same simple name as a type declared in that package. There is no special access relationship in the Java language between a package named oliver and another package named oliver.twist, or between packages named evelyn.wood and evelyn.Waugh. For example, the code in a package named oliver.twist has no better access to the types declared within package oliver than code in any other package.


7.2 Host Support for Packages

Each Java host determines how packages, compilation units, and subpackages are created and stored; which top-level package names are in scope in a particular compilation; and which packages are accessible.

The packages may be stored in a local file system in simple implementations of Java. Other implementations may use a distributed file system or some form of database to store Java source and/or binary code.


7.2.1 Storing Packages in a File System

As an extremely simple example, all the Java packages and source and binary code on a system might be stored in a single directory and its subdirectories. Each immediate subdirectory of this directory would represent a top-level package, that is, one whose fully qualified name consists of a single simple name. The directory might contain the following immediate subdirectories:

COM
gls
jag
java
wnj

where directory java would contain the standard Java Application Programming Interface packages that are part of every standard Java system; the directories jag, gls, and wnj might contain packages that the three authors of this specification created for their personal use and to share with each other within this small group; and the directory COM would contain packages procured from companies that used the conventions described in §7.7 to generate unique names for their packages.

Continuing the example, the directory java would probably contain at least the following subdirectories:

applet
awt
io
lang
net
util

corresponding to the standard packages java.applet, java.awt, java.io, java.lang, java.net, and java.util that are defined as part of the standard Java Application Programming Interface.

Still continuing the example, if we were to look inside the directory util, we might see the following files:

BitSet.java										Observable.java
BitSet.class										Observable.class
Date.java										Observer.java
Date.class										Observer.class
Dictionary.java										Properties.java
Dictionary.class										Properties.class
EmptyStackException.java										Random.java
EmptyStackException.class										Random.class
Enumeration.java										Stack.java
Enumeration.class										Stack.class
Hashtable.java										StringTokenizer.java
Hashtable.class										StringTokenizer.class
NoSuchElementException.java										Vector.java
NoSuchElementException.class										Vector.class

where each of the .java files contains the source for a compilation unit (§7.3) that contains the definition of a class or interface whose binary compiled form is contained in the corresponding .class file.

Under this simple organization of packages, an implementation of Java would transform a package name into a pathname by concatenating the components of the package name, placing a file name separator (directory indicator) between adjacent components. For example, if this simple organization were used on a UNIX system, where the file name separator is /, the package name:

jag.scrabble.board

would be transformed into the directory name:

jag/scrabble/board

and:

COM.Sun.sunsoft.DOE

would be transformed to the directory name:

COM/Sun/sunsoft/DOE

In fact, the standard JavaSoft Java Developer's Kit on UNIX differs from the very simple discipline described here only in that it provides a CLASSPATH environment variable that specifies a set of directories, each of which is treated like the single directory described here. These directories are searched in order for definitions of named packages and types.

A package name component or class name might contain a character that cannot correctly appear in a host file system's ordinary directory name, such as a Unicode character on a system that allows only ASCII characters in file names. As a convention, the character can be escaped by using, say, the @ character followed by four hexadecimal digits giving the numeric value of the character, as in the \u xxxx escape (§3.3), so that the package name:

children.activities.crafts.papierM\u00e2ch\u00e9

which can also be written using full Unicode as:

children.activities.crafts.papierMache;

might be mapped to the directory name:

children/activities/crafts/papierM@00e2ch@00e9

If the @ character is not a valid character in a file name for some given host file system, then some other character that is not valid in a Java identifier could be used instead.


7.2.2 Storing Packages in a Database

A host system may store packages and their compilation units and subpackages in a database.

Java allows such a database to relax the restrictions (§7.6) on compilation units in file-based implementations. For example, a system that uses a database to store packages need not enforce a maximum of one public class or interface per compilation unit. Systems that use a database must, however, provide an option to convert a Java program to a form that obeys the restrictions, for purposes of export to file-based implementations.


7.3 Compilation Units

CompilationUnit is the goal symbol (§2.1) for the syntactic grammar (§2.3) of Java programs. It is defined by the following productions:

CompilationUnit:

    PackageDeclarationopt ImportDeclarationsopt TypeDeclarationsopt

ImportDeclarations:

    ImportDeclaration

    ImportDeclarations ImportDeclaration

TypeDeclarations:

    TypeDeclaration

    TypeDeclarations TypeDeclaration

Types declared in different compilation units can depend on each other, circularly. A Java compiler must arrange to compile all such types at the same time.

A compilation unit consists of three parts, each of which is optional:

  • A package declaration (§7.4), giving the fully qualified name (§6.7) of the package to which the compilation unit belongs
  • import declarations (§7.5) that allow types from other packages to be referred to using their simple names
  • Type declarations (§7.6) of class and interface types

Every compilation unit automatically and implicitly imports every public type name declared in the predefined package java.lang, so that the names of all those types are available as simple names, as described in §7.5.3.


7.4 Package Declarations

A package declaration appears within a compilation unit to indicate the package to which the compilation unit belongs. A compilation unit that has no package declaration is part of an unnamed package.


7.4.1 Named Packages

A package declaration in a compilation unit specifies the name (§6.2) of the package to which the compilation unit belongs.

PackageDeclaration:

    package PackageName ;

The package name mentioned in a package declaration must be the fully qualified name (§6.7) of the package.

If a type named T is declared in a compilation unit of a package whose fully qualified name is P, then the fully qualified name of the type is P.T; thus in the example:

package wnj.points;
class Point { int x, y; }

the fully qualified name of class Point is wnj.points.Point.


7.4.2 Unnamed Packages

A compilation unit that has no package declaration is part of an unnamed package. As an example, the compilation unit:

class FirstCall {
    public static void main(String[] args) {
        System.out.println("Mr. Watson, come here. "
                                    + "I want you.");
    }
}

defines a very simple compilation unit as part of an unnamed package.

A Java system must support at least one unnamed package; it may support more than one unnamed package but is not required to do so. Which compilation units are in each unnamed package is determined by the host system.

In Java systems that use a hierarchical file system for storing packages, one typical strategy is to associate an unnamed package with each directory; only one unnamed package is available at a time, namely the one that is associated with the "current working directory." The precise meaning of "current working directory" depends on the host system.

Unnamed packages are provided by Java principally for convenience when developing small or temporary applications or when just beginning development.

Caution must be taken when using unnamed packages. It is possible for a compilation unit in a named package to import a type from an unnamed package, but the compiled version of this compilation unit will likely then work only when that particular unnamed package is "current." For this reason, it is strongly recommended that compilation units of named packages never import types from unnamed packages. It is also recommended that any type declared in an unnamed package not be declared public, to keep them from accidentally being imported by a named package.

It is recommended that a Java system provide safeguards against unintended consequences in situations where compilation units of named packages import types from unnamed packages. One strategy is to provide a way to associate with each named package at most one unnamed package, and then to detect and warn about situations in which a named package is used by more than one unnamed package. It is specifically not required-indeed, it is strongly discouraged-for an implementation to support use of a named package by more than one unnamed package by maintaining multiple compiled versions of the named package.


7.4.3 Scope and Hiding of a Package Name

Which top-level package names are in scope (§6.3, §6.5) is determined by conventions of the host system.

Package names never hide other names.


7.4.4 Access to Members of a Package

Whether access to members of a package is allowed is determined by the host system. The package java should always be accessible, and its standard subpackages lang, io, and util should always be accessible.

It is strongly recommended that the protections of a file system or database used to store Java programs be set to make all compilation units of a package available whenever any of the compilation units is available.


7.5 Import Declarations

An import declaration allows a type declared in another package to be referred to by a simple name (§6.2) that consists of a single identifier. Without the use of an appropriate import declaration, the only way to refer to a type declared in another package is to use its fully qualified name (§6.7).

ImportDeclaration:

    SingleTypeImportDeclaration

    TypeImportOnDemandDeclaration

A single-type-import declaration (§7.5.1) imports a single type, by mentioning its fully qualified name. A type-import-on-demand declaration (§7.5.2) imports all the public types of a named package as needed.

An import declaration makes types available by their simple names only within the compilation unit that actually contains the import declaration. The scope of the name(s) it introduces specifically does not include the package statement, other import statements in the current compilation unit, or other compilation units in the same package. Please see §7.5.4 for an illustrative example.


7.5.1 Single-Type-Import Declaration

A single-type-import declaration imports a single type by giving its fully qualified name, making it available under a simple name in the class and interface declarations of its compilation unit.

SingleTypeImportDeclaration:

    import TypeName ;

The TypeName must be the fully qualified name of a class or interface type; a compile-time error occurs if the named type does not exist. If the named type is not in the current package, then it must be accessible (§6.6)-in an accessible package and declared public (§8.1.2, §9.1.2)-or a compile-time error occurs.

The example:

import java.util.Vector;

causes the simple name Vector to be available within the class and interface declarations in a compilation unit. Thus, the simple name Vector refers to the type Vector in the package java.util in all places where it is not hidden (§6.3) by a declaration of a field, parameter, or local variable with the same name.

If two single-type-import declarations in the same compilation unit attempt to import types with the same simple name, then a compile-time error occurs, unless the two types are the same type, in which case the duplicate declaration is ignored. If another type with the same name is otherwise declared in the current compilation unit except by a type-import-on-demand declaration (§7.5.2), then a compile-time error occurs.

So the sample program:

import java.util.Vector;

class Vector { Object[] vec; }

causes a compile-time error because of the duplicate declaration of Vector, as does:

import java.util.Vector;

import myVector.Vector;

where myVector is a package containing the compilation unit:

package myVector;

public class Vector { Object[] vec; }

The compiler keeps track of types by their fully qualified names (§6.7). Simple names and fully qualified names may be used interchangeably whenever they are both available.

Note that an import statement cannot import a subpackage, only a type. For example, it does not work to try to import java.util and then use the name util.Random to refer to the type java.util.Random:

import java.util;										// incorrect: compile-time error

class Test { util.Random generator; }


7.5.2 Type-Import-on-Demand Declaration

A type-import-on-demand declaration allows all public types declared in the package named by a fully qualified name to be imported as needed.

TypeImportOnDemandDeclaration:

    import PackageName . * ;

It is a compile-time error for a type-import-on-demand declaration to name a package that is not accessible (§6.6), as determined by the host system (§7.2). Two or more type-import-on-demand declarations in the same compilation unit may name the same package; the effect is as if there were exactly one such declaration. It is not a compile-time error to name the current package or java.lang in a type-import-on-demand declaration, even though they are already imported; the duplicate type-import-on-demand declaration is ignored.

The example:

import java.util.*;

causes the simple names of all public types declared in the package java.util to be available within the class and interface declarations of the compilation unit. Thus, the simple name Vector refers to the type Vector in the package java.util in all places where it is not hidden (§6.3) by a single-type-import declaration of a type whose simple name is Vector; by a type named Vector and declared in the package to which the compilation unit belongs; or by a declaration of a field, parameter, or local variable named Vector. (It would be unusual for any of these conditions to occur.)


7.5.3 Automatic Imports

Each compilation unit automatically imports each of the public type names declared in the predefined package java.lang, as if the declaration:

import java.lang.*;

appeared at the beginning of each compilation unit, immediately following any package statement.

The full specification of java.lang is given in Chapter 20. The following public types are defined in java.lang:

AbstractMethodError										LinkageError
ArithmeticException										Long
ArrayStoreException										Math
Boolean										NegativeArraySizeException
Character										NoClassDefFoundError
Class										NoSuchFieldError
ClassCastException										NoSuchMethodError
ClassCircularityError										NullPointerException
ClassFormatError										Number
ClassLoader										NumberFormatException
ClassNotFoundException										Object
CloneNotSupportedException										OutOfMemoryError
Cloneable										Process
Compiler										Runnable
Double										Runtime
Error										RuntimeException
Exception										SecurityException
ExceptionInInitializerError										SecurityManager
Float										StackOverflowError
IllegalAccessError										String
IllegalAccessException										StringBuffer
IllegalArgumentException										System
IllegalMonitorStateException										Thread
IllegalThreadStateException										ThreadDeath
IncompatibleClassChangeError										ThreadGroup
IndexOutOfBoundsException										Throwable
InstantiationError										UnknownError
InstantiationException										UnsatisfiedLinkError
Integer										VerifyError
InternalError										VirtualMachineError
InterruptedException


7.5.4 A Strange Example

Package names and type names are usually different under the naming conventions described in §6.8. Nevertheless, in a contrived example where there is an unconventionally-named package Vector, which declares a public class named Mosquito:

package Vector;

public class Mosquito { int capacity; }

and then the compilation unit:

package strange.example;

import java.util.Vector;

import Vector.Mosquito;

class Test {
    public static void main(String[] args) {
        System.out.println(new Vector().getClass());
        System.out.println(new Mosquito().getClass());
    }
}

the single-type-import declaration (§7.5.1) importing class Vector from package java.util does not prevent the package name Vector from appearing and being correctly recognized in subsequent import declarations. The example compiles and produces the output:

class java.util.Vector
class Vector.Mosquito


7.6 Type Declarations

A type declaration declares a class type (§8) or an interface type (§9):

TypeDeclaration:

    ClassDeclaration

    InterfaceDeclaration

    ;

A Java compiler must ignore extra ";" tokens appearing at the level of type declarations. Stray semicolons are permitted in Java solely as a concession to C++ programmers who are used to writing:

class date { int month, day, year; };

(In C++, but not in Java, one can provide a comma-separated list of identifiers in order to declare variables between the "}" and the ";".) Extra semicolons should not be used in new Java code. Software that reformats Java code can delete them.

By default, the types declared in a package are accessible only within the compilation units of that package, but a type may be declared to be public to grant access to the type from code in other packages (§6.6, §8.1.2, §9.1.2).

A Java implementation must keep track of types within packages by their fully qualified names (§6.7). Multiple ways of naming a type must be expanded to fully qualified names to make sure that such names are understood as referring to the same type. For example, if a compilation unit contains the single-type-import declaration (§7.5.1):

import java.util.Vector;

then within that compilation unit the simple name Vector and the fully qualified name java.util.Vector refer to the same type.

When Java packages are stored in a file system (§7.2.1), the host system may choose to enforce the restriction that it is a compile-time error if a type is not found in a file under a name composed of the type name plus an extension (such as .java or .jav) if either of the following is true:

  • The type is referred to by code in other compilation units of the package in which the type is declared.
  • The type is declared public (and therefore is potentially accessible from code in other packages).

This restriction implies that there must be at most one such type per compilation unit. This restriction makes it easy for a Java compiler and Java Virtual Machine to find a named class within a package; for example, the source code for a public type wet.sprocket.Toad would be found in a file Toad.java in the directory wet/sprocket, and the corresponding object code would be found in the file Toad.class in the same directory.

When Java packages are stored in a database (§7.2.2), the host system need not enforce such restrictions.

In practice, many Java programmers choose to put each class or interface type in its own compilation unit, whether or not it is public or is referred to by code in other compilation units.


7.7 Unique Package Names

Did I ever tell you that Mrs. McCave
Had twenty-three sons and she named them all "Dave"?
Well, she did. And that wasn't a smart thing to do. . . .

-Dr. Seuss (Theodore Geisel), Too Many Daves (1961)

Developers should take steps to avoid the possibility of two published packages having the same name by choosing unique package names for packages that are widely distributed. This allows packages to be easily and automatically installed and catalogued. This section specifies a standard convention, not enforced by a Java compiler, for generating such unique package names. Java systems are encouraged to provide automatic support for converting a set of packages from local and casual package names to the unique name format described here.

If unique package names are not used, then package name conflicts may arise far from the point of creation of either of the conflicting packages. This may create a situation that is difficult or impossible for the user or programmer to resolve. The class ClassLoader (§20.14) of the standard Java Virtual Machine environment can be used to isolate packages with the same name from each other in those cases where the packages will have constrained interactions, but not in a way that is transparent to a naive Java program.

You form a unique package name by first having (or belonging to an organization that has) an Internet domain name, such as Sun.COM. You then reverse this name, component by component, to obtain, in this example, COM.Sun, and use this as a prefix for your package names, using a convention developed within your organization to further administer package names.

Such a convention might specify that certain directory name components be division, department, project, machine, or login names. Some possible examples:

COM.Sun.sunsoft.DOE
COM.Sun.java.jag.scrabble
COM.Apple.quicktime.v2
EDU.cmu.cs.bovik.cheese
GOV.whitehouse.socks.mousefinder

The first component of a unique package name is always written in all-uppercase ASCII letters and should be one of the top-level domain names, currently COM, EDU, GOV, MIL, NET, ORG, or one of the English two-letter codes identifying countries as specified in ISO Standard 3166, 1981. For more information, refer to the documents stored at ftp://rs.internic.net/rfc, for example, rfc920.txt and rfc1032.txt.

The name of a package is not meant to imply anything about where the package is stored within the Internet; for example, a package named EDU.cmu.cs.bovik.cheese is not necessarily obtainable from Internet address cmu.EDU or from cs.cmu.EDU or from bovik.cs.cmu.EDU. The Java convention for generating unique package names is merely a way to piggyback a package naming convention on top of an existing, widely known unique name registry instead of having to create a separate registry for Java package names.

If you need to get a new Internet domain name, you can get an application form from ftp://ftp.internic.net and submit the complete forms by E-mail to domreg@internic.net. To find out what the currently registered domain names are, you can telnet to rs.internic.net and use the whois facility.


 8. Classes

CHAPTER 8

Classes

class 1. The noun class derives from Medieval French and French classe from Latin classis, probably originally a summons, hence a summoned collection of persons, a group liable to be summoned: perhaps for callassis from calare, to call, hence to summon.
—Eric Partridge, Origins: A Short Etymological Dictionary of Modern English

Class declarations define new reference types and describe how they are implemented (§8.1).

The name of a class has as its scope all type declarations in the package in which the class is declared (§8.1.1). A class may be declared abstract (§8.1.2.1) and must be declared abstract if it is incompletely implemented; such a class cannot be instantiated, but can be extended by subclasses. A class may be declared final (§8.1.2.2), in which case it cannot have subclasses. If a class is declared public, then it can be referred to from other packages.

Each class except Object is an extension of (that is, a subclass of) a single existing class (§8.1.3) and may implement interfaces (§8.1.4).

The body of a class declares members (fields and methods), static initializers, and constructors (§8.1.5). The scope of the name of a member is the entire declaration of the class to which the member belongs. Field, method, and constructor declarations may include the access modifiers (§6.6) public, protected, or private. The members of a class include both declared and inherited members (§8.2). Newly declared fields can hide fields declared in a superclass or superinterface. Newly declared methods can hide, implement, or override methods declared in a superclass or superinterface.

Field declarations (§8.3) describe class variables, which are incarnated once, and instance variables, which are freshly incarnated for each instance of the class. A field may be declared final (§8.3.1.2), in which case it cannot be assigned to except as part of its declaration. Any field declaration may include an initializer; the declaration of a final field must include an initializer.

Method declarations (§8.4) describe code that may be invoked by method invocation expressions (§15.11). A class method is invoked relative to the class type; an instance method is invoked with respect to some particular object that is an instance of the class type. A method whose declaration does not indicate how it is implemented must be declared abstract. A method may be declared final (§8.4.3.3), in which case it cannot be hidden or overridden. A method may be implemented by platform-dependent native code (§8.4.3.4). A synchronized method (§8.4.3.5) automatically locks an object before executing its body and automatically unlocks the object on return, as if by use of a synchronized statement (§14.17), thus allowing its activities to be synchronized with those of other threads (§17).

Method names may be overloaded (§8.4.7).

Static initializers (§8.5) are blocks of executable code that may be used to help initialize a class when it is first loaded (§12.4).

Constructors (§8.6) are similar to methods, but cannot be invoked directly by a method call; they are used to initialize new class instances. Like methods, they may be overloaded (§8.6.6).


8.1 Class Declaration

A class declaration specifies a new reference type:

ClassDeclaration:

    ClassModifiersopt class Identifier Superopt Interfacesopt ClassBody

If a class is declared in a named package (§7.4.1) with fully qualified name P (§6.7), then the class has the fully qualified name P.Identifier. If the class is in an unnamed package (§7.4.2), then the class has the fully qualified name Identifier. In the example:

class Point { int x, y; }

the class Point is declared in a compilation unit with no package statement, and thus Point is its fully qualified name, whereas in the example:

package vista;
class Point { int x, y; }

the fully qualified name of the class Point is vista.Point. (The package name vista is suitable for local or personal use; if the package were intended to be widely distributed, it would be better to give it a unique package name (§7.7).)

A compile-time error occurs if the Identifier naming a class appears as the name of any other class type or interface type declared in the same package (§7.6).

A compile-time error occurs if the Identifier naming a class is also declared as a type by a single-type-import declaration (§7.5.1) in the compilation unit (§7.3) containing the class declaration.

In the example:

package test;

import java.util.Vector;

class Point {
    int x, y;
}

interface Point {											// compile-time error #1
    int getR();
    int getTheta();
}

class Vector { Point[] pts; }											// compile-time error #2

the first compile-time error is caused by the duplicate declaration of the name Point as both a class and an interface in the same package. A second error detected at compile time is the attempt to declare the name Vector both by a class type declaration and by a single-type-import declaration.

Note, however, that it is not an error for the Identifier that names a class also to name a type that otherwise might be imported by a type-import-on-demand declaration (§7.5.2) in the compilation unit (§7.3) containing the class declaration. In the example:

package test;

import java.util.*;

class Vector { Point[] pts; }											// not a compile-time error

the declaration of the class Vector is permitted even though there is also a class java.util.Vector. Within this compilation unit, the simple name Vector refers to the class test.Vector, not to java.util.Vector (which can still be referred to by code within the compilation unit, but only by its fully qualified name).


8.1.1 Scope of a Class Type Name

The Identifier in a class declaration specifies the name of the class. This class name has as its scope (§6.3) the entire package in which the class is declared. As an example, the compilation unit:

package points;

class Point {
    int x, y;									// coordinates
    PointColor color;									// color of this point
    Point next;									// next point with this color

    static int nPoints;
}

class PointColor {
    Point first;									// first point with this color
    PointColor(int color) {
        this.color = color;
    }
    private int color;									// color components
}

defines two classes that use each other in the declarations of their class members. Because the class type names Point and PointColor have the entire package points, including the entire current compilation unit, as their scope, this example compiles correctly-that is, forward reference is not a problem.


8.1.2 Class Modifiers

A class declaration may include class modifiers.

ClassModifiers:

    ClassModifier

    ClassModifiers ClassModifier

ClassModifier: one of

    public abstract final

The access modifier public is discussed in §6.6. A compile-time error occurs if the same modifier appears more than once in a class declaration. If two or more class modifiers appear in a class declaration, then it is customary, though not required, that they appear in the order consistent with that shown above in the production for ClassModifier.

8.1.2.1 abstract Classes

An abstract class is a class that is incomplete, or to be considered incomplete. Only abstract classes may have abstract methods (§8.4.3.1, §9.4), that is, methods that are declared but not yet implemented. If a class that is not abstract contains an abstract method, then a compile-time error occurs. A class has abstract methods if any of the following is true:

  • It explicitly contains a declaration of an abstract method (§8.4.3).
  • It inherits an abstract method from its direct superclass (§8.1.3).
  • A direct superinterface (§8.1.4) of the class declares or inherits a method (which is therefore necessarily abstract) and the class neither declares nor inherits a method that implements it.

In the example:

abstract class Point {
    int x = 1, y = 1;
    void move(int dx, int dy) {
        x += dx;
        y += dy;
        alert();
    }
    abstract void alert();
}

abstract class ColoredPoint extends Point {
    int color;
}

class SimplePoint extends Point {
    void alert() { }
}

a class Point is declared that must be declared abstract, because it contains a declaration of an abstract method named alert. The subclass of Point named ColoredPoint inherits the abstract method alert, so it must also be declared abstract. On the other hand, the subclass of Point named SimplePoint provides an implementation of alert, so it need not be abstract.

A compile-time error occurs if an attempt is made to create an instance of an abstract class using a class instance creation expression (§15.8). An attempt to instantiate an abstract class using the newInstance method of class Class (§20.3.6) will cause an InstantiationException (§11.5.1) to be thrown. Thus, continuing the example just shown, the statement:

    Point p = new Point();

would result in a compile-time error; the class Point cannot be instantiated because it is abstract. However, a Point variable could correctly be initialized with a reference to any subclass of Point, and the class SimplePoint is not abstract, so the statement:

    Point p = new SimplePoint();

would be correct.

A subclass of an abstract class that is not itself abstract may be instantiated, resulting in the execution of a constructor for the abstract class and, therefore, the execution of the field initializers for instance variables of that class. Thus, in the example just given, instantiation of a SimplePoint causes the default constructor and field initializers for x and y of Point to be executed.

It is a compile-time error to declare an abstract class type such that it is not possible to create a subclass that implements all of its abstract methods. This situation can occur if the class would have as members two abstract methods that have the same method signature (§8.4.2) but different return types. As an example, the declarations:

interface Colorable { void setColor(int color); }

abstract class Colored implements Colorable {
    abstract int setColor(int color);
}

result in a compile-time error: it would be impossible for any subclass of class Colored to provide an implementation of a method named setColor, taking one argument of type int, that can satisfy both abstract method specifications, because the one in interface Colorable requires the same method to return no value, while the one in class Colored requires the same method to return a value of type int (§8.4).

A class type should be declared abstract only if the intent is that subclasses can be created to complete the implementation. If the intent is simply to prevent instantiation of a class, the proper way to express this is to declare a constructor (§8.6.8) of no arguments, make it private, never invoke it, and declare no other constructors. A class of this form usually contains class methods and variables. The class java.lang.Math is an example of a class that cannot be instantiated; its declaration looks like this:

public final class Math {

    private Math() { }							// never instantiate this class

    declarations of class variables and methods

}

8.1.2.2 final Classes

A class can be declared final if its definition is complete and no subclasses are desired or required. A compile-time error occurs if the name of a final class appears in the extends clause (§8.1.3) of another class declaration; this implies that a final class cannot have any subclasses. A compile-time error occurs if a class is declared both final and abstract, because the implementation of such a class could never be completed (§8.1.2.1).

Because a final class never has any subclasses, the methods of a final class are never overridden (§8.4.6.1).


8.1.3 Superclasses and Subclasses

The optional extends clause in a class declaration specifies the direct superclass of the current class. A class is said to be a direct subclass of the class it extends. The direct superclass is the class from whose implementation the implementation of the current class is derived. The extends clause must not appear in the definition of the class java.lang.Object (§20.1), because it is the primordial class and has no direct superclass. If the class declaration for any other class has no extends clause, then the class has the class java.lang.Object as its implicit direct superclass.

Super:

    extends ClassType

The following is repeated from §4.3 to make the presentation here clearer:

ClassType:

    TypeName

The ClassType must name an accessible (§6.6) class type, or a compile-time error occurs. All classes in the current package are accessible. Classes in other packages are accessible if the host system permits access to the package (§7.2) and the class is declared public. If the specified ClassType names a class that is final (§8.1.2.2), then a compile-time error occurs; final classes are not allowed to have subclasses.

In the example:

class Point { int x, y; }

final class ColoredPoint extends Point { int color; }

class Colored3DPoint extends ColoredPoint { int z; } // error

the relationships are as follows:

  • The class Point is a direct subclass of java.lang.Object.
  • The class java.lang.Object is the direct superclass of the class Point.
  • The class ColoredPoint is a direct subclass of class Point.
  • The class Point is the direct superclass of class ColoredPoint.

The declaration of class Colored3dPoint causes a compile-time error because it attempts to extend the final class ColoredPoint.

The subclass relationship is the transitive closure of the direct subclass relationship. A class A is a subclass of class C if either of the following is true:

  • A is the direct subclass of C.
  • There exists a class B such that A is a subclass of B, and B is a subclass of C, applying this definition recursively.

Class C is said to be a superclass of class A whenever A is a subclass of C.

In the example:

class Point { int x, y; }

class ColoredPoint extends Point { int color; }

final class Colored3dPoint extends ColoredPoint { int z; }

the relationships are as follows:

  • The class Point is a superclass of class ColoredPoint.
  • The class Point is a superclass of class Colored3dPoint.
  • The class ColoredPoint is a subclass of class Point.
  • The class ColoredPoint is a superclass of class Colored3dPoint.
  • The class Colored3dPoint is a subclass of class ColoredPoint.
  • The class Colored3dPoint is a subclass of class Point.

A compile-time error occurs if a class is declared to be a subclass of itself. For example:

class Point extends ColoredPoint { int x, y; }

class ColoredPoint extends Point { int color; }

causes a compile-time error. If circularly declared classes are detected at run time, as classes are loaded (§12.2), then a ClassCircularityError is thrown.


8.1.4 Superinterfaces

The optional implements clause in a class declaration lists the names of interfaces that are direct superinterfaces of the class being declared:

Interfaces:

    implements InterfaceTypeList

InterfaceTypeList:

    InterfaceType

    InterfaceTypeList , InterfaceType

The following is repeated from §4.3 to make the presentation here clearer:

InterfaceType:

    TypeName

Each InterfaceType must name an accessible (§6.6) interface type, or a compile- time error occurs. All interfaces in the current package are accessible. Interfaces in other packages are accessible if the host system permits access to the package (§7.4.4) and the interface is declared public.

A compile-time error occurs if the same interface is mentioned two or more times in a single implements clause, even if the interface is named in different ways; for example, the code:

class Redundant implements java.lang.Cloneable, Cloneable {
    int x;
}

results in a compile-time error because the names java.lang.Cloneable and Cloneable refer to the same interface.

An interface type I is a superinterface of class type C if any of the following is true:

  • I is a direct superinterface of C.
  • C has some direct superinterface J for which I is a superinterface, using the definition of "superinterface of an interface" given in §9.1.3.
  • I is a superinterface of the direct superclass of C, using this definition recursively.

A class is said to implement all its superinterfaces.

In the example:

public interface Colorable {
    void setColor(int color);
    int getColor();
}

public interface Paintable extends Colorable {
    int MATTE = 0, GLOSSY = 1;
    void setFinish(int finish);
    int getFinish();
}

class Point { int x, y; }

class ColoredPoint extends Point implements Colorable {
    int color;
    public void setColor(int color) { this.color = color; }
    public int getColor() { return color; }
}

class PaintedPoint extends ColoredPoint implements Paintable

{
    int finish;
    public void setFinish(int finish) {
        this.finish = finish;
    }
    public int getFinish() { return finish; }
}

the relationships are as follows:

  • The interface Paintable is a superinterface of class PaintedPoint.
  • The interface Colorable is a superinterface of class ColoredPoint and of class PaintedPoint.
  • The interface Paintable is a subinterface of the interface Colorable, and Colorable is a superinterface of Paintable, as defined in §9.1.3.

A class can have a superinterface in more than one way. In this example, the class PaintedPoint has Colorable as a superinterface both because it is a superinterface of ColoredPoint and because it is a superinterface of Paintable.

Unless the class being declared is abstract, the declarations of the methods defined in each direct superinterface must be implemented either by a declaration in this class or by an existing method declaration inherited from the direct superclass, because a class that is not abstract is not permitted to have abstract methods (§8.1.2.1).

Thus, the example:

interface Colorable {
    void setColor(int color);
    int getColor();
}

class Point { int x, y; };

class ColoredPoint extends Point implements Colorable {
    int color;
}

causes a compile-time error, because ColoredPoint is not an abstract class but it fails to provide an implementation of methods setColor and getColor of the interface Colorable.

It is permitted for a single method declaration in a class to implement methods of more than one superinterface. For example, in the code:

interface Fish { int getNumberOfScales(); }

interface Piano { int getNumberOfScales(); }

class Tuna implements Fish, Piano {
    // You can tune a piano, but can you tuna fish?
    int getNumberOfScales() { return 91; }
}

the method getNumberOfScales in class Tuna has a name, signature, and return type that matches the method declared in interface Fish and also matches the method declared in interface Piano; it is considered to implement both.

On the other hand, in a situation such as this:

interface Fish { int getNumberOfScales(); }

interface StringBass { double getNumberOfScales(); }

class Bass implements Fish, StringBass {
    // This declaration cannot be correct, no matter what type is used.
    public ??? getNumberOfScales() { return 91; }
}

it is impossible to declare a method named getNumberOfScales with the same signature and return type as those of both the methods declared in interface Fish and in interface StringBass, because a class can have only one method with a given signature (§8.4). Therefore, it is impossible for a single class to implement both interface Fish and interface StringBass (§8.4.6).


8.1.5 Class Body and Member Declarations

A class body may contain declarations of members of the class, that is, fields (§8.3) and methods (§8.4). A class body may also contain static initializers (§8.5) and declarations of constructors (§8.6) for the class.

ClassBody:

    { ClassBodyDeclarationsopt }

ClassBodyDeclarations:

    ClassBodyDeclaration

    ClassBodyDeclarations ClassBodyDeclaration

ClassBodyDeclaration:

    ClassMemberDeclaration

    StaticInitializer

    ConstructorDeclaration

ClassMemberDeclaration:

    FieldDeclaration

    MethodDeclaration

The scope of the name of a member declared in or inherited by a class type is the entire body of the class type declaration.


8.2 Class Members

The members of a class type are all of the following:

  • Members inherited from its direct superclass (§8.1.3), except in class Object, which has no direct superclass
  • Members inherited from any direct superinterfaces (§8.1.4)
  • Members declared in the body of the class (§8.1.5)

Members of a class that are declared private are not inherited by subclasses of that class. Only members of a class that are declared protected or public are inherited by subclasses declared in a package other than the one in which the class is declared.

Constructors and static initializers are not members and therefore are not inherited.

The example:

class Point {
    int x, y;
    private Point() { reset(); }
    Point(int x, int y) { this.x = x; this.y = y; }
    private void reset() { this.x = 0; this.y = 0; }
}

class ColoredPoint extends Point {
    int color;
    void clear() { reset(); }														// error
}

class Test {
    public static void main(String[] args) {
        ColoredPoint c = new ColoredPoint(0, 0);													// error
        c.reset();													// error
    }
}

causes four compile-time errors:

  • An error occurs because ColoredPoint has no constructor declared with two integer parameters, as requested by the use in main. This illustrates the fact that ColoredPoint does not inherit the constructors of its superclass Point.
  • Another error occurs because ColoredPoint declares no constructors, and therefore a default constructor for it is automatically created (§8.6.7), and this default constructor is equivalent to: ColoredPoint() { super(); }

which invokes the constructor, with no arguments, for the direct superclass of the class ColoredPoint. The error is that the constructor for Point that takes no arguments is private, and therefore is not accessible outside the class Point, even through a superclass constructor invocation (§8.6.5).

  • Two more errors occur because the method reset of class Point is private, and therefore is not inherited by class ColoredPoint. The method invocations in method clear of class ColoredPoint and in method main of class Test are therefore not correct.


8.2.1 Examples of Inheritance

This section illustrates inheritance of class members through several examples.

8.2.1.1 Example: Inheritance with Default Access

Consider the example where the points package declares two compilation units:

package points;

public class Point {
    int x, y;

    public void move(int dx, int dy) { x += dx; y += dy; }
}

and:

package points;

public class Point3d extends Point {
    int z;
    public void move(int dx, int dy, int dz) {
        x += dx; y += dy; z += dz;
    }
}

and a third compilation unit, in another package, is:

import points.Point3d;

class Point4d extends Point3d {
    int w;
    public void move(int dx, int dy, int dz, int dw) {
        x += dx; y += dy; z += dz; w += dw; // compile-time errors
    }
}

Here both classes in the points package compile. The class Point3d inherits the fields x and y of class Point, because it is in the same package as Point. The class Point4d, which is in a different package, does not inherit the fields x and y of class Point or the field z of class Point3d, and so fails to compile.

A better way to write the third compilation unit would be:

import points.Point3d;

class Point4d extends Point3d {
    int w;
    public void move(int dx, int dy, int dz, int dw) {
        super.move(dx, dy, dz); w += dw;
    }
}

using the move method of the superclass Point3d to process dx, dy, and dz. If Point4d is written in this way it will compile without errors.

8.2.1.2 Inheritance with public and protected

Given the class Point:

package points;

public class Point {

    public int x, y;

    protected int useCount = 0;

    static protected int totalUseCount = 0;

    public void move(int dx, int dy) {
        x += dx; y += dy; useCount++; totalUseCount++;
    }

}

the public and protected fields x, y, useCount and totalUseCount are inherited in all subclasses of Point. Therefore, this test program, in another package, can be compiled successfully:

class Test extends points.Point {
    public void moveBack(int dx, int dy) {
        x -= dx; y -= dy; useCount++; totalUseCount++;
    }
}

8.2.1.3 Inheritance with private

In the example:

class Point {

    int x, y;

    void move(int dx, int dy) {
        x += dx; y += dy; totalMoves++;
    }

    private static int totalMoves;

    void printMoves() { System.out.println(totalMoves); }

}

class Point3d extends Point {

    int z;

    void move(int dx, int dy, int dz) {
        super.move(dx, dy); z += dz; totalMoves++;
    }

}

the class variable totalMoves can be used only within the class Point; it is not inherited by the subclass Point3d. A compile-time error occurs at the point where method move of class Point3d tries to increment totalMoves.

8.2.1.4 Accessing Members of Inaccessible Classes

Even though a class might not be declared public, instances of the class might be available at run time to code outside the package in which it is declared if it has a public superclass or superinterface. An instance of the class can be assigned to a variable of such a public type. An invocation of a public method of the object referred to by such a variable may invoke a method of the class if it implements or overrides a method of the public superclass or superinterface. (In this situation, the method is necessarily declared public, even though it is declared in a class that is not public.)

Consider the compilation unit:

package points;

public class Point {
    public int x, y;
    public void move(int dx, int dy) {
        x += dx; y += dy;
    }
}

and another compilation unit of another package:

package morePoints;

class Point3d extends points.Point {
    public int z;
    public void move(int dx, int dy, int dz) {
        super.move(dx, dy); z += dz;
    }
}

public class OnePoint {
    static points.Point getOne() { return new Point3d(); }
}

An invocation morePoints.OnePoint.getOne() in yet a third package would return a Point3d that can be used as a Point, even though the type Point3d is not available outside the package morePoints. The method move could then be invoked for that object, which is permissible because method move of Point3d is public (as it must be, for any method that overrides a public method must itself be public, precisely so that situations such as this will work out correctly). The fields x and y of that object could also be accessed from such a third package.

While the field z of class Point3d is public, it is not possible to access this field from code outside the package morePoints, given only a reference to an instance of class Point3d in a variable p of type Point. This is because the expression p.z is not correct, as p has type Point and class Point has no field named z; also, the expression ((Point3d)p).z is not correct, because the class type Point3d cannot be referred to outside package morePoints. The declaration of the field z as public is not useless, however. If there were to be, in package morePoints, a public subclass Point4d of the class Point3d:

package morePoints;

public class Point4d extends Point3d {
    public int w;
    public void move(int dx, int dy, int dz, int dw) {
        super.move(dx, dy, dz); w += dw;
    }
}

then class Point4d would inherit the field z, which, being public, could then be accessed by code in packages other than morePoints, through variables and expressions of the public type Point4d.


8.3 Field Declarations

Poetic fields encompass me around,
And still I seem to tread on classic ground.
—Joseph Addison (1672-1719), A Letter from Italy

The variables of a class type are introduced by field declarations:

FieldDeclaration:

    FieldModifiersopt Type VariableDeclarators ;

VariableDeclarators:

    VariableDeclarator

    VariableDeclarators , VariableDeclarator

VariableDeclarator:

    VariableDeclaratorId

    VariableDeclaratorId = VariableInitializer

VariableDeclaratorId:

    Identifier

    VariableDeclaratorId [ ]

VariableInitializer:

    Expression

    ArrayInitializer

The FieldModifiers are described in §8.3.1. The Identifier in a FieldDeclarator may be used in a name to refer to the field. The name of a field has as its scope (§6.3) the entire body of the class declaration in which it is declared. More than one field may be declared in a single field declaration by using more than one declarator; the FieldModifiers and Type apply to all the declarators in the declaration. Variable declarations involving array types are discussed in §10.2.

It is a compile-time error for the body of a class declaration to contain declarations of two fields with the same name. Methods and fields may have the same name, since they are used in different contexts and are disambiguated by the different lookup procedures (§6.5).

If the class declares a field with a certain name, then the declaration of that field is said to hide (§6.3.1) any and all accessible declarations of fields with the same name in the superclasses and superinterfaces of the class.

If a field declaration hides the declaration of another field, the two fields need not have the same type.

A class inherits from its direct superclass and direct superinterfaces all the fields of the superclass and superinterfaces that are both accessible to code in the class and not hidden by a declaration in the class.

It is possible for a class to inherit more than one field with the same name (§8.3.3.3). Such a situation does not in itself cause a compile-time error. However, any attempt within the body of the class to refer to any such field by its simple name will result in a compile-time error, because such a reference is ambiguous.

There might be several paths by which the same field declaration might be inherited from an interface. In such a situation, the field is considered to be inherited only once, and it may be referred to by its simple name without ambiguity.

A hidden field can be accessed by using a qualified name (if it is static) or by using a field access expression (§15.10) that contains the keyword super or a cast to a superclass type. See §15.10.2 for discussion and an example.


8.3.1 Field Modifiers

FieldModifiers:

    FieldModifier

    FieldModifiers FieldModifier

FieldModifier: one of

    public protected private

    final static transient volatile

The access modifiers public, protected, and private are discussed in §6.6. A compile-time error occurs if the same modifier appears more than once in a field declaration, or if a field declaration has more than one of the access modifiers public, protected, and private. If two or more (distinct) field modifiers appear in a field declaration, it is customary, though not required, that they appear in the order consistent with that shown above in the production for FieldModifier.

8.3.1.1 static Fields

If a field is declared static, there exists exactly one incarnation of the field, no matter how many instances (possibly zero) of the class may eventually be created. A static field, sometimes called a class variable, is incarnated when the class is initialized (§12.4).

A field that is not declared static (sometimes called a non-static field) is called an instance variable. Whenever a new instance of a class is created, a new variable associated with that instance is created for every instance variable declared in that class or any of its superclasses.

The example program:

class Point {
    int x, y, useCount;
    Point(int x, int y) { this.x = x; this.y = y; }
    final static Point origin = new Point(0, 0);
}

class Test {
    public static void main(String[] args) {
        Point p = new Point(1,1);
        Point q = new Point(2,2);
        p.x = 3; p.y = 3; p.useCount++; p.origin.useCount++;
        System.out.println("(" + q.x + "," + q.y + ")");
        System.out.println(q.useCount);
        System.out.println(q.origin == Point.origin);
        System.out.println(q.origin.useCount);
    }
}

prints:

(2,2)
0
true
1

showing that changing the fields x, y, and useCount of p does not affect the fields of q, because these fields are instance variables in distinct objects. In this example, the class variable origin of the class Point is referenced both using the class name as a qualifier, in Point.origin, and using variables of the class type in field access expressions (§15.10), as in p.origin and q.origin. These two ways of accessing the origin class variable access the same object, evidenced by the fact that the value of the reference equality expression (§15.20.3):

q.origin==Point.origin

is true. Further evidence is that the incrementation:

p.origin.useCount++;

causes the value of q.origin.useCount to be 1; this is so because p.origin and q.origin refer to the same variable.

8.3.1.2 final Fields

A field can be declared final, in which case its declarator must include a variable initializer or a compile-time error occurs. Both class and instance variables (static and non-static fields) may be declared final.

Any attempt to assign to a final field results in a compile-time error. Therefore, once a final field has been initialized, it always contains the same value. If a final field holds a reference to an object, then the state of the object may be changed by operations on the object, but the field will always refer to the same object. This applies also to arrays, because arrays are objects; if a final field holds a reference to an array, then the components of the array may be changed by operations on the array, but the field will always refer to the same array.

Declaring a field final can serve as useful documentation that its value will not change, can help to avoid programming errors, and can make it easier for a compiler to generate efficient code.

In the example:

class Point {
    int x, y;
    int useCount;
    Point(int x, int y) { this.x = x; this.y = y; }
    final static Point origin = new Point(0, 0);
}

the class Point declares a final class variable origin. The origin variable holds a reference to an object that is an instance of class Point whose coordinates are (0, 0). The value of the variable Point.origin can never change, so it always refers to the same Point object, the one created by its initializer. However, an operation on this Point object might change its state-for example, modifying its useCount or even, misleadingly, its x or y coordinate.

8.3.1.3 transient Fields

Variables may be marked transient to indicate that they are not part of the persistent state of an object. If an instance of the class Point:

class Point {
    int x, y;
    transient float rho, theta;
}

were saved to persistent storage by a system service, then only the fields x and y would be saved. This specification does not yet specify details of such services; we intend to provide them in a future version of this specification.

8.3.1.4 volatile Fields

As described in §17, the Java language allows threads that access shared variables to keep private working copies of the variables; this allows a more efficient implementation of multiple threads. These working copies need be reconciled with the master copies in the shared main memory only at prescribed synchronization points, namely when objects are locked or unlocked. As a rule, to ensure that shared variables are consistently and reliably updated, a thread should ensure that it has exclusive use of such variables by obtaining a lock that, conventionally, enforces mutual exclusion for those shared variables.

Java provides a second mechanism that is more convenient for some purposes: a field may be declared volatile, in which case a thread must reconcile its working copy of the field with the master copy every time it accesses the variable. Moreover, operations on the master copies of one or more volatile variables on behalf of a thread are performed by the main memory in exactly the order that the thread requested.

If, in the following example, one thread repeatedly calls the method one (but no more than Integer.MAX_VALUE (§20.7.2) times in all), and another thread repeatedly calls the method two:

class Test {

    static int i = 0, j = 0;

    static void one() { i++; j++; }

    static void two() {
        System.out.println("i=" + i + " j=" + j);
    }

}

then method two could occasionally print a value for j that is greater than the value of i, because the example includes no synchronization and, under the rules explained in §17, the shared values of i and j might be updated out of order.

One way to prevent this out-or-order behavior would be to declare methods one and two to be synchronized (§8.4.3.5):

class Test {

    static int i = 0, j = 0;

    static synchronized void one() { i++; j++; }

    static synchronized void two() {
        System.out.println("i=" + i + " j=" + j);
    }

}

This prevents method one and method two from being executed concurrently, and furthermore guarantees that the shared values of i and j are both updated before method one returns. Therefore method two never observes a value for j greater than that for i; indeed, it always observes the same value for i and j.

Another approach would be to declare i and j to be volatile:

class Test {

    static volatile int i = 0, j = 0;

    static void one() { i++; j++; }

    static void two() {
        System.out.println("i=" + i + " j=" + j);
    }

}

This allows method one and method two to be executed concurrently, but guarantees that accesses to the shared values for i and j occur exactly as many times, and in exactly the same order, as they appear to occur during execution of the program text by each thread. Therefore, method two never observes a value for j greater than that for i, because each update to i must be reflected in the shared value for i before the update to j occurs. It is possible, however, that any given invocation of method two might observe a value for j that is much greater than the value observed for i, because method one might be executed many times between the moment when method two fetches the value of i and the moment when method two fetches the value of j.

See §17 for more discussion and examples.

A compile-time error occurs if a final variable is also declared volatile.


8.3.2 Initialization of Fields

If a field declarator contains a variable initializer, then it has the semantics of an assignment (§15.25) to the declared variable, and:

  • If the declarator is for a class variable (that is, a static field), then the variable initializer is evaluated and the assignment performed exactly once, when the class is initialized (§12.4).
  • If the declarator is for an instance variable (that is, a field that is not static), then the variable initializer is evaluated and the assignment performed each time an instance of the class is created (§12.5).

The example:

class Point {
    int x = 1, y = 5;
}

class Test {
    public static void main(String[] args) {
        Point p = new Point();
        System.out.println(p.x + ", " + p.y);
    }
}

produces the output:

1, 5

because the assignments to x and y occur whenever a new Point is created.

Variable initializers are also used in local variable declaration statements (§14.3), where the initializer is evaluated and the assignment performed each time the local variable declaration statement is executed.

It is a compile-time error if the evaluation of a variable initializer for a field of a class (or interface) can complete abruptly with a checked exception (§11.2).

8.3.2.1 Initializers for Class Variables

A compile-time error occurs if an initialization expression for a class variable contains a use by a simple name of that class variable or of another class variable whose declaration occurs to its right (that is, textually later) in the same class. Thus:

class Test {
    static float f = j;							// compile-time error: forward reference
    static int j = 1;
    static int k = k+1;							// compile-time error: forward reference
}

causes two compile-time errors, because j is referred to in the initialization of f before j is declared and because the initialization of k refers to k itself.

If a reference by simple name to any instance variable occurs in an initialization expression for a class variable, then a compile-time error occurs.

If the keyword this (§15.7.2) or the keyword super (§15.10.2, §15.11) occurs in an initialization expression for a class variable, then a compile-time error occurs.

(One subtlety here is that, at run time, static variables that are final and that are initialized with compile-time constant values are initialized first. This also applies to such fields in interfaces (§9.3.1). These variables are "constants" that will never be observed to have their default initial values (§4.5.4), even by devious programs. See §12.4.2 and §13.4.8 for more discussion.)

8.3.2.2 Initializers for Instance Variables

A compile-time error occurs if an initialization expression for an instance variable contains a use by a simple name of that instance variable or of another instance variable whose declaration occurs to its right (that is, textually later) in the same class. Thus:

class Test {
    float f = j;
    int j = 1;
    int k = k+1;
}

causes two compile-time errors, because j is referred to in the initialization of f before j is declared and because the initialization of k refers to k itself.

Initialization expressions for instance variables may use the simple name of any static variable declared in or inherited by the class, even one whose declaration occurs textually later. Thus the example:

class Test {
    float f = j;
    static int j = 1;
}

compiles without error; it initializes j to 1 when class Test is initialized, and initializes f to the current value of j every time an instance of class Test is created.

Initialization expressions for instance variables are permitted to refer to the current object this (§15.7.2) and to use the keyword super (§15.10.2, §15.11).


8.3.3 Examples of Field Declarations

The following examples illustrate some (possibly subtle) points about field declarations.

8.3.3.1 Example: Hiding of Class Variables

The example:

class Point {
    static int x = 2;
}

class Test extends Point {
    static double x = 4.7;
    public static void main(String[] args) {

        new Test().printX();
    }
    void printX() {
        System.out.println(x + " " + super.x);
    }
}

produces the output:

4.7 2

because the declaration of x in class Test hides the definition of x in class Point, so class Test does not inherit the field x from its superclass Point. Within the declaration of class Test, the simple name x refers to the field declared within class Test. Code in class Test may refer to the field x of class Point as super.x (or, because x is static, as Point.x). If the declaration of Test.x is deleted:

class Point {
    static int x = 2;
}

class Test extends Point {
    public static void main(String[] args) {
        new Test().printX();
    }
    void printX() {
        System.out.println(x + " " + super.x);
    }
}

then the field x of class Point is no longer hidden within class Test; instead, the simple name x now refers to the field Point.x. Code in class Test may still refer to that same field as super.x. Therefore, the output from this variant program is:

2 2

8.3.3.2 Example: Hiding of Instance Variables

This example is similar to that in the previous section, but uses instance variables rather than static variables. The code:

class Point {
    int x = 2;
}

class Test extends Point {
    double x = 4.7;
    void printBoth() {
        System.out.println(x + " " + super.x);
    }
    public static void main(String[] args) {
        Test sample = new Test();
        sample.printBoth();
        System.out.println(sample.x + " " +

                                                ((Point)sample).x);
    }
}

produces the output:

4.7 2
4.7 2

because the declaration of x in class Test hides the definition of x in class Point, so class Test does not inherit the field x from its superclass Point. It must be noted, however, that while the field x of class Point is not inherited by class Test, it is nevertheless implemented by instances of class Test. In other words, every instance of class Test contains two fields, one of type int and one of type float. Both fields bear the name x, but within the declaration of class Test, the simple name x always refers to the field declared within class Test. Code in instance methods of class Test may refer to the instance variable x of class Point as super.x.

Code that uses a field access expression to access field x will access the field named x in the class indicated by the type of reference expression. Thus, the expression sample.x accesses a float value, the instance variable declared in class Test, because the type of the variable sample is Test, but the expression ((Point)sample).x accesses an int value, the instance variable declared in class Point, because of the cast to type Point.

If the declaration of x is deleted from class Test, as in the program:

class Point {
    static int x = 2;
}

class Test extends Point {
    void printBoth() {
        System.out.println(x + " " + super.x);
    }
    public static void main(String[] args) {
        Test sample = new Test();
        sample.printBoth();
        System.out.println(sample.x + " " +

                                                ((Point)sample).x);
    }
}

then the field x of class Point is no longer hidden within class Test. Within instance methods in the declaration of class Test, the simple name x now refers to the field declared within class Point. Code in class Test may still refer to that same field as super.x. The expression sample.x still refers to the field x within type Test, but that field is now an inherited field, and so refers to the field x declared in class Point. The output from this variant program is:

2 2
2 2

8.3.3.3 Example: Multiply Inherited Fields

A class may inherit two or more fields with the same name, either from two interfaces or from its superclass and an interface. A compile-time error occurs on any attempt to refer to any ambiguously inherited field by its simple name. A qualified name or a field access expression that contains the keyword super (§15.10.2) may be used to access such fields unambiguously. In the example:

interface Frob { float v = 2.0f; }

class SuperTest { int v = 3; }

class Test extends SuperTest implements Frob {
    public static void main(String[] args) {
        new Test().printV();
    }
    void printV() { System.out.println(v); }
}

the class Test inherits two fields named v, one from its superclass SuperTest and one from its superinterface Frob. This in itself is permitted, but a compile-time error occurs because of the use of the simple name v in method printV: it cannot be determined which v is intended.

The following variation uses the field access expression super.v to refer to the field named v declared in class SuperTest and uses the qualified name Frob.v to refer to the field named v declared in interface Frob:

interface Frob { float v = 2.0f; }

class SuperTest { int v = 3; }

class Test extends SuperTest implements Frob {
    public static void main(String[] args) {
        new Test().printV();
    }
    void printV() {
        System.out.println((super.v + Frob.v)/2);
    }
}

It compiles and prints:

2.5

Even if two distinct inherited fields have the same type, the same value, and are both final, any reference to either field by simple name is considered ambiguous and results in a compile-time error. In the example:

interface Color { int RED=0, GREEN=1, BLUE=2; }

interface TrafficLight { int RED=0, YELLOW=1, GREEN=2; }

class Test implements Color, TrafficLight {
    public static void main(String[] args) {
        System.out.println(GREEN);										// compile-time error
        System.out.println(RED);										// compile-time error
    }
}

it is not astonishing that the reference to GREEN should be considered ambiguous, because class Test inherits two different declarations for GREEN with different values. The point of this example is that the reference to RED is also considered ambiguous, because two distinct declarations are inherited. The fact that the two fields named RED happen to have the same type and the same unchanging value does not affect this judgment.

8.3.3.4 Example: Re-inheritance of Fields

If the same field declaration is inherited from an interface by multiple paths, the field is considered to be inherited only once. It may be referred to by its simple name without ambiguity. For example, in the code:

public interface Colorable {
    int RED = 0xff0000, GREEN = 0x00ff00, BLUE = 0x0000ff;
}

public interface Paintable extends Colorable {
    int MATTE = 0, GLOSSY = 1;
}

class Point { int x, y; }

class ColoredPoint extends Point implements Colorable {
    . . .
}

class PaintedPoint extends ColoredPoint implements Paintable
{
    . . .       RED       . . .
}

the fields RED, GREEN, and BLUE are inherited by the class PaintedPoint both through its direct superclass ColoredPoint and through its direct superinterface Paintable. The simple names RED, GREEN, and BLUE may nevertheless be used without ambiguity within the class PaintedPoint to refer to the fields declared in interface Colorable.


8.4 Method Declarations

The diversity of physical arguments and opinions embraces all sorts of methods.
—Michael de Montaigne (1533-1592), Of Experience

A method declares executable code that can be invoked, passing a fixed number of values as arguments.

MethodDeclaration:

    MethodHeader MethodBody

MethodHeader:

    MethodModifiersopt ResultType MethodDeclarator Throwsopt

ResultType:

    Type

    void

MethodDeclarator:

    Identifer ( FormalParameterListopt )

The MethodModifiers are described in §8.4.3, the Throws clause in §8.4.4, and the MethodBody in §8.4.5. A method declaration either specifies the type of value that the method returns or uses the keyword void to indicate that the method does not return a value.

The Identifier in a MethodDeclarator may be used in a name to refer to the method. A class can declare a method with the same name as the class or a field of the class.

For compatibility with older versions of Java, a declaration form for a method that returns an array is allowed to place (some or all of) the empty bracket pairs that form the declaration of the array type after the parameter list. This is supported by the obsolescent production:

MethodDeclarator:

    MethodDeclarator [ ]

but should not be used in new Java code.

It is a compile-time error for the body of a class to have as members two methods with the same signature (§8.4.2) (name, number of parameters, and types of any parameters). Methods and fields may have the same name, since they are used in different contexts and are disambiguated by the different lookup procedures (§6.5).


8.4.1 Formal Parameters

The formal parameters of a method, if any, are specified by a list of comma-separated parameter specifiers. Each parameter specifier consists of a type and an identifier (optionally followed by brackets) that specifies the name of the parameter:

FormalParameterList:

    FormalParameter

    FormalParameterList , FormalParameter

FormalParameter:

    Type VariableDeclaratorId

The following is repeated from §8.3 to make the presentation here clearer:

VariableDeclaratorId:

    Identifier

    VariableDeclaratorId [ ]

If a method has no parameters, only an empty pair of parentheses appears in the method's declaration.

If two formal parameters are declared to have the same name (that is, their declarations mention the same Identifier), then a compile-time error occurs.

When the method is invoked (§15.11), the values of the actual argument expressions initialize newly created parameter variables, each of the declared Type, before execution of the body of the method. The Identifier that appears in the DeclaratorId may be used as a simple name in the body of the method to refer to the formal parameter.

The scope of formal parameter names is the entire body of the method. These parameter names may not be redeclared as local variables or exception parameters within the method; that is, hiding the name of a parameter is not permitted.

Formal parameters are referred to only using simple names, never by using qualified names (§6.6).


8.4.2 Method Signature

The signature of a method consists of the name of the method and the number and types of formal parameters to the method. A class may not declare two methods with the same signature, or a compile-time error occurs. The example:

class Point implements Move {
    int x, y;
    abstract void move(int dx, int dy);
    void move(int dx, int dy) { x += dx; y += dy; }
}

causes a compile-time error because it declares two move methods with the same signature. This is an error even though one of the declarations is abstract.


8.4.3 Method Modifiers

MethodModifiers:

    MethodModifier

    MethodModifiers MethodModifier

MethodModifier: one of

    public protected private

    abstract static final synchronized native

The access modifiers public, protected, and private are discussed in §6.6. A compile-time error occurs if the same modifier appears more than once in a method declaration, or if a method declaration has more than one of the access modifiers public, protected, and private. A compile-time error occurs if a method declaration that contains the keyword abstract also contains any one of the keywords private, static, final, native, or synchronized.

If two or more method modifiers appear in a method declaration, it is customary, though not required, that they appear in the order consistent with that shown above in the production for MethodModifier.

8.4.3.1 abstract Methods

An abstract method declaration introduces the method as a member, providing its signature (name and number and type of parameters), return type, and throws clause (if any), but does not provide an implementation. The declaration of an abstract method m must appear within an abstract class (call it A); otherwise a compile-time error results. Every subclass of A that is not abstract must provide an implementation for m, or a compile-time error occurs. More precisely, for every subclass C of the abstract class A, if C is not abstract, then there must be some class B such that all of the following are true:

  • B is a superclass of C or is C itself.
  • B is a subclass of A.
  • B provides a declaration of the method m that is not abstract, and this declaration is inherited by C, thereby providing an implementation of method m that is visible to C.

If there is no such class B, then a compile-time error occurs.

It is a compile-time error for a private method to be declared abstract. It would be impossible for a subclass to implement a private abstract method, because private methods are not visible to subclasses; therefore such a method could never be used.

It is a compile-time error for a static method to be declared abstract.

It is a compile-time error for a final method to be declared abstract.

An abstract class can override an abstract method by providing another abstract method declaration. This can provide a place to put a documentation comment (§18), or to declare that the set of checked exceptions (§11.2) that can be thrown by that method, when it is implemented by its subclasses, is to be more limited. For example, consider this code:

class BufferEmpty extends Exception {
    BufferEmpty() { super(); }
    BufferEmpty(String s) { super(s); }
}

class BufferError extends Exception {
    BufferError() { super(); }
    BufferError(String s) { super(s); }
}

public interface Buffer {
    char get() throws BufferEmpty, BufferError;
}

public abstract class InfiniteBuffer implements Buffer {
    abstract char get() throws BufferError;
}

The overriding declaration of method get in class InfiniteBuffer states that method get in any subclass of InfiniteBuffer never throws a BufferEmpty exception, putatively because it generates the data in the buffer, and thus can never run out of data.

An instance method that is not abstract can be overridden by an abstract method. For example, we can declare an abstract class Point that requires its subclasses to implement toString if they are to be complete, instantiable classes:

abstract class Point {
    int x, y;
    public abstract String toString();
}

This abstract declaration of toString overrides the non-abstract toString method of class Object (§20.1.2). (Class Object is the implicit direct superclass of class Point.) Adding the code:

class ColoredPoint extends Point {
    int color;
    public String toString() {
        return super.toString() + ": color " + color; // error
    }
}

results in a compile-time error because the invocation super.toString() refers to method toString in class Point, which is abstract and therefore cannot be invoked. Method toString of class Object can be made available to class ColoredPoint only if class Point explicitly makes it available through some other method, as in:

abstract class Point {
    int x, y;
    public abstract String toString();
    protected String objString() { return super.toString(); }
}

class ColoredPoint extends Point {
    int color;
    public String toString() {
        return objString() + ": color " + color;														// correct
    }
}

8.4.3.2 static Methods

A method that is declared static is called a class method. A class method is always invoked without reference to a particular object. An attempt to reference the current object using the keyword this or the keyword super in the body of a class method results in a compile time error. It is a compile-time error for a static method to be declared abstract.

A method that is not declared static is called an instance method, and sometimes called a non-static method). An instance method is always invoked with respect to an object, which becomes the current object to which the keywords this and super refer during execution of the method body.

8.4.3.3 final Methods

A method can be declared final to prevent subclasses from overriding or hiding it. It is a compile-time error to attempt to override or hide a final method.

A private method and all methods declared in a final class (§8.1.2.2) are implicitly final, because it is impossible to override them. It is permitted but not required for the declarations of such methods to redundantly include the final keyword.

It is a compile-time error for a final method to be declared abstract.

At run-time, a machine-code generator or optimizer can easily and safely "inline" the body of a final method, replacing an invocation of the method with the code in its body, as in the example:

final class Point {
    int x, y;
    void move(int dx, int dy) { x += dx; y += dy; }
}

class Test {
    public static void main(String[] args) {
        Point[] p = new Point[100];
        for (int i = 0; i < p.length; i++) {
            p[i] = new Point();
            p[i].move(i, p.length-1-i);
        }
    }
}

Here, inlining the method move of class Point in method main would transform the for loop to the form:

        for (int i = 0; i < p.length; i++) {
            p[i] = new Point();
            Point pi = p[i];
            pi.x += i;
            pi.y += p.length-1-i;
        }

The loop might then be subject to further optimizations.

Such inlining cannot be done at compile time unless it can be guaranteed that Test and Point will always be recompiled together, so that whenever Point-and specifically its move method-changes, the code for Test.main will also be updated.

8.4.3.4 native Methods

A method that is native is implemented in platform-dependent code, typically written in another programming language such as C, C++, FORTRAN, or assembly language. The body of a native method is given as a semicolon only, indicating that the implementation is omitted, instead of a block.

A compile-time error occurs if a native method is declared abstract.

For example, the class RandomAccessFile of the standard package java.io might declare the following native methods:

package java.io;

public class RandomAccessFile

    implements DataOutput, DataInput
{	. . .
    public native void open(String name, boolean writeable)
        throws IOException;
    public native int readBytes(byte[] b, int off, int len)
        throws IOException;
    public native void writeBytes(byte[] b, int off, int len)
        throws IOException;
    public native long getFilePointer() throws IOException;
    public native void seek(long pos) throws IOException;
    public native long length() throws IOException;
    public native void close() throws IOException;
}

8.4.3.5 synchronized Methods

A synchronized method acquires a lock (§17.1) before it executes. For a class (static) method, the lock associated with the Class object (§20.3) for the method's class is used. For an instance method, the lock associated with this (the object for which the method was invoked) is used. These are the same locks that can be used by the synchronized statement (§14.17); thus, the code:

class Test {
    int count;
    synchronized void bump() { count++; }
    static int classCount;
    static synchronized void classBump() {
        classCount++;
    }
}

has exactly the same effect as:

class BumpTest {
    int count;
    void bump() {
        synchronized (this) {
            count++;
        }
    }
    static int classCount;
    static void classBump() {
        try {
            synchronized (Class.forName("BumpTest")) {
                classCount++;
            }
        } catch (ClassNotFoundException e) {
                ...
        }
    }
}

The more elaborate example:

public class Box {

    public synchronized Object get() {
        return contents;
    }

    public synchronized boolean put(Object contents) {
            return false;
        return true;
    }

}

defines a class which is designed for concurrent use. Each instance of the class Box has an instance variable contents that can hold a reference to any object. You can put an object in a Box by invoking put, which returns false if the box is already full. You can get something out of a Box by invoking get, which returns a null reference if the box is empty.

If put and get were not synchronized, and two threads were executing methods for the same instance of Box at the same time, then the code could misbehave. It might, for example, lose track of an object because two invocations to put occurred at the same time.

See §17 for more discussion of threads and locks.


8.4.4 Throws

A throws clause is used to declare any checked exceptions (§11.2) that can result from the execution of a method or constructor:

Throws:

    throws ClassTypeList

ClassTypeList:

    ClassType

    ClassTypeList , ClassType

A compile-time error occurs if any ClassType mentioned in a throws clause is not the class Throwable (§20.22) or a subclass of Throwable. It is permitted but not required to mention other (unchecked) exceptions in a throws clause.

For each checked exception that can result from execution of the body of a method or constructor, a compile-time error occurs unless that exception type or a superclass of that exception type is mentioned in a throws clause in the declaration of the method or constructor.

The requirement to declare checked exceptions allows the compiler to ensure that code for handling such error conditions has been included. Methods or constructors that fail to handle exceptional conditions thrown as checked exceptions will normally result in a compile-time error because of the lack of a proper exception type in a throws clause. Java thus encourages a programming style where rare and otherwise truly exceptional conditions are documented in this way.

The predefined exceptions that are not checked in this way are those for which declaring every possible occurrence would be unimaginably inconvenient:

  • Exceptions that are represented by the subclasses of class Error, for example OutOfMemoryError, are thrown due to a failure in or of the virtual machine. Many of these are the result of linkage failures and can occur at unpredictable points in the execution of a Java program. Sophisticated programs may yet wish to catch and attempt to recover from some of these conditions.
  • The exceptions that are represented by the subclasses of the class RuntimeException, for example NullPointerException, result from runtime integrity checks and are thrown either directly from the Java program or in library routines. It is beyond the scope of the Java language, and perhaps beyond the state of the art, to include sufficient information in the program to reduce to a manageable number the places where these can be proven not to occur.

A method that overrides or hides another method (§8.4.6), including methods that implement abstract methods defined in interfaces, may not be declared to throw more checked exceptions than the overridden or hidden method.

More precisely, suppose that B is a class or interface, and A is a superclass or superinterface of B, and a method declaration n in B overrides or hides a method declaration m in A. If n has a throws clause that mentions any checked exception types, then m must have a throws clause, and for every checked exception type listed in the throws clause of n, that same exception class or one of its superclasses must occur in the throws clause of m; otherwise, a compile-time error occurs.

See §11 for more information about exceptions and a large example.


8.4.5 Method Body

A method body is either a block of code that implements the method or simply a semicolon, indicating the lack of an implementation. The body of a method must be a semicolon if and only if the method is either abstract (§8.4.3.1) or native (§8.4.3.4).

MethodBody:

    Block

    ;

A compile-time error occurs if a method declaration is either abstract or native and has a block for its body. A compile-time error occurs if a method declaration is neither abstract nor native and has a semicolon for its body.

If an implementation is to be provided for a method but the implementation requires no executable code, the method body should be written as a block that contains no statements: "{ }".

If a method is declared void, then its body must not contain any return statement (§14.15) that has an Expression.

If a method is declared to have a return type, then every return statement (§14.15) in its body must have an Expression. A compile-time error occurs if the body of the method can complete normally (§14.1). In other words, a method with a return type must return only by using a return statement that provides a value return; it is not allowed to "drop off the end of its body."

Note that it is possible for a method to have a declared return type and yet contain no return statements. Here is one example:

class DizzyDean {

    int pitch() { throw new RuntimeException("90 mph?!"); }

}


8.4.6 Inheritance, Overriding, and Hiding

A class inherits from its direct superclass and direct superinterfaces all the methods (whether abstract or not) of the superclass and superinterfaces that are accessible to code in the class and are neither overridden (§8.4.6.1) nor hidden (§8.4.6.2) by a declaration in the class.

8.4.6.1 Overriding (By Instance Methods)

If a class declares an instance method, then the declaration of that method is said to override any and all methods with the same signature in the superclasses and superinterfaces of the class that would otherwise be accessible to code in the class. Moreover, if the method declared in the class is not abstract, then the declaration of that method is said to implement any and all declarations of abstract methods with the same signature in the superclasses and superinterfaces of the class that would otherwise be accessible to code in the class.

A compile-time error occurs if an instance method overrides a static method. In this respect, overriding of methods differs from hiding of fields (§8.3), for it is permissible for an instance variable to hide a static variable.

An overridden method can be accessed by using a method invocation expression (§15.11) that contains the keyword super. Note that a qualified name or a cast to a superclass type is not effective in attempting to access an overridden method; in this respect, overriding of methods differs from hiding of fields. See §15.11.4.10 for discussion and examples of this point.

8.4.6.2 Hiding (By Class Methods)

If a class declares a static method, then the declaration of that method is said to hide any and all methods with the same signature in the superclasses and superinterfaces of the class that would otherwise be accessible to code in the class. A compile-time error occurs if a static method hides an instance method. In this respect, hiding of methods differs from hiding of fields (§8.3), for it is permissible for a static variable to hide an instance variable.

A hidden method can be accessed by using a qualified name or by using a method invocation expression (§15.11) that contains the keyword super or a cast to a superclass type. In this respect, hiding of methods is similar to hiding of fields.

8.4.6.3 Requirements in Overriding and Hiding

If a method declaration overrides or hides the declaration of another method, then a compile-time error occurs if they have different return types or if one has a return type and the other is void. Moreover, a method declaration must not have a throws clause that conflicts (§8.4.4) with that of any method that it overrides or hides; otherwise, a compile-time error occurs. In these respects, overriding of methods differs from hiding of fields (§8.3), for it is permissible for a field to hide a field of another type.

The access modifier (§6.6) of an overriding or hiding method must provide at least as much access as the overridden or hidden method, or a compile-time error occurs. In more detail:

  • If the overridden or hidden method is public, then the overriding or hiding method must be public; otherwise, a compile-time error occurs.
  • If the overridden or hidden method is protected, then the overriding or hiding method must be protected or public; otherwise, a compile-time error occurs.
  • If the overridden or hidden method has default (package) access, then the overriding or hiding method must not be private; otherwise, a compile-time error occurs.

Note that a private method is never accessible to subclasses and so cannot be hidden or overridden in the technical sense of those terms. This means that a subclass can declare a method with the same signature as a private method in one of its superclasses, and there is no requirement that the return type or throws clause of such a method bear any relationship to those of the private method in the superclass.

8.4.6.4 Inheriting Methods with the Same Signature

It is possible for a class to inherit more than one method with the same signature (§8.4.6.4). Such a situation does not in itself cause a compile-time error. There are then two possible cases:

  • If one of the inherited methods is not abstract, then there are two subcases:
    • If the method that is not abstract is static, a compile-time error occurs.
    • Otherwise, the method that is not abstract is considered to override, and therefore to implement, all the other methods on behalf of the class that inherits it. A compile-time error occurs if, comparing the method that is not abstract with each of the other of the inherited methods, for any such pair, either they have different return types or one has a return type and the other is void. Moreover, a compile-time error occurs if the inherited method that is not abstract has a throws clause that conflicts (§8.4.4) with that of any other of the inherited methods.
  • If none of the inherited methods is not abstract, then the class is necessarily an abstract class and is considered to inherit all the abstract methods. A compile-time error occurs if, for any two such inherited methods, either they have different return types or one has a return type and the other is void. (The throws clauses do not cause errors in this case.)

It is not possible for two or more inherited methods with the same signature not to be abstract, because methods that are not abstract are inherited only from the direct superclass, not from superinterfaces.

There might be several paths by which the same method declaration might be inherited from an interface. This fact causes no difficulty and never, of itself, results in a compile-time error.


8.4.7 Overloading

If two methods of a class (whether both declared in the same class, or both inherited by a class, or one declared and one inherited) have the same name but different signatures, then the method name is said to be overloaded. This fact causes no difficulty and never of itself results in a compile-time error. There is no required relationship between the return types or between the throws clauses of two methods with the same name but different signatures.

Methods are overridden on a signature-by-signature basis. If, for example, a class declares two public methods with the same name, and a subclass overrides one of them, the subclass still inherits the other method. In this respect, Java differs from C++.

When a method is invoked (§15.11), the number of actual arguments and the compile-time types of the arguments are used, at compile time, to determine the signature of the method that will be invoked (§15.11.2). If the method that is to be invoked is an instance method, the actual method to be invoked will be determined at run time, using dynamic method lookup (§15.11.4).


8.4.8 Examples of Method Declarations

The following examples illustrate some (possibly subtle) points about method declarations.

8.4.8.1 Example: Overriding

In the example:

class Point {

    int x = 0, y = 0;

    void move(int dx, int dy) { x += dx; y += dy; }

}

class SlowPoint extends Point {

    int xLimit, yLimit;

    void move(int dx, int dy) {
        super.move(limit(dx, xLimit), limit(dy, yLimit));
    }

    static int limit(int d, int limit) {
        return d > limit ? limit : d < -limit ? -limit : d;
    }

}

the class SlowPoint overrides the declarations of method move of class Point with its own move method, which limits the distance that the point can move on each invocation of the method. When the move method is invoked for an instance of class SlowPoint, the overriding definition in class SlowPoint will always be called, even if the reference to the SlowPoint object is taken from a variable whose type is Point.

8.4.8.2 Example: Overloading, Overriding, and Hiding

In the example:

class Point {

    int x = 0, y = 0;

    void move(int dx, int dy) { x += dx; y += dy; }

    int color;

}

class RealPoint extends Point {

    float x = 0.0f, y = 0.0f;

    void move(int dx, int dy) { move((float)dx, (float)dy); }

    void move(float dx, float dy) { x += dx; y += dy; }

}

the class RealPoint hides the declarations of the int instance variables x and y of class Point with its own float instance variables x and y, and overrides the method move of class Point with its own move method. It also overloads the name move with another method with a different signature (§8.4.2).

In this example, the members of the class RealPoint include the instance variable color inherited from the class Point, the float instance variables x and y declared in RealPoint, and the two move methods declared in RealPoint.

Which of these overloaded move methods of class RealPoint will be chosen for any particular method invocation will be determined at compile time by the overloading resolution procedure described in §15.11.

8.4.8.3 Example: Incorrect Overriding

This example is an extended variation of that in the preceding section:

class Point {

    int x = 0, y = 0, color;

    void move(int dx, int dy) { x += dx; y += dy; }

    int getX() { return x; }

    int getY() { return y; }

}

class RealPoint extends Point {

    float x = 0.0f, y = 0.0f;

    void move(int dx, int dy) { move((float)dx, (float)dy); }

    void move(float dx, float dy) { x += dx; y += dy; }

    float getX() { return x; }

    float getY() { return y; }

}

Here the class Point provides methods getX and getY that return the values of its fields x and y; the class RealPoint then overrides these methods by declaring methods with the same signature. The result is two errors at compile time, one for each method, because the return types do not match; the methods in class Point return values of type int, but the wanna-be overriding methods in class RealPoint return values of type float.

8.4.8.4 Example: Overriding versus Hiding

This example corrects the errors of the example in the preceding section:

class Point {

    int x = 0, y = 0;

    void move(int dx, int dy) { x += dx; y += dy; }

    int getX() { return x; }

    int getY() { return y; }

    int color;

}

class RealPoint extends Point {

    float x = 0.0f, y = 0.0f;

    void move(int dx, int dy) { move((float)dx, (float)dy); }

    void move(float dx, float dy) { x += dx; y += dy; }

    int getX() { return (int)Math.floor(x); }

    int getY() { return (int)Math.floor(y); }

}

Here the overriding methods getX and getY in class RealPoint have the same return types as the methods of class Point that they override, so this code can be successfully compiled.

Consider, then, this test program:

class Test {

    public static void main(String[] args) {
        RealPoint rp = new RealPoint();
        Point p = rp;
        rp.move(1.71828f, 4.14159f);
        p.move(1, -1);
        show(p.x, p.y);
        show(rp.x, rp.y);
        show(p.getX(), p.getY());
        show(rp.getX(), rp.getY());
    }

    static void show(int x, int y) {
        System.out.println("(" + x + ", " + y + ")");
    }

    static void show(float x, float y) {
        System.out.println("(" + x + ", " + y + ")");
    }

}

The output from this program is:

(0, 0)
(2.7182798, 3.14159)
(2, 3)
(2, 3)

The first line of output illustrates the fact that an instance of RealPoint actually contains the two integer fields declared in class Point; it is just that their names are hidden from code that occurs within the declaration of class RealPoint (and those of any subclasses it might have). When a reference to an instance of class RealPoint in a variable of type Point is used to access the field x, the integer field x declared in class Point is accessed. The fact that its value is zero indicates that the method invocation p.move(1, -1) did not invoke the method move of class Point; instead, it invoked the overriding method move of class RealPoint.

The second line of output shows that the field access rp.x refers to the field x declared in class RealPoint. This field is of type float, and this second line of output accordingly displays floating-point values. Incidentally, this also illustrates the fact that the method name show is overloaded; the types of the arguments in the method invocation dictate which of the two definitions will be invoked.

The last two lines of output show that the method invocations p.getX() and rp.getX() each invoke the getX method declared in class RealPoint. Indeed, there is no way to invoke the getX method of class Point for an instance of class RealPoint from outside the body of RealPoint, no matter what the type of the variable we may use to hold the reference to the object. Thus, we see that fields and methods behave differently: hiding is different from overriding.

8.4.8.5 Example: Invocation of Hidden Class Methods

A hidden class (static) method can be invoked by using a reference whose type is the class that actually contains the declaration of the method. In this respect, hiding of static methods is different from overriding of instance methods. The example:

class Super {
    static String greeting() { return "Goodnight"; }
    String name() { return "Richard"; }
}

class Sub extends Super {
    static String greeting() { return "Hello"; }
    String name() { return "Dick"; }
}

class Test {
    public static void main(String[] args) {
        Super s = new Sub();
        System.out.println(s.greeting() + ", " + s.name());
    }
}

produces the output:

Goodnight, Dick

because the invocation of greeting uses the type of s, namely Super, to figure out, at compile time, which class method to invoke, whereas the invocation of name uses the class of s, namely Sub, to figure out, at run time, which instance method to invoke.

8.4.8.6 Large Example of Overriding

Overriding makes it easy for subclasses to extend the behavior of an existing class, as shown in this example:

import java.io.OutputStream;

import java.io.IOException;

class BufferOutput {

    private OutputStream o;

    BufferOutput(OutputStream o) { this.o = o; }

    protected byte[] buf = new byte[512];

    protected int pos = 0;

    public void putchar(char c) throws IOException {
        if (pos == buf.length)
            flush();
        buf[pos++] = (byte)c;
    }

    public void putstr(String s) throws IOException {
        for (int i = 0; i < s.length(); i++)
            putchar(s.charAt(i));
    }

    public void flush() throws IOException {
        o.write(buf, 0, pos);
        pos = 0;
    }

}

class LineBufferOutput extends BufferOutput {

    LineBufferOutput(OutputStream o) { super(o); }

    public void putchar(char c) throws IOException {
        super.putchar(c);
        if (c == '\n')
            flush();
    }

}

class Test {
    public static void main(String[] args)

        throws IOException

    {
        LineBufferOutput lbo =

            new LineBufferOutput(System.out);
        lbo.putstr("lbo\nlbo");
        System.out.print("print\n");
        lbo.putstr("\n");
    }
}

This example produces the output:

lbo
print
lbo

The class BufferOutput implements a very simple buffered version of an OutputStream, flushing the output when the buffer is full or flush is invoked. The subclass LineBufferOutput declares only a constructor and a single method putchar, which overrides the method putchar of BufferOutput. It inherits the methods putstr and flush from class Buffer.

In the putchar method of a LineBufferOutput object, if the character argument is a newline, then it invokes the flush method. The critical point about overriding in this example is that the method putstr, which is declared in class BufferOutput, invokes the putchar method defined by the current object this, which is not necessarily the putchar method declared in class BufferOutput.

Thus, when putstr is invoked in main using the LineBufferOutput object lbo, the invocation of putchar in the body of the putstr method is an invocation of the putchar of the object lbo, the overriding declaration of putchar that checks for a newline. This allows a subclass of BufferOutput to change the behavior of the putstr method without redefining it.

Documentation for a class such as BufferOutput, which is designed to be extended, should clearly indicate what is the contract between the class and its subclasses, and should clearly indicate that subclasses may override the putchar method in this way. The implementor of the BufferOutput class would not, therefore, want to change the implementation of putstr in a future implementation of BufferOutput not to use the method putchar, because this would break the preexisting contract with subclasses. See the further discussion of binary compatibility in §13, especially §13.2.

8.4.8.7 Example: Incorrect Overriding because of Throws

This example uses the usual and conventional form for declaring a new exception type, in its declaration of the class BadPointException:

class BadPointException extends Exception {
    BadPointException() { super(); }
    BadPointException(String s) { super(s); }
}

class Point {
    int x, y;
    void move(int dx, int dy) { x += dx; y += dy; }
}

class CheckedPoint extends Point {
    void move(int dx, int dy) throws BadPointException {
        if ((x + dx) < 0 || (y + dy) < 0)
            throw new BadPointException();
        x += dx; y += dy;
    }
}

This example results in a compile-time error, because the override of method move in class CheckedPoint declares that it will throw a checked exception that the move in class Point has not declared. If this were not considered an error, an invoker of the method move on a reference of type Point could find the contract between it and Point broken if this exception were thrown.

Removing the throws clause does not help:

class CheckedPoint extends Point {
    void move(int dx, int dy) {
        if ((x + dx) < 0 || (y + dy) < 0)
            throw new BadPointException();
        x += dx; y += dy;
    }
}

A different compile-time error now occurs, because the body of the method move cannot throw a checked exception, namely BadPointException, that does not appear in the throws clause for move.


8.5 Static Initializers

Any static initializers declared in a class are executed when the class is initialized and, together with any field initializers (§8.3.2) for class variables, may be used to initialize the class variables of the class (§12.4).

StaticInitializer:

    static Block

It is a compile-time error for a static initializer to be able to complete abruptly (§14.1, §15.5) with a checked exception (§11.2).

The static initializers and class variable initializers are executed in textual order and may not refer to class variables declared in the class whose declarations appear textually after the use, even though these class variables are in scope. This restriction is designed to catch, at compile time, circular or otherwise malformed initializations. Thus, both:

class Z {
    static int i = j + 2;
    static int j = 4;
}

and:

class Z {
    static { i = j + 2; }
    static int i, j;
    static { j = 4; }
}

result in compile-time errors.

Accesses to class variables by methods are not checked in this way, so:

class Z {
    static int peek() { return j; }

    static int i = peek();
    static int j = 1;
}

class Test {
    public static void main(String[] args) {
        System.out.println(Z.i);
    }

}

produces the output:

0

because the variable initializer for i uses the class method peek to access the value of the variable j before j has been initialized by its variable initializer, at which point it still has its default value (§4.5.4).

If a return statement (§14.15) appears anywhere within a static initializer, then a compile-time error occurs.

If the keyword this (§15.7.2) or the keyword super (§15.10, §15.11) appears anywhere within a static initializer, then a compile-time error occurs.


8.6 Constructor Declarations

The constructor of wharves, bridges, piers, bulk-heads,
floats, stays against the sea . . .
—Walt Whitman, Song of the Broad-Axe (1856)

A constructor is used in the creation of an object that is an instance of a class:

ConstructorDeclaration:

    ConstructorModifiersopt ConstructorDeclarator

        Throwsopt ConstructorBody

ConstructorDeclarator:

    SimpleTypeName ( FormalParameterListopt )

The SimpleTypeName in the ConstructorDeclarator must be the simple name of the class that contains the constructor declaration; otherwise a compile-time error occurs. In all other respects, the constructor declaration looks just like a method declaration that has no result type.

Here is a simple example:

class Point {
    int x, y;
    Point(int x, int y) { this.x = x; this.y = y; }
}

Constructors are invoked by class instance creation expressions (§15.8), by the newInstance method of class Class (§20.3), by the conversions and concatenations caused by the string concatenation operator + (§15.17.1), and by explicit constructor invocations from other constructors (§8.6.5). Constructors are never invoked by method invocation expressions (§15.11).

Access to constructors is governed by access modifiers (§6.6). This is useful, for example, in preventing instantiation by declaring an inaccessible constructor (§8.6.8).

Constructor declarations are not members. They are never inherited and therefore are not subject to hiding or overriding.


8.6.1 Formal Parameters

The formal parameters of a constructor are identical in structure and behavior to the formal parameters of a method (§8.4.1).


8.6.2 Constructor Signature

The signature of a constructor is identical in structure and behavior to the signature of a method (§8.4.2).


8.6.3 Constructor Modifiers

ConstructorModifiers:

    ConstructorModifier

    ConstructorModifiers ConstructorModifier

ConstructorModifier: one of

    public protected private

The access modifiers public, protected, and private are discussed in §6.6. A compile-time error occurs if the same modifier appears more than once in a constructor declaration, or if a constructor declaration has more than one of the access modifiers public, protected, and private.

Unlike methods, a constructor cannot be abstract, static, final, native, or synchronized. A constructor is not inherited, so there is no need to declare it final and an abstract constructor could never be implemented. A constructor is always invoked with respect to an object, so it makes no sense for a constructor to be static. There is no practical need for a constructor to be synchronized, because it would lock the object under construction, which is normally not made available to other threads until all constructors for the object have completed their work. The lack of native constructors is an arbitrary language design choice that makes it easy for an implementation of the Java Virtual Machine to verify that superclass constructors are always properly invoked during object creation.


8.6.4 Throws

The throws clause for a constructor is identical in structure and behavior to the throws clause for a method (§8.4.4).


8.6.5 Constructor Body

The first statement of a constructor body may be an explicit invocation of another constructor of the same class, written as this followed by a parenthesized argument list, or an explicit invocation of a constructor of the direct superclass, written as super followed by a parenthesized argument list.

ConstructorBody:

    { ExplicitConstructorInvocationopt BlockStatementsopt }

ExplicitConstructorInvocation:

    this ( ArgumentListopt ) ;

    super ( ArgumentListopt ) ;

It is a compile-time error for a constructor to directly or indirectly invoke itself through a series of one or more explicit constructor invocations involving this.

If a constructor body does not begin with an explicit constructor invocation and the constructor being declared is not part of the primordial class Object, then the constructor body is implicitly assumed by the compiler to begin with a superclass constructor invocation "super();", an invocation of the constructor of its direct superclass that takes no arguments.

Except for the possibility of explicit constructor invocations, the body of a constructor is like the body of a method (§8.4.5). A return statement (§14.15) may be used in the body of a constructor if it does not include an expression.

In the example:

class Point {

    int x, y;

    Point(int x, int y) { this.x = x; this.y = y; }

}

class ColoredPoint extends Point {

    static final int WHITE = 0, BLACK = 1;

    int color;

    ColoredPoint(int x, int y) {
        this(x, y, WHITE);
    }

    ColoredPoint(int x, int y, int color) {
        super(x, y);

        this.color = color;

    }

}

the first constructor of ColoredPoint invokes the second, providing an additional argument; the second constructor of ColoredPoint invokes the constructor of its superclass Point, passing along the coordinates.

An explicit constructor invocation statement may not refer to any instance variables or instance methods declared in this class or any superclass, or use this or super in any expression; otherwise, a compile-time error occurs. For example, if the first constructor of ColoredPoint in the example above were changed to:

    ColoredPoint(int x, int y) {
        this(x, y, color);
    }

then a compile-time error would occur, because an instance variable cannot be used within a superclass constructor invocation.

An invocation of the constructor of the direct superclass, whether it actually appears as an explicit constructor invocation statement or is provided automatically (§8.6.7), performs an additional implicit action after a normal return of control from the constructor: all instance variables that have initializers are initialized at that time, in the textual order in which they appear in the class declaration. An invocation of another constructor in the same class using the keyword this does not perform this additional implicit action.

§12.5 describes the creation and initialization of new class instances.


8.6.6 Constructor Overloading

Overloading of constructors is identical in behavior to overloading of methods. The overloading is resolved at compile time by each class instance creation expression (§15.8).


8.6.7 Default Constructor

If a class contains no constructor declarations, then a default constructor that takes no parameters is automatically provided:

  • If the class being declared is the primordial class Object, then the default constructor has an empty body.
  • Otherwise, the default constructor takes no parameters and simply invokes the superclass constructor with no arguments.

A compile-time error occurs if a default constructor is provided by the compiler but the superclass does not have a constructor that takes no arguments.

If the class is declared public, then the default constructor is implicitly given the access modifier public (§6.6); otherwise, the default constructor has the default access implied by no access modifier. Thus, the example:

public class Point {
    int x, y;
}

is equivalent to the declaration:

public class Point {
    int x, y;
    public Point() { super(); }
}

where the default constructor is public because the class Point is public.


8.6.8 Preventing Instantiation of a Class

A class can be designed to prevent code outside the class declaration from creating instances of the class by declaring at least one constructor, to prevent the creation of an implicit constructor, and declaring all constructors to be private. A public class can likewise prevent the creation of instances outside its package by declaring at least one constructor, to prevent creation of a default constructor with public access, and declaring no constructor that is public.

Thus, in the example:

class ClassOnly {
    private ClassOnly() { }
    static String just = "only the lonely";
}

the class ClassOnly cannot be instantiated, while in the example:

package just;

public class PackageOnly {
    PackageOnly() { }
    String[] justDesserts = { "cheesecake", "ice cream" };
}

the class PackageOnly can be instantiated only within the package just, in which it is declared.

Bow, bow, ye lower middle classes!
Bow, bow, ye tradesmen, bow, ye masses!
Blow the trumpets, bang the brasses!
Tantantara! Tzing! Boom!
—W.S. Gilbert, Iolanthe


 9. Interfaces

CHAPTER 9

Interfaces

My apple trees will never get across
And eat the cones under his pines, I tell him.
He only says "Good Fences Make Good Neighbors."
—Robert Frost, Mending Wall (1914)

An interface declaration introduces a new reference type whose members are constants and abstract methods. This type has no implementation, but otherwise unrelated classes can implement it by providing implementations for its abstract methods.

Java programs can use interfaces to make it unnecessary for related classes to share a common abstract superclass or to add methods to Object.

An interface may be declared to be an direct extension of one or more other interfaces, meaning that it implicitly specifies all the abstract methods and constants of the interfaces it extends, except for any constants that it may hide.

A class may be declared to directly implement one or more interfaces, meaning that any instance of the class implements all the abstract methods specified by the interface or interfaces. A class necessarily implements all the interfaces that its direct superclasses and direct superinterfaces do. This (multiple) interface inheritance allows objects to support (multiple) common behaviors without sharing any implementation.

A variable whose declared type is an interface type may have as its value a reference to any object that is an instance of a class declared to implement the specified interface. It is not sufficient that the class happen to implement all the abstract methods of the interface; the class or one of its superclasses must actually be declared to implement the interface, or else the class is not considered to implement the interface.


9.1 Interface Declarations

An interface declaration specifies a new reference type:

InterfaceDeclaration:

    InterfaceModifiersopt interface Identifier

        ExtendsInterfacesopt InterfaceBody

A compile-time error occurs if the Identifier naming an interface appears as the name of any other class or interface in the same package. A compile-time error also occurs if the Identifier naming an interface appears as the name by which a class or interface is to be known via a single-type-import declaration (§7.5.1) in the compilation unit containing the interface declaration. In the example:

class Point { int x, y; }

interface Point { void move(int dx, int dy); }

a compile-time error occurs because a class and an interface in the same package cannot have the same name.


9.1.1 Scope of an Interface Type Name

The Identifier specifies the name of the interface and has as its scope the entire package in which it is declared. This is the same scoping rule as for class type names; see §8.1.1 for an example involving classes.


9.1.2 Interface Modifiers

An interface declaration may be preceded by interface modifiers:

InterfaceModifiers:

    InterfaceModifier

    InterfaceModifiers InterfaceModifier

InterfaceModifier: one of

    public abstract

The access modifier public is discussed in §6.6. A compile-time error occurs if the same modifier appears more than once in an interface declaration.

9.1.2.1 abstract Interfaces

Every interface is implicitly abstract. This modifier is obsolete and should not be used in new Java programs.


9.1.3 Superinterfaces

If an extends clause is provided, then the interface being declared extends each of the other named interfaces and therefore inherits the methods and constants of each of the other named interfaces. These other named interfaces are the direct superinterfaces of the interface being declared. Any class that implements the declared interface is also considered to implement all the interfaces that this interface extends and that are accessible to the class.

ExtendsInterfaces:

    extends InterfaceType

    ExtendsInterfaces , InterfaceType

The following is repeated from §4.3 to make the presentation here clearer:

InterfaceType:

    TypeName

Each InterfaceType in the extends clause of an interface declaration must name an accessible interface type; otherwise a compile-time error occurs.

A compile-time error occurs if there is a circularity such that an interface directly or indirectly extends itself.

There is no analogue of the class Object for interfaces; that is, while every class is an extension of class Object, there is no single interface of which all interfaces are extensions.

The superinterface relationship is the transitive closure of the direct superinterface relationship. An interface K is a superinterface of interface I if either of the following is true:

  • K is a direct superinterface of I.
  • There exists an interface J such that K is a superinterface of J, and J is a superinterface of I, applying this definition recursively.

Interface I is said to be a subinterface of interface K whenever K is a superinterface of I.


9.1.4 Interface Body and Member Declarations

The body of an interface may declare members of the interface:

InterfaceBody:

    { InterfaceMemberDeclarationsopt }

InterfaceMemberDeclarations:

    InterfaceMemberDeclaration

    InterfaceMemberDeclarations InterfaceMemberDeclaration

InterfaceMemberDeclaration:

    ConstantDeclaration

    AbstractMethodDeclaration

The scope of the name of a member declared in an interface type is the entire body of the interface type declaration.


9.1.5 Access to Interface Member Names

All interface members are implicitly public. They are accessible outside the package where the interface is declared if the interface is also declared public and the package containing the interface is accessible as described in §7.1.


9.2 Interface Members

The members of an interface are those members inherited from direct superinterfaces and those members declared in the interface.

The interface inherits, from the interfaces it extends, all members of those interfaces, except for fields that it hides and methods that it overrides.


9.3 Field (Constant) Declarations

The materials of action are variable,
but the use we make of them should be constant.
—Epictetus (circa 60 A.D.), translated by Thomas Wentworth Higginson

ConstantDeclaration:

    ConstantModifiers Type VariableDeclarator

ConstantModifiers: one of

    public static final

Every field declaration in the body of an interface is implicitly public, static, and final. It is permitted, but strongly discouraged as a matter of style, to redundantly specify any or all of these modifiers for such fields.

A constant declaration in an interface must not include any of the modifiers synchronized, transient, or volatile, or a compile-time error occurs.

It is possible for an interface to inherit more than one field with the same name (§8.3.3.3). Such a situation does not in itself cause a compile-time error. However, any attempt within the body of the interface to refer to either field by its simple name will result in a compile-time error, because such a reference is ambiguous.

There might be several paths by which the same field declaration might be inherited from an interface. In such a situation, the field is considered to be inherited only once, and it may be referred to by its simple name without ambiguity.


9.3.1 Initialization of Fields in Interfaces

Every field in the body of an interface must have an initialization expression, which need not be a constant expression. The variable initializer is evaluated and the assignment performed exactly once, when the interface is initialized (§12.4).

A compile-time error occurs if an initialization expression for an interface field contains a reference by simple name to the same field or to another field whose declaration occurs textually later in the same interface. Thus:

interface Test {
    float f = j;
    int j = 1;
    int k = k+1;
}

causes two compile-time errors, because j is referred to in the initialization of f before j is declared and because the initialization of k refers to k itself.

(One subtlety here is that, at run time, fields that are initialized with compile-time constant values are initialized first. This applies also to static final fields in classes (§8.3.2.1). This means, in particular, that these fields will never be observed to have their default initial values (§4.5.4), even by devious programs. See §12.4.2 and §13.4.8 for more discussion.)

If the keyword this (§15.7.2) or the keyword super (15.10.2, 15.11) occurs in an initialization expression for a field of an interface, then a compile-time error occurs.


9.3.2 Examples of Field Declarations

The following example illustrates some (possibly subtle) points about field declarations.

9.3.2.1 Ambiguous Inherited Fields

If two fields with the same name are inherited by an interface because, for example, two of its direct superinterfaces declare fields with that name, then a single ambiguous member results. Any use of this ambiguous member will result in a compile-time error. Thus in the example:

interface BaseColors {
    int RED = 1, GREEN = 2, BLUE = 4;
}

interface RainbowColors extends BaseColors {
    int YELLOW = 3, ORANGE = 5, INDIGO = 6, VIOLET = 7;
}

interface PrintColors extends BaseColors {
    int YELLOW = 8, CYAN = 16, MAGENTA = 32;
}

interface LotsOfColors extends RainbowColors, PrintColors {
    int FUCHSIA = 17, VERMILION = 43, CHARTREUSE = RED+90;
}

the interface LotsOfColors inherits two fields named YELLOW. This is all right as long as the interface does not contain any reference by simple name to the field YELLOW. (Such a reference could occur within a variable initializer for a field.)

Even if interface PrintColors were to give the value 3 to YELLOW rather than the value 8, a reference to field YELLOW within interface LotsOfColors would still be considered ambiguous.

9.3.2.2 Multiply Inherited Fields

If a single field is inherited multiple times from the same interface because, for example, both this interface and one of this interface's direct superinterfaces extend the interface that declares the field, then only a single member results. This situation does not in itself cause a compile-time error.

In the example in the previous section, the fields RED, GREEN, and BLUE are inherited by interface LotsOfColors in more than one way, through interface RainbowColors and also through interface PrintColors, but the reference to field RED in interface LotsOfColors is not considered ambiguous because only one actual declaration of the field RED is involved.


9.4 Abstract Method Declarations

AbstractMethodDeclaration:

    AbstractMethodModifiersopt ResultType MethodDeclarator Throwsopt ;

AbstractMethodModifiers:

    AbstractMethodModifier

    AbstractMethodModifiers AbstractMethodModifier

AbstractMethodModifier: one of

    public abstract

The access modifier public is discussed in §6.6. A compile-time error occurs if the same modifier appears more than once in an abstract method declaration.

Every method declaration in the body of an interface is implicitly abstract, so its body is always represented by a semicolon, not a block. For compatibility with older versions of Java, it is permitted but discouraged, as a matter of style, to redundantly specify the abstract modifier for methods declared in interfaces.

Every method declaration in the body of an interface is implicitly public. It is permitted, but strongly discouraged as a matter of style, to redundantly specify the public modifier for interface methods.

Note that a method declared in an interface must not be declared static, or a compile-time error occurs, because in Java static methods cannot be abstract.

Note that a method declared in an interface must not be declared native or synchronized, or a compile-time error occurs, because those keywords describe implementation properties rather than interface properties. However, a method declared in an interface may be implemented by a method that is declared native or synchronized in a class that implements the interface.

Note that a method declared in an interface must not be declared final or a compile-time error occurs. However, a method declared in an interface may be implemented by a method that is declared final in a class that implements the interface.


9.4.1 Inheritance and Overriding

If the interface declares a method, then the declaration of that method is said to override any and all methods with the same signature in the superinterfaces of the interface that would otherwise be accessible to code in this interface.

If a method declaration in an interface overrides the declaration of a method in another interface, a compile-time error occurs if the methods have different return types or if one has a return type and the other is void. Moreover, a method declaration must not have a throws clause that conflicts (§8.4.4) with that of any method that it overrides; otherwise, a compile-time error occurs.

Methods are overridden on a signature-by-signature basis. If, for example, an interface declares two public methods with the same name, and a subinterface overrides one of them, the subinterface still inherits the other method.

An interface inherits from its direct superinterfaces all methods of the superinterfaces that are not overridden by a declaration in the interface.

It is possible for an interface to inherit more than one method with the same signature (§8.4.2). Such a situation does not in itself cause a compile-time error. The interface is considered to inherit all the methods. However, a compile-time error occurs if, for any two such inherited methods, either they have different return types or one has a return type and the other is void. (The throws clauses do not cause errors in this case.)

There might be several paths by which the same method declaration is inherited from an interface. This fact causes no difficulty and never of itself results in a compile-time error.


9.4.2 Overloading

If two methods of an interface (whether both declared in the same interface, or both inherited by a interface, or one declared and one inherited) have the same name but different signatures, then the method name is said to be overloaded. This fact causes no difficulty and never of itself results in a compile-time error. There is no required relationship between the return types or between the throws clauses of two methods with the same name but different signatures.


9.4.3 Examples of Abstract Method Declarations

The following examples illustrate some (possibly subtle) points about abstract method declarations.

9.4.3.1 Example: Overriding

Methods declared in interfaces are abstract and thus contain no implementation. About all that can be accomplished by an overriding method declaration, other than to affirm a method signature, is to restrict the exceptions that might be thrown by an implementation of the method. Here is a variation of the example shown in §8.4.3.1:

class BufferEmpty extends Exception {
    BufferEmpty() { super(); }
    BufferEmpty(String s) { super(s); }
}

class BufferError extends Exception {
    BufferError() { super(); }
    BufferError(String s) { super(s); }
}

public interface Buffer {
    char get() throws BufferEmpty, BufferError;
}

public interface InfiniteBuffer extends Buffer {
     char get() throws BufferError;												// override
}

9.4.3.2 Example: Overloading

In the example code:

interface PointInterface {
    void move(int dx, int dy);
}

interface RealPointInterface extends PointInterface {
    void move(float dx, float dy);
    void move(double dx, double dy);
}

the method name move is overloaded in interface RealPointInterface with three different signatures, two of them declared and one inherited. Any class that implements interface RealPointInterface must provide implementations of all three method signatures.

Death, life, and sleep, reality and thought,
Assist me, God, their boundaries to know . . .
—William Wordsworth, Maternal Grief


 10. Arrays

CHAPTER 10

Arrays

Even Solomon in all his glory was not arrayed like one of these.
—Matthew 6:29

Java arrays are objects (§4.3.1), are dynamically created, and may be assigned to variables of type Object (§4.3.2). All methods of class Object may be invoked on an array.

An array object contains a number of variables. The number of variables may be zero, in which case the array is said to be empty. The variables contained in an array have no names; instead they are referenced by array access expressions that use nonnegative integer index values. These variables are called the components of the array. If an array has n components, we say n is the length of the array; the components of the array are referenced using integer indices from 0 to [image], inclusive.

All the components of an array have the same type, called the component type of the array. If the component type of an array is T, then the type of the array itself is written T[].

The component type of an array may itself be an array type. The components of such an array may contain references to subarrays. If, starting from any array type, one considers its component type, and then (if that is also an array type) the component type of that type, and so on, eventually one must reach a component type that is not an array type; this is called the element type of the original array, and the components at this level of the data structure are called the elements of the original array.

There is one situation in which an element of an array can be an array: if the element type is Object, then some or all of the elements may be arrays, because any array object can be assigned to any variable of type Object.


10.1 Array Types

An array type is written as the name of an element type followed by some number of empty pairs of square brackets []. The number of bracket pairs indicates the depth of array nesting. An array's length is not part of its type.

The element type of an array may be any type, whether primitive or reference. In particular:

  • Arrays with an interface type as the component type are allowed. The elements of such an array may have as their value a null reference or instances of any class type that implements the interface.
  • Arrays with an abstract class type as the component type are allowed. The elements of such an array may have as their value a null reference or instances of any subclass of the abstract class that is not itself abstract.

Array types are used in declarations and in cast expressions (§15.15).


10.2 Array Variables

A variable of array type holds a reference to an object. Declaring a variable of array type does not create an array object or allocate any space for array components. It creates only the variable itself, which can contain a reference to an array. However, the initializer part of a declarator (§8.3) may create an array, a reference to which then becomes the initial value of the variable.

Because an array's length is not part of its type, a single variable of array type may contain references to arrays of different lengths.

Here are examples of declarations of array variables that do not create arrays:

int[] ai;							// array of int
short[][] as;							// array of array of short
Object[]			ao,				// array of Object
            otherAo;				// array of Object
short		s,					// scalar short
        aas[][];					// array of array of short

Here are some examples of declarations of array variables that create array objects:

Exception ae[] = new Exception[3];
Object aao[][] = new Exception[2][3];
int[] factorial = { 1, 1, 2, 6, 24, 120, 720, 5040 };
char ac[] = { 'n', 'o', 't', ' ', 'a', ' ',
                 'S', 't', 'r', 'i', 'n', 'g' };
String[] aas = { "array", "of", "String", };

The [] may appear as part of the type at the beginning of the declaration, or as part of the declarator for a particular variable, or both, as in this example:

byte[] rowvector, colvector, matrix[];

This declaration is equivalent to:

byte rowvector[], colvector[], matrix[][];

Once an array object is created, its length never changes. To make an array variable refer to an array of different length, a reference to a different array must be assigned to the variable.

If an array variable v has type A[], where A is a reference type, then v can hold a reference to an instance of any array type B[], provided B can be assigned to A. This may result in a run-time exception on a later assignment; see §10.10 for a discussion.


10.3 Array Creation

An array is created by an array creation expression (§15.9) or an array initializer (§10.6).

An array creation expression specifies the element type, the number of levels of nested arrays, and the length of the array for at least one of the levels of nesting. The array's length is available as a final instance variable length.

An array initializer creates an array and provides initial values for all its components. (Contrast this with C and C++, where it is possible for an array initializer to specify initial values for some but not all of the components of an array.)


10.4 Array Access

A component of an array is accessed by an array access expression (§15.12) that consists of an expression whose value is an array reference followed by an indexing expression enclosed by [ and ], as in A[i]. All arrays are 0-origin. An array with length n can be indexed by the integers 0 to n-1.

Arrays must be indexed by int values; short, byte, or char values may also be used as index values because they are subjected to unary numeric promotion (§5.6.1) and become int values. An attempt to access an array component with a long index value results in a compile-time error.

All array accesses are checked at run time; an attempt to use an index that is less than zero or greater than or equal to the length of the array causes an IndexOutOfBoundsException to be thrown.


10.5 A Simple Example

The example:

class Gauss {
    public static void main(String[] args) {
        int[] ia = new int[101];
        for (int i = 0; i < ia.length; i++)
            ia[i] = i;
        int sum = 0;
        for (int i = 0; i < ia.length; i++)
            sum += ia[i];
        System.out.println(sum);
    }
}

that produces output:

5050

declares a variable ia that has type array of int, that is, int[]. The variable ia is initialized to reference a newly created array object, created by an array creation expression (§15.9). The array creation expression specifies that the array should have 101 components. The length of the array is available using the field length, as shown.

The example program fills the array with the integers from 0 to 100, sums these integers, and prints the result.


10.6 Arrays Initializers

An array initializer may be specified in a declaration, creating an array and providing some initial values:

ArrayInitializer:

    { VariableInitializersopt ,opt }

VariableInitializers:

    VariableInitializer

    VariableInitializers , VariableInitializer

The following is repeated from §8.3 to make the presentation here clearer:

VariableInitializer:

    Expression

    ArrayInitializer

An array initializer is written as a comma-separated list of expressions, enclosed by braces "{" and "}".

The length of the constructed array will equal the number of expressions.

Each expression specifies a value for one array component. Each expression must be assignment-compatible (§5.2) with the array's component type, or a compile-time error results.

If the component type is itself an array type, then the expression specifying a component may itself be an array initializer; that is, array initializers may be nested.

A trailing comma may appear after the last expression in an array initializer and is ignored.

As an example:

class Test {
    public static void main(String[] args) {
        int ia[][] = { {1, 2}, null };
        for (int i = 0; i < 2; i++)
            for (int j = 0; j < 2; j++)
                System.out.println(ia[i][j]);
    }
}

prints:

1
2

before causing a NullPointerException in trying to index the second component of the array ia, which is a null reference.


10.7 Array Members

The members of an array type are all of the following:

  • The public final field length, which contains the number of components of the array (length may be positive or zero)
  • The public method clone, which overrides the method of the same name in class Object and throws no checked exceptions
  • All the members inherited from class Object; the only method of Object that is not inherited is its clone method

An array thus has the same methods as the following class:

class A implements Cloneable {
    public final int length = X;
    public Object clone() {
        try {
            return super.clone();
        } catch (CloneNotSupportedException e) {
            throw new InternalError(e.getMessage());
        }
    }

}

Every array implements interface Cloneable. That arrays are cloneable is shown by the test program:

class Test {
    public static void main(String[] args) {
        int ia1[] = { 1, 2 };
        int ia2[] = (int[])ia1.clone();
        System.out.print((ia1 == ia2) + " ");
        ia1[1]++;
        System.out.println(ia2[1]);
    }
}

which prints:

false 2

showing that the components of the arrays referenced by ia1 and ia2 are different variables. (In some early implementations of Java this example failed to compile because the compiler incorrectly believed that the clone method for an array could throw a CloneNotSupportedException.)

A clone of a multidimensional array is shallow, which is to say that it creates only a single new array. Subarrays are shared, as shown by the example program:

class Test {
    public static void main(String[] args) throws Throwable {
        int ia[][] = { { 1 , 2}, null };
        int ja[][] = (int[][])ia.clone();
        System.out.print((ia == ja) + " ");
        System.out.println(ia[0] == ja[0] && ia[1] == ja[1]);
    }
}

which prints:

false true

showing that the int[] array that is ia[0] and the int[] array that is ja[0] are the same array.


10.8 Class Objects for Arrays

Every array has an associated Class object, shared with all other arrays with the same component type. The superclass of an array type is considered to be Object, as shown by the following example code:

class Test {
    public static void main(String[] args) {
        int[] ia = new int[3];
        System.out.println(ia.getClass());
        System.out.println(ia.getClass().getSuperclass());
    }
}

which prints:

class [I
class java.lang.Object

where the string "[I" is the run-time type signature for the class object "array with component type int" (§20.1.1).


10.9 An Array of Characters is Not a String

In Java, unlike C, an array of char is not a String (§20.12), and neither a String nor an array of char is terminated by '\u0000' (the NUL character).

A Java String object is immutable, that is, its contents never change, while an array of char has mutable elements. The method toCharArray in class String returns an array of characters containing the same character sequence as a String. The class StringBuffer implements useful methods on mutable arrays of characters (§20.13).


10.10 Array Store Exception

If an array variable v has type A[], where A is a reference type, then v can hold a reference to an instance of any array type B[], provided B can be assigned to A.

Thus, the example:

class Point { int x, y; }

class ColoredPoint extends Point { int color; }

class Test {
    public static void main(String[] args) {
        ColoredPoint[] cpa = new ColoredPoint[10];
        Point[] pa = cpa;
        System.out.println(pa[1] == null);
        try {
            pa[0] = new Point();
        } catch (ArrayStoreException e) {
            System.out.println(e);
        }
    }
}

produces the output:

true
java.lang.ArrayStoreException

Here the variable pa has type Point[] and the variable cpa has as its value a reference to an object of type ColoredPoint[]. A ColoredPoint can be assigned to a Point; therefore, the value of cpa can be assigned to pa.

A reference to this array pa, for example, testing whether pa[1] is null, will not result in a run-time type error. This is because the element of the array of type ColoredPoint[] is a ColoredPoint, and every ColoredPoint can stand in for a Point, since Point is the superclass of ColoredPoint.

On the other hand, an assignment to the array pa can result in a run-time error. At compile time, an assignment to an element of pa is checked to make sure that the value assigned is a Point. But since pa holds a reference to an array of ColoredPoint, the assignment is valid only if the type of the value assigned at run-time is, more specifically, a ColoredPoint.

Java checks for such a situation at run-time to ensure that the assignment is valid; if not, an ArrayStoreException is thrown. More formally: an assignment to an element of an array whose type is A[], where A is a reference type, is checked at run-time to ensure that the value assigned can be assigned to the actual element type of the array, where the actual element type may be any reference type that is assignable to A.

At length burst in the argent revelry,
With plume, tiara, and all rich array . . .
—John Keats, The Eve of St. Agnes (1819)


 11. Exceptions

CHAPTER 11

Exceptions

If anything can go wrong, it will.
—Finagle's Law (often incorrectly attributed to Murphy, whose law is
rather different—which only goes to show that Finagle was right)

When a Java program violates the semantic constraints of the Java language, a Java Virtual Machine signals this error to the program as an exception. An example of such a violation is an attempt to index outside the bounds of an array. Some programming languages and their implementations react to such errors by peremptorily terminating the program; other programming languages allow an implementation to react in an arbitrary or unpredictable way. Neither of these approaches is compatible with the design goals of Java: to provide portability and robustness. Instead, Java specifies that an exception will be thrown when semantic constraints are violated and will cause a non-local transfer of control from the point where the exception occurred to a point that can be specified by the programmer. An exception is said to be thrown from the point where it occurred and is said to be caught at the point to which control is transferred.

Java programs can also throw exceptions explicitly, using throw statements (§14.16). This provides an alternative to the old-fashioned style of handling error conditions by returning funny values, such as the integer value -1 where a negative value would not normally be expected. Experience shows that too often such funny values are ignored or not checked for by callers, leading to programs that are not robust, exhibit undesirable behavior, or both.

Every exception is represented by an instance of the class Throwable or one of its subclasses; such an object can be used to carry information from the point at which an exception occurs to the handler that catches it. Handlers are established by catch clauses of try statements (§14.18). During the process of throwing an exception, a Java Virtual Machine abruptly completes, one by one, any expressions, statements, method and constructor invocations, static initializers, and field initialization expressions that have begun but not completed execution in the current thread. This process continues until a handler is found that indicates that it handles that particular exception by naming the class of the exception or a superclass of the class of the exception. If no such handler is found, then the method uncaughtException (§20.21.31) is invoked for the ThreadGroup that is the parent of the current thread-thus every effort is made to avoid letting an exception go unhandled.

The Java exception mechanism is integrated with the Java synchronization model (§17), so that locks are released as synchronized statements (§14.17) and invocations of synchronized methods (§8.4.3.5, §15.11) complete abruptly.

This chapter describes the different causes of exceptions (§11.1). It details how exceptions are checked at compile time (§11.2) and processed at run time (§11.3). A detailed example (§11.4) is then followed by an explanation of the exception hierarchy and the standard exception classes (§11.5).


11.1 The Causes of Exceptions

If we do not succeed, then we run the risk of failure.
—J. Danforth Quayle (1990)

An exception is thrown for one of three reasons:

  • An abnormal execution condition was synchronously detected by a Java Virtual Machine. Such conditions arise because:
    • evaluation of an expression violates the normal semantics of the Java language, such as an integer divide by zero, as summarized in §15.5
    • an error occurs in loading or linking part of the Java program (§12.2, §12.3)
    • some limitation a resource is exceeded, such as using too much memory

These exceptions are not thrown at an arbitrary point in the program, but rather at a point where they are specified as a possible result of an expression evaluation or statement execution.

  • A throw statement (§14.16) was executed in Java code.
  • An asynchronous exception occurred either because:
    • the method stop of class Thread (§20.20.16) was invoked
    • an internal error has occurred in the virtual machine (§11.5.2.2)

Exceptions are represented by instances of the class Throwable and instances of its subclasses. These classes are, collectively, the exception classes.


11.2 Compile-Time Checking of Exceptions

The Java language checks, at compile time, that a Java program contains handlers for checked exceptions, by analyzing which checked exceptions can result from execution of a method or constructor. For each checked exception which is a possible result, the throws clause for the method (§8.4.4) or constructor (§8.6.4) must mention the class of that exception or one of the superclasses of the class of that exception. This compile-time checking for the presence of exception handlers is designed to reduce the number of exceptions which are not properly handled.

The unchecked exceptions classes are the class RuntimeException and its subclasses, and the class Error and its subclasses. All other exception classes are checked exception classes. The standard Java API defines a number of exception classes, both checked and unchecked. Additional exception classes, both checked and unchecked, may be declared by Java programmers. See §11.5 for a description of the Java exception class hierarchy and the exception classes defined by the standard Java API and Java Virtual Machine.

The checked exception classes named in the throws clause are part of the contract between the implementor and user of the method or constructor. The throws clause of an overriding method may not specify that this method will result in throwing any checked exception which the overridden method is not permitted, by its throws clause, to throw. When interfaces are involved, more than one method declaration may be overridden by a single overriding declaration. In this case, the overriding declaration must have a throws clause that is compatible with all the overridden declarations (§9.4).

Variable initializers for fields (§8.3.2) and static initializers (§8.5) must not result in a checked exception; if one does, a compile-time error occurs.


11.2.1 Why Errors are Not Checked

Those unchecked exception classes which are the error classes (Error and its subclasses) are exempted from compile-time checking because they can occur at many points in the program and recovery from them is difficult or impossible. A Java program declaring such exceptions would be cluttered, pointlessly.


11.2.2 Why Runtime Exceptions are Not Checked

The runtime exception classes (RuntimeException and its subclasses) are exempted from compile-time checking because, in the judgment of the designers of Java, having to declare such exceptions would not aid significantly in establishing the correctness of Java programs. Many of the operations and constructs of the Java language can result in runtime exceptions. The information available to a Java compiler, and the level of analysis the compiler performs, are usually not sufficient to establish that such runtime exceptions cannot occur, even though this may be obvious to the Java programmer. Requiring such exception classes to be declared would simply be an irritation to Java programmers.

For example, certain code might implement a circular data structure that, by construction, can never involve null references; the programmer can then be certain that a NullPointerException cannot occur, but it would be difficult for a compiler to prove it. The theorem-proving technology that is needed to establish such global properties of data structures is beyond the scope of this Java Language Specification.


11.3 Handling of an Exception

When an exception is thrown, control is transferred from the code that caused the exception to the nearest dynamically-enclosing catch clause of a try statement (§14.18) that handles the exception.

A statement or expression is dynamically enclosed by a catch clause if it appears within the try block of the try statement of which the catch clause is a part, or if the caller of the statement or expression is dynamically enclosed by the catch clause.

The caller of a statement or expression depends on where it occurs:

  • If within a method, then the caller is the method invocation expression (§15.11) that was executed to cause the method to be invoked.
  • If within a constructor or the initializer for an instance variable, then the caller is the class instance creation expression (§15.8) or the method invocation of newInstance that was executed to cause an object to be created.
  • If within a static initializer or an initializer for a static variable, then the caller is the expression that used the class or interface so as to cause it to be initialized.

Whether a particular catch clause handles an exception is determined by comparing the class of the object that was thrown to the declared type of the parameter of the catch clause. The catch clause handles the exception if the type of its parameter is the class of the exception or a superclass of the class of the exception. Equivalently, a catch clause will catch any exception object that is an instanceof (§15.19.2) the declared parameter type.

The control transfer that occurs when an exception is thrown causes abrupt completion of expressions (§15.5) and statements (§14.1) until a catch clause is encountered that can handle the exception; execution then continues by executing the block of that catch clause. The code that caused the exception is never resumed.

If no catch clause handling an exception can be found, then the current thread (the thread that encountered the exception) is terminated, but only after all finally clauses have been executed and the method uncaughtException (§20.21.31) has been invoked for the ThreadGroup that is the parent of the current thread.

In situations where it is desirable to ensure that one block of code is always executed after another, even if that other block of code completes abruptly, a try statement with a finally clause (§14.18.2) may be used. If a try or catch block in a try-finally or try-catch-finally statement completes abruptly, then the finally clause is executed during propagation of the exception, even if no matching catch clause is ultimately found. If a finally clause is executed because of abrupt completion of a try block and the finally clause itself completes abruptly, then the reason for the abrupt completion of the try block is discarded and the new reason for abrupt completion is propagated from there.

The exact rules for abrupt completion and for the catching of exceptions are specified in detail with the specification of each statement in §14 and for expressions in §15 (especially §15.5).


11.3.1 Exceptions are Precise

Exceptions in Java are precise: when the transfer of control takes place, all effects of the statements executed and expressions evaluated before the point from which the exception is thrown must appear to have taken place. No expressions, statements, or parts thereof that occur after the point from which the exception is thrown may appear to have been evaluated. If optimized code has speculatively executed some of the expressions or statements which follow the point at which the exception occurs, such code must be prepared to hide this speculative execution from the user-visible state of the Java program.


11.3.2 Handling Asynchronous Exceptions

Most exceptions in Java occur synchronously as a result of an action by the thread in which they occur, and at a point in the Java program that is specified to possibly result in such an exception. An asynchronous exception is, by contrast, an exception that can potentially occur at any point in the execution of a Java program.

Asynchronous exceptions are rare in Java. They occur only as a result of:

  • An invocation of the stop methods of class Thread (§20.20.15, §20.20.16) or ThreadGroup (§20.21.8, §20.21.9)
  • An InternalError (§11.5.2.2) in the Java Virtual Machine

The stop methods may be invoked by one thread to affect another thread or all the threads in a specified thread group. They are asynchronous because they may occur at any point in the execution of the other thread or threads. An InternalError is considered asynchronous so that it may be handled using the same mechanism that handles the stop method, as will now be described.

Java permits a small but bounded amount of execution to occur before an asynchronous exception is thrown. This delay is permitted to allow optimized code to detect and throw these exceptions at points where it is practical to handle them while obeying the semantics of the Java language.

A simple implementation might poll for asynchronous exceptions at the point of each control transfer instruction. Since a Java program has a finite size, this provides a bound on the total delay in detecting an asynchronous exception. Since no asynchronous exception will occur between control transfers, the code generator has some flexibility to reorder computation between control transfers for greater performance.

The paper Polling Efficiently on Stock Hardware by Mark Feeley, Proc. 1993 Conference on Functional Programming and Computer Architecture, Copenhagen, Denmark, pp. 179-187, is recommended as further reading.

Like all exceptions, asynchronous exceptions are precise (§11.3.1).


11.4 An Example of Exceptions

Consider the following example:

class TestException extends Exception {

    TestException() { super(); }

    TestException(String s) { super(s); }

}

class Test {

    public static void main(String[] args) {
        for (int i = 0; i < args.length; i++) {

            try {
                thrower(args[i]);
                System.out.println("Test \"" + args[i] +
                    "\" didn't throw an exception");
            } catch (Exception e) {
                System.out.println("Test \"" + args[i] +
                    "\" threw a " + e.getClass() +
                    "\n        with message: " + e.getMessage());
            }
        }
    }

    static int thrower(String s) throws TestException {
        try {
            if (s.equals("divide")) {
                int i = 0;
                return i/i;
            }
            if (s.equals("null")) {
                s = null;
                return s.length();
            }
            if (s.equals("test"))
                throw new TestException("Test message");
            return 0;
        } finally {
            System.out.println("[thrower(\"" + s +
                    "\") done]");
        }
    }
}

If we execute the test program, passing it the arguments:

divide null not test

it produces the output:

[thrower("divide") done]
Test "divide" threw a class java.lang.ArithmeticException
        with message: / by zero
[thrower("null") done]
Test "null" threw a class java.lang.NullPointerException
        with message: null
[thrower("not") done]
Test "not" didn't throw an exception
[thrower("test") done]
Test "test" threw a class TestException
        with message: Test message

This example declares an exception class TestException. The main method of class Test invokes the thrower method four times, causing exceptions to be thrown three of the four times. The try statement in method main catches each exception that the thrower throws. Whether the invocation of thrower completes normally or abruptly, a message is printed describing what happened.

The declaration of the method thrower must have a throws clause because it can throw instances of TestException, which is a checked exception class (§11.2). A compile-time error would occur if the throws clause were omitted.

Notice that the finally clause is executed on every invocation of thrower, whether or not an exception occurs, as shown by the "[thrower(...) done]" output that occurs for each invocation.


11.5 The Exception Hierarchy

The possible exceptions in a Java program are organized in a hierarchy of classes, rooted at class Throwable (§20.22), a direct subclass of Object. The classes Exception and Error are direct subclasses of Throwable. The class RuntimeException is a direct subclass of Exception.

The exception classes declared by the standard packages java.lang, java.util, java.io and java.net are called the standard exception classes.

Java programs can use the pre-existing exception classes in throw statements, or define additional exception classes, as subclasses of Throwable or of any of its subclasses, as appropriate. To take advantage of Java's compile-time checking for exception handlers, it is typical to define most new exception classes as checked exception classes, specifically as subclasses of Exception that are not subclasses of RuntimeException.


11.5.1 The Classes Exception and RuntimeException

The class Exception is the superclass of all the exceptions that ordinary programs may wish to recover from.

11.5.1.1 Standard Runtime Exceptions

The class RuntimeException is a subclass of class Exception. The subclasses of RuntimeException are unchecked exception classes.

Package java.lang defines the following standard unchecked runtime exceptions, which, like all other classes in package java.lang, are implicitly imported and therefore may be referred to by their simple names:

  • ArithmeticException: An exceptional arithmetic situation has arisen, such as an integer division (§15.16.2) operation with a zero divisor.
  • ArrayStoreException: An attempt has been made to store into an array component a value whose class is not assignment compatible with the component type of the array (§10.10, §15.25.1).
  • ClassCastException: An attempt has been made to cast (§5.4, §15.15) a reference to an object to an inappropriate type.
  • IllegalArgumentException: A method was passed an invalid or inappropriate argument or invoked on an inappropriate object. Subclasses of this class include:
    • IllegalThreadStateException: A thread was not in an appropriate state for a requested operation.
    • NumberFormatException: An attempt was made to convert a String to a value of a numeric type, but the String did not have an appropriate format.
  • IllegalMonitorStateException: A thread has attempted to wait on (§20.1.6, §20.1.7, §20.1.8) or notify (§20.1.9, §20.1.10) other threads waiting on an object that it has not locked.
  • IndexOutOfBoundsException: Either an index of some sort (such as to an array, a string, or a vector) or a subrange, specified either by two index values or by an index and a length, was out of range.
  • NegativeArraySizeException: An attempt was made to create an array with a negative length (§15.9).
  • NullPointerException: An attempt was made to use a null reference in a case where an object reference was required.
  • SecurityException: A security violation was detected (§20.17).

Package java.util defines the following additional standard unchecked runtime exceptions:

  • java.util.EmptyStackException: An attempt was made to access an element of an empty stack.
  • java.util.NoSuchElementException: An attempt was made to access an element of an empty vector.

11.5.1.2 Standard Checked Exceptions

The standard subclasses of Exception other than RuntimeException are all checked exception classes.

Package java.lang defines the following standard exceptions, which, like all other classes in package java.lang, are implicitly imported and therefore may be referred to by their simple names:

  • ClassNotFoundException: A class or interface with a specified name could not be found (§20.3.8).
  • CloneNotSupportedException: The clone method (§20.1.5) of class Object has been invoked to clone an object, but the class of that object does not implement the Cloneable interface.
  • IllegalAccessException: An attempt has been made to load a class using a string giving its fully qualified name, but the currently executing method does not have access to the definition of the specified class because the class is not public and is in another package.
  • InstantiationException: An attempt was made to create an instance of a class using the newInstance method in class Class, but the specified class object cannot be instantiated because it is an interface, is abstract, or is an array.
  • InterruptedException: The current thread was waiting, and another thread has interrupted the current thread, using the interrupt method of class Thread (§20.20.31).

Package java.io defines the following additional standard exceptions:

  • java.io.IOException: A requested I/O operation could not be completed normally. Subclasses of this class include:
    • java.io.EOFException: End of file has been encountered before normal completion of an input operation.
    • java.io.FileNotFoundException: A file with the name specified by a file name string or path was not found within the file system.
    • java.io.InterruptedIOException: The current thread was waiting for completion of an I/O operation, and another thread has interrupted the current thread, using the interrupt method of class Thread (§20.20.31).
    • java.io.UTFDataFormatException: A requested conversion of a string to or from Java modified UTF-8 format could not be completed (§22.1.15, §22.2.14) because the string was too long or because the purported UTF-8 data was not the result of encoding a Unicode string into UTF-8.

The standard package java.net defines the following additional subclasses of java.io.IOException:

u java.net.MalformedURLException: A string that was provided as a URL, or as part of a URL, had an inappropriate format or specified an unknown protocol.

    • java.net.ProtocolException: Some aspect of a network protocol was not correctly carried out.
    • java.net.SocketException: An operation involving a socket could not be completed normally.
    • java.net.UnknownHostException: The name of a network host could not be resolved to a network address.
    • java.net.UnknownServiceException: The network connection cannot support the requested service.


11.5.2 The Class Error

The class Error and its standard subclasses are exceptions from which ordinary programs are not ordinarily expected to recover. The class Error is a separate subclass of Throwable, distinct from Exception in the class hierarchy, to allow programs to use the idiom:

} catch (Exception e) {

to catch all exceptions from which recovery may be possible without catching errors from which recovery is typically not possible.

Package java.lang defines all the error classes described here. These classes, like all other classes in package java.lang, are implicitly imported and therefore may be referred to by their simple names.

11.5.2.1 Loading and Linkage Errors

A Java Virtual Machine throws an object that is an instance of a subclass of LinkageError when a loading, linkage, preparation, verification or initialization error occurs:

  • The loading process is described in §12.2. The errors ClassFormatError, ClassCircularityError, and NoClassDefFoundError are described there.
  • The linking process is described in §12.3. The linking errors are described there. These errors include IllegalAccessError, InstantiationError, NoSuchFieldError, and NoSuchMethodError, all of which are subclasses of IncompatibleClassChangeError, and, also, UnsatisfiedLinkError.
  • The class verification process is described in §12.3.1. The verification failure error VerifyError is described there.
  • The class preparation process is described in §12.3.2. The preparation error described there is AbstractMethodError.
  • The class initialization process is described in §12.4. A virtual machine will throw the error ExceptionInInitializerError if execution of a static initializer or of an initializer for a static field results in an exception that is not an Error or a subclass of Error.

11.5.2.2 Virtual Machine Errors

A Java Virtual Machine throws an object that is an instance of a subclass of the class VirtualMachineError when an internal error or resource limitation prevents it from implementing the semantics of the Java Language. This language specification and the Java Virtual Machine Specification define the following virtual machine errors:

  • InternalError: An internal error has occurred in a Java Virtual Machine, because of a fault in the software implementing the virtual machine, a fault in the underlying host system software, or a fault in the hardware. This error is delivered asynchronously when it is detected, and may occur at any point in a Java program.
  • OutOfMemoryError: A Java Virtual Machine has run out of either virtual or physical memory, and the automatic storage manager wasn't able to reclaim enough memory to satisfy an object creation request.
  • StackOverflowError: A Java Virtual Machine has run out of stack space for a thread, typically because the thread is doing an unbounded number of recursive invocations due to a fault in the executing program.
  • UnknownError: An exception or error has occurred but, for some reason, a Java Virtual Machine is unable to report the actual exception or error.

A sophisticated Java program may be designed to handle OutOfMemoryError and attempt to recover from it, perhaps by carefully dropping references to objects.

We are exploring enhancements to Java to simplify handling of out-of-memory conditions. One possibility would be to support automatic suspension of a thread which encounters an OutOfMemoryError and allow another thread to handle the error situation. Such a technique might also permit a Java program to recover from a StackOverflowError if this overflow does not result from a nonterminating recursion. Suggestions for other approaches are welcomed.

No rule is so general, which admits not some exception.
—Robert Burton (1576-1640)


 12. Execution

CHAPTER 12

Execution

We must all hang together, or assuredly we shall all hang separately.
—Benjamin Franklin (July 4, 1776)

This chapter specifies activities that occur during execution of a Java program. It is organized around the life cycle of a Java Virtual Machine and of the classes, interfaces, and objects that form a Java program.

A Java Virtual Machine starts up by loading a specified class and then invoking the method main in this specified class. Section §12.1 outlines the loading, linking, and initialization steps involved in executing main, as an introduction to the concepts in this chapter. Further sections specify the details of loading (§12.2), linking (§12.3), and initialization (§12.4).

The chapter continues with a specification of the procedures for creation of new class instances (§12.5); finalization of class instances (§12.6); and finalization of classes (§12.7). It concludes by describing the unloading of classes (§12.8) and the procedure followed when a virtual machine exits (§12.9).


12.1 Virtual Machine Start-Up

A Java Virtual Machine starts execution by invoking the method main of some specified class, passing it a single argument, which is an array of strings. In the examples in this specification, this first class is typically called Test.

The manner in which the initial class is specified to the Java Virtual Machine is beyond the scope of this specification, but it is typical, in host environments that use command lines, for the fully-qualified name of the class to be specified as a command-line argument and for following command-line arguments to be used as strings to be provided as the argument to the method main. For example, in a UNIX implementation, the command line:

java Test reboot Bob Dot Enzo

will typically start a Java Virtual Machine by invoking method main of class Test (a class in an unnamed package), passing it an array containing the four strings "reboot", "Bob", "Dot", and "Enzo".

We now outline the steps the virtual machine may take to execute Test, as an example of the loading, linking, and initialization processes that are described further in later sections.


12.1.1 Load the Class Test

The initial attempt to execute the method main of class Test discovers that the class Test is not loaded-that is, that the virtual machine does not currently contain a binary representation for this class. The virtual machine then uses a class loader (§20.14) to attempt to find such a binary representation. If this process fails, then an error is thrown. This loading process is described further in §12.2.


12.1.2 Link Test: Verify, Prepare, (Optionally) Resolve

After Test is loaded, it must be initialized before main can be invoked. And Test, like all (class or interface) types, must be linked before it is initialized. Linking involves verification, preparation and (optionally) resolution. Linking is described further in §12.3.

Verification checks that the loaded representation of Test is well-formed, with a proper symbol table. Verification also checks that the code that implements Test obeys the semantic requirements of Java and the Java Virtual Machine. If a problem is detected during verification, then an error is thrown. Verification is described further in §12.3.1.

Preparation involves allocation of static storage and any data structures that are used internally by the virtual machine, such as method tables. If a problem is detected during preparation, then an error is thrown. Preparation is described further in §12.3.2.

Resolution is the process of checking symbolic references from Test to other classes and interfaces, by loading the other classes and interfaces that are mentioned and checking that the references are correct.

The resolution step is optional at the time of initial linkage. An implementation may resolve symbolic references from a class or interface that is being linked very early, even to the point of resolving all symbolic references from the classes and interfaces that are further referenced, recursively. (This resolution may result in errors from these further loading and linking steps.) This implementation choice represents one extreme and is similar to the kind of "static" linkage that has been done for many years in simple implementations of the C language. (In these implementations, a compiled program is typically represented as an "a.out" file that contains a fully-linked version of the program, including completely resolved links to library routines used by the program. Copies of these library routines are included in the "a.out" file.)

An implementation may instead choose to resolve a symbolic reference only when it is actively used; consistent use of this strategy for all symbolic references would represent the "laziest" form of resolution. In this case, if Test had several symbolic references to another class, then the references might be resolved one at a time, as they are used, or perhaps not at all, if these references were never used during execution of the program.

The only requirement on when resolution is performed is that any errors detected during resolution must be thrown at a point in the program where some action is taken by the program that might, directly or indirectly, require linkage to the class or interface involved in the error. Using the "static" example implementation choice described above, loading and linkage errors could occur before the program is executed if they involved a class or interface mentioned in the class Test or any of the further, recursively referenced, classes and interfaces. In a system that implemented the "laziest" resolution, these errors would be thrown only when an incorrect symbolic reference is actively used.

The resolution process is described further in §12.3.3.


12.1.3 Initialize Test: Execute Initializers

In our continuing example, the virtual machine is still trying to execute the method main of class Test. This is an attempted active use (§12.4.1) of the class, which is permitted only if the class has been initialized.

Initialization consists of execution of any class variable initializers and static initializers of the class Test, in textual order. But before Test can be initialized, its direct superclass must be initialized, as well as the direct superclass of its direct superclass, and so on, recursively. In the simplest case, Test has Object as its implicit direct superclass; if class Object has not yet been initialized, then it must be initialized before Test is initialized. Class Object has no superclass, so the recursion terminates here.

If class Test has another class Super as its superclass, then Super must be initialized before Test. This requires loading, verifying, and preparing Super if this has not already been done and, depending on the implementation, may also involve resolving the symbolic references from Super and so on, recursively.

Initialization may thus cause loading, linking, and initialization errors, including such errors involving other types.

The initialization process is described further in §12.4.


12.1.4 Invoke Test.main

Finally, after completion of the initialization for class Test (during which other consequential loading, linking, and initializing may have occurred), the method main of Test is invoked.

The method main must be declared public, static, and void. It must accept a single argument that is an array of strings.


12.2 Loading of Classes and Interfaces

Loading refers to the process of finding the binary form of a class or interface type with a particular name, perhaps by computing it on the fly, but more typically by retrieving a binary representation previously computed from source code by a compiler, and constructing, from that binary form, a Class object to represent the class or interface.

The binary format of a class or interface is normally the class file format described in The Java Virtual Machine, but other formats are possible, provided they meet the requirements specified in §13.1. The method defineClass (§20.14.3) of class ClassLoader may be used to construct Class objects from binary representations in the class file format.

A Java Virtual Machine system should maintain an internal table of classes and interfaces that have been loaded for the sake of resolving symbolic references. Each entry in the table should consist of a fully qualified class name (as a string), a class loader, and a Class object. Whenever a symbolic reference to a class or interface is to be resolved, a class loader is identified that is responsible for loading the class or interface, if necessary. The table should be consulted first, however; if it already contains an entry for that class name and class loader, then the class object in that entry should be used and no method of the class loader should be invoked. If the table contains no such entry, then the method loadClass (§20.14.2) of the class loader should be invoked, giving it the name of the class or interface. If and when it returns, the class object that it returns should be used to make a new entry in the table for that class name and class loader.

The purpose of this internal table is to allow the verification process (§12.3.1) to assume, for its purposes, that two classes or interfaces are the same if they have the same name and the same class loader. This property allows a class to be verified without loading all the classes and interfaces that it uses, whether actively or passively. Well-behaved class loaders do maintain this property: given the same name twice, a good class loader should return the same class object each time. But without the internal table, a malicious class loader could violate this property and undermine the security of the Java type system. A basic principle of the design of the Java language is that the type system cannot be subverted by code written in Java, not even by implementations of such otherwise sensitive system classes as ClassLoader (§20.14) and SecurityManager (§20.17).

An entry may be deleted from the internal table only after unloading (§12.8) the class or interface represented by the class object in the entry.


12.2.1 The Loading Process

The loading process is implemented by the class ClassLoader (§20.14) and its subclasses. Different subclasses of ClassLoader may implement different loading policies. In particular, a class loader may cache binary representations of classes and interfaces, prefetch them based on expected usage, or load a group of related classes together. These activities may not be completely transparent to a running Java application if, for example, a newly compiled version of a class is not found because an older version is cached by a class loader. It is the responsibility of a class loader, however, to reflect loading errors only at points in the program they could have arisen without prefetching or group loading.

If an error occurs during class loading, then an instance of one of the following subclasses of class LinkageError will be thrown at any point in the Java program that (directly or indirectly) uses the type:

  • ClassCircularityError: A class or interface could not be loaded because it would be its own superclass or superinterface (§13.4.4).
  • ClassFormatError: The binary data that purports to specify a requested compiled class or interface is malformed.
  • NoClassDefFoundError: No definition for a requested class or interface could be found by the relevant class loader.

Because loading involves the allocation of new data structures, it may fail with an OutOfMemoryError.


12.2.2 Implications for Code Generation

A cooperating class loader can enable a code generator to generate code for a group of class and interface types-perhaps an entire package-by loading the binary code for these types as a group. A format can be designed that allows all the internal symbolic references in such a group to be resolved, before the group is loaded. Such a strategy may also allow the generated code to be optimized before loading based on the known concrete types in the group. This approach may be useful in specific cases, but is discouraged as a general technique, since such a class file format is unlikely to be widely understood.


12.3 Linking of Classes and Interfaces

Linking is the process of taking a binary form of a class or interface type and combining it into the runtime state of the Java Virtual Machine, so that it can be executed. A class or interface type is always loaded before it is linked. Three different activities are involved in linking: verification, preparation, and resolution of symbolic references.

Java allows an implementation flexibility as to when linking activities (and, because of recursion, loading) take place, provided that the semantics of the language are respected, that a class or interface is completely verified and prepared before it is initialized, and that errors detected during linkage are thrown at a point in the program where some action is taken by the program that might require linkage to the class or interface involved in the error.

For example, an implementation may choose to resolve each symbolic reference in a class or interface individually, only when it is used (lazy or late resolution), or to resolve them all at once while the class is being verified (static resolution). This means that the resolution process may continue, in some implementations, after a class or interface has been initialized.

Because linking involves the allocation of new data structures, it may fail with an OutOfMemoryError.


12.3.1 Verification of the Binary Representation

Verification ensures that the binary representation of a class or interface is structurally correct. For example, it checks that every instruction has a valid operation code; that every branch instruction branches to the start of some other instruction, rather than into the middle of an instruction; that every method is provided with a structurally correct signature; and that every instruction obeys the type discipline of the Java language.

For a more detailed description of the verification process, see the separate volume of this series, The Java Virtual Machine Specification.

If an error occurs during verification, then an instance of the following subclass of class LinkageError will be thrown at the point in the Java program that caused the class to be verified:

  • VerifyError: The binary definition for a class or interface failed to pass a set of required checks to verify that it obeys the semantics of the Java language and that it cannot violate the integrity of the Java Virtual Machine. (See §13.4.2, §13.4.4, §13.4.8, and §13.4.16 for some examples.)


12.3.2 Preparation of a Class or Interface Type

Preparation involves creating the static fields (class variables and constants) for a class or interface and initializing such fields to the standard default values (§4.5.4). This does not require the execution of any Java code; explicit initializers for static fields are executed as part of initialization (§12.4), not preparation.

Java implementations must detect the following error during preparation:

  • AbstractMethodError: A class that is not declared to be abstract has an abstract method. This can occur, for example, if a method that is originally not abstract is changed to be abstract after another class that inherits the now abstract method declaration has been compiled (§13.4.15).

If such an error is detected, then an instance of AbstractMethodError should be thrown at the point in the Java program that caused the class to be prepared.

Implementations of the Java Virtual Machine may precompute additional data structures at preparation time in order to make later operations on a class or interface more efficient. One particularly useful data structure is a "method table" or other data structure that allows any method to be invoked on instances of a class without requiring a search of superclasses at invocation time.


12.3.3 Resolution of Symbolic References

A Java binary file references other classes and interfaces and their fields, methods, and constructors symbolically, using the fully-qualified names of the other classes and interfaces (§13.1). For fields and methods, these symbolic references include the name of the class or interface type that declares the field or method as well as the name of the field or method itself, together with appropriate type information.

Before a symbolic reference can be used it must be undergo resolution, wherein a symbolic reference is checked to be correct and, typically, replaced with a direct reference that can be more efficiently processed if the reference is used repeatedly.

If an error occurs during resolution, then an error will be thrown. Most typically, this will be an instance of one of the following subclasses of the class IncompatibleClassChangeError, but it may also be an instance of some other subclass of IncompatibleClassChangeError or even an instance of the class IncompatibleClassChangeError itself. This error may be thrown at any point in the program that uses a symbolic reference to the type, directly or indirectly:

  • IllegalAccessError: A symbolic reference has been encountered that specifies a use or assignment of a field, or invocation of a method, or creation of an instance of a class, to which the code containing the reference does not have access because the field or method was declared private, protected, or default access (not public), or because the class was not declared public. This can occur, for example, if a field that is originally declared public is changed to be private after another class that refers to the field has been compiled (§13.4.6).
  • InstantiationError: A symbolic reference has been encountered that is used in a class instance creation expression, but an instance cannot be created because the reference turns out to refer to an interface or to an abstract class. This can occur, for example, if a class that is originally not abstract is changed to be abstract after another class that refers to the class in question has been compiled (§13.4.1).
  • NoSuchFieldError: A symbolic reference has been encountered that refers to a specific field of a specific class or interface, but the class or interface does not declare a field of that name (it is specifically not sufficient for it simply to be an inherited field of that class or interface). This can occur, for example, if a field declaration was deleted from a class after another class that refers to the field was compiled (§13.4.7).
  • NoSuchMethodError: A symbolic reference has been encountered that refers to a specific method of a specific class or interface, but the class or interface does not declare a method of that signature (it is specifically not sufficient for it simply to be an inherited method of that class or interface). This can occur, for example, if a method declaration was deleted from a class after another class that refers to the method was compiled (§13.4.12).

Additionally, an UnsatisfiedLinkError (a subclass of LinkageError) may be thrown if a class declares a native method for which no implementation can be found. The error will occur if the method is used, or earlier depending on what kind of resolution strategy is being used by the virtual machine (§12.3).


12.3.4 Implications for Code Generation

The symbolic references within a group of types may be resolved even before the group is loaded (§12.2.2), in an implementation that uses a special (non-standard) binary format (§13.1). This corresponds to the traditional practice of "linkage editing." Even if this is not done, a Java implementation has a lot of flexibility. It may resolve all symbolic references from a type at the point of the first linkage activity on the type, or defer the resolution of each symbolic reference to the first use of that reference.

We note that the flexibility accorded the Java implementation in the linkage process does not affect correctly formed Java programs, which should never encounter linkage errors.


12.4 Initialization of Classes and Interfaces

Initialization of a class consists of executing its static initializers and the initializers for static fields (class variables) declared in the class. Initialization of an interface consists of executing the initializers for fields (constants) declared there.

Before a class is initialized, its superclass must be initialized, but interfaces implemented by the class need not be initialized. Similarly, the superinterfaces of an interface need not be initialized before the interface is initialized.


12.4.1 When Initialization Occurs

A class or interface type T will be initialized at its first active use, which occurs if:

  • T is a class and a method actually declared in T (rather than inherited from a superclass) is invoked.
  • T is a class and a constructor for class T is invoked, or U is an array with element type T, and an array of type U is created.
  • A non-constant field declared in T (rather than inherited from a superclass or superinterface) is used or assigned. A constant field is one that is (explicitly or implicitly) both final and static, and that is initialized with the value of a compile-time constant expression (§15.27). Java specifies that a reference to a constant field must be resolved at compile time to a copy of the compile-time constant value, so uses of such a field are never active uses. See §13.4.8 for a further discussion.

All other uses of a type are passive uses.

The intent here is that a class or interface type has a set of initializers that put it in a consistent state, and that this state is the first state that is observed by other classes. The static initializers and class variable initializers are executed in textual order, and may not refer to class variables declared in the class whose declarations appear textually after the use, even though these class variables are in scope (§8.5). This restriction is designed to detect, at compile time, most circular or otherwise malformed initializations.

As shown in an example in §8.5, the fact that initialization code is unrestricted allows examples to be constructed where the value of a class variable can be observed when it still has its initial default value, before its initializing expression is evaluated, but such examples are rare in practice. (Such examples can be also constructed for instance variable initialization; see the example at the end of §12.5). Java provides the full power of the language in these initializers; programmers must exercise some care. This power places an extra burden on code generators, but this burden would arise in any case because Java is concurrent (§12.4.3).

Before a class is initialized, its superclasses are initialized, if they have not previously been initialized.

Thus, the test program:

class Super {
    static { System.out.print("Super "); }
}

class One {
    static { System.out.print("One "); }
}

class Two extends Super {
    static { System.out.print("Two "); }
}

class Test {
    public static void main(String[] args) {
        One o = null;
        Two t = new Two();
        System.out.println((Object)o == (Object)t);
    }
}

prints:

Super Two false

The class One is never initialized, because it not used actively and therefore is never linked to. The class Two is initialized only after its superclass Super has been initialized.

A reference to a field is an active use of only the class or interface that actually declares it, even though it might be referred to through the name of a subclass, a subinterface, or a class that implements an interface. The test program:

class Super { static int taxi = 1729; }

class Sub extends Super {
    static { System.out.print("Sub "); }
}

class Test {
    public static void main(String[] args) {
        System.out.println(Sub.taxi);
    }
}

prints only:

1729

because the class Sub is never initialized; the reference to Sub.taxi is a reference to a field actually declared in class Super and is not an active use of the class Sub.

Initialization of an interface does not, of itself, require initialization of any of its superinterfaces. Thus, the test program:

interface I {
    int i = 1, ii = Test.out("ii", 2);
}

interface J extends I {
    int j = Test.out("j", 3), jj = Test.out("jj", 4);
}

interface K extends J {
    int k = Test.out("k", 5);
}

class Test {

    public static void main(String[] args) {
        System.out.println(J.i);
        System.out.println(K.j);
    }

    static int out(String s, int i) {
        System.out.println(s + "=" + i);
        return i;
    }
}

produces the output:

1
j=3
jj=4
3

The reference to J.i is to a field that is a compile-time constant; therefore, it does not cause I to be initialized. The reference to K.j is a reference to a field actually declared in interface J that is not a compile-time constant; this causes initialization of the fields of interface J, but not those of its superinterface I, nor those of interface K. Despite the fact that the name K is used to refer to field j of interface J, interface K is not actively used.


12.4.2 Detailed Initialization Procedure

Because Java is multithreaded, initialization of a class or interface requires careful synchronization, since some other thread may be trying to initialize the same class or interface at the same time. There is also the possibility that initialization of a class or interface may be requested recursively as part of the initialization of that class or interface; for example, a variable initializer in class A might invoke a method of an unrelated class B, which might in turn invoke a method of class A. The implementation of the Java Virtual Machine is responsible for taking care of synchronization and recursive initialization by using the following procedure. It assumes that the Class object has already been verified and prepared, and that the Class object contains state that indicates one of four situations:

  • This Class object is verified and prepared but not initialized.
  • This Class object is being initialized by some particular thread T.
  • This Class object is fully initialized and ready for use.
  • This Class object is in an erroneous state, perhaps because the verification or preparation step failed, or because initialization was attempted and failed.

The procedure for initializing a class or interface is then as follows:

  1. Synchronize (§14.17) on the Class object that represents the class or interface to be initialized. This involves waiting until the current thread can obtain the lock for that object (§17.13).
  2. If initialization is in progress for the class or interface by some other thread, then wait (§20.1.6) on this Class object (which temporarily releases the lock). When the current thread awakens from the wait, repeat this step.
  3. If initialization is in progress for the class or interface by the current thread, then this must be a recursive request for initialization. Release the lock on the Class object and complete normally.
  4. If the class or interface has already been initialized, then no further action is required. Release the lock on the Class object and complete normally.
  5. If the Class object is in an erroneous state, then initialization is not possible. Release the lock on the Class object and throw a NoClassDefFoundError.
  6. Otherwise, record the fact that initialization of the Class object is now in progress by the current thread and release the lock on the Class object.
  7. Next, if the Class object represents a class rather than an interface, and the superclass of this class has not yet been initialized, then recursively perform this entire procedure for the superclass. If necessary, verify and prepare the superclass first. If the initialization of the superclass completes abruptly because of a thrown exception, then lock this Class object, label it erroneous, notify all waiting threads (§20.1.10), release the lock, and complete abruptly, throwing the same exception that resulted from initializing the superclass.
  8. Next, execute either the class variable initializers and static initializers of the class, or the field initializers of the interface, in textual order, as though they were a single block, except that final class variables and fields of interfaces whose values are compile-time constants are initialized first (§8.3.2.1, §9.3.1, §13.4.8).
  9. If the execution of the initializers completes normally, then lock this Class object, label it fully initialized, notify all waiting threads (§20.1.10), release the lock, and complete this procedure normally.
  10. Otherwise, the initializers must have completed abruptly by throwing some exception E. If the class of E is not Error or one of its subclasses, then create a new instance of the class ExceptionInInitializerError, with E as the argument, and use this object in place of E in the following step. But if a new instance of ExceptionInInitializerError cannot be created because an OutOfMemoryError occurs, then instead use an OutOfMemoryError object in place of E in the following step.
  11. Lock the Class object, label it erroneous, notify all waiting threads (§20.1.10), release the lock, and complete this procedure abruptly with reason E or its replacement as determined in the previous step.
(Due to a flaw in some early implementations of Java, a exception during class initialization was ignored, rather than causing an ExceptionInInitializerError as described here.)


12.4.3 Implications for Code Generation

Code generators need to preserve the points of possible initialization of a class or interface, inserting an invocation of the initialization procedure just described. If this initialization procedure completes normally and the Class object is fully initialized and ready for use, then the invocation of the initialization procedure is no longer necessary and it may be eliminated from the code-for example, by patching it out or otherwise regenerating the code.

Compile-time analysis may, in some cases, be able to eliminate many of the checks that a type has been initialized from the generated code, if an initialization order for a group of related types can be determined. Such analysis must, however, fully account for the fact that Java is concurrent and that initialization code is unrestricted.


12.5 Creation of New Class Instances

A new class instance is explicitly created when one of the following situations occurs:

  • Evaluation of a class instance creation expression (§15.8) creates a new instance of the class whose name appears in the expression.
  • Invocation of the newInstance method (§20.3.6) of class Class creates a new instance of the class represented by the Class object for which the method was invoked.

A new class instance may be implicitly created in the following situations:

  • Loading of a class or interface that contains a String literal (§3.10.5) may create a new String object (§20.12) to represent that literal. (This might not occur if the same String has previously been interned (§3.10.5).)
  • Execution of a string concatenation operator (§15.17.1) that is not part of a constant expression sometimes creates a new String object to represent the result. String concatenation operators may also create temporary wrapper objects for a value of a primitive type.

Each of these situations identifies a particular constructor to be called with specified arguments (possibly none) as part of the class instance creation process.

Whenever a new class instance is created, memory space is allocated for it with room for all the instance variables declared in the class type and all the instance variables declared in each superclass of the class type, including all the instance variables that may be hidden. If there is not sufficient space available to allocate memory for the object, then creation of the class instance completes abruptly with an OutOfMemoryError. Otherwise, all the instance variables in the new object, including those declared in superclasses, are initialized to their default values (§4.5.4). Just before a reference to the newly created object is returned as the result, the indicated constructor is processed to initialize the new object using the following procedure:

  1. Assign the arguments for the constructor to newly created parameter variables for this constructor invocation.
  2. If this constructor begins with an explicit constructor invocation of another constructor in the same class (using this), then evaluate the arguments and process that constructor invocation recursively using these same five steps. If that constructor invocation completes abruptly, then this procedure completes abruptly for the same reason; otherwise, continue with step 5.
  3. This constructor does not begin with an explicit constructor invocation of another constructor in the same class (using this). If this constructor is for a class other than Object, then this constructor will begin with a explicit or implicit invocation of a superclass constructor (using super). Evaluate the arguments and process that superclass constructor invocation recursively using these same five steps. If that constructor invocation completes abruptly, then this procedure completes abruptly for the same reason. Otherwise, continue with step 4.
  4. Execute the instance variable initializers for this class, assigning their values to the corresponding instance variables, in the left-to-right order in which they appear textually in the source code for the class. If execution of any of these initializers results in an exception, then no further initializers are processed and this procedure completes abruptly with that same exception. Otherwise, continue with step 5. (In some early Java implementations, the compiler incorrectly omitted the code to initialize a field if the field initializer expression was a constant expression whose value was equal to the default initialization value for its type.)
  5. Execute the rest of the body of this constructor. If that execution completes abruptly, then this procedure completes abruptly for the same reason. Otherwise, this procedure completes normally.
In the example:

class Point {
    int x, y;
    Point() { x = 1; y = 1; }
}

class ColoredPoint extends Point {
    int color = 0xFF00FF;
}

class Test {
    public static void main(String[] args) {
        ColoredPoint cp = new ColoredPoint();
        System.out.println(cp.color);
    }
}

a new instance of ColoredPoint is created. First, space is allocated for the new ColoredPoint, to hold the fields x, y, and color. All these fields are then initialized to their default values (in this case, 0 for each field). Next, the ColoredPoint constructor with no arguments is first invoked. Since ColoredPoint declares no constructors, a default constructor of the form:

ColoredPoint() { super(); }

is provided for it automatically by the Java compiler.

This constructor then invokes the Point constructor with no arguments. The Point constructor does not begin with an invocation of a constructor, so the compiler provides an implicit invocation of its superclass constructor of no arguments, as though it had been written:

Point() { super(); x = 1; y = 1; }

Therefore, the constructor for Object which takes no arguments is invoked.

The class Object has no superclass, so the recursion terminates here. Next, any instance variable initializers and static initializers of Object are invoked. Next, the body of the constructor of Object that takes no arguments is executed. No such constructor is declared in Object, so the compiler supplies a default one, which in this special case is:

Object() { }

This constructor executes without effect and returns.

Next, all initializers for the instance variables of class Point are executed. As it happens, the declarations of x and y do not provide any initialization expressions, so no action is required for this step of the example. Then the body of the Point constructor is executed, setting x to 1 and y to 1.

Next, the initializers for the instance variables of class ColoredPoint are executed. This step assigns the value 0xFF00FF to color. Finally, the rest of the body of the ColoredPoint constructor is executed (the part after the invocation of super); there happen to be no statements in the rest of the body, so no further action is required and initialization is complete.

Unlike C++, the Java language does not specify altered rules for method dispatch during the creation of a new class instance. If methods are invoked that are overridden in subclasses in the object being initialized, then these overriding methods are used, even before the new object is completely initialized. Thus, compiling and running the example:

class Super {
    Super() { printThree(); }
    void printThree() { System.out.println("three"); }
}

class Test extends Super {
    int indiana = (int)Math.PI;													// That is, 3

    public static void main(String[] args) {
        Test t = new Test();
        t.printThree();
    }
    void printThree() { System.out.println(indiana); }
}

produces the output:

0
3

This shows that the invocation of printThree in the constructor for class Super does not invoke the definition of printThree in class Super, but rather invokes the overriding definition of printThree in class Test. This method therefore runs before the field initializers of Test have been executed, which is why the first value output is 0, the default value to which the field three of Test is initialized. The later invocation of printThree in method main invokes the same definition of printThree, but by that point the initializer for instance variable three has been executed, and so the value 3 is printed.

See §8.6 for more details on constructor declarations.


12.6 Finalization of Class Instances

The class Object has a protected method called finalize (§20.1.11); this method can be overridden by other classes. The particular definition of finalize that can be invoked for an object is called the finalizer of that object. Before the storage for an object is reclaimed by the garbage collector, the Java Virtual Machine will invoke the finalizer of that object.

Finalizers provide a chance to free up resources (such as file descriptors or operating system graphics contexts) that cannot be freed automatically by an automatic storage manager. In such situations, simply reclaiming the memory used by an object would not guarantee that the resources it held would be reclaimed.

The Java language does not specify how soon a finalizer will be invoked, except to say that it will happen before the storage for the object is reused. Also, the Java language does not specify which thread will invoke the finalizer for any given object. If an uncaught exception is thrown during the finalization, the exception is ignored and finalization of that object terminates.

The finalize method declared in class Object takes no action. However, the fact that class Object declares a finalize method means that the finalize method for any class can always invoke the finalize method for its superclass, which is usually good practice. (Unlike constructors, finalizers do not automatically invoke the finalizer for the superclass; such an invocation must be coded explicitly.)

For efficiency, an implementation may keep track of classes that do not override the finalize method of class Object, or override it in a trivial way, such as:

protected void finalize() throws Throwable {

    super.finalize();

}

We encourage implementations to treat such objects as having a finalizer that is not overridden, and to finalize them more efficiently, as described in §12.6.1.

A finalizer may be invoked explicitly, just like any other method.


12.6.1 Implementing Finalization

Every object can be characterized by two attributes: it may be reachable, finalizer- reachable, or unreachable, and it may also be unfinalized, finalizable, or finalized.

A reachable object is any object that can be accessed in any potential continuing computation from any live thread. Optimizing transformations of a program can be designed that reduce the number of objects that are reachable to be less than those which would naively be considered reachable. For example, a compiler or code generator may choose, explicitly or implicitly, to set a variable or parameter that will no longer be used to null to cause the storage for such an object to be potentially reclaimable sooner. A finalizer-reachable object can be reached from some finalizable object through some chain of references, but not from any live thread. An unreachable object cannot be reached by either means.

An unfinalized object has never had its finalizer automatically invoked; a finalized object has had its finalizer automatically invoked. A finalizable object has never had its finalizer automatically invoked, but the Java Virtual Machine may eventually automatically invoke its finalizer.

The life cycle of an object obeys the following transition diagram, where we abbreviate "finalizer-reachable" as "f-reachable":

When an object is first created (A), it is reachable and unfinalized.

As references to an object are discarded during program execution, an object that was reachable may become finalizer-reachable (B, C, D) or unreachable (E, F). (Note that a finalizer-reachable object never becomes unreachable directly; it becomes reachable when the finalizer from which it can be reached is invoked, as explained below.)

If the Java Virtual Machine detects that an unfinalized object has become finalizer-reachable or unreachable, it may label the object finalizable (G, H); moreover, if the object was unreachable, it becomes finalizer-reachable (H).

If the Java Virtual Machine detects that a finalized object has become unreachable, it may reclaim the storage occupied by the object because the object will never again become reachable (I).

At any time, a Java Virtual Machine may take any finalizable object, label it finalized, and then invoke its finalize method in some thread. This causes the object to become finalized and reachable (J, K), and it also may cause other objects that were finalizer-reachable to become reachable again (L, M, N).

A finalizable object cannot also be unreachable; it can be reached because its finalizer may eventually be invoked, whereupon the thread running the finalizer will have access to the object, as this (§15.7.2). Thus, there are actually only eight possible states for an object.

After an object has been finalized, no further action is taken until the automatic storage management determines that it is unreachable. Because of the way that an object progresses from the unfinalized state through the finalizable state to the finalized state, the finalize method is never automatically invoked more than once by a Java Virtual Machine for each object, even if the object is again made reachable after it has been finalized.

Explicit invocation of a finalizer ignores the current state of the object and does not change the state of the object from unfinalized or finalizable to finalized.

If a class does not override method finalize of class Object (or overrides it in only a trivial way, as described above), then if instances of such as class become unreachable, they may be discarded immediately rather than made to await a second determination that they have become unreachable. This strategy is indicated by the dashed arrow (O) in the transition diagram.

Java programmers should also be aware that a finalizer can be automatically invoked, even though it is reachable, during finalization-on-exit (§12.9); moreover, a finalizer can also be invoked explicitly as an ordinary method. Therefore, we recommend that the design of finalize methods be kept simple and that they be programmed defensively, so that they will work in all cases.


12.6.2 Finalizer Invocations are Not Ordered

Java imposes no ordering on finalize method calls. Finalizers may be called in any order, or even concurrently.

As an example, if a circularly linked group of unfinalized objects becomes unreachable (or finalizer-reachable), then all the objects may become finalizable together. Eventually, the finalizers for these objects may be invoked, in any order, or even concurrently using multiple threads. If the automatic storage manager later finds that the objects are unreachable, then their storage can be reclaimed.

It is straightforward to implement a Java class that will cause a set of finalizer-like methods to be invoked in a specified order for a set of objects when all the objects become unreachable. Defining such a class is left as an exercise for the reader.


12.7 Finalization of Classes

If a class declares a class method classFinalize that takes no arguments and returns no result:

static void classFinalize() throws Throwable { . . . }

then this method will be invoked before the class is unloaded (§12.8). Like the finalize method for objects, this method will be automatically invoked only once. This method may optionally be declared private, protected, or public.


12.8 Unloading of Classes and Interfaces

A Java Virtual Machine may provide mechanisms whereby classes are unloaded. The details of such mechanisms are not specified in this version of the Java Language Specification. In general, groups of related class and interface types will be unloaded together. This can be used, for example, to unload a group of related types that have been loaded using a particular class loader. Such a group might consist of all the classes implementing a single applet in a Java-based browser such as HotJava, for example.

A class may not be unloaded while any instance of it is still reachable (§12.6). A class or interface may not be unloaded while the Class object that represents it is still reachable.

Classes that declare class finalizers (§12.7) will have these finalizers run before they are unloaded.


12.9 Virtual Machine Exit

A Java Virtual Machine terminates all its activity and exits when one of two things happens:

  • All the threads that are not daemon threads (§20.20.24) terminate.
  • Some thread invokes the exit method (§20.16.2) of class Runtime or class System and the exit operation is not forbidden by the security manager (§20.17.13).

A Java program can specify that the finalizers of all objects that have finalizers, and all classes that have class finalizers, that have not yet been automatically invoked are to be run before the virtual machine exits. This is done by invoking the method runFinalizersOnExit of class System with the argument true. The default is to not run finalizers on exit, and this behavior may be restored by invoking runFinalizersOnExit with the argument false. An invocation of the runFinalizersOnExit method is permitted only if the caller is allowed to exit, and is otherwise rejected by the SecurityManager (§20.17).

. . . Farewell!
The day frowns more and more. Thou'rt like to have
A lullaby too rough: I never saw
The heavens so dim by day: A savage clamour!
Well may I get aboard! This is the chase.
I am gone for ever! [Exit, pursued by a bear]
—William Shakespeare, The Winter's Tale, Act III, scene iii


 13. Binary Compatibility

CHAPTER 13

Binary Compatibility

Java development tools should support automatic recompilation as necessary whenever source code is available. Particular implementations of Java may also store the source and binary of types in a versioning database and implement a ClassLoader (§20.14) that uses integrity mechanisms of the database to prevent linkage errors by providing binary-compatible versions of types to clients.

Developers of packages and classes that are to be widely distributed face a different set of problems. In the Internet, which is our favorite example of a widely distributed system, it is often impractical or impossible to automatically recompile the pre-existing binaries that directly or indirectly depend on a type that is to be changed. Instead, Java defines a set of changes that developers are permitted to make to a package or to a class or interface type while preserving (not breaking) compatibility with existing binaries.

The paper quoted above appears in Proceedings of OOPSLA '95, published as ACM SIGPLAN Notices, Volume 30, Number 10, October 1995, pages 426-438. Within the framework of that paper, Java binaries are binary (release-to-release) compatible under all relevant transformations that the authors identify. Using their scheme, here is a list of some important binary compatible changes that Java supports:

  • Reimplementing existing methods, constructors, and initializers to improve performance.
  • Changing methods or constructors to return values on inputs for which they previously either threw exceptions that normally should not occur or failed by going into an infinite loop or causing a deadlock.
  • Adding new fields, methods, or constructors to an existing class or interface.
  • Deleting private fields, methods, or constructors of a class or interface.
  • When an entire package is updated, deleting default (package-only) access fields, methods, or constructors of classes and interfaces in the package.
  • Reordering the fields, methods, or constructors in an existing type declaration.
  • Moving a method upward in the class hierarchy, provided a forwarding method is left in its place.
  • Reordering the list of direct superinterfaces of a class or interface.
  • Inserting new class or interface types in the type hierarchy.

This chapter specifies minimum standards for binary compatibility guaranteed by all Java implementations. Java guarantees compatibility when binaries of classes and interfaces are mixed that are not known to be from compatible sources, but whose sources have been modified in the compatible ways described here.

We encourage Java development systems to provide facilities that alert developers to the impact of changes on pre-existing binaries that cannot be recompiled.

This chapter first specifies some properties that any Java binary format must have (§13.1). It next defines binary compatibility, explaining what it is and what it is not (§13.2). It finally enumerates a large set of possible changes to packages (§13.3), classes (§13.4) and interfaces (§13.5), specifying which changes are guaranteed to preserve binary compatibility and which are not.


13.1 The Form of a Java Binary

While many Java binary files are likely to be in exactly the class file format specified by the The Java Virtual Machine Specification, this specification does not mandate the use of any specific binary file format. Rather, it specifies properties that any binary format for compiled types must obey. A number of these properties are specifically chosen to support source code transformations that preserve binary compatibility.

The requirements are:

  • Binary formats for Java programs must be defined and processed to respect the specifications of loading (§12.2), linking (§12.3) and initialization (§12.4) of class and interface types.
  • A reference to another class or interface type must be symbolic, using the fully qualified name of the type as determined at compile time.
  • A reference to a field of another class or interface must be resolved at compile time to a symbolic reference to the class or interface in which the field is declared, plus the simple name of the field. (Including the exact class or interface in which the field is declared makes the binaries more robust, since adding another field with the same name, even in a subclass, cannot cause confusion at link time. This rule does mean, however, that moving a field to a superclass is not a binary compatible change; see §13.4.5 for a discussion.) The reference must also include a symbolic reference to the declared type of the field so that the verifier can check that the type is as expected. References to fields that are static, final, and initialized with compile-time constant expressions are resolved at compile time to the constant value that is denoted. No reference to such a constant field should be present in the code in a binary file (except in the class or interface containing the constant field, which will have code to initialize it), and such constant fields must always appear to have been initialized; the default initial value for the type of such a field must never be observed. See §13.4.8 for a discussion.
  • A reference to a method or constructor must be resolved at compile time to a symbolic reference to the class or interface in which the denoted method or constructor is declared, plus the signature of the method or constructor. (As for fields, this makes the binaries more robust, with the caveat that such a method cannot be moved to a superclass without leaving a forwarding method behind; see §13.4.5 for a discussion.) A reference to a method must also include either a symbolic reference to the return type of the denoted method or an indication that the denoted method is declared void and does not return a value. The signature of a method must include all of the following:
    • The simple name of the method
    • The number of parameters to the method
    • A symbolic reference to the type of each parameter

    The signature of a constructor must include both:
    • The number of parameters to the constructor
    • A symbolic reference to the type of each parameter

A Java binary representation for a class or interface must also contain all of the following:

  • If it is a class and is not class java.lang.Object, then a symbolic reference to the direct superclass of this class
  • A symbolic reference to each direct superinterface, if any
  • A specification of each field that is not private declared in the class or interface, given as the simple name of the field and a symbolic reference to the type of the field
  • If it is a class, then the signature of each constructor, as described above
  • For each method that is not private declared in the class or interface, its signature and return type, as described above
  • The code needed to implement the class or interface:
    • For an interface, code for the field initializers
    • For a class, code for the field initializers, the static initializers, and the implementation of each method or constructor that is not declared private

If a Java system defines a binary format that represents a group of classes and interfaces comprised by an entire package, then this binary format need not expose information about fields, methods, or constructors that are declared with default (package) access.

The following sections specify the changes that may be made to class and interface type declarations without breaking compatibility with pre-existing binaries. The Java Virtual Machine and its standard class file format support these changes; other Java binary formats are required to support these changes as well.


13.2 What Binary Compatibility Is and Is Not

A change to a type is binary compatible with (equivalently, does not break binary compatibility with) preexisting binaries if preexisting binaries that previously linked without error will continue to link without error.

As described in §13.1, symbolic references to methods and fields name the exact class or interface in which the method or field is declared. This means that binaries are compiled to rely on the accessible members and constructors of other classes and interfaces. To preserve binary compatibility, a class or interface should treat these accessible members and constructors, their existence and behavior, as a contract with users of the class or interface.

Java is designed to prevent additions to contracts and accidental name collisions from breaking binary compatibility; specifically:

  • Introducing a new field with the same name as an existing field, in a subclass of the class containing the existing field declaration, does not break compatibility with preexisting binaries. See the example at the beginning of §13.4.5.
  • Addition of more methods overloading a particular method name does not break compatibility with preexisting binaries. The method signature that the preexisting binary will use for method lookup is chosen by Java's method overload resolution algorithm at compile time (§15.11.2). (If Java had been designed so that the particular method to be executed was chosen at run time, then such an ambiguity might be detected at run time. Such a rule would imply that adding an additional overloaded method so as to make ambiguity possible at a call site became possible could break compatibility with an unknown number of preexisting binaries. See §13.4.22 for more discussion.)

Binary compatibility is not the same as source compatibility. In particular, the example in §13.4.5 shows that a set of compatible binaries can be produced from sources that will not compile all together. This example is typical: a new declaration is added, changing the meaning of a name in an unchanged part of the source code, while the preexisting binary for that unchanged part of the source code retains the fully-qualified, previous meaning of the name. Producing a consistent set of source code requires providing a qualified name or field access expression corresponding to the previous meaning.

We hope to make some improvements to future versions of Java to better support both source and binary compatible evolution of types. In particular, we are considering a mechanism to allow a class to implement two interfaces that have methods with the same signature but are to be considered different or have different return types. We welcome suggestions and proposals that would help us to make additional improvements, either in managing name and signature conflicts or other sources of incompatibility.


13.3 Evolution of Packages

A new class or interface type may be added to a package without breaking compatibility with pre-existing binaries, provided the new type does not reuse a name previously given to an unrelated type. If a new type reuses a name previously given to an unrelated type, then a conflict may result, since binaries for both types could not be loaded by the same class loader.

Changes in class and interface types that are not public and that are not a superclass or superinterface, respectively, of a public type, affect only types within the package in which they are declared. Such types may be deleted or otherwise changed, even if incompatibilities are otherwise described here, provided that the affected binaries of that package are updated together.


13.4 Evolution of Classes

This section describes the effects of changes to the declaration of a class and its members and constructors on pre-existing binaries.


13.4.1 abstract Classes

If a class that was not abstract is changed to be declared abstract, then pre- existing binaries that attempt to create new instances of that class will throw either an InstantiationError at link time, or an InstantiationException at run time (if the method newInstance (§20.3.6) of class Class is used); such a change is therefore not recommended for widely distributed classes.

Changing a class that was declared abstract to no longer be declared abstract does not break compatibility with pre-existing binaries.


13.4.2 final Classes

If a class that was not declared final is changed to be declared final, then a VerifyError is thrown if a binary of a pre-existing subclass of this class is loaded, because final classes can have no subclasses; such a change is not recommended for widely distributed classes.

Changing a class that was declared final to no longer be declared final does not break compatibility with pre-existing binaries.


13.4.3 public Classes

Changing a class that was not declared public to be declared public does not break compatibility with pre-existing binaries.

If a class that was declared public is changed to not be declared public, then an IllegalAccessError is thrown if a pre-existing binary is linked that needs but no longer has access to the class type; such a change is not recommended for widely distributed classes.


13.4.4 Superclasses and Superinterfaces

A ClassCircularityError is thrown at load time if a class would be a superclass of itself. Changes to the class hierarchy that could result in such a circularity when newly compiled binaries are loaded with pre-existing binaries are not recommended for widely distributed classes.

Changing the direct superclass or the set of direct superinterfaces of a class type will not break compatibility with pre-existing binaries, provided that the total set of superclasses or superinterfaces, respectively, of the class type loses no members.

Changes to the set of superclasses of a class will not break compatibility with pre-existing binaries simply because of uses of class variables and class methods. This is because uses of class variables and class methods are resolved at compile time to symbolic references to the name of the class that declares them. Such uses therefore depend only on the continuing existence of the class declaring the variable or method, not on the shape of the class hierarchy.

If a change to the direct superclass or the set of direct superinterfaces results in any class or interface no longer being a superclass or superinterface, respectively, then link-time errors may result if pre-existing binaries are loaded with the binary of the modified class. Such changes are not recommended for widely distributed classes. The resulting errors are detected by the verifier of the Java Virtual Machine when an operation that previously compiled would violate the type system. For example, suppose that the following test program:

class Hyper { char h = 'h'; }
class Super extends Hyper { char s = 's'; }
class Test extends Super {
    public static void main(String[] args) {
        Hyper h = new Super();
        System.out.println(h.h);
    }
}

is compiled and executed, producing the output:

h

Suppose that a new version of class Super is then compiled:

class Super { char s = 's'; }

This version of class Super is not a subclass of Hyper. If we then run the existing binaries of Hyper and Test with the new version of Super, then a VerifyError is thrown at link time. The verifier objects because the result of new Super() cannot be assigned to a variable of type Hyper, because Super is not a subclass of Hyper.

It is instructive to consider what might happen without the verification step: the program might run and print:

s

This demonstrates that without the verifier the type system could be defeated by linking inconsistent binary files, even though each was produced by a correct Java compiler.

As a further example, here is an implementation of a cast from a reference type to int, which could be made to run in certain implementations of Java if they failed to perform the verification process. Assume an implementation that uses method dispatch tables and whose linker assigns offsets into those tables in a sequential and straightforward manner. Then suppose that the following Java code is compiled:

class Hyper { int zero(Object o) { return 0; } }
class Super extends Hyper { int peek(int i) { return i; }  }

class Test extends Super {
    public static void main(String[] args) throws Throwable {
        Super as = new Super();
        System.out.println(as);
        System.out.println(Integer.toHexString(as.zero(as)));
    }
}

The assumed implementation determines that the class Super has two methods: the first is method zero inherited from class Hyper, and the second is the method peek. Any subclass of Super would also have these same two methods in the first two entries of its method table. (Actually, all these methods would be preceded in the method tables by all the methods inherited from class Object but, to simplify the discussion, we ignore that here.) For the method invocation as.zero(as), the compiler specifies that the first method of the method table should be invoked; this is always correct if type safety is preserved.

If the compiled code is then executed, it prints something like:

Super@ee300858
0

which is the correct output. But if a new version of Super is compiled, which is the same except for the extends clause:

class Super { int peek(int i) { return i; }  }

then the first method in the method table for Super will now be peek, not zero. Using the new binary code for Super with the old binary code for Hyper and Test will cause the method invocation as.zero(as) to dispatch to the method peek in Super, rather than the method zero in Hyper. This is a type violation, of course; the argument is of type Super but the parameter is of type int. With a few plausible assumptions about internal data representations and the consequences of the type violation, execution of this incorrect program might produce the output:

Super@ee300848
ee300848

A poke method, capable of altering any location in memory, could be concocted in a similar manner. This is left as an exercise for the reader.

The lesson is that a implementation of Java that lacks a verifier or fails to use it will not maintain type safety and is, therefore, not a valid Java implementation.


13.4.5 Class Body and Member Declarations

No incompatibility with pre-existing binaries is caused by adding a class member that has the same name (for fields) or same name, signature, and return type (for methods) as a member of a superclass or subclass. References to the original field or method were resolved at compile time to a symbolic reference containing the name of the class in which they were declared. This makes compiled Java code more robust against changes than it might otherwise be. No error occurs even if the set of classes being linked would encounter a compile-time error. As an example, if the program:

class Hyper { String h = "Hyper"; }
class Super extends Hyper { }
class Test extends Super {
    public static void main(String[] args) {
        String s = new Test().h;
        System.out.println(s);
    }
}

is compiled and executed, it produces the output:

Hyper

Suppose that a new version of class Super is then compiled:

class Super extends Hyper { char h = 'h'; }

If the resulting binary is used with the existing binaries for Hyper and Test, then the output is still:

Hyper

even though compiling the source for these binaries:

class Hyper { String h = "Hyper"; }
class Super extends Hyper { char h = 'h'; }
class Test extends Super {
    public static void main(String[] args) {
        String s = new Test().h;
        System.out.println(s);
    }
}

would result in a compile-time error, because the h in the source code for main would now be construed as referring to the char field declared in Super, and a char value can't be assigned to a String.

Deleting a class member or constructor that is not declared private may cause a linkage error if the member or constructor is used by a pre-existing binary, even if the member was an instance method that was overriding a superclass method. This is because, during resolution, the linker looks only in the class that was identified at compile time. Thus, if the program:

class Hyper {
    void hello() { System.out.println("hello from Hyper"); }
}

class Super extends Hyper {
    void hello() { System.out.println("hello from Super"); }
}

class Test {
    public static void main(String[] args) {
        new Super().hello();
    }
}

is compiled and executed, it produces the output:

hello from Super

Suppose that a new version of class Super is produced:

class Super extends Hyper { }

If Super and Hyper are recompiled but not Test, then a NoSuchMethodError will result at link time, because the method hello is no longer declared in class Super.

To preserve binary compatibility, methods should not be deleted; instead, "forwarding methods" should be used. In our example, replacing the declaration of Super with:

class Super extends Hyper {
    void hello() { super.hello(); }
}

then recompiling Super and Hyper and executing these new binaries with the original binary for Test, produces the output:

hello from Hyper

as might have naively been expected from the previous example.

The super keyword can be used to access a method declared in a superclass, bypassing any methods declared in the current class. The expression:

super.Identifier

is resolved, at compile time, to a method M declared in a particular superclass S. The method M must still be declared in that class at run time or a linkage error will result. If the method M is an instance method, then the method MR invoked at run time is the method with the same signature as M that is a member of the direct superclass of the class containing the expression involving super. Thus, if the program:

class Hyper {
    void hello() { System.out.println("hello from Hyper"); }
}
class Super extends Hyper { }
class Test extends Super {

    public static void main(String[] args) {
        new Test().hello();
    }

    void hello() {
        super.hello();
    }
}

is compiled and executed, it produces the output:

hello from Hyper

Suppose that a new version of class Super is produced:

class Super extends Hyper {
    void hello() { System.out.println("hello from Super"); }
}

If Super and Hyper are recompiled but not Test, then running the new binaries with the existing binary of Test produces the output:

hello from Super

as you might expect. (A flaw in some early versions of Java caused them to print:

hello from Hyper

incorrectly.)


13.4.6 Access to Members and Constructors

Changing the declared access of a member or constructor to permit less access may break compatibility with pre-existing binaries, causing a linkage error to be thrown when these binaries are resolved. Less access is permitted if the access modifier is changed from default access to private access; from protected access to default or private access; or from public access to protected, default, or private access. Changing a member or constructor to permit less access is therefore not recommended for widely distributed classes.

Perhaps surprisingly, Java is defined so that changing a member or constructor to be more accessible does not cause a linkage error when a subclass (already) defines a method to have less access. So, for example, if the package points defines the class Point:

package points;

public class Point {
    public int x, y;
    protected void print() {
        System.out.println("(" + x + "," + y + ")");
    }
}

used by the Test program:

class Test extends points.Point {
    protected void print() { System.out.println("Test"); }
    public static void main(String[] args) {
        Test t = new Test();
        t.print();
    }
}

then these classes compile and Test executes to produce the output:

Test

If the method print in class Point is changed to be public, and then only the Point class is recompiled, and then executed with the previously existing binary for Test then no linkage error occurs, even though it is improper, at compile time, for a public method to be overridden by a protected method (as shown by the fact that the class Test could not be recompiled using this new Point class unless print were changed to be public.)

Allowing superclasses to change protected methods to be public without breaking binaries of preexisting subclasses helps make Java binaries less fragile. The alternative, where such a change would cause a linkage error, would create additional binary incompatibilities with no apparent benefit.


13.4.7 Field Declarations

Adding a field to a class will not break compatibility with any pre-existing binaries that are not recompiled, even in the case where a class could no longer be recompiled because a field access previously referenced a field of a superclass with an incompatible type. The previously compiled class with such a reference will continue to reference the field declared in a superclass. Thus compiling and executing the code:

class Hyper { String h = "hyper"; }
class Super extends Hyper { String s = "super"; }
class Test {
    public static void main(String[] args) {
        System.out.println(new Super().h);
    }
}

produces the output:

hyper

Changing Super to be defined as:

class Super extends Hyper {
    String s = "super";
    int h = 0;
}

recompiling Hyper and Super, and executing the resulting new binaries with the old binary of Test produces the output:

hyper

The field h of Hyper is output by the original binary of main no matter what type field h is declared in Super. While this may seem surprising at first, it serves to reduce the number of incompatibilities that occur at run time. (In an ideal world, all source files that needed recompilation would be recompiled whenever any one of them changed, eliminating such surprises. But such a mass recompilation is often impractical or impossible, especially in the Internet. And, as was previously noted, such recompilation would sometimes require further changes to the source code.)

Deleting a field from a class will break compatibility with any pre-existing binaries that reference this field, and a NoSuchFieldError will be thrown when such a reference from a pre-existing binary is linked. Only private fields may be safely deleted from a widely distributed class.


13.4.8 final Fields and Constants

If a field that was not final is changed to be final, then it can break compatibility with pre-existing binaries that attempt to assign new values to the field. For example, if the program:

class Super { static char s; }

class Test extends Super {
    public static void main(String[] args) {
        s = 'a';
        System.out.println(s);
    }
}

is compiled and executed, it produces the output:

a

Suppose that a new version of class Super is produced:

class Super { static char s; }

If Super is recompiled but not Test, then running the new binary with the existing binary of Test results in a IncompatibleClassChangeError. (In certain early implementations of Java this example would run without error, because of a flaw in the implementation.)

We call a field that is static, final, and initialized with a compile-time constant expression a primitive constant. Note that all fields in interfaces are implicitly static and final, and they are often, but not always, constants.

If a field is not a primitive constant, then deleting the keyword final or changing the value to which the field is initialized does not break compatibility with existing binaries.

If a field is a primitive constant, then deleting the keyword final or changing its value will not break compatibility with pre-existing binaries by causing them not to run, but they will not see any new value for the constant unless they are recompiled. If the example:

class Flags { final static boolean debug = true; }

class Test {
    public static void main(String[] args) {
        if (Flags.debug)
            System.out.println("debug is true");
    }
}

is compiled and executed, it produces the output:

debug is true

Suppose that a new version of class Flags is produced:

class Flags { final static boolean debug = false; }

If Flags is recompiled but not Test, then running the new binary with the existing binary of Test produces the output:

debug is true

because the value of debug was a compile-time primitive constant, and could have been used in compiling Test without making a reference to the class Flags.

This behavior would not change if Flags were changed to be an interface, as in the modified example:

interface Flags { boolean debug = true; }
class Test {
    public static void main(String[] args) {
        if (Flags.debug)
            System.out.println("debug is true");
    }
}

(One reason for requiring inlining of primitive constants is that Java switch statements require constants on each case, and no two such constant values may be the same. Java checks for duplicate constant values in a switch statement at compile time; the class file format does not do symbolic linkage of case values.)

The best way to avoid problems with "inconstant constants" in widely-distributed code is to declare as primitive constants only values which truly are unlikely ever to change. Many primitive constants in interfaces are small integer values replacing enumerated types, which Java does not support; these small values can be chosen arbitrarily, and should not need to be changed. Other than for true mathematical constants, we recommend that Java code make very sparing use of class variables that are declared static and final. If the read-only nature of final is required, a better choice is to declare a private static variable and a suitable accessor method to get its value. Thus we recommend:

private static int N;
public static int getN() { return N; }

rather than:

public static final int N = ...;

There is no problem with:

public static int N = ...;

if N need not be read-only. We also recommend, as a general rule, that only truly constant values be declared in interfaces. We note, but do not recommend, that if a field of primitive type of an interface may change, its value may be expressed idiomatically as in:

interface Flags {
    boolean debug = new Boolean(true).booleanValue();
}

insuring that this value is not a constant. Similar idioms exist for the other primitive types.

One other thing to note is that static final fields that have constant values (whether of primitive or String type) must never appear to have the default initial value for their type (§4.5.4). This means that all such fields appear to be initialized first during class initialization (§8.3.2.1, §9.3.1, §12.4.2).


13.4.9 static Fields

If a field that is not declared private was not declared static and is changed to be declared static, or vice versa, then a linkage time error, specifically an IncompatibleClassChangeError, will result if the field is used by a preexisting binary which expected a field of the other kind. Such changes are not recommended in code that has been widely distributed.


13.4.10 transient Fields

Adding or deleting a transient modifier of a field does not break compatibility with pre-existing binaries.


13.4.11 volatile Fields

If a field that is not declared private was not declared volatile and is changed to be declared volatile, or vice versa, then a linkage time error, specifically an IncompatibleClassChangeError, may result if the field is used by a preexisting binary that expected a field of the opposite volatility. Such changes are not recommended in code that has been widely distributed.


13.4.12 Method and Constructor Declarations

Adding a method or constructor declaration to a class will not break compatibility with any pre-existing binaries, even in the case where a type could no longer be recompiled because a method invocation previously referenced a method of a superclass with an incompatible type. The previously compiled class with such a reference will continue to reference the method declared in a superclass.

Deleting a method or constructor from a class will break compatibility with any pre-existing binary that referenced this method or constructor; a NoSuchMethodError will be thrown when such a reference from a pre-existing binary is linked. Only private methods or constructors may be safely deleted from a widely distributed class.

If the source code for a class contains no declared constructors, the Java compiler automatically supplies a constructor with no parameters. Adding one or more constructor declarations to the source code of such a class will prevent this default constructor from being supplied automatically, effectively deleting a constructor, unless one of the new constructors also has no parameters, thus replacing the default constructor. The automatically supplied constructor with no parameters is given the same access modifier as the class of its declaration, so any replacement should have as much or more access if compatibility with pre-existing binaries is to be preserved.


13.4.13 Method and Constructor Parameters

Changing the name of a formal parameter of a method or constructor does not impact pre-existing binaries. Changing the name of a method, the type of a formal parameter to a method or constructor, or adding a parameter to or deleting a parameter from a method or constructor declaration creates a method or constructor with a new signature, and has the combined effect of deleting the method or constructor with the old signature and adding a method or constructor with the new signature (see §13.4.12).


13.4.14 Method Result Type

Changing the result type of a method, replacing a result type with void, or replacing void with a result type has the combined effect of deleting the old method or constructor and adding a new method or constructor with the new result type or newly void result (see §13.4.12).


13.4.15 abstract Methods

Changing a method that is declared abstract to no longer be declared abstract does not break compatibility with pre-existing binaries.

Changing a method that is not declared abstract to be declared abstract will break compatibility with pre-existing binaries that previously invoked the method, causing an AbstractMethodError. If the example program:

class Super { void out() { System.out.println("Out"); } }

class Test extends Super {
    public static void main(String[] args) {
        Test t = new Test();
        System.out.println("Way ");
        t.out();
    }
}

is compiled and executed, it produces the output:

Way
Out

Suppose that a new version of class Super is produced:

abstract class Super {
    abstract void out();
}

If Super is recompiled but not Test, then running the new binary with the existing binary of Test results in a AbstractMethodError, because class Test has no implementation of the method out, and is therefore is (or should be) abstract. (An early version of Java incorrectly produced the output:

Way

before encountering an AbstractMethodError while invoking the method out, incorrectly allowing the class Test to be prepared even though it has an abstract method and is not declared abstract.)


13.4.16 final Methods

Changing an instance method that is not final to be final may break compatibility with existing binaries that depend on the ability to override the method. If the test program:

class Super { void out() { System.out.println("out"); } }
class Test extends Super {

    public static void main(String[] args) {
        Test t = new Test();
        t.out();
    }
    void out() { super.out(); }
}

is compiled and executed, it produces the output:

out

Suppose that a new version of class Super is produced:

class Super { final void out() { System.out.println("!"); } }

If Super is recompiled but not Test, then running the new binary with the existing binary of Test results in a VerifyError because the class Test improperly tries to override the instance method out.

Changing a class (static) method that is not final to be final does not break compatibility with existing binaries, because the class of the actual method to be invoked is resolved at compile time.

Removing the final modifier from a method does not break compatibility with pre-existing binaries.


13.4.17 native Methods

Adding or deleting a native modifier of a method does not break compatibility with pre-existing binaries.

The impact of changes to Java types on preexisting native methods that are not recompiled is beyond the scope of this specification and should be provided with the description of an implementation of Java. Implementations are encouraged, but not required, to implement native methods in a way that limits such impact.


13.4.18 static Methods

If a method that is not declared private was declared static (that is, a class method) and is changed to not be declared static (that is, to an instance method), or vice versa, then compatibility with pre-existing binaries may be broken, resulting in a linkage time error, namely an IncompatibleClassChangeError, if these methods are used by the pre-existing binaries. Such changes are not recommended in code that has been widely distributed.


13.4.19 synchronized Methods

Adding or deleting a synchronized modifier of a method does not break compatibility with existing binaries.


13.4.20 Method and Constructor Throws

Changes to the throws clause of methods or constructors do not break compatibility with existing binaries; these clauses are checked only at compile time.

We are considering whether a future version of the Java language should require more rigorous checking of throws clauses when classes are verified.


13.4.21 Method and Constructor Body

Changes to the body of a method or constructor do not break compatibility with pre-existing binaries.

We note that a compiler cannot inline expand a method at compile time unless, for example, either:

  • the method is private to its class
  • an entire package is guaranteed to be kept together and the method is accessible only within that package
  • a set of Java code is being compiled to a special binary format where the specified method is available only within a binary or set of binaries which are being kept together.

The keyword final on a method does not mean that the method can be safely inlined; it only means that the method cannot be overridden. Unless the compiler has extraordinary knowledge, it is still possible that a new version of that method will be provided at link time.

In general we suggest that Java implementations use late-bound (run-time) code generation and optimization.


13.4.22 Method and Constructor Overloading

Adding new methods that overload existing method names does not break compatibility with pre-existing binaries. The method signature to be used for each method invocation was determined when these existing binaries were compiled; therefore newly added methods will not be used, even if their signatures are both applicable and more specific than the method signature originally chosen.

While adding a new overloaded method or constructor may cause a compile-time error the next time a class or interface is compiled because there is no method or constructor that is most specific (§15.11.2.2), no such error occurs when a Java program is executed, because no overload resolution is done at execution time.

If the example program:

class Super {
    static void out(float f) { System.out.println("float"); }
}

class Test {
    public static void main(String[] args) {
        Super.out(2);
    }
}

is compiled and executed, it produces the output:

float

Suppose that a new version of class Super is produced:

class Super {
    static void out(float f) { System.out.println("float"); }
    static void out(int i) { System.out.println("int"); }
}

If Super is recompiled but not Test, then running the new binary with the existing binary of Test still produces the output:

float

However, if Test is then recompiled, using this new Super, the output is then:

int

as might have been naively expected in the previous case.


13.4.23 Method Overriding

If an instance method is added to a subclass and it overrides a method in a superclass, then the subclass method will be found by method invocations in pre-existing binaries, and these binaries are not impacted. If a class method is added to a class, then this method will not be found, because the invocation of a class method is resolved at compile time to use the fully qualified name of the class where the method is declared. Thus if the example:

class Hyper {
    void hello() { System.out.print("Hello, "); }
    static void world() { System.out.println("world!"); }
}
class Super extends Hyper { }

class Test {
    public static void main(String[] args) {
        Super s = new Super();
        s.hello();
        s.world();
    }
}

is compiled and executed, it produces the output:

Hello, world!

Suppose that a new version of class Super is produced:

class Super extends Hyper {
    void hello() { System.out.print("Goodbye, cruel "); }
    static void world() { System.out.println("earth!"); }
}

If Super is recompiled but not Hyper or Test, then running the new binary with the existing binaries for Hyper and Test will produce the output:

Goodbye, cruel world!

This example demonstrates that the invocation in:

s.world();

in the method main is resolved, at compile time, to a symbolic reference to the class containing the class method world, as though it had been written:

Hyper.world();

This is why the world method of Hyper rather than Super is invoked in this example. Of course, recompiling all the classes to produce new binaries will allow the output:

Goodbye, cruel earth!

to be produced.


13.4.24 Static Initializers

Adding, deleting, or changing a static initializer (§8.5) of a class does not impact pre-existing binaries.


13.5 Evolution of Interfaces

This section describes the impact of changes to the declaration of an interface and its members on pre-existing binaries.


13.5.1 public Interfaces

Changing an interface that is not declared public to be declared public does not break compatibility with pre-existing binaries.

If an interface that is declared public is changed to not be declared public, then an IllegalAccessError is thrown if a pre-existing binary is linked that needs but no longer has access to the interface type, so such a change is not recommended for widely distributed interfaces.


13.5.2 Superinterfaces

Changes to the interface hierarchy cause errors in the same way that changes to the class hierarchy do, as described in §13.4.4. In particular, changes that result in any previous superinterface of a class no longer being a superinterface can break compatibility with pre-existing binaries, resulting in a VerifyError.


13.5.3 The Interface Members

Adding a member to an interface does not break compatibility with pre-existing binaries.

Deleting a member from an interface may cause linkage errors in pre-existing binaries. If the example program:

interface I { void hello(); }
class Test implements I {

    public static void main(String[] args) {
        I anI = new Test();
        anI.hello();
    }
    public void hello() { System.out.println("hello"); }
}

is compiled and executed, it produces the output:

hello

Suppose that a new version of interface I is compiled:

interface I { }

If I is recompiled but not Test, then running the new binary with the existing binary for Test will result in a NoSuchMethodError. (In some early implementations of Java this program still executed; the fact that the method hello no longer exists in interface I was not correctly detected.)


13.5.4 Field Declarations

The considerations for changing field declarations in interfaces are the same as those for static final fields in classes, as described in §13.4.7 and §13.4.8.


13.5.5 Abstract Method Declarations

The considerations for changing abstract method declarations in interfaces are the same as those for abstract methods in classes, as described in §13.4.13, §13.4.14, §13.4.20, and §13.4.22.

Lo! keen-eyed, towering Science! . . .
Yet again, lo! the Soul—above all science . . .
For it, the partial to the permanent flowing,
For it, the Real to the Ideal tends.
For it, the mystic evolution . . .
—Walt Whitman, Song of the Universal (1874)


 14. Blocks and Statements

CHAPTER 14

Blocks and Statements

He was not merely a chip of the old block, but the old block itself.
—Edmund Burke, On Pitt's First Speech

The sequence of execution of a Java program is controlled by statements, which are executed for their effect and do not have values.

Some statements contain other statements as part of their structure; such other statements are substatements of the statement. We say that statement S immediately contains statement U if there is no statement T different from S and U such that S contains T and T contains U. In the same manner, some statements contain expressions (§15) as part of their structure.

The first section of this chapter discusses the distinction between normal and abrupt completion of statements (§14.1). Most of the remaining sections explain the various kinds of statements, describing in detail both their normal behavior and any special treatment of abrupt completion.

Blocks are explained first (§14.2), because they can appear in certain places where other kinds of statements are not allowed, and because one other kind of statement, a local variable declaration statement (§14.3), must be immediately contained within a block.

Next a grammatical maneuver is explained that sidesteps the familiar "dangling else" problem (§14.4).

Statements that will be familiar to C and C++ programmers are the empty (§14.5), labeled (§14.6), expression (§14.7), if (§14.8), switch (§14.9), while (§14.10), do (§14.11), for (§14.12), break (§14.13), continue (§14.14), and return (§14.15) statements.

Unlike C and C++, Java has no goto statement. However, the break and continue statements are extended in Java to allow them to mention statement labels.

The Java statements that are not in the C language are the throw (§14.16), synchronized (§14.17), and try (§14.18) statements.

The last section (§14.19) of this chapter addresses the requirement that every statement be reachable in a certain technical sense.


14.1 Normal and Abrupt Completion of Statements

Poirot's abrupt departure had intrigued us all greatly.
—Agatha Christie, The Mysterious Affair at Styles (1920), Chapter 12

Every statement has a normal mode of execution in which certain computational steps are carried out. The following sections describe the normal mode of execution for each kind of statement. If all the steps are carried out as described, with no indication of abrupt completion, the statement is said to complete normally. However, certain events may prevent a statement from completing normally:

  • The break (§14.13), continue (§14.14), and return (§14.15) statements cause a transfer of control that may prevent normal completion of statements that contain them.
  • Evaluation of certain Java expressions may throw exceptions from the Java Virtual Machine; these expressions are summarized in §15.5. An explicit throw (§14.16) statement also results in an exception. An exception causes a transfer of control that may prevent normal completion of statements.

If such an event occurs, then execution of one or more statements may be terminated before all steps of their normal mode of execution have completed; such statements are said to complete abruptly. An abrupt completion always has an associated reason, which is one of the following:

  • A break with no label
  • A break with a given label
  • A continue with no label
  • A continue with a given label
  • A return with no value
  • A return with a given value
  • A throw with a given value, including exceptions thrown by the Java Virtual Machine

The terms "complete normally" and "complete abruptly" also apply to the evaluation of expressions (§15.5). The only reason an expression can complete abruptly is that an exception is thrown, because of either a throw with a given value (§14.16) or a run-time exception or error (§11, §15.5).

If a statement evaluates an expression, abrupt completion of the expression always causes the immediate abrupt completion of the statement, with the same reason. All succeeding steps in the normal mode of execution are not performed.

Unless otherwise specified in this chapter, abrupt completion of a substatement causes the immediate abrupt completion of the statement itself, with the same reason, and all succeeding steps in the normal mode of execution of the statement are not performed.

Unless otherwise specified, a statement completes normally if all expressions it evaluates and all substatements it executes complete normally.


14.2 Blocks

A block is a sequence of statements and local variable declaration statements within braces.

Block:

    { BlockStatementsopt }

BlockStatements:

    BlockStatement

    BlockStatements BlockStatement

BlockStatement:

    LocalVariableDeclarationStatement

    Statement

A block is executed by executing each of the local variable declaration statements and other statements in order from first to last (left to right). If all of these block statements complete normally, then the block completes normally. If any of these block statements complete abruptly for any reason, then the block completes abruptly for the same reason.


14.3 Local Variable Declaration Statements

A local variable declaration statement declares one or more local variable names.

LocalVariableDeclarationStatement:

    LocalVariableDeclaration ;

LocalVariableDeclaration:

    Type VariableDeclarators

The following are repeated from §8.3 to make the presentation here clearer:

VariableDeclarators:

    VariableDeclarator

    VariableDeclarators , VariableDeclarator

VariableDeclarator:

    VariableDeclaratorId

    VariableDeclaratorId = VariableInitializer

VariableDeclaratorId:

    Identifier

    VariableDeclaratorId [ ]

VariableInitializer:

    Expression

    ArrayInitializer

Every local variable declaration statement is immediately contained by a block. Local variable declaration statements may be intermixed freely with other kinds of statements in the block.

A local variable declaration can also appear in the header of a for statement (§14.12). In this case it is executed in the same manner as if it were part of a local variable declaration statement.


14.3.1 Local Variable Declarators and Types

Each declarator in a local variable declaration declares one local variable, whose name is the Identifier that appears in the declarator.

The type of the variable is denoted by the Type that appears at the start of the local variable declaration, followed by any bracket pairs that follow the Identifier in the declarator. Thus, the local variable declaration:

int a, b[], c[][];

is equivalent to the series of declarations:

int a;
int[] b;
int[][] c;

Brackets are allowed in declarators as a nod to the tradition of C and C++. The general rule, however, also means that the local variable declaration:

float[][] f[][], g[][][], h[];	// Yechh!

is equivalent to the series of declarations:

float[][][][] f;
float[][][][][] g;
float[][][] h;

We do not recommend such "mixed notation" for array declarations.


14.3.2 Scope of Local Variable Declarations

The scope of a local variable declared in a block is the rest of the block, including its own initializer. The name of the local variable parameter may not be redeclared as a local variable or exception parameter within its scope, or a compile-time error occurs; that is, hiding the name of a local variable is not permitted.

A local variable cannot be referred to using a qualified name (§6.6), only a simple name.

The example:

class Test {
    static int x;
    public static void main(String[] args) {
        int x = x;
    }
}

causes a compile-time error because the initialization of x is within the scope of the declaration of x as a local variable, and the local x does not yet have a value and cannot be used.

The following program does compile:

class Test {
    static int x;
    public static void main(String[] args) {
        int x = (x=2)*2;
        System.out.println(x);
    }
}

because the local variable x is definitely assigned (§16) before it is used. It prints:

4

Here is another example:

class Test {
    public static void main(String[] args) {
        System.out.print("2+1=");
        int two = 2, three = two + 1;
        System.out.println(three);
    }
}

which compiles correctly and produces the output:

2+1=3

The initializer for three can correctly refer to the variable two declared in an earlier declarator, and the method invocation in the next line can correctly refer to the variable three declared earlier in the block.

The scope of a local variable declared in a for statement is the rest of the for statement, including its own initializer.

If a declaration of an identifier as a local variable appears within the scope of a parameter or local variable of the same name, a compile-time error occurs. Thus the following example does not compile:

class Test {
    public static void main(String[] args) {
        int i;
        for (int i = 0; i < 10; i++)
            System.out.println(i);
    }
}

This restriction helps to detect some otherwise very obscure bugs. (A similar restriction on hiding of members by local variables was judged impractical, because the addition of a member in a superclass could cause subclasses to have to rename local variables.)

On the other hand, local variables with the same name may be declared in two separate blocks or for statements neither of which contains the other. Thus:

class Test {
    public static void main(String[] args) {
        for (int i = 0; i < 10; i++)
            System.out.print(i + " ");
        for (int i = 10; i > 0; i--)
            System.out.print(i + " ");
        System.out.println();
    }
}

compiles without error and, when executed, produces the output:

0 1 2 3 4 5 6 7 8 9 10 9 8 7 6 5 4 3 2 1


14.3.3 Hiding of Names by Local Variables

If a name declared as a local variable is already declared as a field or type name, then that outer declaration is hidden throughout the scope of the local variable. The field or type name can almost always (§6.8) still be accessed using an appropriately qualified name. For example, the keyword this can be used to access a hidden field x, using the form this.x. Indeed, this idiom typically appears in constructors (§8.6):

class Pair {
    Object first, second;
    public Pair(Object first, Object second) {
        this.first = first;
        this.second = second;
    }
}

In this example, the constructor takes parameters having the same names as the fields to be initialized. This is simpler than having to invent different names for the parameters and is not too confusing in this stylized context. In general, however, it is considered poor style to have local variables with the same names as fields.


14.3.4 Execution of Local Variable Declarations

A local variable declaration statement is an executable statement. Every time it is executed, the declarators are processed in order from left to right. If a declarator has an initialization expression, the expression is evaluated and its value is assigned to the variable. If a declarator does not have an initialization expression, then a Java compiler must prove, using exactly the algorithm given in §16, that every reference to the variable is necessarily preceded by execution of an assignment to the variable. If this is not the case, then a compile-time error occurs.

Each initialization (except the first) is executed only if the evaluation of the preceding initialization expression completes normally. Execution of the local variable declaration completes normally only if evaluation of the last initialization expression completes normally; if the local variable declaration contains no initialization expressions, then executing it always completes normally.


14.4 Statements

There are many kinds of statements in the Java language. Most correspond to statements in the C and C++ languages, but some are unique to Java.

As in C and C++, the Java if statement suffers from the so-called "dangling else problem," illustrated by this misleadingly formatted example:

if (door.isOpen())
    if (resident.isVisible())
        resident.greet("Hello!");
else door.bell.ring();								// A "dangling else"

The problem is that both the outer if statement and the inner if statement might conceivably own the else clause. In this example, one might surmise that the programmer intended the else clause to belong to the outer if statement. The Java language, like C and C++ and many languages before them, arbitrarily decree that an else clause belongs to the innermost if to which it might possibly belong. This rule is captured by the following grammar:

Statement:

    StatementWithoutTrailingSubstatement

    LabeledStatement

    IfThenStatement

    IfThenElseStatement

    WhileStatement

    ForStatement

StatementNoShortIf:

    StatementWithoutTrailingSubstatement

    LabeledStatementNoShortIf

    IfThenElseStatementNoShortIf

    WhileStatementNoShortIf

    ForStatementNoShortIf

StatementWithoutTrailingSubstatement:

    Block

    EmptyStatement

    ExpressionStatement

    SwitchStatement

    DoStatement

    BreakStatement

    ContinueStatement

    ReturnStatement

    SynchronizedStatement

    ThrowStatement

    TryStatement

The following are repeated from §14.8 to make the presentation here clearer:

IfThenStatement:

    if ( Expression ) Statement

IfThenElseStatement:

    if ( Expression ) StatementNoShortIf else Statement

IfThenElseStatementNoShortIf:

    if ( Expression ) StatementNoShortIf else StatementNoShortIf

Statements are thus grammatically divided into two categories: those that might end in an if statement that has no else clause (a "short if statement") and those that definitely do not. Only statements that definitely do not end in a short if statement may appear as an immediate substatement before the keyword else in an if statement that does have an else clause. This simple rule prevents the "dangling else" problem. The execution behavior of a statement with the "no short if" restriction is identical to the execution behavior of the same kind of statement without the "no short if" restriction; the distinction is drawn purely to resolve the syntactic difficulty.


14.5 The Empty Statement

An empty statement does nothing.

EmptyStatement:

    ;

Execution of an empty statement always completes normally.


14.6 Labeled Statements

Statements may have label prefixes.

LabeledStatement:

    Identifier : Statement

LabeledStatementNoShortIf:

    Identifier : StatementNoShortIf

The Identifier is declared to be the label of the immediately contained Statement.

Unlike C and C++, the Java language has no goto statement; identifier statement labels are used with break (§14.13) or continue (§14.14) statements appearing anywhere within the labeled statement.

A statement labeled by an identifier must not appear anywhere within another statement labeled by the same identifier, or a compile-time error will occur. Two statements can be labeled by the same identifier only if neither statement contains the other.

There is no restriction against using the same identifier as a label and as the name of a package, class, interface, method, field, parameter, or local variable. Use of an identifier to label a statement does not hide a package, class, interface, method, field, parameter, or local variable with the same name. Use of an identifier as a local variable or as the parameter of an exception handler (§14.18) does not hide a statement label with the same name.

A labeled statement is executed by executing the immediately contained Statement. If the statement is labeled by an Identifier and the contained Statement completes abruptly because of a break with the same Identifier, then the labeled statement completes normally. In all other cases of abrupt completion of the Statement, the labeled statement completes abruptly for the same reason.


14.7 Expression Statements

Certain kinds of expressions may be used as statements by following them with semicolons:

ExpressionStatement:

    StatementExpression ;

StatementExpression:

    Assignment

    PreIncrementExpression

    PreDecrementExpression

    PostIncrementExpression

    PostDecrementExpression

    MethodInvocation

    ClassInstanceCreationExpression

An expression statement is executed by evaluating the expression; if the expression has a value, the value is discarded. Execution of the expression statement completes normally if and only if evaluation of the expression completes normally.

Unlike C and C++, the Java language allows only certain forms of expressions to be used as expression statements. Note that Java does not allow a "cast to void"-void is not a type in Java-so the traditional C trick of writing an expression statement such as:

(void) ... ;		// This idiom belongs to C, not to Java!

does not work in Java. On the other hand, Java allows all the most useful kinds of expressions in expressions statements, and Java does not require a method invocation used as an expression statement to invoke a void method, so such a trick is almost never needed. If a trick is needed, either an assignment statement (§15.25) or a local variable declaration statement (§14.3) can be used instead.


14.8 The if Statement

The if statement allows conditional execution of a statement or a conditional choice of two statements, executing one or the other but not both.

IfThenStatement:

    if ( Expression ) Statement

IfThenElseStatement:

    if ( Expression ) StatementNoShortIf else Statement

IfThenElseStatementNoShortIf:

    if ( Expression ) StatementNoShortIf else StatementNoShortIf

The Expression must have type boolean, or a compile-time error occurs.


14.8.1 The if-then Statement

I took an early opportunity of testing that statement . . .
--Agatha Christie, The Mysterious Affair at Styles (1920), Chapter 12

An if-then statement is executed by first evaluating the Expression. If evaluation of the Expression completes abruptly for some reason, the if-then statement completes abruptly for the same reason. Otherwise, execution continues by making a choice based on the resulting value:

  • If the value is true, then the contained Statement is executed; the if-then statement completes normally only if execution of the Statement completes normally.
  • If the value is false, no further action is taken and the if-then statement completes normally.


14.8.2 The if-then-else Statement

An if-then-else statement is executed by first evaluating the Expression. If evaluation of the Expression completes abruptly for some reason, then the if- then-else statement completes abruptly for the same reason. Otherwise, execution continues by making a choice based on the resulting value:

  • If the value is true, then the first contained Statement (the one before the else keyword) is executed; the if-then-else statement completes normally only if execution of that statement completes normally.
  • If the value is false, then the second contained Statement (the one after the else keyword) is executed; the if-then-else statement completes normally only if execution of that statement completes normally.


14.9 The switch Statement

The switch statement transfers control to one of several statements depending on the value of an expression.

SwitchStatement:

    switch ( Expression ) SwitchBlock

SwitchBlock:

    { SwitchBlockStatementGroupsopt SwitchLabelsopt }

SwitchBlockStatementGroups:

    SwitchBlockStatementGroup

    SwitchBlockStatementGroups SwitchBlockStatementGroup

SwitchBlockStatementGroup:

    SwitchLabels BlockStatements

SwitchLabels:

    SwitchLabel

    SwitchLabels SwitchLabel

SwitchLabel:

    case ConstantExpression :

    default :

The type of the Expression must be char, byte, short, or int, or a compile-time error occurs.

The body of a switch statement must be a block. Any statement immediately contained by the block may be labeled with one or more case or default labels. These labels are said to be associated with the switch statement, as are the values of the constant expressions (§15.27) in the case labels.

All of the following must be true, or a compile-time error will result:

  • Every case constant expression associated with a switch statement must be assignable (§5.2) to the type of the switch Expression.
  • No two of the case constant expressions associated with a switch statement may have the same value.
  • At most one default label may be associated with the same switch statement.

In C and C++ the body of a switch statement can be a statement and statements with case labels do not have to be immediately contained by that statement. Consider the simple loop:

for (i = 0; i < n; ++i) foo();

where n is known to be positive. A trick known as Duff's device can be used in C or C++ to unroll the loop, but this is not valid Java code:

int q = (n+7)/8;
switch (n%8) {
case 0:			do {		foo(); // Great C hack, Tom,
case 7:					foo(); // but it's not valid in Java.
case 6:					foo();
case 5:					foo();
case 4:					foo();
case 3:					foo();
case 2:					foo();
case 1:					foo();
            } while (--q >= 0);
}

Fortunately, this trick does not seem to be widely known or used. Moreover, it is less needed nowadays; this sort of code transformation is properly in the province of state-of-the-art optimizing compilers.

When the switch statement is executed, first the Expression is evaluated. If evaluation of the Expression completes abruptly for some reason, the switch statement completes abruptly for the same reason. Otherwise, execution continues by comparing the value of the Expression with each case constant. Then there is a choice:

  • If one of the case constants is equal to the value of the expression, then we say that the case matches, and all statements after the matching case label in the switch block, if any, are executed in sequence. If all these statements complete normally, or if there are no statements after the matching case label, then the entire switch statement completes normally.
  • If no case matches but there is a default label, then all statements after the matching default label in the switch block, if any, are executed in sequence. If all these statements complete normally, or if there are no statements after the default label, then the entire switch statement completes normally.
  • If no case matches and there is no default label, then no further action is taken and the switch statement completes normally.

If any statement immediately contained by the Block body of the switch statement completes abruptly, it is handled as follows:

  • If execution of the Statement completes abruptly because of a break with no label, no further action is taken and the switch statement completes normally.
  • If execution of the Statement completes abruptly for any other reason, the switch statement completes abruptly for the same reason. The case of abrupt completion because of a break with a label is handled by the general rule for labeled statements (§14.6).

As in C and C++, execution of statements in a switch block "falls through labels" in Java. For example, the program:

class Toomany {

    static void howMany(int k) {
        switch (k) {
        case 1:			System.out.print("one ");
        case 2:			System.out.print("too ");
        case 3:			System.out.println("many");
        }
    }

    public static void main(String[] args) {
        howMany(3);
        howMany(2);
        howMany(1);
    }

}

contains a switch block in which the code for each case falls through into the code for the next case. As a result, the program prints:

many
too many
one too many

If code is not to fall through case to case in this manner, then break statements should be used, as in this example:

class Twomany {

    static void howMany(int k) {
        switch (k) {
        case 1:			System.out.println("one");
                    break; // exit the switch
        case 2:			System.out.println("two");
                    break; // exit the switch
        case 3:			System.out.println("many");
                    break; // not needed, but good style
        }
    }

    public static void main(String[] args) {
        howMany(1);
        howMany(2);
        howMany(3);
    }

}

This program prints:

one
two
many


14.10 The while Statement

The while statement executes an Expression and a Statement repeatedly until the value of the Expression is false.

WhileStatement:

    while ( Expression ) Statement

WhileStatementNoShortIf:

    while ( Expression ) StatementNoShortIf

The Expression must have type boolean, or a compile-time error occurs.

A while statement is executed by first evaluating the Expression. If evaluation of the Expression completes abruptly for some reason, the while statement completes abruptly for the same reason. Otherwise, execution continues by making a choice based on the resulting value:

  • If the value is true, then the contained Statement is executed. Then there is a choice:
    • If execution of the Statement completes normally, then the entire while statement is executed again, beginning by re-evaluating the Expression.
    • If execution of the Statement completes abruptly, see §14.10.1 below.
  • If the value of the Expression is false, no further action is taken and the while statement completes normally.

If the value of the Expression is false the first time it is evaluated, then the Statement is not executed.


14.10.1 Abrupt Completion

Abrupt completion of the contained Statement is handled in the following manner:

  • If execution of the Statement completes abruptly because of a break with no label, no further action is taken and the while statement completes normally.
    • If execution of the Statement completes abruptly because of a continue with no label, then the entire while statement is executed again.
    • If execution of the Statement completes abruptly because of a continue with label L, then there is a choice:
      • If the while statement has label L, then the entire while statement is executed again.
      • If the while statement does not have label L, the while statement completes abruptly because of a continue with label L.
    • If execution of the Statement completes abruptly for any other reason, the while statement completes abruptly for the same reason. Note that the case of abrupt completion because of a break with a label is handled by the general rule for labeled statements (§14.6).


14.11 The do Statement

The do statement executes a Statement and an Expression repeatedly until the value of the Expression is false.

DoStatement:

    do Statement while ( Expression ) ;

The Expression must have type boolean, or a compile-time error occurs.

A do statement is executed by first executing the Statement. Then there is a choice:

  • If execution of the Statement completes normally, then the Expression is evaluated. If evaluation of the Expression completes abruptly for some reason, the do statement completes abruptly for the same reason. Otherwise, there is a choice based on the resulting value:
    • If the value is true, then the entire do statement is executed again.
    • If the value is false, no further action is taken and the do statement completes normally.
  • If execution of the Statement completes abruptly, see §14.11.1 below.

Executing a do statement always executes the contained Statement at least once.


14.11.1 Abrupt Completion

Abrupt completion of the contained Statement is handled in the following manner:

  • If execution of the Statement completes abruptly because of a break with no label, then no further action is taken and the do statement completes normally.
  • If execution of the Statement completes abruptly because of a continue with no label, then the Expression is evaluated. Then there is a choice based on the resulting value:
    • If the value is true, then the entire do statement is executed again.
    • If the value is false, no further action is taken and the do statement completes normally.
  • If execution of the Statement completes abruptly because of a continue with label L, then there is a choice:
    • If the do statement has label L, then the Expression is evaluated. Then there is a choice:
      • If the value of the Expression is true, then the entire do statement is executed again.
      • If the value of the Expression is false, no further action is taken and the do statement completes normally.
    • If the do statement does not have label L, the do statement completes abruptly because of a continue with label L.
  • If execution of the Statement completes abruptly for any other reason, the do statement completes abruptly for the same reason. The case of abrupt completion because of a break with a label is handled by the general rule (§14.6).


14.11.2 Example

The following code is one possible implementation of the toHexString method (§20.7.14) of class Integer:

public static String toHexString(int i) {
    StringBuffer buf = new StringBuffer(8);
    do {
        buf.append(Character.forDigit(i & 0xF, 16));
        i >>>= 4;
    } while (i != 0);
    return buf.reverse().toString();
}

Because at least one digit must be generated, the do statement is an appropriate control structure.


14.12 The for Statement

The for statement executes some initialization code, then executes an Expression, a Statement, and some update code repeatedly until the value of the Expression is false.

ForStatement:

    for ( ForInitopt ; Expressionopt ; ForUpdateopt )

        Statement

ForStatementNoShortIf:

    for ( ForInitopt ; Expressionopt ; ForUpdateopt )

        StatementNoShortIf

ForInit:

    StatementExpressionList

    LocalVariableDeclaration

ForUpdate:

    StatementExpressionList

StatementExpressionList:

    StatementExpression

    StatementExpressionList , StatementExpression

The Expression must have type boolean, or a compile-time error occurs.


14.12.1 Initialization

A for statement is executed by first executing the ForInit code:

  • If the ForInit code is a list of statement expressions (§14.7), the expressions are evaluated in sequence from left to right; their values, if any, are discarded. If evaluation of any expression completes abruptly for some reason, the for statement completes abruptly for the same reason; any ForInit statement expressions to the right of the one that completed abruptly are not evaluated.
  • If the ForInit code is a local variable declaration, it is executed as if it were a local variable declaration statement (§14.3) appearing in a block. In this case, the scope of a declared local variable is its own initializer and any further declarators in the ForInit part, plus the Expression, ForUpdate, and contained Statement of the for statement. If execution of the local variable declaration completes abruptly for any reason, the for statement completes abruptly for the same reason.
  • If the ForInit part is not present, no action is taken.


14.12.2 Iteration

Next, a for iteration step is performed, as follows:

  • If the Expression is present, it is evaluated, and if evaluation of the Expression completes abruptly, the for statement completes abruptly for the same reason. Otherwise, there is then a choice based on the presence or absence of the Expression and the resulting value if the Expression is present:
    • If the Expression is not present, or it is present and the value resulting from its evaluation is true, then the contained Statement is executed. Then there is a choice:
      • If execution of the Statement completes normally, then the following two steps are performed in sequence:
        • First, if the ForUpdate part is present, the expressions are evaluated in sequence from left to right; their values, if any, are discarded. If evaluation of any expression completes abruptly for some reason, the for statement completes abruptly for the same reason; any ForUpdate statement expressions to the right of the one that completed abruptly are not evaluated. If the ForUpdate part is not present, no action is taken.
        • Second, another for iteration step is performed.
      • If execution of the Statement completes abruptly, see §14.12.3 below.
    • If the Expression is present and the value resulting from its evaluation is false, no further action is taken and the for statement completes normally.

If the value of the Expression is false the first time it is evaluated, then the Statement is not executed.

If the Expression is not present, then the only way a for statement can complete normally is by use of a break statement.


14.12.3 Abrupt Completion

Abrupt completion of the contained Statement is handled in the following manner:

  • If execution of the Statement completes abruptly because of a break with no label, no further action is taken and the for statement completes normally.
  • If execution of the Statement completes abruptly because of a continue with no label, then the following two steps are performed in sequence:
    • First, if the ForUpdate part is present, the expressions are evaluated in sequence from left to right; their values, if any, are discarded. If the ForUpdate part is not present, no action is taken.
    • Second, another for iteration step is performed.
  • If execution of the Statement completes abruptly because of a continue with label L, then there is a choice:
    • If the for statement has label L, then the following two steps are performed in sequence:
      • First, if the ForUpdate part is present, the expressions are evaluated in sequence from left to right; their values, if any, are discarded. If the ForUpdate is not present, no action is taken.
      • Second, another for iteration step is performed.
    • If the for statement does not have label L, the for statement completes abruptly because of a continue with label L.
  • If execution of the Statement completes abruptly for any other reason, the for statement completes abruptly for the same reason. Note that the case of abrupt completion because of a break with a label is handled by the general rule for labeled statements (§14.6).


14.13 The break Statement

A break statement transfers control out of an enclosing statement.

BreakStatement:

    break Identifieropt ;

A break statement with no label attempts to transfer control to the innermost enclosing switch, while, do, or for statement; this statement, which is called the break target, then immediately completes normally. To be precise, a break statement with no label always completes abruptly, the reason being a break with no label. If no switch, while, do, or for statement encloses the break statement, a compile-time error occurs.

A break statement with label Identifier attempts to transfer control to the enclosing labeled statement (§14.6) that has the same Identifier as its label; this statement, which is called the break target, then immediately completes normally. In this case, the break target need not be a while, do, for, or switch statement. To be precise, a break statement with label Identifier always completes abruptly, the reason being a break with label Identifier. If no labeled statement with Identifier as its label encloses the break statement, a compile-time error occurs.

It can be seen, then, that a break statement always completes abruptly.

The preceding descriptions say "attempts to transfer control" rather than just "transfers control" because if there are any try statements (§14.18) within the break target whose try blocks contain the break statement, then any finally clauses of those try statements are executed, in order, innermost to outermost, before control is transferred to the break target. Abrupt completion of a finally clause can disrupt the transfer of control initiated by a break statement.

In the following example, a mathematical graph is represented by an array of arrays. A graph consists of a set of nodes and a set of edges; each edge is an arrow that points from some node to some other node, or from a node to itself. In this example it is assumed that there are no redundant edges; that is, for any two nodes P and Q, where Q may be the same as P, there is at most one edge from P to Q. Nodes are represented by integers, and there is an edge from node i to node edges[i][j] for every i and j for which the array reference edges[i][j] does not throw an IndexOutOfBoundsException.

The task of the method loseEdges, given integers i and j, is to construct a new graph by copying a given graph but omitting the edge from node i to node j, if any, and the edge from node j to node i, if any:

class Graph {
    int edges[][];
    public Graph(int[][] edges) { this.edges = edges; }

    public Graph loseEdges(int i, int j) {
        int n = edges.length;
        int[][] newedges = new int[n][];
        for (int k = 0; k < n; ++k) {

            edgelist: {
                int z;

                search: {
                    if (k == i) {
                        for (z = 0; z < edges[k].length; ++z)
                            if (edges[k][z] == j)
                                break search;
                    } else if (k == j) {
                        for (z = 0; z < edges[k].length; ++z)
                            if (edges[k][z] == i)
                                break search;
                    }
                    // No edge to be deleted; share this list.
                    newedges[k] = edges[k];
                    break edgelist;
                }//search
                // Copy the list, omitting the edge at position z.
                int m = edges[k].length - 1;
                int ne[] = new int[m];
                System.arraycopy(edges[k], 0, ne, 0, z);
                System.arraycopy(edges[k], z+1, ne, z, m-z);
                newedges[k] = ne;
            }//edgelist
        }
        return new Graph(newedges);
    }
}

Note the use of two statement labels, edgelist and search, and the use of break statements. This allows the code that copies a list, omitting one edge, to be shared between two separate tests, the test for an edge from node i to node j, and the test for an edge from node j to node i.


14.14 The continue Statement

A continue statement may occur only in a while, do, or for statement; statements of these three kinds are called iteration statements. Control passes to the loop-continuation point of an iteration statement.

ContinueStatement:

    continue Identifieropt ;

A continue statement with no label attempts to transfer control to the innermost enclosing while, do, or for statement; this statement, which is called the continue target, then immediately ends the current iteration and begins a new one. To be precise, such a continue statement always completes abruptly, the reason being a continue with no label. If no while, do, or for statement encloses the continue statement, a compile-time error occurs.

A continue statement with label Identifier attempts to transfer control to the enclosing labeled statement (§14.6) that has the same Identifier as its label; that statement, which is called the continue target, then immediately ends the current iteration and begins a new one. The continue target must be a while, do, or for statement or a compile-time error occurs. More precisely, a continue statement with label Identifier always completes abruptly, the reason being a continue with label Identifier. If no labeled statement with Identifier as its label contains the continue statement, a compile-time error occurs.

It can be seen, then, that a continue statement always completes abruptly.

See the descriptions of the while statement (§14.10), do statement (§14.11), and for statement (§14.12) for a discussion of the handling of abrupt termination because of continue.

The preceding descriptions say "attempts to transfer control" rather than just "transfers control" because if there are any try statements (§14.18) within the continue target whose try blocks contain the continue statement, then any finally clauses of those try statements are executed, in order, innermost to outermost, before control is transferred to the continue target. Abrupt completion of a finally clause can disrupt the transfer of control initiated by a continue statement.

In the Graph example in the preceding section, one of the break statements is used to finish execution of the entire body of the outermost for loop. This break can be replaced by a continue if the for loop itself is labeled:

class Graph {
    . . .
    public Graph loseEdges(int i, int j) {
        int n = edges.length;
        int[][] newedges = new int[n][];

        edgelists: for (int k = 0; k < n; ++k) {
            int z;

            search: {
                if (k == i) {
                    . . .
                } else if (k == j) {
                    . . .
                }
                newedges[k] = edges[k];
                continue edgelists;
            }//search
            . . .
        }//edgelists
        return new Graph(newedges);
    }
}

Which to use, if either, is largely a matter of programming style.


14.15 The return Statement

A return statement returns control to the invoker of a method (§8.4, §15.11) or constructor (§8.6, §15.8).

ReturnStatement:

    return Expressionopt ;

A return statement with no Expression must be contained in the body of a method that is declared, using the keyword void, not to return any value (§8.4), or in the body of a constructor (§8.6). A compile-time error occurs if a return statement appears within a static initializer (§8.5). A return statement with no Expression attempts to transfer control to the invoker of the method or constructor that contains it. To be precise, a return statement with no Expression always completes abruptly, the reason being a return with no value.

A return statement with an Expression must be contained in a method declaration that is declared to return a value (§8.4) or a compile-time error occurs. The Expression must denote a variable or value of some type T, or a compile-time error occurs. The type T must be assignable (§5.2) to the declared result type of the method, or a compile-time error occurs.

A return statement with an Expression attempts to transfer control to the invoker of the method that contains it; the value of the Expression becomes the value of the method invocation. More precisely, execution of such a return statement first evaluates the Expression. If the evaluation of the Expression completes abruptly for some reason, then the return statement completes abruptly for that reason. If evaluation of the Expression completes normally, producing a value V, then the return statement completes abruptly, the reason being a return with value V.

It can be seen, then, that a return statement always completes abruptly.

The preceding descriptions say "attempts to transfer control" rather than just "transfers control" because if there are any try statements (§14.18) within the method or constructor whose try blocks contain the return statement, then any finally clauses of those try statements will be executed, in order, innermost to outermost, before control is transferred to the invoker of the method or constructor. Abrupt completion of a finally clause can disrupt the transfer of control initiated by a return statement.


14.16 The throw Statement

A throw statement causes an exception (§11) to be thrown. The result is an immediate transfer of control (§11.3) that may exit multiple statements and multiple constructor, static and field initializer evaluations, and method invocations until a try statement (§14.18) is found that catches the thrown value. If no such try statement is found, then execution of the thread (§17, §20.20) that executed the throw is terminated (§11.3) after invocation of the UncaughtException method (§20.21.31) for the thread group to which the thread belongs.

ThrowStatement:

    throw Expression ;

The Expression in a throw statement must denote a variable or value of a reference type which is assignable (§5.2) to the type Throwable, or a compile-time error occurs. Moreover, at least one of the following three conditions must be true, or a compile-time error occurs:

  • The exception is not a checked exception (§11.2)-specifically, one of the following situations is true:
    • The type of the Expression is the class RuntimeException or a subclass of RuntimeException.
    • The type of the Expression is the class Error or a subclass of Error.
  • The throw statement is contained in the try block of a try statement (§14.18) and the type of the Expression is assignable (§5.2) to the type of the parameter of at least one catch clause of the try statement. (In this case we say the thrown value is caught by the try statement.)
  • The throw statement is contained in a method or constructor declaration and the type of the Expression is assignable (§5.2) to at least one type listed in the throws clause (§8.4.4, §8.6.4) of the declaration.

A throw statement first evaluates the Expression. If the evaluation of the Expression completes abruptly for some reason, then the throw completes abruptly for that reason. If evaluation of the Expression completes normally, producing a value V, then the throw statement completes abruptly, the reason being a throw with value V.

It can be seen, then, that a throw statement always completes abruptly.

If there are any enclosing try statements (§14.18) whose try blocks contain the throw statement, then any finally clauses of those try statements are executed as control is transferred outward, until the thrown value is caught. Note that abrupt completion of a finally clause can disrupt the transfer of control initiated by a throw statement.

If a throw statement is contained in a method declaration, but its value is not caught by some try statement that contains it, then the invocation of the method completes abruptly because of the throw.

If a throw statement is contained in a constructor declaration, but its value is not caught by some try statement that contains it, then the class instance creation expression (or the method invocation of method newInstance of class Class) that invoked the constructor will complete abruptly because of the throw.

If a throw statement is contained in a static initializer (§8.5), then a compile-time check ensures that either its value is always an unchecked exception or its value is always caught by some try statement that contains it. If, despite this check, the value is not caught by some try statement that contains the throw statement, then the value is rethrown if it is an instance of class Error or one of its subclasses; otherwise, it is wrapped in an ExceptionInInitializerError object, which is then thrown (§12.4.2).

By convention, user-declared throwable types should usually be declared to be subclasses of class Exception, which is a subclass of class Throwable (§11.5, §20.22).


14.17 The synchronized Statement

A synchronized statement acquires a mutual-exclusion lock (§17.13) on behalf of the executing thread, executes a block, then releases the lock. While the executing thread owns the lock, no other thread may acquire the lock.

SynchronizedStatement:

    synchronized ( Expression ) Block

The type of Expression must be a reference type, or a compile-time error occurs.

A synchronized statement is executed by first evaluating the Expression.

If evaluation of the Expression completes abruptly for some reason, then the synchronized statement completes abruptly for the same reason.

Otherwise, if the value of the Expression is null, a NullPointerException is thrown.

Otherwise, let the non-null value of the Expression be V. The executing thread locks the lock associated with V. Then the Block is executed. If execution of the Block completes normally, then the lock is unlocked and the synchronized statement completes normally. If execution of the Block completes abruptly for any reason, then the lock is unlocked and the synchronized statement then completes abruptly for the same reason.

Acquiring the lock associated with an object does not of itself prevent other threads from accessing fields of the object or invoking unsynchronized methods on the object. Other threads can also use synchronized methods or the synchronized statement in a conventional manner to achieve mutual exclusion.

The locks acquired by synchronized statements are the same as the locks that are acquired implicitly by synchronized methods; see §8.4.3.5. A single thread may hold a lock more than once. The example:

class Test {
    public static void main(String[] args) {
        Test t = new Test();
        synchronized(t) {
            synchronized(t) {
                System.out.println("made it!");
            }
        }
    }
}

prints:

made it!

This example would deadlock if a single thread were not permitted to lock a lock more than once.


14.18 The try statement

These are the times that try men's souls.
—Thomas Paine, The American Crisis (1780)

. . . and they all fell to playing the game of catch as catch can,
till the gunpowder ran out at the heels of their boots.
—Samuel Foote

A try statement executes a block. If a value is thrown and the try statement has one or more catch clauses that can catch it, then control will be transferred to the first such catch clause. If the try statement has a finally clause, then another block of code is executed, no matter whether the try block completes normally or abruptly, and no matter whether a catch clause is first given control.

TryStatement:

    try Block Catches

    try Block Catchesopt Finally

Catches:

    CatchClause

    Catches CatchClause

CatchClause:

    catch ( FormalParameter ) Block

Finally:

    finally Block

The following is repeated from §8.4.1 to make the presentation here clearer:

FormalParameter:

    Type VariableDeclaratorId

The following is repeated from §8.3 to make the presentation here clearer:

VariableDeclaratorId:

    Identifier

    VariableDeclaratorId [ ]

The Block immediately after the keyword try is called the try block of the try statement. The Block immediately after the keyword finally is called the finally block of the try statement.

A try statement may have catch clauses (also called exception handlers). A catch clause must have exactly one parameter (which is called an exception parameter); the declared type of the exception parameter must be the class Throwable or a subclass of Throwable, or a compile-time error occurs. The scope of the parameter variable is the Block of the catch clause. An exception parameter must not have the same name as a local variable or parameter in whose scope it is declared, or a compile-time error occurs.

The scope of the name of an exception parameter is the Block of the catch clause. The name of the parameter may not be redeclared as a local variable or exception parameter within the Block of the catch clause; that is, hiding the name of an exception parameter is not permitted.

Exception parameters cannot be referred to using qualified names (§6.6), only by simple names.

Exception handlers are considered in left-to-right order: the earliest possible catch clause accepts the exception, receiving as its actual argument the thrown exception object.

A finally clause ensures that the finally block is executed after the try block and any catch block that might be executed, no matter how control leaves the try block or catch block.

Handling of the finally block is rather complex, so the two cases of a try statement with and without a finally block are described separately.


14.18.1 Execution of try-catch

Our supreme task is the resumption of our onward, normal way.
—Warren G. Harding, Inaugural Address (1921)

A try statement without a finally block is executed by first executing the try block. Then there is a choice:

  • If execution of the try block completes normally, then no further action is taken and the try statement completes normally.
  • If execution of the try block completes abruptly because of a throw of a value V, then there is a choice:
    • If the run-time type of V is assignable (§5.2) to the Parameter of any catch clause of the try statement, then the first (leftmost) such catch clause is selected. The value V is assigned to the parameter of the selected catch clause, and the Block of that catch clause is executed. If that block completes normally, then the try statement completes normally; if that block completes abruptly for any reason, then the try statement completes abruptly for the same reason.
    • If the run-time type of V is not assignable to the parameter of any catch clause of the try statement, then the try statement completes abruptly because of a throw of the value V.
  • If execution of the try block completes abruptly for any other reason, then the try statement completes abruptly for the same reason.

In the example:

class BlewIt extends Exception {
    BlewIt() { }
    BlewIt(String s) { super(s); }
}
class Test {
    static void blowUp() throws BlewIt { throw new BlewIt(); }
    public static void main(String[] args) {

        try {
            blowUp();
        } catch (RuntimeException r) {
            System.out.println("RuntimeException:" + r);
        } catch (BlewIt b) {
            System.out.println("BlewIt");
        }
    }

}

the exception BlewIt is thrown by the method blowUp. The try-catch statement in the body of main has two catch clauses. The run-time type of the exception is BlewIt which is not assignable to a variable of type RuntimeException, but is assignable to a variable of type BlewIt, so the output of the example is:

BlewIt


14.18.2 Execution of try-catch-finally

After the great captains and engineers have accomplish'd their work,
After the noble inventors—after the scientists, the chemist,
the geologist, ethnologist,
Finally shall come the Poet . . .
—Walt Whitman, Passage to India (1870)

A try statement with a finally block is executed by first executing the try block. Then there is a choice:

  • If execution of the try block completes normally, then the finally block is executed, and then there is a choice:
    • If the finally block completes normally, then the try statement completes normally.
    • If the finally block completes abruptly for reason S, then the try statement completes abruptly for reason S.
  • If execution of the try block completes abruptly because of a throw of a value V, then there is a choice:
    • If the run-time type of V is assignable to the parameter of any catch clause of the try statement, then the first (leftmost) such catch clause is selected. The value V is assigned to the parameter of the selected catch clause, and the Block of that catch clause is executed. Then there is a choice:
      • If the catch block completes normally, then the finally block is executed. Then there is a choice:
        • If the finally block completes normally, then the try statement completes normally.
        • If the finally block completes abruptly for any reason, then the try statement completes abruptly for the same reason.
      • If the catch block completes abruptly for reason R, then the finally block is executed. Then there is a choice:
        • If the finally block completes normally, then the try statement completes abruptly for reason R.
        • If the finally block completes abruptly for reason S, then the try statement completes abruptly for reason S (and reason R is discarded).
    • If the run-time type of V is not assignable to the parameter of any catch clause of the try statement, then the finally block is executed. Then there is a choice:
      • If the finally block completes normally, then the try statement completes abruptly because of a throw of the value V.
      • If the finally block completes abruptly for reason S, then the try statement completes abruptly for reason S (and the throw of value V is discarded and forgotten).
  • If execution of the try block completes abruptly for any other reason R, then the finally block is executed. Then there is a choice:
    • If the finally block completes normally, then the try statement completes abruptly for reason R.
    • If the finally block completes abruptly for reason S, then the try statement completes abruptly for reason S (and reason R is discarded).

The example:

class BlewIt extends Exception {
    BlewIt() { }
    BlewIt(String s) { super(s); }
}

class Test {

    static void blowUp() throws BlewIt {

        throw new NullPointerException();

    }

    public static void main(String[] args) {
        try {
            blowUp();
        } catch (BlewIt b) {
            System.out.println("BlewIt");
        } finally {
            System.out.println("Uncaught Exception");
        }
    }

}

produces the output:

Uncaught Exception
java.lang.NullPointerException
    at Test.blowUp(Test.java:7)
    at Test.main(Test.java:11)

The NullPointerException (which is a kind of RuntimeException) that is thrown by method blowUp is not caught by the try statement in main, because a NullPointerException is not assignable to a variable of type BlewIt. This causes the finally clause to execute, after which the thread executing main, which is the only thread of the test program, terminates because of an uncaught exception (§20.21.31), which results in printing the exception name and a simple backtrace.


14.19 Unreachable Statements

That looks like a path.
Is that the way to reach the top from here?
—Robert Frost, The Mountain (1915)

It is a compile-time error if a statement cannot be executed because it is unreachable. Every Java compiler must carry out the conservative flow analysis specified here to make sure all statements are reachable.

This section is devoted to a precise explanation of the word "reachable." The idea is that there must be some possible execution path from the beginning of the constructor, method, or static initializer that contains the statement to the statement itself. The analysis takes into account the structure of statements. Except for the special treatment of while, do, and for statements whose condition expression has the constant value true, the values of expressions are not taken into account in the flow analysis. For example, a Java compiler will accept the code:

{
    int n = 5;
    while (n > 7) n = 2;
}

even though the value of n is known at compile time and in principle it can be known at compile time that the assignment to k can never be executed. A Java compiler must operate according to the rules laid out in this section.

The rules in this section define two technical terms:

  • whether a statement is reachable
  • whether a statement can complete normally

The definitions here allow a statement to complete normally only if it is reachable.

To shorten the description of the rules, the customary abbreviation "iff" is used to mean "if and only if."

The rules are as follows:

  • The block that is the body of a constructor, method, or static initializer is reachable.
  • An empty block that is not a switch block can complete normally iff it is reachable. A nonempty block that is not a switch block can complete normally iff the last statement in it can complete normally. The first statement in a nonempty block that is not a switch block is reachable iff the block is reachable. Every other statement S in a nonempty block that is not a switch block is reachable iff the statement preceding S can complete normally.
  • A local variable declaration statement can complete normally iff it is reachable.
  • An empty statement can complete normally iff it is reachable.
  • A labeled statement can complete normally if at least one of the following is true:
    • The contained statement can complete normally.
    • There is a reachable break statement that exits the labeled statement.

The contained statement is reachable iff the labeled statement is reachable.

  • An expression statement can complete normally iff it is reachable.
  • The if statement, whether or not it has an else part, is handled in an unusual manner. For this reason, it is discussed separately at the end of this section.
  • A switch statement can complete normally iff at least one of the following is true:
    • The last statement in the switch block can complete normally.
    • The switch block is empty or contains only switch labels.
    • There is at least one switch label after the last switch block statement group.
    • There is a reachable break statement that exits the switch statement.
  • A switch block is reachable iff its switch statement is reachable.
  • A statement in a switch block is reachable iff its switch statement is reachable and at least one of the following is true:
    • It bears a case or default label.
    • There is a statement preceding it in the switch block and that preceding statement can complete normally.
  • A while statement can complete normally iff at least one of the following is true:
    • The while statement is reachable and the condition expression is not a constant expression with value true.
    • There is a reachable break statement that exits the while statement.

The contained statement is reachable iff the while statement is reachable and the condition expression is not a constant expression whose value is false.

  • A do statement can complete normally iff at least one of the following is true:
    • The contained statement can complete normally and the condition expression is not a constant expression with value true.
    • There is a reachable break statement that exits the do statement.

The contained statement is reachable iff the do statement is reachable.

  • A for statement can complete normally iff at least one of the following is true:
    • The for statement is reachable, there is a condition expression, and the condition expression is not a constant expression with value true.
    • There is a reachable break statement that exits the for statement.

The contained statement is reachable iff the for statement is reachable and the condition expression is not a constant expression whose value is false.

  • A break, continue, return, or throw statement cannot complete normally.
  • A synchronized statement can complete normally iff the contained statement can complete normally. The contained statement is reachable iff the synchronized statement is reachable.
  • A try statement can complete normally iff both of the following are true:
    • The try block can complete normally or any catch block can complete normally.
    • If the try statement has a finally block, then the finally block can complete normally.
  • The try block is reachable iff the try statement is reachable.
  • A catch block C is reachable iff both of the following are true:
    • Some expression or throw statement in the try block is reachable and can throw an exception whose type is assignable to the parameter of the catch clause C. (An expression is considered reachable iff the innermost statement containing it is reachable.)
    • There is no earlier catch block A in the try statement such that the type of C's parameter is the same as or a subclass of the type of A's parameter.
  • If a finally block is present, it is reachable iff the try statement is reachable.

One might expect the if statement to be handled in the following manner, but these are not the rules that Java actually uses:

  • HYPOTHETICAL: An if-then statement can complete normally iff at least one of the following is true:
    • The if-then statement is reachable and the condition expression is not a constant expression whose value is true.
    • The then-statement can complete normally.

The then-statement is reachable iff the if-then statement is reachable and the condition expression is not a constant expression whose value is false.

  • HYPOTHETICAL: An if-then-else statement can complete normally iff the then-statement can complete normally or the else-statement can complete normally. The then-statement is reachable iff the if-then-else statement is reachable and the condition expression is not a constant expression whose value is false. The else statement is reachable iff the if-then-else statement is reachable and the condition expression is not a constant expression whose value is true.

This approach would be consistent with the treatment of other control structures in Java. However, in order to allow the if statement to be used conveniently for "conditional compilation" purposes, the actual rules are as follows:

  • ACTUAL: An if-then statement can complete normally iff it is reachable. The then-statement is reachable iff the if-then statement is reachable.
  • ACTUAL: An if-then-else statement can complete normally iff the then-statement can complete normally or the else-statement can complete normally. The then-statement is reachable iff the if-then-else statement is reachable. The else-statement is reachable iff the if-then-else statement is reachable.

As an example, the following statement results in a compile-time error:

while (false) { x=3; }

because the statement x=3; is not reachable; but the superficially similar case:

if (false) { x=3; }

does not result in a compile-time error. An optimizing compiler may realize that the statement x=3; will never be executed and may choose to omit the code for that statement from the generated class file, but the statement x=3; is not regarded as "unreachable" in the technical sense specified here.

The rationale for this differing treatment is to allow programmers to define "flag variables" such as:

static final boolean DEBUG = false;

and then write code such as:

if (DEBUG) { x=3; }

The idea is that it should be possible to change the value of DEBUG from false to true or from true to false and then compile the code correctly with no other changes to the program text.

This ability to "conditionally compile" has a significant impact on, and relationship to, binary compatibility (§13). If a set of classes that use such a "flag" variable are compiled and conditional code is omitted, it does not suffice later to distribute just a new version of the class or interface that contains the definition of the flag. A change to the value of a flag is, therefore, not binary compatible with preexisting binaries (§13.4.8). (There are other reasons for such incompatibility as well, such as the use of constants in case labels in switch statements; see §13.4.8.)

One ought not to be thrown into confusion
By a plain statement of relationship . . .
—Robert Frost, The Generations of Men (1914)


 15. Expressions

CHAPTER 15

Expressions

When you can measure what you are speaking about,
and express it in numbers, you know something about it;
but when you cannot measure it, when you cannot express it in numbers,
your knowledge of it is of a meager and unsatisfactory kind:
it may be the beginning of knowledge, but you have scarcely,
in your thoughts, advanced to the stage of science.
—William Thompson, Lord Kelvin

Much of the work in a Java program is done by evaluating expressions, either for their side effects, such as assignments to variables, or for their values, which can be used as arguments or operands in larger expressions, or to affect the execution sequence in statements, or both.

This chapter specifies the meanings of Java expressions and the rules for their evaluation.


15.1 Evaluation, Denotation, and Result

When an expression in a Java program is evaluated (executed), the result denotes one of three things:

  • A variable (§4.5) (in C, this would be called an lvalue)
  • A value (§4.2, §4.3)
  • Nothing (the expression is said to be void)

Evaluation of an expression can also produce side effects, because expressions may contain embedded assignments, increment operators, decrement operators, and method invocations.

An expression denotes nothing if and only if it is a method invocation (§15.11) that invokes a method that does not return a value, that is, a method declared void (§8.4). Such an expression can be used only as an expression statement (§14.7), because every other context in which an expression can appear requires the expression to denote something. An expression statement that is a method invocation may also invoke a method that produces a result; in this case the value returned by the method is quietly discarded.

Each expression occurs in the declaration of some (class or interface) type that is being declared: in a field initializer, in a static initializer, in a constructor declaration, or in the code for a method.


15.2 Variables as Values

If an expression denotes a variable, and a value is required for use in further evaluation, then the value of that variable is used. In this context, if the expression denotes a variable or a value, we may speak simply of the value of the expression.


15.3 Type of an Expression

If an expression denotes a variable or a value, then the expression has a type known at compile time. The rules for determining the type of an expression are explained separately below for each kind of expression.

The value of an expression is always assignment compatible (§5.2) with the type of the expression, just as the value stored in a variable is always compatible with the type of the variable. In other words, the value of an expression whose type is T is always suitable for assignment to a variable of type T.

Note that an expression whose type is a class type F that is declared final is guaranteed to have a value that is either a null reference or an object whose class is F itself, because final types have no subclasses.


15.4 Expressions and Run-Time Checks

If the type of an expression is a primitive type, then the value of the expression is of that same primitive type. But if the type of an expression is a reference type, then the class of the referenced object, or even whether the value is a reference to an object rather than null, is not necessarily known at compile time. There are a few places in the Java language where the actual class of a referenced object affects program execution in a manner that cannot be deduced from the type of the expression. They are as follows:

  • Method invocation (§15.11). The particular method used for an invocation o.m(...) is chosen based on the methods that are part of the class or interface that is the type of o. For instance methods, the class of the object referenced by the run-time value of o participates because a subclass may override a specific method already declared in a parent class so that this overriding method is invoked. (The overriding method may or may not choose to further invoke the original overridden m method.)
  • The instanceof operator (§15.19.2). An expression whose type is a reference type may be tested using instanceof to find out whether the class of the object referenced by the run-time value of the expression is assignment compatible (§5.2) with some other reference type.
  • Casting (§5.4, §15.15). The class of the object referenced by the run-time value of the operand expression might not be compatible with the type specified by the cast. For reference types, this may require a run-time check that throws an error if the class of the referenced object, as determined at run time, is not assignment compatible (§5.2) with the target type.
  • Assignment to an array component of reference type (§10.10, §15.12, §15.25.1). The type-checking rules allow the array type S[] to be treated as a subtype of T[] if S is a subtype of T, but this requires a run-time check for assignment to an army component, similar to the check performed for a cast.
  • Exception handling (§14.18). An exception is caught by a catch clause only if the class of the thrown exception object is an instanceof the type of the formal parameter of the catch clause.

The first two of the cases just listed ought never to result in detecting a type error. Thus, a Java run-time type error can occur only in these situations:

  • In a cast, when the actual class of the object referenced by the value of the operand expression is not compatible with the target type specified by the cast operator (§5.4, §15.15); in this case a ClassCastException is thrown.
  • In an assignment to an array component of reference type, when the actual class of the object referenced by the value to be assigned is not compatible with the actual run-time component type of the array (§10.10, §15.12, §15.25.1); in this case an ArrayStoreException is thrown.
  • When an exception is not caught by any catch handler (§11.3); in this case the thread of control that encountered the exception first invokes the method uncaughtException (§20.21.31) for its thread group and then terminates.


15.5 Normal and Abrupt Completion of Evaluation

No more: the end is sudden and abrupt.
--William Wordsworth, Apology for the Foregoing Poems (1831)

Every expression has a normal mode of evaluation in which certain computational steps are carried out. The following sections describe the normal mode of evaluation for each kind of expression. If all the steps are carried out without an exception being thrown, the expression is said to complete normally.

If, however, evaluation of an expression throws an exception, then the expression is said to complete abruptly. An abrupt completion always has an associated reason, which is always a throw with a given value.

Run-time exceptions are thrown by the predefined operators as follows:

  • A class instance creation expression (§15.8), array creation expression (§15.9), or string concatenation operatior expression (§15.17.1) throws an OutOfMemoryError if there is insufficient memory available.
  • An array creation expression throws an ArrayNegativeSizeException if the value of any dimension expression is less than zero (§15.9).
  • A field access (§15.10) throws a NullPointerException if the value of the object reference expression is null.
  • A method invocation expression (§15.11) that invokes an instance method throws a NullPointerException if the target reference is null.
  • An array access (§15.12) throws a NullPointerException if the value of the array reference expression is null.
  • An array access (§15.12) throws an IndexOutOfBoundsException if the value of the array index expression is negative or greater than or equal to the length of the array.
  • A cast (§15.15) throws a ClassCastException if a cast is found to be impermissible at run time.
  • An integer division (§15.16.2) or integer remainder (§15.16.3) operator throws an ArithmeticException if the value of the right-hand operand expression is zero.
  • An assignment to an array component of reference type (§15.25.1) throws an ArrayStoreException when the value to be assigned is not compatible with the component type of the array.

A method invocation expression can also result in an exception being thrown if an exception occurs that causes execution of the method body to complete abruptly. A class instance creation expression can also result in an exception being thrown if an exception occurs that causes execution of the constructor to complete abruptly. Various linkage and virtual machine errors may also occur during the evaluation of an expression. By their nature, such errors are difficult to predict and difficult to handle.

If an exception occurs, then evaluation of one or more expressions may be terminated before all steps of their normal mode of evaluation are complete; such expressions are said to complete abruptly. The terms "complete normally" and "complete abruptly" are also applied to the execution of statements (§14.1). A statement may complete abruptly for a variety of reasons, not just because an exception is thrown.

If evaluation of an expression requires evaluation of a subexpression, abrupt completion of the subexpression always causes the immediate abrupt completion of the expression itself, with the same reason, and all succeeding steps in the normal mode of evaluation are not performed.


15.6 Evaluation Order

Let all things be done decently and in order.
--I Corinthians 14:40

Java guarantees that the operands of operators appear to be evaluated in a specific evaluation order, namely, from left to right.

It is recommended that Java code not rely crucially on this specification. Code is usually clearer when each expression contains at most one side effect, as its outermost operation, and when code does not depend on exactly which exception arises as a consequence of the left-to-right evaluation of expressions.


15.6.1 Left-Hand Operand First

The left-hand operand of a binary operator appears to be fully evaluated before any part of the right-hand operand is evaluated. For example, if the left-hand operand contains an assignment to a variable and the right-hand operand contains a reference to that same variable, then the value produced by the reference will reflect the fact that the assignment occurred first.

Thus:

class Test {
    public static void main(String[] args) {
        int i = 2;
        int j = (i=3) * i;
        System.out.println(j);
    }
}

prints:

9

It is not permitted for it to print 6 instead of 9.

If the operator is a compound-assignment operator (§15.25.2), then evaluation of the left-hand operand includes both remembering the variable that the left-hand operand denotes and fetching and saving that variable's value for use in the implied combining operation. So, for example, the test program:

class Test {
    public static void main(String[] args) {
        int a = 9;
        a += (a = 3);									// first example
        System.out.println(a);
        int b = 9;
        b = b + (b = 3);									// second example
        System.out.println(b);
    }
}

prints:

12
12

because the two assignment statements both fetch and remember the value of the left-hand operand, which is 9, before the right-hand operand of the addition is evaluated, thereby setting the variable to 3. It is not permitted for either example to produce the result 6. Note that both of these examples have unspecified behavior in C, according to the ANSI/ISO standard.

If evaluation of the left-hand operand of a binary operator completes abruptly, no part of the right-hand operand appears to have been evaluated.

Thus, the test program:

class Test {

    public static void main(String[] args) {

        int j = 1;

        try {
            int i = forgetIt() / (j = 2);
        } catch (Exception e) {
            System.out.println(e);
            System.out.println("Now j = " + j);
        }
    }

    static int forgetIt() throws Exception {
        throw new Exception("I'm outta here!");
    }
}

prints:

java.lang.Exception: I'm outta here!
Now j = 1

because the left-hand operand forgetIt() of the operator / throws an exception before the right-hand operand and its embedded assignment of 2 to j occurs.


15.6.2 Operands before Operation

Java also guarantees that every operand of an operator (except the conditional operators &&, ||, and ? :) appears to be fully evaluated before any part of the operation itself is performed.

If the binary operator is an integer division / (§15.16.2) or integer remainder % (§15.16.3), then its execution may raise an ArithmeticException, but this exception is thrown only after both operands of the binary operator have been evaluated and only if these evaluations completed normally.

So, for example, the program:

class Test {

    public static void main(String[] args) {
        int divisor = 0;
        try {
            int i = 1 / (divisor * loseBig());
        } catch (Exception e) {
            System.out.println(e);
        }
    }

    static int loseBig() throws Exception {
        throw new Exception("Shuffle off to Buffalo!");
    }

}

always prints:

java.lang.Exception: Shuffle off to Buffalo!

and not:

java.lang.ArithmeticException: / by zero

since no part of the division operation, including signaling of a divide-by-zero exception, may appear to occur before the invocation of loseBig completes, even though the implementation may be able to detect or infer that the division operation would certainly result in a divide-by-zero exception.


15.6.3 Parentheses and Precedence Respected

That is too weighty a subject to be discussed parenthetically . . .
--John Stuart Mill, On Liberty (1869), Chapter IV

Java implementations must respect the order of evaluation as indicated explicitly by parentheses and implicitly by operator precedence. An implementation may not take advantage of algebraic identities such as the associative law to rewrite expressions into a more convenient computational order unless it can be proven that the replacement expression is equivalent in value and in its observable side effects, even in the presence of multiple threads of execution (using the thread execution model in §17), for all possible computational values that might be involved.

In the case of floating-point calculations, this rule applies also for infinity and not-a-number (NaN) values. For example, !(x<y) may not be rewritten as x>=y, because these expressions have different values if either x or y is NaN.

Specifically, floating-point calculations that appear to be mathematically associative are unlikely to be computationally associative. Such computations must not be naively reordered. For example, it is not correct for a Java compiler to rewrite 4.0*x*0.5 as 2.0*x; while roundoff happens not to be an issue here, there are large values of x for which the first expression produces infinity (because of overflow) but the second expression produces a finite result.

So, for example, the test program:

class Test {

    public static void main(String[] args) {
        double d = 8e+307;
        System.out.println(4.0 * d * 0.5);
        System.out.println(2.0 * d);
    }
}

prints:

Infinity
1.6e+308

because the first expression overflows and the second does not.

In contrast, integer addition and multiplication are provably associative in Java; for example a+b+c, where a, b, and c are local variables (this simplifying assumption avoids issues involving multiple threads and volatile variables), will always produce the same answer whether evaluated as (a+b)+c or a+(b+c); if the expression b+c occurs nearby in the code, a smart compiler may be able to use this common subexpression.


15.6.4 Argument Lists Evaluated Left-to-Right

In a method or constructor invocation or class instance creation expression, argument expressions may appear within the parentheses, separated by commas. Each argument expression appears to be fully evaluated before any part of any argument expression to its right.

Thus:

class Test {

    public static void main(String[] args) {
        String s = "going, ";
        print3(s, s, s = "gone");
    }

    static void print3(String a, String b, String c) {
        System.out.println(a + b + c);
    }
}

always prints:

going, going, gone

because the assignment of the string "gone" to s occurs after the first two arguments to print3 have been evaluated.

If evaluation of an argument expression completes abruptly, no part of any argument expression to its right appears to have been evaluated.

Thus, the example:

class Test {
    static int id;
    public static void main(String[] args) {
        try {
            test(id = 1, oops(), id = 3);
        } catch (Exception e) {
            System.out.println(e + ", id=" + id);
        }
    }

    static int oops() throws Exception {
        throw new Exception("oops");
    }

    static int test(int a, int b, int c) {
        return a + b + c;
    }

}

prints:

java.lang.Exception: oops, id=1

because the assignment of 3 to id is not executed.


15.6.5 Ordering of Other Expressions

The order of evaluation for some expressions is not completely covered by these general rules, because these expressions may raise exceptional conditions at times that must be specified. See, specifically, the detailed explanations of evaluation order for the following kinds of expressions:

  • class instance creation expressions (§15.8.1)
  • array creation expressions (§15.9.1)
  • method invocation expressions (§15.11.4)
  • array access expressions (§15.12.1)
  • assignments involving array components (§15.25)


15.7 Primary Expressions

Primary expressions include most of the simplest kinds of expressions, from which all others are constructed: literals, field accesses, method invocations, and array accesses. A parenthesized expression is also treated syntactically as a primary expression.

Primary:

    PrimaryNoNewArray

    ArrayCreationExpression

PrimaryNoNewArray:

    Literal

    this

    ( Expression )

    ClassInstanceCreationExpression

    FieldAccess

    MethodInvocation

    ArrayAccess

As programming language grammars go, this part of the Java grammar is unusual, in two ways. First, one might expect simple names, such as names of local variables and method parameters, to be primary expressions. For technical reasons, names are lumped together with primary expressions a little later when postfix expressions are introduced (§15.13).

The technical reasons have to do with allowing left-to-right parsing of Java programs with only one-token lookahead. Consider the expressions (z[3]) and (z[]). The first is a parenthesized array access (§15.12) and the second is the start of a cast (§15.15). At the point that the look-ahead symbol is [, a left-to-right parse will have reduced the z to the nonterminal Name. In the context of a cast we prefer not to have to reduce the name to a Primary, but if Name were one of the alternatives for Primary, then we could not tell whether to do the reduction (that is, we could not determine whether the current situation would turn out to be a parenthesized array access or a cast) without looking ahead two tokens, to the token following the [. The Java grammar presented here avoids the problem by keeping Name and Primary separate and allowing either in certain other syntax rules (those for MethodInvocation, ArrayAccess, PostfixExpression, but not for FieldAccess, because this is covered by Name). This strategy effectively defers the question of whether a Name should be treated as a Primary until more context can be examined. (Other problems remain with cast expressions; see §19.1.5.)

The second unusual feature avoids a potential grammatical ambiguity in the expression:

new int[3][3]

which in Java always means a single creation of a multidimensional array, but which, without appropriate grammatical finesse, might also be interpreted as meaning the same as:

(new int[3])[3]

This ambiguity is eliminated by splitting the expected definition of Primary into Primary and PrimaryNoNewArray. (This may be compared to the splitting of Statement into Statement and StatementNoShortIf (§14.4) to avoid the "dangling else" problem.)


15.7.1 Literals

A literal (§3.10) denotes a fixed, unchanging value.

The following production from §3.10 is repeated here for convenience:

Literal:

    IntegerLiteral

    FloatingPointLiteral

    BooleanLiteral

    CharacterLiteral

    StringLiteral

    NullLiteral

The type of a literal is determined as follows:

  • The type of an integer literal that ends with L or l is long; the type of any other integer literal is int.
  • The type of a floating-point literal that ends with F or f is float; the type of any other floating-point literal is double.
  • The type of a boolean literal is boolean.
  • The type of a character literal is char.
  • The type of a string literal is String.
  • The type of the null literal null is the null type; its value is the null reference.

Evaluation of a literal always completes normally.


15.7.2 this

The keyword this may be used only in the body of an instance method or constructor, or in the initializer of an instance variable of a class. If it appears anywhere else, a compile-time error occurs.

When used as a primary expression, the keyword this denotes a value, that is a reference to the object for which the instance method was invoked (§15.11), or to the object being constructed. The type of this is the class C within which the keyword this occurs. At run time, the class of the actual object referred to may be the class C or any subclass of C.

In the example:

class IntVector {
    int[] v;
    boolean equals(IntVector other) {
        if (this == other)
            return true;
        if (v.length != other.v.length)
            return false;
        for (int i = 0; i < v.length; i++)
            if (v[i] != other.v[i])
                return false;
        return true;
    }

}

the class IntVector implements a method equals, which compares two vectors. If the other vector is the same vector object as the one for which the equals method was invoked, then the check can skip the length and value comparisons. The equals method implements this check by comparing the reference to the other object to this.

The keyword this is also used in a special explicit constructor invocation statement, which can appear at the beginning of a constructor body (§8.6.5).


15.7.3 Parenthesized Expressions

A parenthesized expression is a primary expression whose type is the type of the contained expression and whose value at run time is the value of the contained expression.


15.8 Class Instance Creation Expressions

A class instance creation expression is used to create new objects that are instances of classes.

ClassInstanceCreationExpression:

    new ClassType ( ArgumentListopt )

ArgumentList:

    Expression

    ArgumentList , Expression

In a class instance creation expression, the ClassType must name a class that is not abstract. This class type is the type of the creation expression.

The arguments in the argument list, if any, are used to select a constructor declared in the body of the named class type, using the same matching rules as for method invocations (§15.11). As in method invocations, a compile-time method matching error results if there is no unique constructor that is both applicable to the provided arguments and the most specific of all the applicable constructors.


15.8.1 Run-time Evaluation of Class Instance Creation Expressions

At run time, evaluation of a class instance creation expression is as follows.

First, space is allocated for the new class instance. If there is insufficient space to allocate the object, evaluation of the class instance creation expression completes abruptly by throwing an OutOfMemoryError (§15.8.2).

The new object contains new instances of all the fields declared in the specified class type and all its superclasses. As each new field instance is created, it is initialized to its standard default value (§4.5.4).

Next, the argument list is evaluated, left-to-right. If any of the argument evaluations completes abruptly, any argument expressions to its right are not evaluated, and the class instance creation expression completes abruptly for the same reason.

Next, the selected constructor of the specified class type is invoked. This results in invoking at least one constructor for each superclass of the class type. This process can be directed by explicit constructor invocation statements (§8.6) and is described in detail in §12.5.

The value of a class instance creation expression is a reference to the newly created object of the specified class. Every time the expression is evaluated, a fresh object is created.


15.8.2 Example: Evaluation Order and Out-of-Memory Detection

If evaluation of a class instance creation expression finds there is insufficient memory to perform the creation operation, then an OutOfMemoryError is thrown. This check occurs before any argument expressions are evaluated.

So, for example, the test program:

class List {
    int value;
    List next;
    static List head = new List(0);
    List(int n) { value = n; next = head; head = this; }
}

class Test {
    public static void main(String[] args) {
        int id = 0, oldid = 0;
        try {
            for (;;) {
                ++id;
                new List(oldid = id);
            }
        } catch (Error e) {
            System.out.println(e + ", " + (oldid==id));
        }
    }
}

prints:

java.lang.OutOfMemoryError: List, false

because the out-or-memory condition is detected before the argument expression oldid = id is evaluated.

Compare this to the treatment of array creation expressions (§15.9), for which the out-of-memory condition is detected after evaluation of the dimension expressions (§15.9.3).


15.9 Array Creation Expressions

An array instance creation expression is used to create new arrays (§10).

ArrayCreationExpression:

    new PrimitiveType DimExprs Dimsopt

    new TypeName DimExprs Dimsopt

DimExprs:

    DimExpr

    DimExprs DimExpr

DimExpr:

    [ Expression ]

Dims:

    [ ]

    Dims [ ]

An array creation expression creates an object that is a new array whose elements are of the type specified by the PrimitiveType or TypeName. The TypeName may name any reference type, even an abstract class type (§8.1.2.1) or an interface type (§9).

The type of the creation expression is an array type that can denoted by a copy of the creation expression from which the new keyword and every DimExpr expression have been deleted; for example, the type of the creation expression:

new double[3][3][]

is:

double[][][]

The type of each dimension expression DimExpr must be an integral type, or a compile-time error occurs. Each expression undergoes unary numeric promotion (§5.6.1). The promoted type must be int, or a compile-time error occurs; this means, specifically, that the type of a dimension expression must not be long.


15.9.1 Run-time Evaluation of Array Creation Expressions

At run time, evaluation of an array creation expression behaves as follows.

First, the dimension expressions are evaluated, left-to-right. If any of the expression evaluations completes abruptly, the expressions to the right of it are not evaluated.

Next, the values of the dimension expressions are checked. If the value of any DimExpr expression is less than zero, then an NegativeArraySizeException is thrown.

Next, space is allocated for the new array. If there is insufficient space to allocate the array, evaluation of the array creation expression completes abruptly by throwing an OutOfMemoryError.

Then, if a single DimExpr appears, a single-dimensional array is created of the specified length, and each component of the array is initialized to its standard default value (§4.5.4).

If an array creation expression contains N DimExpr expressions, then it effectively executes a set of nested loops of depth [image] to create the implied arrays of arrays. For example, the declaration:

float[][] matrix = new float[3][3];

is equivalent in behavior to:

float[][] matrix = new float[3][];
for (int d = 0; d < matrix.length; d++)
    matrix[d] = new float[3];

and:

Age[][][][][] Aquarius = new Age[6][10][8][12][];

is equivalent to:

Age[][][][][] Aquarius = new Age[6][][][][];
for (int d1 = 0; d1 < Aquarius.length; d1++) {
    Aquarius[d1] = new Age[8][][][];
    for (int d2 = 0; d2 < Aquarius[d1].length; d2++) {
        Aquarius[d1][d2] = new Age[10][][];
        for (int d3 = 0; d3 < Aquarius[d1][d2].length; d3++) {
            Aquarius[d1][d2][d3] = new Age[12][];
        }
    }
}

with d, d1, d2 and d3 replaced by names that are not already locally declared. Thus, a single new expression actually creates one array of length 6, 6 arrays of length 10, [image] arrays of length 8, and [image] arrays of length 12. This example leaves the fifth dimension, which would be arrays containing the actual array elements (references to Age objects), initialized only to null references. These arrays can be filled in later by other code, such as:

Age[] Hair = { new Age("quartz"), new Age("topaz") };
Aquarius[1][9][6][9] = Hair;

A multidimensional array need not have arrays of the same length at each level; thus, a triangular matrix may be created by:

float triang[][] = new float[100][];
for (int i = 0; i < triang.length; i++)
    triang[i] = new float[i+1];

There is, however, no way to get this effect with a single creation expression.


15.9.2 Example: Evaluation Order

In an array creation expression (§15.9), there may be one or more dimension expressions, each within brackets. Each dimension expression is fully evaluated before any part of any dimension expression to its right.

Thus:

class Test {
    public static void main(String[] args) {
        int i = 4;
        int ia[][] = new int[i][i=3];
        System.out.println(
            "[" + ia.length + "," + ia[0].length + "]");
    }
}

prints:

[4,3]

because the first dimension is calculated as 4 before the second dimension expression sets i to 3.

If evaluation of a dimension expression completes abruptly, no part of any dimension expression to its right will appear to have been evaluated. Thus, the example:

class Test {

    public static void main(String[] args) {
        int[][] a = { { 00, 01 }, { 10, 11 } };
        int i = 99;
        try {
            a[val()][i = 1]++;
        } catch (Exception e) {
            System.out.println(e + ", i=" + i);
        }
    }

    static int val() throws Exception {
        throw new Exception("unimplemented");
    }

}

prints:

java.lang.Exception: unimplemented, i=99

because the embedded assignment that sets i to 1 is never executed.


15.9.3 Example: Evaluation Order and Out-of-Memory Detection

If evaluation of an array creation expression finds there is insufficient memory to perform the creation operation, then an OutOfMemoryError is thrown. This check occurs only after evaluation of all dimension expressions has completed normally.

So, for example, the test program:

class Test {
    public static void main(String[] args) {
        int len = 0, oldlen = 0;
        Object[] a = new Object[0];
        try {
            for (;;) {
                ++len;
                Object[] temp = new Object[oldlen = len];
                temp[0] = a;
                a = temp;
            }
        } catch (Error e) {
            System.out.println(e + ", " + (oldlen==len));
        }
    }
}

prints:

java.lang.OutOfMemoryError, true

because the out-of-memory condition is detected after the argument expression oldlen = len is evaluated.

Compare this to class instance creation expressions (§15.8), which detect the out-of-memory condition before evaluating argument expressions (§15.8.2).


15.10 Field Access Expressions

A field access expression may access a field of an object or array, a reference to which is the value of either an expression or the special keyword super. (It is also possible to refer to a field of the current instance or current class by using a simple name; see §15.13.1.)

FieldAccess:

    Primary . Identifier

    super . Identifier

The meaning of a field access expression is determined using the same rules as for qualified names (§6.6), but limited by the fact that an expression cannot denote a package, class type, or interface type.


15.10.1 Field Access Using a Primary

The type of the Primary must be a reference type T, or a compile-time error occurs. The meaning of the field access expression is determined as follows:

  • If the identifier names several accessible member fields of type T, then the field access is ambiguous and a compile-time error occurs.
  • If the identifier does not name an accessible member field of type T, then the field access is undefined and a compile-time error occurs.
  • Otherwise, the identifier names a single accessible member field of type T and the type of the field access expression is the declared type of the field. At run time, the result of the field access expression is computed as follows:
    • If the field is static:
      • If the field is final, then the result is the value of the specified class variable in the class or interface that is the type of the Primary expression.
      • If the field is not final, then the result is a variable, namely, the specified class variable in the class that is the type of the Primary expression.
    • If the field is not static:
      • If the value of the Primary is null, then a NullPointerException is thrown.
      • If the field is final, then the result is the value of the specified instance variable in the object referenced by the value of the Primary.
      • If the field is not final, then the result is a variable, namely, the specified instance variable in the object referenced by the value of the Primary.

Note, specifically, that only the type of the Primary expression, not the class of the actual object referred to at run time, is used in determining which field to use.

Thus, the example:

class S { int x = 0; }
class T extends S { int x = 1; }
class Test {
    public static void main(String[] args) {

        T t = new T();
        System.out.println("t.x=" + t.x + when("t", t));

        S s = new S();
        System.out.println("s.x=" + s.x + when("s", s));

        s = t;
        System.out.println("s.x=" + s.x + when("s", s));

    }

    static String when(String name, Object t) {
        return " when " + name + " holds a "
            + t.getClass() + " at run time.";
    }
}

produces the output:

t.x=1 when t holds a class T at run time.
s.x=0 when s holds a class S at run time.
s.x=0 when s holds a class T at run time.

The last line shows that, indeed, the field that is accessed does not depend on the run-time class of the referenced object; even if s holds a reference to an object of class T, the expression s.x refers to the x field of class S, because the type of the expression s is S. Objects of class T contain two fields named x, one for class T and one for its superclass S.

This lack of dynamic lookup for field accesses allows Java to run efficiently with straightforward implementations. The power of late binding and overriding is available in Java, but only when instance methods are used. Consider the same example using instance methods to access the fields:

class S { int x = 0; int z() { return x; } }
class T extends S { int x = 1; int z() { return x; } }
class Test {

    public static void main(String[] args) {
        T t = new T();
        System.out.println("t.z()=" + t.z() + when("t", t));
        S s = new S();
        System.out.println("s.z()=" + s.z() + when("s", s));
        s = t;
        System.out.println("s.z()=" + s.z() + when("s", s));
    }

    static String when(String name, Object t) {
        return " when " + name + " holds a "
            + t.getClass() + " at run time.";
    }
}

Now the output is:

t.z()=1 when t holds a class T at run time.
s.z()=0 when s holds a class S at run time.
s.z()=1 when s holds a class T at run time.

The last line shows that, indeed, the method that is accessed does depend on the run-time class of referenced object; when s holds a reference to an object of class T, the expression s.z() refers to the z method of class T, despite the fact that the type of the expression s is S. Method z of class T overrides method z of class S.

The following example demonstrates that a null reference may be used to access a class (static) variable without causing an exception:

class Test {
    static String mountain = "Chocorua";

    static Test favorite(){
        System.out.print("Mount ");
        return null;
    }

    public static void main(String[] args) {
        System.out.println(favorite().mountain);
    }
}

It compiles, executes, and prints:

Mount Chocorua

Even though the result of favorite() is null, a NullPointerException is not thrown. That "Mount " is printed demonstrates that the Primary expression is indeed fully evaluated at run time, despite the fact that only its type, not its value, is used to determine which field to access (because the field mountain is static).


15.10.2 Accessing Superclass Members using super

The special form using the keyword super is valid only in an instance method or constructor, or in the initializer of an instance variable of a class; these are exactly the same situations in which the keyword this may be used (§15.7.2). The form involving super may not be used anywhere in the class Object, since Object has no superclass; if super appears in class Object, then a compile-time error results.

Suppose that a field access expression super.name appears within class C, and the immediate superclass of C is class S. Then super.name is treated exactly as if it had been the expression ((S)this).name; thus, it refers to the field named name of the current object, but with the current object viewed as an instance of the superclass. Thus it can access the field named name that is visible in class S, even if that field is hidden by a declaration of a field named name in class C.

The use of super is demonstrated by the following example:

interface I { int x = 0; }
class T1 implements I { int x = 1; }
class T2 extends T1 { int x = 2; }
class T3 extends T2 {
    int x = 3;
    void test() {
        System.out.println("x=\t\t"+x);
        System.out.println("super.x=\t\t"+super.x);
        System.out.println("((T2)this).x=\t"+((T2)this).x);
        System.out.println("((T1)this).x=\t"+((T1)this).x);
        System.out.println("((I)this).x=\t"+((I)this).x);
    }
}
class Test {
    public static void main(String[] args) {
        new T3().test();
    }
}

which produces the output:

x=					3
super.x=					2
((T2)this).x=					2
((T1)this).x=					1
((I)this).x=					0

Within class T3, the expression super.x is treated exactly as if it were:

((T2)this).x


15.11 Method Invocation Expressions

A method invocation expression is used to invoke a class or instance method.

MethodInvocation:

    MethodName ( ArgumentListopt )

    Primary . Identifier ( ArgumentListopt )

    super . Identifier ( ArgumentListopt )

The definition of ArgumentList from §15.8 is repeated here for convenience:

ArgumentList:

    Expression

    ArgumentList , Expression

Resolving a method name at compile time is more complicated than resolving a field name because of the possibility of method overloading. Invoking a method at run time is also more complicated than accessing a field because of the possibility of instance method overriding.

Determining the method that will be invoked by a method invocation expression involves several steps. The following three sections describe the compile-time processing of a method invocation; the determination of the type of the method invocation expression is described in §15.11.3.


15.11.1 Compile-Time Step 1: Determine Class or Interface to Search

The first step in processing a method invocation at compile time is to figure out the name of the method to be invoked and which class or interface to check for definitions of methods of that name. There are several cases to consider, depending on the form that precedes the left parenthesis, as follows:

  • If the form is MethodName, then there are three subcases:
    • If it is a simple name, that is, just an Identifier, then the name of the method is the Identifier and the class or interface to search is the one whose declaration contains the method invocation.
    • If it is a qualified name of the form TypeName . Identifier, then the name of the method is the Identifier and the class to search is the one named by the TypeName. If TypeName is the name of an interface rather than a class, then a compile-time error occurs, because this form can invoke only static methods and interfaces have no static methods.
    • In all other cases, the qualified name has the form FieldName . Identifier; then the name of the method is the Identifier and the class or interface to search is the declared type of the field named by the FieldName.
  • If the form is Primary . Identifier, then the name of the method is the Identifier and the class or interface to be searched is the type of the Primary expression.
  • If the form is super . Identifier, then the name of the method is the Identifier and the class to be searched is the superclass of the class whose declaration contains the method invocation. A compile-time error occurs if such a method invocation occurs in an interface, or in the class Object, or in a static method, a static initializer, or the initializer for a static variable. It follows that a method invocation of this form may appear only in a class other than Object, and only in the body of an instance method, the body of a constructor, or an initializer for an instance variable.


15.11.2 Compile-Time Step 2: Determine Method Signature

The hand-writing experts were called upon for their opinion of the signature . . .
—Agatha Christie, The Mysterious Affair at Styles (1920), Chapter 11

The second step searches the class or interface determined in the previous step for method declarations. This step uses the name of the method and the types of the argument expressions to locate method declarations that are both applicable and accessible, that is, declarations that can be correctly invoked on the given arguments. There may be more than one such method declaration, in which case the most specific one is chosen. The descriptor (signature plus return type) of the most specific method declaration is one used at run time to do the method dispatch.

15.11.2.1 Find Methods that are Applicable and Accessible

A method declaration is applicable to a method invocation if and only if both of the following are true:

  • The number of parameters in the method declaration equals the number of argument expressions in the method invocation.
  • The type of each actual argument can be converted by method invocation conversion (§5.3) to the type of the corresponding parameter. Method invocation conversion is the same as assignment conversion (§5.2), except that constants of type int are never implicitly narrowed to byte, short, or char.

The class or interface determined by the process described in §15.11.1 is searched for all method declarations applicable to this method invocation; method definitions inherited from superclasses and superinterfaces are included in this search.

Whether a method declaration is accessible to a method invocation depends on the access modifier (public, none, protected, or private) in the method declaration and on where the method invocation appears.

If the class or interface has no method declaration that is both applicable and accessible, then a compile-time error occurs.

In the example program:

public class Doubler {
    static int two() { return two(1); }
    private static int two(int i) { return 2*i; }
}

class Test extends Doubler {
    public static long two(long j) {return j+j; }

    public static void main(String[] args) {
        System.out.println(two(3));
        System.out.println(Doubler.two(3));	// compile-time error
    }
}

for the method invocation two(1) within class Doubler, there are two accessible methods named two, but only the second one is applicable, and so that is the one invoked at run time. For the method invocation two(3) within class Test, there are two applicable methods, but only the one in class Test is accessible, and so that is the one to be invoked at run time (the argument 3 is converted to type long). For the method invocation Doubler.two(3), the class Doubler, not class Test, is searched for methods named two; the only applicable method is not accessible, and so this method invocation causes a compile-time error.

Another example is:

class ColoredPoint {
    int x, y;
    byte color;
    void setColor(byte color) { this.color = color; }
}

class Test {
    public static void main(String[] args) {
        ColoredPoint cp = new ColoredPoint();
        byte color = 37;
        cp.setColor(color);
        cp.setColor(37);											// compile-time error
    }
}

Here, a compile-time error occurs for the second invocation of setColor, because no applicable method can be found at compile time. The type of the literal 37 is int, and int cannot be converted to byte by method invocation conversion. Assignment conversion, which is used in the initialization of the variable color, performs an implicit conversion of the constant from type int to byte, which is permitted because the value 37 is small enough to be represented in type byte; but such a conversion is not allowed for method invocation conversion.

If the method setColor had, however, been declared to take an int instead of a byte, then both method invocations would be correct; the first invocation would be allowed because method invocation conversion does permit a widening conversion from byte to int. However, a narrowing cast would then be required in the body of setColor:

    void setColor(int color) { this.color = (byte)color; }

15.11.2.2 Choose the Most Specific Method

If more than one method is both accessible and applicable to a method invocation, it is necessary to choose one to provide the descriptor for the run-time method dispatch. Java uses the rule that the most specific method is chosen.

The informal intuition is that one method declaration is more specific than another if any invocation handled by the first method could be passed on to the other one without a compile-time type error.

The precise definition is as follows. Let m be a name and suppose that there are two declarations of methods named m, each having n parameters. Suppose that one declaration appears within a class or interface T and that the types of the parameters are T1, . . . , Tn; suppose moreover that the other declaration appears within a class or interface U and that the types of the parameters are U1, . . . , Un. Then the method m declared in T is more specific than the method m declared in U if and only if both of the following are true:

  • T can be converted to U by method invocation conversion.
  • Tj can be converted to Uj by method invocation conversion, for all j from 1 to n.

A method is said to be maximally specific for a method invocation if it is applicable and accessible and there is no other applicable and accessible method that is more specific.

If there is exactly one maximally specific method, then it is in fact the most specific method; it is necessarily more specific than any other method that is applicable and accessible. It is then subjected to some further compile-time checks as described in §15.11.3.

It is possible that no method is the most specific, because there are two or more maximally specific method declarations. In this case, we say that the method invocation is ambiguous, and a compile-time error occurs.

15.11.2.3 Example: Overloading Ambiguity

Consider the example:

class Point { int x, y; }
class ColoredPoint extends Point { int color; }

class Test {

    static void test(ColoredPoint p, Point q) {
        System.out.println("(ColoredPoint, Point)");
    }

    static void test(Point p, ColoredPoint q) {
        System.out.println("(Point, ColoredPoint)");
    }

    public static void main(String[] args) {
        ColoredPoint cp = new ColoredPoint();
        test(cp, cp);											// compile-time error
    }
}

This example produces an error at compile time. The problem is that there are two declarations of test that are applicable and accessible, and neither is more specific than the other. Therefore, the method invocation is ambiguous.

If a third definition of test were added:

    static void test(ColoredPoint p, ColoredPoint q) {
        System.out.println("(ColoredPoint, ColoredPoint)");
    }

then it would be more specific than the other two, and the method invocation would no longer be ambiguous.

15.11.2.4 Example: Return Type Not Considered

As another example, consider:

class Point { int x, y; }
class ColoredPoint extends Point { int color; }
class Test {

    static int test(ColoredPoint p) {
        return color;
    }

    static String test(Point p) {
        return "Point";
    }

    public static void main(String[] args) {
        ColoredPoint cp = new ColoredPoint();
        String s = test(cp); // compile-time error
    }
}

Here the most specific declaration of method test is the one taking a parameter of type ColoredPoint. Because the result type of the method is int, a compile- time error occurs because an int cannot be converted to a String by assignment conversion. This example shows that, in Java, the result types of methods do not participate in resolving overloaded methods, so that the second test method, which returns a String, is not chosen, even though it has a result type that would allow the example program to compile without error.

15.11.2.5 Example: Compile-Time Resolution

The most applicable method is chosen at compile time; its descriptor determines what method is actually executed at run time. If a new method is added to a class, then Java code that was compiled with the old definition of the class might not use the new method, even if a recompilation would cause this method to be chosen.

So, for example, consider two compilation units, one for class Point:

package points;
public class Point {
    public int x, y;
    public Point(int x, int y) { this.x = x; this.y = y; }
    public String toString() { return toString(""); }

    public String toString(String s) {
        return "(" + x + "," + y + s + ")";
    }
}

and one for class ColoredPoint:

package points;
public class ColoredPoint extends Point {

    public static final int
        RED = 0, GREEN = 1, BLUE = 2;

    public static String[] COLORS =
        { "red", "green", "blue" };
    public byte color;

    public ColoredPoint(int x, int y, int color) {
        super(x, y); this.color = (byte)color;
    }

    /** Copy all relevant fields of the argument into
            this ColoredPoint object. */
    public void adopt(Point p) { x = p.x; y = p.y; }

    public String toString() {
        String s = "," + COLORS[color];
        return super.toString(s);
    }
}

Now consider a third compilation unit that uses ColoredPoint:

import points.*;
class Test {
    public static void main(String[] args) {
        ColoredPoint cp =
            new ColoredPoint(6, 6, ColoredPoint.RED);
        ColoredPoint cp2 =
            new ColoredPoint(3, 3, ColoredPoint.GREEN);
        cp.adopt(cp2);
        System.out.println("cp: " + cp);
    }
}

The output is:

cp: (3,3,red)

The application programmer who coded class Test has expected to see the word green, because the actual argument, a ColoredPoint, has a color field, and color would seem to be a "relevant field" (of course, the documentation for the package Points ought to have been much more precise!).

Notice, by the way, that the most specific method (indeed, the only applicable method) for the method invocation of adopt has a signature that indicates a method of one parameter, and the parameter is of type Point. This signature becomes part of the binary representation of class Test produced by the compiler and is used by the method invocation at run time.

Suppose the programmer reported this software error and the maintainer of the points package decided, after due deliberation, to correct it by adding a method to class ColoredPoint:

public void adopt(ColoredPoint p) {
    adopt((Point)p); color = p.color;
}

If the application programmer then runs the old binary file for Test with the new binary file for ColoredPoint, the output is still:

cp: (3,3,red)

because the old binary file for Test still has the descriptor "one parameter, whose type is Point; void" associated with the method call cp.adopt(cp2). If the source code for Test is recompiled, the compiler will then discover that there are now two applicable adopt methods, and that the signature for the more specific one is "one parameter, whose type is ColoredPoint; void"; running the program will then produce the desired output:

cp: (3,3,green)

With forethought about such problems, the maintainer of the points package could fix the ColoredPoint class to work with both newly compiled and old code, by adding defensive code to the old adopt method for the sake of old code that still invokes it on ColoredPoint arguments:

public void adopt(Point p) {
    if (p instanceof ColoredPoint)
        color = ((ColoredPoint)p).color;
    x = p.x; y = p.y;
}

A similar consideration applies if a method is to be moved from a class to a superclass. In this case a forwarding method can be left behind for the sake of old code. The maintainer of the points package might choose to move the adopt method that takes a Point argument up to class Point, so that all Point objects may enjoy the adopt functionality. To avoid compatibility problems with old binary code, the maintainer should leave a forwarding method behind in class ColoredPoint:

public void adopt(Point p) {
    if (p instanceof ColoredPoint)
        color = ((ColoredPoint)p).color;
    super.adopt(p);
}

Ideally, Java code should be recompiled whenever code that it depends on is changed. However, in an environment where different Java classes are maintained by different organizations, this is not always feasible. Defensive programming with careful attention to the problems of class evolution can make upgraded code much more robust. See §13 for a detailed discussion of binary compatibility and type evolution.


15.11.3 Compile-Time Step 3: Is the Chosen Method Appropriate?

If there is a most specific method declaration for a method invocation, it is called the compile-time declaration for the method invocation. Two further checks must be made on the compile-time declaration:

  • If the method invocation has, before the left parenthesis, a MethodName of the form Identifier, and the method invocation appears within a static method, a static initializer, or the initializer for a static variable, then the compile-time declaration must be static. If, instead, the compile-time declaration for the method invocation is for an instance method, then a compile-time error occurs. (The reason is that a method invocation of this form cannot be used to invoke an instance method in places where this (§15.7.2) is not defined.)
  • If the method invocation has, before the left parenthesis, a MethodName of the form TypeName . Identifier, then the compile-time declaration should be static. If the compile-time declaration for the method invocation is for an instance method, then a compile-time error occurs. (The reason is that a method invocation of this form does not specify a reference to an object that can serve as this within the instance method.)
  • If the compile-time declaration for the method invocation is void, then the method invocation must be a top-level expression, that is, the Expression in an expression statement (§14.7) or in the ForInit or ForUpdate part of a for statement (§14.12), or a compile-time error occurs. (The reason is that such a method invocation produces no value and so must be used only in a situation where a value is not needed.)

The following compile-time information is then associated with the method invocation for use at run time:

  • The name of the method.
  • The class or interface that contains the compile-time declaration.
  • The number of parameters and the types of the parameters, in order.
  • The result type, or void, as declared in the compile-time declaration.
  • The invocation mode, computed as follows:
    • If the compile-time declaration has the static modifier, then the invocation mode is static.
    • Otherwise, if the compile-time declaration has the private modifier, then the invocation mode is nonvirtual.
    • Otherwise, if the part of the method invocation before the left parenthesis is of the form super . Identifier, then the invocation mode is super.
    • Otherwise, if the compile-time declaration is in an interface, then the invocation mode is interface.
    • Otherwise, the invocation mode is virtual.

If the compile-time declaration for the method invocation is not void, then the type of the method invocation expression is the result type specified in the compile-time declaration.


15.11.4 Runtime Evaluation of Method Invocation

At run time, method invocation requires five steps. First, a target reference may be computed. Second, the argument expressions are evaluated. Third, the accessibility of the method to be invoked is checked. Fourth, the actual code for the method to be executed is located. Fifth, a new activation frame is created, synchronization is performed if necessary, and control is transferred to the method code.

15.11.4.1 Compute Target Reference (If Necessary)

There are several cases to consider, depending on which of the three productions for MethodInvocation (§15.11) is involved:

  • If the first production for MethodInvocation, which includes a MethodName, is involved, then there are three subcases:
    • If the MethodName is a simple name, that is, just an Identifier, then there are two subcases:
      • If the invocation mode is static, then there is no target reference.
      • Otherwise, the target reference is the value of this.
    • If the MethodName is a qualified name of the form TypeName . Identifier, then there is no target reference.
    • If the MethodName is a qualified name of the form FieldName . Identifier, then there are two subcases:
      • If the invocation mode is static, then there is no target reference.
      • Otherwise, the target reference is the value of the expression FieldName.
  • If the second production for MethodInvocation, which includes a Primary, is involved, then there are two subcases:
    • If the invocation mode is static, then there is no target reference. The expression Primary is evaluated, but the result is then discarded.
    • Otherwise, the expression Primary is evaluated and the result is used as the target reference.

In either case, if the evaluation of the Primary expression completes abruptly, then no part of any argument expression appears to have been evaluated, and the method invocation completes abruptly for the same reason.

  • If the third production for MethodInvocation, which includes the keyword super, is involved, then the target reference is the value of this.

15.11.4.2 Evaluate Arguments

The argument expressions are evaluated in order, from left to right. If the evaluation of any argument expression completes abruptly, then no part of any argument expression to its right appears to have been evaluated, and the method invocation completes abruptly for the same reason.

15.11.4.3 Check Accessibility of Type and Method

Let C be the class containing the method invocation, and let T be the class or interface that contained the method being invoked, and m be the name of the method, as determined at compile time (§15.11.3).

A Java Virtual Machine must insure, as part of linkage, that the method m still exists in the type T. If this is not true, then a NoSuchMethodError (which is a subclass of IncompatibleClassChangeError) occurs. If the invocation mode is interface, then the virtual machine must also check that the target reference type still implements the specified interface. If the target reference type does not still implement the interface, then an IncompatibleClassChangeError occurs.

The virtual machine must also insure, during linkage, that the type T and the method m are accessible. For the type T:

  • If T is in the same package as C, then T is accessible.
  • If T is in a different package than C, and T is public, then T is accessible.

For the method m:

  • If m is public, then m is accessible. (All members of interfaces are public (§9.2)).
  • If m is protected, then m is accessible if and only if either T is in the same package as C, or C is T or a subclass of T.
  • If m has default (package) access, then m is accessible if and only if T is in the same package as C.
  • If m is private, then m is accessible if and only if and C is T.

If either T or m is not accessible, then an IllegalAccessError occurs (§12.3).

15.11.4.4 Locate Method to Invoke

The strategy for method lookup depends on the invocation mode.

If the invocation mode is static, no target reference is needed and overriding is not allowed. Method m of class T is the one to be invoked.

Otherwise, an instance method is to be invoked and there is a target reference. If the target reference is null, a NullPointerException is thrown at this point. Otherwise, the target reference is said to refer to a target object and will be used as the value of the keyword this in the invoked method. The other four possibilities for the invocation mode are then considered.

If the invocation mode is nonvirtual, overriding is not allowed. Method m of class T is the one to be invoked.

Otherwise, the invocation mode is interface, virtual, or super, and overriding may occur. A dynamic method lookup is used. The dynamic lookup process starts from a class S, determined as follows:

  • If the invocation mode is interface or virtual, then S is initially the actual run-time class R of the target object. If the target object is an array, R is the class Object. (Note that for invocation mode interface, R necessarily implements T; for invocation mode virtual, R is necessarily either T or a subclass of T.)
  • If the invocation mode is super, then S is initially the superclass of the class C that contains the method invocation.

The dynamic method lookup uses the following procedure to search class S, and then the superclasses of class S, as necessary, for method m.

  • If class S contains a declaration for a method named m with the same descriptor (same number of parameters, the same parameter types, and the same return type) required by the method invocation as determined at compile time (§15.11.3), then this is the method to be invoked, and the procedure terminates. (We note that as part of the loading and linking process that the virtual machine checks that an overriding method is at least as accessible as the overridden method; an IncompatibleClassChangeError occurs if this is not the case.)
  • Otherwise, if S is not T, this same lookup procedure is performed using the superclass of S; whatever it comes up with is the result of this lookup.

This procedure will find a suitable method when it reaches class T, because otherwise an IllegalAccessError would have been thrown by the checks of the previous section §15.11.4.3.

We note that the dynamic lookup process, while described here explicitly, will often be implemented implicitly, for example as a side-effect of the construction and use of per-class method dispatch tables, or the construction of other per-class structures used for efficient dispatch.

15.11.4.5 Create Frame, Synchronize, Transfer Control

A method m in some class S has been identified as the one to be invoked.

Now a new activation frame is created, containing the target reference (if any) and the argument values (if any), as well as enough space for the local variables and stack for the method to be invoked and any other bookkeeping information that may be required by the implementation (stack pointer, program counter, reference to previous activation frame, and the like). If there is not sufficient memory available to create such an activation frame, an OutOfMemoryError is thrown.

The newly created activation frame becomes the current activation frame. The effect of this is to assign the argument values to corresponding freshly created parameter variables of the method, and to make the target reference available as this, if there is a target reference.

If the method m is a native method but the necessary native, implementation-dependent binary code has not been loaded (§20.16.13, §20.16.14) or otherwise cannot be dynamically linked, then an UnsatisfiedLinkError is thrown.

If the method m is not synchronized, control is transferred to the body of the method m to be invoked.

If the method m is synchronized, then an object must be locked before the transfer of control. No further progress can be made until the current thread can obtain the lock. If there is a target reference, then the target must be locked; otherwise the Class object for class S, the class of the method m, must be locked. Control is then transferred to the body of the method m to be invoked. The object is automatically unlocked when execution of the body of the method has completed, whether normally or abruptly. The locking and unlocking behavior is exactly as if the body of the method were embedded in a synchronized statement (§14.17).

15.11.4.6 Implementation Note: Combining Frames

In order to allow certain kinds of code optimization, implementations are permitted some freedom to combine activation frames. Suppose that a method invocation within class C is to invoke a method m within class S. Then the current activation frame may be used to provide space for S instead of creating a new activation frame only if one of the following conditions is true:

  • Class C and class S have the same class loader (§20.14) and class S is not SecurityManager or a subclass of SecurityManager.
  • Class S has no class loader (this fact indicates that it is a system class); class S is not SecurityManager or a subclass of SecurityManager; and method m is known not to call, directly or indirectly, any method of SecurityManager (§20.17) or any of its subclasses.

15.11.4.7 Example: Target Reference and Static Methods

When a target reference is computed and then discarded because the invocation mode is static, the reference is not examined to see whether it is null:

class Test {
    static void mountain() {

        System.out.println("Monadnock");

    }

    static Test favorite(){
        System.out.print("Mount ");
        return null;
    }

    public static void main(String[] args) {
        favorite().mountain();
    }
}

which prints:

Mount Monadnock

Here favorite returns null, yet no NullPointerException is thrown.

15.11.4.8 Example: Evaluation Order

As part of an instance method invocation (§15.11), there is an expression that denotes the object to be invoked. This expression appears to be fully evaluated before any part of any argument expression to the method invocation is evaluated.

So, for example, in:

class Test {
    public static void main(String[] args) {
        String s = "one";
        if (s.startsWith(s = "two"))
            System.out.println("oops");
    }
}

the occurrence of s before ".startsWith" is evaluated first, before the argument expression s="two". Therefore, a reference to the string "one" is remembered as the target reference before the local variable s is changed to refer to the string "two". As a result, the startsWith method (§20.12.20) is invoked for target object "one" with argument "two", so the result of the invocation is false, as the string "one" does not start with "two". It follows that the test program does not print "oops".

15.11.4.9 Example: Overriding

In the example:

class Point {

    final int EDGE = 20;
    int x, y;

    void move(int dx, int dy) {
        x += dx; y += dy;
        if (Math.abs(x) >= EDGE || Math.abs(y) >= EDGE)
            clear();
    }

    void clear() {
        System.out.println("\tPoint clear");
        x = 0; y = 0;
    }
}

class ColoredPoint extends Point {
    int color;

    void clear() {
        System.out.println("\tColoredPoint clear");
        super.clear();
        color = 0;
    }
}

the subclass ColoredPoint extends the clear abstraction defined by its superclass Point. It does so by overriding the clear method with its own method, which invokes the clear method of its superclass, using the form super.clear.

This method is then invoked whenever the target object for an invocation of clear is a ColoredPoint. Even the method move in Point invokes the clear method of class ColoredPoint when the class of this is ColoredPoint, as shown by the output of this test program:

class Test {
    public static void main(String[] args) {
        Point p = new Point();
        System.out.println("p.move(20,20):");
        p.move(20, 20);
        ColoredPoint cp = new ColoredPoint();
        System.out.println("cp.move(20,20):");
        cp.move(20, 20);
        p = new ColoredPoint();
        System.out.println("p.move(20,20), p colored:");
        p.move(20, 20);
    }
}

which is:

p.move(20,20):
    Point clear
cp.move(20,20):
    ColoredPoint clear
    Point clear
p.move(20,20), p colored:
    ColoredPoint clear
    Point clear

Overriding is sometimes called "late-bound self-reference"; in this example it means that the reference to clear in the body of Point.move (which is really syntactic shorthand for this.clear) invokes a method chosen "late" (at run time, based on the run-time class of the object referenced by this) rather than a method chosen "early" (at compile time, based only on the type of this). This provides the Java programmer a powerful way of extending abstractions and is a key idea in object-oriented programming.

15.11.4.10 Example: Method Invocation using super

An overridden instance method of a superclass may be accessed by using the keyword super to access the members of the immediate superclass, bypassing any overriding declaration in the class that contains the method invocation.

When accessing an instance variable, super means the same as a cast of this (§15.10.2), but this equivalence does not hold true for method invocation. This is demonstrated by the example:

class T1 {
    String s() { return "1"; }
}

class T2 extends T1 {
    String s() { return "2"; }
}

class T3 extends T2 {
    String s() { return "3"; }

    void test() {
        System.out.println("s()=\t\t"+s());
        System.out.println("super.s()=\t"+super.s());
        System.out.print("((T2)this).s()=\t");
            System.out.println(((T2)this).s());
        System.out.print("((T1)this).s()=\t");
            System.out.println(((T1)this).s());
    }
}

class Test {
    public static void main(String[] args) {
        T3 t3 = new T3();
        t3.test();
    }
}

which produces the output:

s()=					3
super.s()=					2
((T2)this).s()=					3
((T1)this).s()=					3

The casts to types T1 and T2 do not change the method that is invoked, because the instance method to be invoked is chosen according to the run-time class of the object referred to be this. A cast does not change the class of an object; it only checks that the class is compatible with the specified type.


15.12 Array Access Expressions

An array access expression refers to a variable that is a component of an array.

ArrayAccess:

    ExpressionName [ Expression ]

    PrimaryNoNewArray [ Expression ]

An array access expression contains two subexpressions, the array reference expression (before the left bracket) and the index expression (within the brackets). Note that the array reference expression may be a name or any primary expression that is not an array creation expression (§15.9).

The type of the array reference expression must be an array type (call it T[], an array whose components are of type T) or a compile-time error results. Then the type of the array access expression is T.

The index expression undergoes unary numeric promotion (§5.6.1); the promoted type must be int.

The result of an array reference is a variable of type T, namely the variable within the array selected by the value of the index expression. This resulting variable, which is a component of the array, is never considered final, even if the array reference was obtained from a final variable.


15.12.1 Run-time Evaluation

An array access expression is evaluated using the following procedure:

  • First, the array reference expression is evaluated. If this evaluation completes abruptly, then the array access completes abruptly for the same reason and the index expression is not evaluated.
  • Otherwise, the index expression is evaluated. If this evaluation completes abruptly, then the array access completes abruptly for the same reason.
  • Otherwise, if the value of the array reference expression is null, then a NullPointerException is thrown.
  • Otherwise, the value of the array reference expression indeed refers to an array. If the value of the index expression is less than zero, or greater than or equal to the array's length, then an IndexOutOfBoundsException is thrown.
  • Otherwise, the result of the array reference is the variable of type T, within the array, selected by the value of the index expression. (Note that this resulting variable, which is a component of the array, is never considered final, even if the array reference expression is a final variable.)


15.12.2 Examples: Array Access Evaluation Order

In an array access, the expression to the left of the brackets appears to be fully evaluated before any part of the expression within the brackets is evaluated. For example, in the (admittedly monstrous) expression a[(a=b)[3]], the expression a is fully evaluated before the expression (a=b)[3]; this means that the original value of a is fetched and remembered while the expression (a=b)[3] is evaluated. This array referenced by the original value of a is then subscripted by a value that is element 3 of another array (possibly the same array) that was referenced by b and is now also referenced by a.

Thus, the example:

class Test {
    public static void main(String[] args) {
        int[] a = { 11, 12, 13, 14 };
        int[] b = { 0, 1, 2, 3 };
        System.out.println(a[(a=b)[3]]);
    }
}

prints:

14

because the monstrous expression's value is equivalent to a[b[3]] or a[3] or 14.

If evaluation of the expression to the left of the brackets completes abruptly, no part of the expression within the brackets will appear to have been evaluated. Thus, the example:

class Test {
    public static void main(String[] args) {
        int index = 1;
        try {
            skedaddle()[index=2]++;
        } catch (Exception e) {
            System.out.println(e + ", index=" + index);
        }
    }
    static int[] skedaddle() throws Exception {
        throw new Exception("Ciao");
    }
}

prints:

java.lang.Exception: Ciao, index=1

because the embedded assignment of 2 to index never occurs.

If the array reference expression produces null instead of a reference to an array, then a NullPointerException is thrown at run time, but only after all parts of the array reference expression have been evaluated and only if these evaluations completed normally. Thus, the example:

class Test {

    public static void main(String[] args) {
        int index = 1;
        try {
            nada()[index=2]++;
        } catch (Exception e) {
            System.out.println(e + ", index=" + index);
        }
    }
    static int[] nada() { return null; }
}

prints:

java.lang.NullPointerException, index=2

because the embedded assignment of 2 to index occurs before the check for a null pointer. As a related example, the program:

class Test {

    public static void main(String[] args) {
        int[] a = null;
        try {
            int i = a[vamoose()];
            System.out.println(i);
        } catch (Exception e) {
            System.out.println(e);
        }
    }

    static int vamoose() throws Exception {
        throw new Exception("Twenty-three skidoo!");
    }
}

always prints:

java.lang.Exception: Twenty-three skidoo!

A NullPointerException never occurs, because the index expression must be completely evaluated before any part of the indexing operation occurs, and that includes the check as to whether the value of the left-hand operand is null.


15.13 Postfix Expressions

Postfix expressions include uses of the postfix ++ and -- operators. Also, as discussed in §15.7, names are not considered to be primary expressions, but are handled separately in the grammar to avoid certain ambiguities. They become interchangeable only here, at the level of precedence of postfix expressions.

PostfixExpression:

    Primary

    ExpressionName

    PostIncrementExpression

    PostDecrementExpression


15.13.1 Names

A name occurring in an expression may be, syntactically, an ExpressionName (§6.5). The meaning of such an ExpressionName depends on its form:

  • If it is a simple name, that is, just an Identifier, then there are two cases:
    • If the Identifier occurs within the scope of a parameter or local variable named by that same Identifier, then the type of the ExpressionName is the declared type of the parameter or local variable; moreover, the value of the ExpressionName is a variable, namely, the parameter or local variable itself.
    • Otherwise, the ExpressionName is treated exactly as if it had been the field access expression (§15.10):
    this.Identifier containing the keyword this (§15.7.2).

  • Otherwise, if it is a qualified name of the form PackageName . Identifier, then a compile-time error occurs.
  • Otherwise, if it is a qualified name of the form TypeName . Identifier, then it is refers to a static field of the class or interface named by the TypeName. A compile-time error occurs if TypeName does not name a class or interface. A compile-time error occurs if the class or interface named by TypeName does not contain an accessible static field named by the Identifier. The type of the ExpressionName is the declared type of the static field. The value of the ExpressionName is a variable, namely, the static field itself.
  • Otherwise, it is a qualified name of the form Ename . Identifier, where Ename is itself an ExpressionName, and the ExpressionName is treated exactly as if it had been the field access expression (§15.10): (Ename).Identifier

    containing a parenthesized expression (§15.7.3).


15.13.2 Postfix Increment Operator ++

PostIncrementExpression:

    PostfixExpression ++

A postfix expression followed by a ++ operator is a postfix increment expression. The result of the postfix expression must be a variable of a numeric type, or a compile-time error occurs. The type of the postfix increment expression is the type of the variable. The result of the postfix increment expression is not a variable, but a value.

At run time, if evaluation of the operand expression completes abruptly, then the postfix increment expression completes abruptly for the same reason and no incrementation occurs. Otherwise, the value 1 is added to the value of the variable and the sum is stored back into the variable. Before the addition, binary numeric promotion (§5.6.2) is performed on the value 1 and the value of the variable. If necessary, the sum is narrowed by a narrowing primitive conversion (§5.1.3) to the type of the variable before it is stored. The value of the postfix increment expression is the value of the variable before the new value is stored.

A variable that is declared final cannot be incremented, because when an access of a final variable is used as an expression, the result is a value, not a variable. Thus, it cannot be used as the operand of a postfix increment operator.


15.13.3 Postfix Decrement Operator --

PostDecrementExpression:

    PostfixExpression --

A postfix expression followed by a -- operator is a postfix decrement expression. The result of the postfix expression must be a variable of a numeric type, or a compile-time error occurs. The type of the postfix decrement expression is the type of the variable. The result of the postfix decrement expression is not a variable, but a value.

At run time, if evaluation of the operand expression completes abruptly, then the postfix decrement expression completes abruptly for the same reason and no decrementation occurs. Otherwise, the value 1 is subtracted from the value of the variable and the difference is stored back into the variable. Before the subtraction, binary numeric promotion (§5.6.2) is performed on the value 1 and the value of the variable. If necessary, the difference is narrowed by a narrowing primitive conversion (§5.1.3) to the type of the variable before it is stored. The value of the postfix decrement expression is the value of the variable before the new value is stored.

A variable that is declared final cannot be decremented, because when an access of a final variable is used as an expression, the result is a value, not a variable. Thus, it cannot be used as the operand of a postfix decrement operator.


15.14 Unary Operators

The unary operators include +, -, ++, --, ~, !, and cast operators. Expressions with unary operators group right-to-left, so that -~x means the same as -(~x).

UnaryExpression:

    PreIncrementExpression

    PreDecrementExpression

    + UnaryExpression

    - UnaryExpression

    UnaryExpressionNotPlusMinus

PreIncrementExpression:

    ++ UnaryExpression

PreDecrementExpression:

    -- UnaryExpression

UnaryExpressionNotPlusMinus:

    PostfixExpression

    ~ UnaryExpression

    ! UnaryExpression

    CastExpression

The following productions from §15.15 are repeated here for convenience:

CastExpression:

    ( PrimitiveType ) UnaryExpression

    ( ReferenceType ) UnaryExpressionNotPlusMinus

This portion of the Java grammar contains some tricks to avoid two potential syntactic ambiguities.

The first potential ambiguity would arise in expressions such as (p)+q, which looks, to a C or C++ programmer, as though it could be either be a cast to type p of a unary + operating on q, or a binary addition of two quantities p and q. In C and C++, the parser handles this problem by performing a limited amount of semantic analysis as it parses, so that it knows whether p is the name of a type or the name of a variable.

Java takes a different approach. The result of the + operator must be numeric, and all type names involved in casts on numeric values are known keywords. Thus, if p is a keyword naming a primitive type, then (p)+q can make sense only as a cast of a unary expression. However, if p is not a keyword naming a primitive type, then (p)+q can make sense only as a binary arithmetic operation. Similar remarks apply to the - operator. The grammar shown above splits CastExpression into two cases to make this distinction. The nonterminal UnaryExpression includes all unary operator, but the nonterminal UnaryExpressionNotPlusMinus excludes uses of all unary operators that could also be binary operators, which in Java are + and -.

The second potential ambiguity is that the expression (p)++ could, to a C or C++ programmer, appear to be either a postfix increment of a parenthesized expression or the beginning of a cast, for example, in (p)++q. As before, parsers for C and C++ know whether p is the name of a type or the name of a variable. But a parser using only one-token lookahead and no semantic analysis during the parse would not be able to tell, when ++ is the lookahead token, whether (p) should be considered a Primary expression or left alone for later consideration as part of a CastExpression.

In Java, the result of the ++ operator must be numeric, and all type names involved in casts on numeric values are known keywords. Thus, if p is a keyword naming a primitive type, then (p)++ can make sense only as a cast of a prefix increment expression, and there had better be an operand such as q following the ++. However, if p is not a keyword naming a primitive type, then (p)++ can make sense only as a postfix increment of p. Similar remarks apply to the -- operator. The nonterminal UnaryExpressionNotPlusMinus therefore also excludes uses of the prefix operators ++ and --.


15.14.1 Prefix Increment Operator ++

A unary expression preceded by a ++ operator is a prefix increment expression. The result of the unary expression must be a variable of a numeric type, or a compile-time error occurs. The type of the prefix increment expression is the type of the variable. The result of the prefix increment expression is not a variable, but a value.

At run time, if evaluation of the operand expression completes abruptly, then the prefix increment expression completes abruptly for the same reason and no incrementation occurs. Otherwise, the value 1 is added to the value of the variable and the sum is stored back into the variable. Before the addition, binary numeric promotion (§5.6.2) is performed on the value 1 and the value of the variable. If necessary, the sum is narrowed by a narrowing primitive conversion (§5.1.3) to the type of the variable before it is stored. The value of the prefix increment expression is the value of the variable after the new value is stored.

A variable that is declared final cannot be incremented, because when an access of a final variable is used as an expression, the result is a value, not a variable. Thus, it cannot be used as the operand of a prefix increment operator.


15.14.2 Prefix Decrement Operator --

He must increase, but I must decrease.
—John 3:30

A unary expression preceded by a -- operator is a prefix decrement expression. The result of the unary expression must be a variable of a numeric type, or a compile-time error occurs. The type of the prefix decrement expression is the type of the variable. The result of the prefix decrement expression is not a variable, but a value.

At run time, if evaluation of the operand expression completes abruptly, then the prefix decrement expression completes abruptly for the same reason and no decrementation occurs. Otherwise, the value 1 is subtracted from the value of the variable and the difference is stored back into the variable. Before the subtraction, binary numeric promotion (§5.6.2) is performed on the value 1 and the value of the variable. If necessary, the difference is narrowed by a narrowing primitive conversion (§5.1.3) to the type of the variable before it is stored. The value of the prefix decrement expression is the value of the variable after the new value is stored.

A variable that is declared final cannot be decremented, because when an access of a final variable is used as an expression, the result is a value, not a variable. Thus, it cannot be used as the operand of a prefix decrement operator.


15.14.3 Unary Plus Operator +

The type of the operand expression of the unary + operator must be a primitive numeric type, or a compile-time error occurs. Unary numeric promotion (§5.6.1) is performed on the operand. The type of the unary plus expression is the promoted type of the operand. The result of the unary plus expression is not a variable, but a value, even if the result of the operand expression is a variable.

At run time, the value of the unary plus expression is the promoted value of the operand.


15.14.4 Unary Minus Operator -

The type of the operand expression of the unary - operator must be a primitive numeric type, or a compile-time error occurs. Unary numeric promotion (§5.6.1) is performed on the operand. The type of the unary minus expression is the promoted type of the operand.

At run time, the value of the unary plus expression is the arithmetic negation of the promoted value of the operand.

For integer values, negation is the same as subtraction from zero. Java uses two's-complement representation for integers, and the range of two's-complement values is not symmetric, so negation of the maximum negative int or long results in that same maximum negative number. Overflow occurs in this case, but no exception is thrown. For all integer values x, -x equals (~x)+1.

For floating-point values, negation is not the same as subtraction from zero, because if x is +0.0, then 0.0-x equals +0.0, but -x equals -0.0. Unary minus merely inverts the sign of a floating-point number. Special cases of interest:

  • If the operand is NaN, the result is NaN (recall that NaN has no sign).
  • If the operand is an infinity, the result is the infinity of opposite sign.
  • If the operand is a zero, the result is the zero of opposite sign.


15.14.5 Bitwise Complement Operator ~

The type of the operand expression of the unary ~ operator must be a primitive integral type, or a compile-time error occurs. Unary numeric promotion (§5.6.1) is performed on the operand. The type of the unary bitwise complement expression is the promoted type of the operand.

At run time, the value of the unary bitwise complement expression is the bitwise complement of the promoted value of the operand; note that, in all cases, ~x equals (-x)-1.


15.14.6 Logical Complement Operator !

The type of the operand expression of the unary ! operator must be boolean, or a compile-time error occurs. The type of the unary logical complement expression is boolean.

At run time, the value of the unary logical complement expression is true if the operand value is false and false if the operand value is true.


15.15 Cast Expressions

My days among the dead are passed;
Around me I behold,
Where'er these casual eyes are cast,
The mighty minds of old . . .
—Robert Southey (1774-1843), Occasional Pieces, xviii

A cast expression converts, at run time, a value of one numeric type to a similar value of another numeric type; or confirms, at compile time, that the type of an expression is boolean; or checks, at run time, that a reference value refers to an object whose class is compatible with a specified reference type.

CastExpression:

    ( PrimitiveType Dimsopt ) UnaryExpression

    ( ReferenceType ) UnaryExpressionNotPlusMinus

See §15.14 for a discussion of the distinction between UnaryExpression and UnaryExpressionNotPlusMinus.

The type of a cast expression is the type whose name appears within the parentheses. (The parentheses and the type they contain are sometimes called the cast operator.) The result of a cast expression is not a variable, but a value, even if the result of the operand expression is a variable.

At run time, the operand value is converted by casting conversion (§5.4) to the type specified by the cast operator.

Not all casts are permitted by the Java language. Some casts result in an error at compile time. For example, a primitive value may not be cast to a reference type. Some casts can be proven, at compile time, always to be correct at run time. For example, it is always correct to convert a value of a class type to the type of its superclass; such a cast should require no special action at run time. Finally, some casts cannot be proven to be either always correct or always incorrect at compile time. Such casts require a test at run time. A ClassCastException is thrown if a cast is found at run time to be impermissible.


15.16 Multiplicative Operators

The operators *, /, and % are called the multiplicative operators. They have the same precedence and are syntactically left-associative (they group left-to-right).

MultiplicativeExpression:

    UnaryExpression

    MultiplicativeExpression * UnaryExpression

    MultiplicativeExpression / UnaryExpression

    MultiplicativeExpression % UnaryExpression

The type of each of the operands of a multiplicative operator must be a primitive numeric type, or a compile-time error occurs. Binary numeric promotion is performed on the operands (§5.6.2). The type of a multiplicative expression is the promoted type of its operands. If this promoted type is int or long, then integer arithmetic is performed; if this promoted type is float or double, then floating-point arithmetic is performed.


15.16.1 Multiplication Operator *

Entia non sunt multiplicanda praeter necessitatem.
—William of Occam (c. 1320)

The binary * operator performs multiplication, producing the product of its operands. Multiplication is a commutative operation if the operand expressions have no side effects. While integer multiplication is associative when the operands are all of the same type, floating-point multiplication is not associative.

If an integer multiplication overflows, then the result is the low-order bits of the mathematical product as represented in some sufficiently large two's-complement format. As a result, if overflow occurs, then the sign of the result may not be the same as the sign of the mathematical product of the two operand values.

The result of a floating-point multiplication is governed by the rules of IEEE 754 arithmetic:

  • If either operand is NaN, the result is NaN.
  • If the result is not NaN, the sign of the result is positive if both operands have the same sign, and negative if the operands have different signs.
  • Multiplication of an infinity by a zero results in NaN.
  • Multiplication of an infinity by a finite value results in a signed infinity. The sign is determined by the rule stated above.
  • In the remaining cases, where neither an infinity or NaN is involved, the product is computed. If the magnitude of the product is too large to represent, we say the operation overflows. The result is then an infinity of appropriate sign. If the magnitude is too small to represent, we say the operation underflows; the result is then a zero of appropriate sign. Otherwise, the product is rounded to the nearest representable value using IEEE 754 round-to-nearest mode. The Java language requires support of gradual underflow as defined by IEEE 754 (§4.2.4).

Despite the fact that overflow, underflow, or loss of information may occur, evaluation of a multiplication operator * never throws a run-time exception.


15.16.2 Division Operator /

Gallia est omnis divisa in partes tres.
—Julius Caesar, Commentaries on the Gallic Wars (58 B.C.)

The binary / operator performs division, producing the quotient of its operands. The left-hand operand is the dividend and the right-hand operand is the divisor.

Integer division rounds toward 0. That is, the quotient produced for operands n and d that are integers after binary numeric promotion (§5.6.2) is an integer value q whose magnitude is as large as possible while satisfying [image]; moreover, q is positive when [image] and n and d have the same sign, but q is negative when [image] and n and d have opposite signs. There is one special case that does not satisfy this rule: if the dividend is the negative integer of largest possible magnitude for its type, and the divisor is -1, then integer overflow occurs and the result is equal to the dividend. Despite the overflow, no exception is thrown in this case. On the other hand, if the value of the divisor in an integer division is 0, then an ArithmeticException is thrown.

The result of a floating-point division is determined by the specification of IEEE arithmetic:

  • If either operand is NaN, the result is NaN.
  • If the result is not NaN, the sign of the result is positive if both operands have the same sign, negative if the operands have different signs.
  • Division of an infinity by an infinity results in NaN.
  • Division of an infinity by a finite value results in a signed infinity. The sign is determined by the rule stated above.
  • Division of a finite value by an infinity results in a signed zero. The sign is determined by the rule stated above.
  • Division of a zero by a zero results in NaN; division of zero by any other finite value results in a signed zero. The sign is determined by the rule stated above.
  • Division of a nonzero finite value by a zero results in a signed infinity. The sign is determined by the rule stated above.
  • In the remaining cases, where neither an infinity, nor a zero, nor NaN is involved, the quotient is computed. If the magnitude of the quotient is too large to represent, we say the operation overflows; the result is then an infinity of appropriate sign. If the magnitude is too small to represent, we say the operation underflows and the result is then a zero of appropriate sign. Otherwise, the quotient is rounded to the nearest representable value using IEEE 754 round-to-nearest mode. The Java language requires support of gradual underflow as defined by IEEE 754 (§4.2.4).

Despite the fact that overflow, underflow, division by zero, or loss of information may occur, evaluation of a floating-point division operator / never throws a run-time exception.


15.16.3 Remainder Operator %

And on the pedestal these words appear:
"My name is Ozymandias, king of kings:
Look on my works, ye Mighty, and despair!"
Nothing beside remains.
—Percy Bysshe Shelley, Ozymandias (1817)

The binary % operator is said to yield the remainder of its operands from an implied division; the left-hand operand is the dividend and the right-hand operand is the divisor.

In C and C++, the remainder operator accepts only integral operands, but in Java, it also accepts floating-point operands.

The remainder operation for operands that are integers after binary numeric promotion (§5.6.2) produces a result value such that (a/b)*b+(a%b) is equal to a. This identity holds even in the special case that the dividend is the negative integer of largest possible magnitude for its type and the divisor is -1 (the remainder is 0). It follows from this rule that the result of the remainder operation can be negative only if the dividend is negative, and can be positive only if the dividend is positive; moreover, the magnitude of the result is always less than the magnitude of the divisor. If the value of the divisor for an integer remainder operator is 0, then an ArithmeticException is thrown.

Examples:

5%3 produces 2		(note that 5/3 produces 1)
5%(-3) produces 2		(note that 5/(-3) produces -1)
(-5)%3 produces -2		(note that (-5)/3 produces -1)
(-5)%(-3) produces -2		(note that (-5)/(-3) produces 1)

The result of a floating-point remainder operation as computed by the % operator is not the same as that produced by the remainder operation defined by IEEE 754. The IEEE 754 remainder operation computes the remainder from a rounding division, not a truncating division, and so its behavior is not analogous to that of the usual integer remainder operator. Instead, the Java language defines % on floating-point operations to behave in a manner analogous to that of the Java integer remainder operator; this may be compared with the C library function fmod. The IEEE 754 remainder operation may be computed by the Java library routine Math.IEEEremainder (§20.11.14).

The result of a Java floating-point remainder operation is determined by the rules of IEEE arithmetic:

  • If either operand is NaN, the result is NaN.
  • If the result is not NaN, the sign of the result equals the sign of the dividend.
  • If the dividend is an infinity, or the divisor is a zero, or both, the result is NaN.
  • If the dividend is finite and the divisor is an infinity, the result equals the dividend.
  • If the dividend is a zero and the divisor is finite, the result equals the dividend.
  • In the remaining cases, where neither an infinity, nor a zero, nor NaN is involved, the floating-point remainder r from the division of a dividend n by a divisor d is defined by the mathematical relation [image] where q is an integer that is negative only if [image] is negative and positive only if [image] is positive, and whose magnitude is as large as possible without exceeding the magnitude of the true mathematical quotient of n and d.

Evaluation of a floating-point remainder operator % never throws a run-time exception, even if the right-hand operand is zero. Overflow, underflow, or loss of precision cannot occur.

Examples:

5.0%3.0 produces 2.0
5.0%(-3.0) produces 2.0
(-5.0)%3.0 produces -2.0
(-5.0)%(-3.0) produces -2.0


15.17 Additive Operators

The operators + and - are called the additive operators. They have the same precedence and are syntactically left-associative (they group left-to-right).

AdditiveExpression:

    MultiplicativeExpression

    AdditiveExpression + MultiplicativeExpression

    AdditiveExpression - MultiplicativeExpression

If the type of either operand of a + operator is String, then the operation is string concatenation.

Otherwise, the type of each of the operands of the + operator must be a primitive numeric type, or a compile-time error occurs.

In every case, the type of each of the operands of the binary - operator must be a primitive numeric type, or a compile-time error occurs.


15.17.1 String Concatenation Operator +

If only one operand expression is of type String, then string conversion is performed on the other operand to produce a string at run time. The result is a reference to a newly created String object that is the concatenation of the two operand strings. The characters of the left-hand operand precede the characters of the right-hand operand in the newly created string.

15.17.1.1 String Conversion

Any type may be converted to type String by string conversion.

A value x of primitive type T is first converted to a reference value as if by giving it as an argument to an appropriate class instance creation expression:

  • If T is boolean, then use new Boolean(x) (§20.4).
  • If T is char, then use new Character(x) (§20.5).
  • If T is byte, short, or int, then use new Integer(x) (§20.7).
  • If T is long, then use new Long(x) (§20.8).
  • If T is float, then use new Float(x) (§20.9).
  • If T is double, then use new Double(x) (§20.10).

This reference value is then converted to type String by string conversion.

Now only reference values need to be considered. If the reference is null, it is converted to the string "null" (four ASCII characters n, u, l, l). Otherwise, the conversion is performed as if by an invocation of the toString method of the referenced object with no arguments; but if the result of invoking the toString method is null, then the string "null" is used instead. The toString method (§20.1.2) is defined by the primordial class Object (§20.1); many classes override it, notably Boolean, Character, Integer, Long, Float, Double, and String.

15.17.1.2 Optimization of String Concatenation

An implementation may choose to perform conversion and concatenation in one step to avoid creating and then discarding an intermediate String object. To increase the performance of repeated string concatenation, a Java compiler may use the StringBuffer class (§20.13) or a similar technique to reduce the number of intermediate String objects that are created by evaluation of an expression.

For primitive objects, an implementation may also optimize away the creation of a wrapper object by converting directly from a primitive type to a string.

15.17.1.3 Examples of String Concatenation

The example expression:

"The square root of 2 is " + Math.sqrt(2)

produces the result:

"The square root of 2 is 1.4142135623730952"

The + operator is syntactically left-associative, no matter whether it is later determined by type analysis to represent string concatenation or addition. In some cases care is required to get the desired result. For example, the expression:

a + b + c

is always regarded as meaning:

(a + b) + c

Therefore the result of the expression:

1 + 2 + " fiddlers"

is:

"3 fiddlers"

but the result of:

"fiddlers " + 1 + 2

is:

"fiddlers 12"

In this jocular little example:

class Bottles {

    static void printSong(Object stuff, int n) {
        String plural = "s";
        loop: while (true) {
            System.out.println(n + " bottle" + plural
                + " of " + stuff + " on the wall,");
            System.out.println(n + " bottle" + plural
                + " of " + stuff + ";");
            System.out.println("You take one down "
                + "and pass it around:");
            --n;
            plural = (n == 1) ? "" : "s";
            if (n == 0)
                break loop;
            System.out.println(n + " bottle" + plural
                + " of " + stuff + " on the wall!");
            System.out.println();
        }
        System.out.println("No bottles of " +
                                stuff + " on the wall!");
    }

}

the method printSong will print a version of a children's song. Popular values for stuff include "pop" and "beer"; the most popular value for n is 100. Here is the output that results from Bottles.printSong("slime", 3):

3 bottles of slime on the wall,
3 bottles of slime;
You take one down and pass it around:
2 bottles of slime on the wall!

2 bottles of slime on the wall,
2 bottles of slime;
You take one down and pass it around:
1 bottle of slime on the wall!

1 bottle of slime on the wall,
1 bottle of slime;
You take one down and pass it around:
No bottles of slime on the wall!

In the code, note the careful conditional generation of the singular "bottle" when appropriate rather than the plural "bottles"; note also how the string concatenation operator was used to break the long constant string:

"You take one down and pass it around:"

into two pieces to avoid an inconveniently long line in the source code.


15.17.2 Additive Operators (+ and -) for Numeric Types

The binary + operator performs addition when applied to two operands of numeric type, producing the sum of the operands. The binary - operator performs subtraction, producing the difference of two numeric operands.

Binary numeric promotion is performed on the operands (§5.6.2). The type of an additive expression on numeric operands is the promoted type of its operands. If this promoted type is int or long, then integer arithmetic is performed; if this promoted type is float or double, then floating-point arithmetic is performed.

Addition is a commutative operation if the operand expressions have no side effects. Integer addition is associative when the operands are all of the same type, but floating-point addition is not associative.

If an integer addition overflows, then the result is the low-order bits of the mathematical sum as represented in some sufficiently large two's-complement format. If overflow occurs, then the sign of the result is not the same as the sign of the mathematical sum of the two operand values.

The result of a floating-point addition is determined using the following rules of IEEE arithmetic:

  • If either operand is NaN, the result is NaN.
  • The sum of two infinities of opposite sign is NaN.
  • The sum of two infinities of the same sign is the infinity of that sign.
  • The sum of an infinity and a finite value is equal to the infinite operand.
  • The sum of two zeros of opposite sign is positive zero.
  • The sum of two zeros of the same sign is the zero of that sign.
  • The sum of a zero and a nonzero finite value is equal to the nonzero operand.
  • The sum of two nonzero finite values of the same magnitude and opposite sign is positive zero.
  • In the remaining cases, where neither an infinity, nor a zero, nor NaN is involved, and the operands have the same sign or have different magnitudes, the sum is computed. If the magnitude of the sum is too large to represent, we say the operation overflows; the result is then an infinity of appropriate sign. If the magnitude is too small to represent, we say the operation underflows; the result is then a zero of appropriate sign. Otherwise, the sum is rounded to the nearest representable value using IEEE 754 round-to-nearest mode. The Java language requires support of gradual underflow as defined by IEEE 754 (§4.2.4).

The binary - operator performs subtraction when applied to two operands of numeric type producing the difference of its operands; the left-hand operand is the minuend and the right-hand operand is the subtrahend. For both integer and floating-point subtraction, it is always the case that a-b produces the same result as a+(-b). Note that, for integer values, subtraction from zero is the same as negation. However, for floating-point operands, subtraction from zero is not the same as negation, because if x is +0.0, then 0.0-x equals +0.0, but -x equals -0.0.

Despite the fact that overflow, underflow, or loss of information may occur, evaluation of a numeric additive operator never throws a run-time exception.


15.18 Shift Operators

What, I say, is to become of those wretches?
. . . What more can you say to them than "shift for yourselves?"
--Thomas Paine, The American Crisis (1780)

The shift operators include left shift <<, signed right shift >>, and unsigned right shift >>>; they are syntactically left-associative (they group left-to-right). The left- hand operand of a shift operator is the value to be shifted; the right-hand operand specifies the shift distance.

ShiftExpression:

    AdditiveExpression

    ShiftExpression << AdditiveExpression

    ShiftExpression >> AdditiveExpression

    ShiftExpression >>> AdditiveExpression

The type of each of the operands of a shift operator must be a primitive integral type, or a compile-time error occurs. Binary numeric promotion (§5.6.2) is not performed on the operands; rather, unary numeric promotion (§5.6.1) is performed on each operand separately. The type of the shift expression is the promoted type of the left-hand operand.

If the promoted type of the left-hand operand is int, only the five lowest-order bits of the right-hand operand are used as the shift distance. It is as if the right-hand operand were subjected to a bitwise logical AND operator & (§15.21.1) with the mask value 0x1f. The shift distance actually used is therefore always in the range 0 to 31, inclusive.

If the promoted type of the left-hand operand is long, then only the six lowest-order bits of the right-hand operand are used as the shift distance. It is as if the right-hand operand were subjected to a bitwise logical AND operator & (§15.21.1) with the mask value 0x3f. The shift distance actually used is therefore always in the range 0 to 63, inclusive.

At run time, shift operations are performed on the two's complement integer representation of the value of the left operand.

The value of n<<s is n left-shifted s bit positions; this is equivalent (even if overflow occurs) to multiplication by two to the power s.

The value of n>>s is n right-shifted s bit positions with sign-extension. The resulting value is [image]. For nonnegative values of n, this is equivalent to truncating integer division, as computed by the integer division operator /, by two to the power s.

The value of n>>>s is n right-shifted s bit positions with zero-extension. If n is positive, then the result is the same as that of n>>s; if n is negative, the result is equal to that of the expression (n>>s)+(2<<~s) if the type of the left-hand operand is int, and to the result of the expression (n>>s)+(2L<<~s) if the type of the left-hand operand is long. The added term (2<<~s) or (2L<<~s) cancels out the propagated sign bit. (Note that, because of the implicit masking of the right-hand operand of a shift operator, ~s as a shift distance is equivalent to 31-s when shifting an int value and to 63-s when shifting a long value.)


15.19 Relational Operators

The relational operators are syntactically left-associative (they group left-to- right), but this fact is not useful; for example, a<b<c parses as (a<b)<c, which is always a compile-time error, because the type of a<b is always boolean and < is not an operator on boolean values.

RelationalExpression:

    ShiftExpression

    RelationalExpression < ShiftExpression

    RelationalExpression > ShiftExpression

    RelationalExpression <= ShiftExpression

    RelationalExpression >= ShiftExpression

    RelationalExpression instanceof ReferenceType

The type of a relational expression is always boolean.


15.19.1 Numerical Comparison Operators <, <=, >, and >=

The type of each of the operands of a numerical comparison operator must be a primitive numeric type, or a compile-time error occurs. Binary numeric promotion is performed on the operands (§5.6.2). If the promoted type of the operands is int or long, then signed integer comparison is performed; if this promoted type is float or double, then floating-point comparison is performed.

The result of a floating-point comparison, as determined by the specification of the IEEE 754 standard, is:

  • If either operand is NaN, then the result is false.
  • All values other than NaN are ordered, with negative infinity less than all finite values, and positive infinity greater than all finite values.
  • Positive zero and negative zero are considered equal. Therefore, -0.0<0.0 is false, for example, but -0.0<=0.0 is true. (Note, however, that the methods Math.min (§20.11.27, §20.11.28) and Math.max (§20.11.31, §20.11.32) treat negative zero as being strictly smaller than positive zero.)

Subject to these considerations for floating-point numbers, the following rules then hold for integer operands or for floating-point operands other than NaN:

  • The value produced by the < operator is true if the value of the left-hand operand is less than the value of the right-hand operand, and otherwise is false.
  • The value produced by the <= operator is true if the value of the left-hand operand is less than or equal to the value of the right-hand operand, and otherwise is false.
  • The value produced by the > operator is true if the value of the left-hand operand is greater than the value of the right-hand operand, and otherwise is false.
  • The value produced by the >= operator is true if the value of the left-hand operand is greater than or equal to the value of the right-hand operand, and otherwise is false.


15.19.2 Type Comparison Operator instanceof

The type of a RelationalExpression operand of the instanceof operator must be a reference type or the null type; otherwise, a compile-time error occurs. The ReferenceType mentioned after the instanceof operator must denote a reference type; otherwise, a compile-time error occurs.

At run time, the result of the instanceof operator is true if the value of the RelationalExpression is not null and the reference could be cast (§15.15) to the ReferenceType without raising a ClassCastException. Otherwise the result is false.

If a cast of the RelationalExpression to the ReferenceType would be rejected as a compile-time error, then the instanceof relational expression likewise produces a compile-time error. In such a situation, the result of the instanceof expression could never be true.

Consider the example program:

class Point { int x, y; }
class Element { int atomicNumber; }
class Test {
    public static void main(String[] args) {
        Point p = new Point();
        Element e = new Element();
        if (e instanceof Point) { // compile-time error
            System.out.println("I get your point!");
            p = (Point)e; // compile-time error
        }
    }
}

This example results in two compile-time errors. The cast (Point)e is incorrect because no instance of Element or any of its possible subclasses (none are shown here) could possibly be an instance of any subclass of Point. The instanceof expression is incorrect for exactly the same reason. If, on the other hand, the class Point were a subclass of Element (an admittedly strange notion in this example):

class Point extends Element { int x, y; }

then the cast would be possible, though it would require a run-time check, and the instanceof expression would then be sensible and valid. The cast (Point)e would never raise an exception because it would not be executed if the value of e could not correctly be cast to type Point.


15.20 Equality Operators

The equality operators are syntactically left-associative (they group left-to-right), but this fact is essentially never useful; for example, a==b==c parses as (a==b)==c. The result type of a==b is always boolean, and c must therefore be of type boolean or a compile-time error occurs. Thus, a==b==c does not test to see whether a, b, and c are all equal.

EqualityExpression:

    RelationalExpression

    EqualityExpression == RelationalExpression

    EqualityExpression != RelationalExpression

The == (equal to) and the != (not equal to) operators are analogous to the relational operators except for their lower precedence. Thus, a<b==c<d is true whenever a<b and c<d have the same truth value.

The equality operators may be used to compare two operands of numeric type, or two operands of type boolean, or two operands that are each of either reference type or the null type. All other cases result in a compile-time error. The type of an equality expression is always boolean.

In all cases, a!=b produces the same result as !(a==b). The equality operators are commutative if the operand expressions have no side effects.


15.20.1 Numerical Equality Operators == and !=

If the operands of an equality operator are both of primitive numeric type, binary numeric promotion is performed on the operands (§5.6.2). If the promoted type of the operands is int or long, then an integer equality test is performed; if the promoted type is float or double, then a floating-point equality test is performed.

Floating-point equality testing is performed in accordance with the rules of the IEEE 754 standard:

  • If either operand is NaN, then the result of == is false but the result of != is true. Indeed, the test x!=x is true if and only if the value of x is NaN. (The methods Float.isNaN (§20.9.19) and Double.isNaN (§20.10.17) may also be used to test whether a value is NaN.)
  • Positive zero and negative zero are considered equal. Therefore, -0.0==0.0 is true, for example.
  • Otherwise, two distinct floating-point values are considered unequal by the equality operators. In particular, there is one value representing positive infinity and one value representing negative infinity; each compares equal only to itself, and each compares unequal to all other values.

Subject to these considerations for floating-point numbers, the following rules then hold for integer operands or for floating-point operands other than NaN:

  • The value produced by the == operator is true if the value of the left-hand operand is equal to the value of the right-hand operand; otherwise, the result is false.
  • The value produced by the != operator is true if the value of the left-hand operand is not equal to the value of the right-hand operand; otherwise, the result is false.


15.20.2 Boolean Equality Operators == and !=

If the operands of an equality operator are both of type boolean, then the operation is boolean equality. The boolean equality operators are associative.

The result of == is true if the operands are both true or both false; otherwise, the result is false.

The result of != is false if the operands are both true or both false; otherwise, the result is true. Thus != behaves the same as ^ (§15.21.2) when applied to boolean operands.


15.20.3 Reference Equality Operators == and !=

Things are more like they are now than they ever were before.
--Dwight D. Eisenhower

If the operands of an equality operator are both of either reference type or the null type, then the operation is object equality.

A compile-time error occurs if it is impossible to convert the type of either operand to the type of the other by a casting conversion (§5.4). The run-time values of the two operands would necessarily be unequal.

At run time, the result of == is true if the operand values are both null or both refer to the same object or array; otherwise, the result is false.

The result of != is false if the operand values are both null or both refer to the same object or array; otherwise, the result is true.

While == may be used to compare references of type String, such an equality test determines whether or not the two operands refer to the same String object. The result is false if the operands are distinct String objects, even if they contain the same sequence of characters. The contents of two strings s and t can be tested for equality by the method invocation s.equals(t) (§20.12.9). See also §3.10.5 and §20.12.47.


15.21 Bitwise and Logical Operators

The bitwise operators and logical operators include the AND operator &, exclusive OR operator ^, and inclusive OR operator |. These operators have different precedence, with & having the highest precedence and | the lowest precedence. Each of these operators is syntactically left-associative (each groups left-to-right). Each operator is commutative if the operand expressions have no side effects. Each operator is associative.

AndExpression:

    EqualityExpression

    AndExpression & EqualityExpression

ExclusiveOrExpression:

    AndExpression

    ExclusiveOrExpression ^ AndExpression

InclusiveOrExpression:

    ExclusiveOrExpression

    InclusiveOrExpression | ExclusiveOrExpression

The bitwise and logical operators may be used to compare two operands of numeric type or two operands of type boolean. All other cases result in a compile-time error.


15.21.1 Integer Bitwise Operators &, ^, and |

When both operands of an operator &, ^, or | are of primitive integral type, binary numeric promotion is first performed on the operands (§5.6.2). The type of the bitwise operator expression is the promoted type of the operands.

For &, the result value is the bitwise AND of the operand values.

For ^, the result value is the bitwise exclusive OR of the operand values.

For |, the result value is the bitwise inclusive OR of the operand values.

For example, the result of the expression 0xff00 & 0xf0f0 is 0xf000. The result of 0xff00 ^ 0xf0f0 is 0x0ff0.The result of 0xff00 | 0xf0f0 is 0xfff0.


15.21.2 Boolean Logical Operators &, ^, and |

When both operands of a &, ^, or | operator are of type boolean, then the type of the bitwise operator expression is boolean.

For &, the result value is true if both operand values are true; otherwise, the result is false.

For ^, the result value is true if the operand values are different; otherwise, the result is false.

For |, the result value is false if both operand values are false; otherwise, the result is true.


15.22 Conditional-And Operator &&

The && operator is like & (§15.21.2), but evaluates its right-hand operand only if the value of its left-hand operand is true. It is syntactically left-associative (it groups left-to-right). It is fully associative with respect to both side effects and result value; that is, for any expressions a, b, and c, evaluation of the expression ((a)&&(b))&&(c) produces the same result, with the same side effects occurring in the same order, as evaluation of the expression (a)&&((b)&&(c)).

ConditionalAndExpression:

    InclusiveOrExpression

    ConditionalAndExpression && InclusiveOrExpression

Each operand of && must be of type boolean, or a compile-time error occurs. The type of a conditional-and expression is always boolean.

At run time, the left-hand operand expression is evaluated first; if its value is false, the value of the conditional-and expression is false and the right-hand operand expression is not evaluated. If the value of the left-hand operand is true, then the right-hand expression is evaluated and its value becomes the value of the conditional-and expression. Thus, && computes the same result as & on boolean operands. It differs only in that the right-hand operand expression is evaluated conditionally rather than always.


15.23 Conditional-Or Operator ||

The || operator is like | (§15.21.2), but evaluates its right-hand operand only if the value of its left-hand operand is false. It is syntactically left-associative (it groups left-to-right). It is fully associative with respect to both side effects and result value; that is, for any expressions a, b, and c, evaluation of the expression ((a)||(b))||(c) produces the same result, with the same side effects occurring in the same order, as evaluation of the expression (a)||((b)||(c)).

ConditionalOrExpression:

    ConditionalAndExpression

    ConditionalOrExpression || ConditionalAndExpression

Each operand of || must be of type boolean, or a compile-time error occurs. The type of a conditional-or expression is always boolean.

At run time, the left-hand operand expression is evaluated first; if its value is true, the value of the conditional-or expression is true and the right-hand operand expression is not evaluated. If the value of the left-hand operand is false, then the right-hand expression is evaluated and its value becomes the value of the conditional-or expression. Thus, || computes the same result as | on boolean operands. It differs only in that the right-hand operand expression is evaluated conditionally rather than always.


15.24 Conditional Operator ? :

The conditional operator ? : uses the boolean value of one expression to decide which of two other expressions should be evaluated.

The conditional operator is syntactically right-associative (it groups right-to-left), so that a?b:c?d:e?f:g means the same as a?b:(c?d:(e?f:g)).

ConditionalExpression:

    ConditionalOrExpression

    ConditionalOrExpression ? Expression : ConditionalExpression

The conditional operator has three operand expressions; ? appears between the first and second expressions, and : appears between the second and third expressions.

The first expression must be of type boolean, or a compile-time error occurs.

The conditional operator may be used to choose between second and third operands of numeric type, or second and third operands of type boolean, or second and third operands that are each of either reference type or the null type. All other cases result in a compile-time error.

Note that it is not permitted for either the second or the third operand expression to be an invocation of a void method. In fact, it is not permitted for a conditional expression to appear in any context where an invocation of a void method could appear (§14.7).

The type of a conditional expression is determined as follows:

  • If the second and third operands have the same type (which may be the null type), then that is the type of the conditional expression.
  • Otherwise, if the second and third operands have numeric type, then there are several cases:
    • If one of the operands is of type byte and the other is of type short, then the type of the conditional expression is short.
    • If one of the operands is of type T where T is byte, short, or char, and the other operand is a constant expression of type int whose value is representable in type T, then the type of the conditional expression is T.
    • Otherwise, binary numeric promotion (§5.6.2) is applied to the operand types, and the type of the conditional expression is the promoted type of the second and third operands.
  • If one of the second and third operands is of the null type and the type of the other is a reference type, then the type of the conditional expression is that reference type.
  • If the second and third operands are of different reference types, then it must be possible to convert one of the types to the other type (call this latter type T) by assignment conversion (§5.2); the type of the conditional expression is T. It is a compile-time error if neither type is assignment compatible with the other type.

At run time, the first operand expression of the conditional expression is evaluated first; its boolean value is then used to choose either the second or the third operand expression:

  • If the value of the first operand is true, then the second operand expression is chosen.
  • If the value of the first operand is false, then the third operand expression is chosen.

The chosen operand expression is then evaluated and the resulting value is converted to the type of the conditional expression as determined by the rules stated above. The operand expression not chosen is not evaluated for that particular evaluation of the conditional expression.


15.25 Assignment Operators

There are 12 assignment operators; all are syntactically right-associative (they group right-to-left). Thus, a=b=c means a=(b=c), which assigns the value of c to b and then assigns the value of b to a.

AssignmentExpression:

    ConditionalExpression

    Assignment

Assignment:

    LeftHandSide AssignmentOperator AssignmentExpression

LeftHandSide:

    ExpressionName

    FieldAccess

    ArrayAccess

AssignmentOperator: one of

    = *= /= %= += -= <<= >>= >>>= &= ^= |=

The result of the first operand of an assignment operator must be a variable, or a compile-time error occurs. This operand may be a named variable, such as a local variable or a field of the current object or class, or it may be a computed variable, as can result from a field access (§15.10) or an array access (§15.12). The type of the assignment expression is the type of the variable.

At run time, the result of the assignment expression is the value of the variable after the assignment has occurred. The result of an assignment expression is not itself a variable.

A variable that is declared final cannot be assigned to, because when an access of a final variable is used as an expression, the result is a value, not a variable, and so it cannot be used as the operand of an assignment operator.


15.25.1 Simple Assignment Operator =

A compile-time error occurs if the type of the right-hand operand cannot be converted to the type of the variable by assignment conversion (§5.2).

At run time, the expression is evaluated in one of two ways. If the left-hand operand expression is not an array access expression, then three steps are required:

  • First, the left-hand operand is evaluated to produce a variable. If this evaluation completes abruptly, then the assignment expression completes abruptly for the same reason; the right-hand operand is not evaluated and no assignment occurs.
  • Otherwise, the right-hand operand is evaluated. If this evaluation completes abruptly, then the assignment expression completes abruptly for the same reason and no assignment occurs.
  • Otherwise, the value of the right-hand operand is converted to the type of the left-hand variable and the result of the conversion is stored into the variable.

If the left-hand operand expression is an array access expression (§15.12), then many steps are required:

  • First, the array reference subexpression of the left-hand operand array access expression is evaluated. If this evaluation completes abruptly, then the assignment expression completes abruptly for the same reason; the index subexpression (of the left-hand operand array access expression) and the right-hand operand are not evaluated and no assignment occurs.
  • Otherwise, the index subexpression of the left-hand operand array access expression is evaluated. If this evaluation completes abruptly, then the assignment expression completes abruptly for the same reason and the right-hand operand is not evaluated and no assignment occurs.
  • Otherwise, the right-hand operand is evaluated. If this evaluation completes abruptly, then the assignment expression completes abruptly for the same reason and no assignment occurs.
  • Otherwise, if the value of the array reference subexpression is null, then no assignment occurs and a NullPointerException is thrown.
  • Otherwise, the value of the array reference subexpression indeed refers to an array. If the value of the index subexpression is less than zero, or greater than or equal to the length of the array, then no assignment occurs and an IndexOutOfBoundsException is thrown.
  • Otherwise, the value of the index subexpression is used to select a component of the array referred to by the value of the array reference subexpression. This component is a variable; call its type SC. Also, let TC be the type of the left-hand operand of the assignment operator as determined at compile time.
    • If TC is a primitive type, then SC is necessarily the same as TC. The value of the right-hand operand is converted to a value of type TC and stored into the selected array component.
    • If T is a reference type, then SC may not be the same as T, but rather a type that extends or implements TC. Let RC be the class of the object referred to by the value of the right-hand operand at run time. The compiler may be able to prove at compile time that the array component will be of type TC exactly (for example, TC might be final). But if the compiler cannot prove at compile time that the array component will be of type TC exactly, then a check must be performed at run time to ensure that the class RC is assignment compatible (§5.2) with the actual type SC of the array component. This check is similar to a narrowing cast (§5.4, §15.15), except that if the check fails, an ArrayStoreException is thrown rather than a ClassCastException. Therefore:

      • If class RC is not assignable to type SC, then no assignment occurs and an ArrayStoreException is thrown.
      • Otherwise, the reference value of the right-hand operand is stored into the selected array component.

The rules for assignment to an array component are illustrated by the following example program:

class ArrayReferenceThrow extends RuntimeException { }

class IndexThrow extends RuntimeException { }

class RightHandSideThrow extends RuntimeException { }

class IllustrateSimpleArrayAssignment {

    static Object[] objects = { new Object(), new Object() };

    static Thread[] threads = { new Thread(), new Thread() };

    static Object[] arrayThrow() {
        throw new ArrayReferenceThrow();
    }

    static int indexThrow() { throw new IndexThrow(); }

    static Thread rightThrow() {
        throw new RightHandSideThrow();
    }

    static String name(Object q) {
        String sq = q.getClass().getName();
        int k = sq.lastIndexOf('.');
        return (k < 0) ? sq : sq.substring(k+1);
    }

    static void testFour(Object[] x, int j, Object y) {
        String sx = x == null ? "null" : name(x[0]) + "s";
        String sy = name(y);
        System.out.println();
        try {
            System.out.print(sx + "[throw]=throw => ");
            x[indexThrow()] = rightThrow();
            System.out.println("Okay!");
        } catch (Throwable e) { System.out.println(name(e)); }
        try {
            System.out.print(sx + "[throw]=" + sy + " => ");
            x[indexThrow()] = y;
            System.out.println("Okay!");
        } catch (Throwable e) { System.out.println(name(e)); }
        try {
            System.out.print(sx + "[" + j + "]=throw => ");
            x[j] = rightThrow();
            System.out.println("Okay!");
        } catch (Throwable e) { System.out.println(name(e)); }
        try {
            System.out.print(sx + "[" + j + "]=" + sy + " => ");
            x[j] = y;
            System.out.println("Okay!");
        } catch (Throwable e) { System.out.println(name(e)); }
    }

    public static void main(String[] args) {
        try {
            System.out.print("throw[throw]=throw => ");
            arrayThrow()[indexThrow()] = rightThrow();
            System.out.println("Okay!");
        } catch (Throwable e) { System.out.println(name(e)); }
        try {
            System.out.print("throw[throw]=Thread => ");
            arrayThrow()[indexThrow()] = new Thread();
            System.out.println("Okay!");
        } catch (Throwable e) { System.out.println(name(e)); }
        try {
            System.out.print("throw[1]=throw => ");
            arrayThrow()[1] = rightThrow();
            System.out.println("Okay!");
        } catch (Throwable e) { System.out.println(name(e)); }
        try {
            System.out.print("throw[1]=Thread => ");
            arrayThrow()[1] = new Thread();
            System.out.println("Okay!");
        } catch (Throwable e) { System.out.println(name(e)); }

        testFour(null, 1, new StringBuffer());
        testFour(null, 1, new StringBuffer());
        testFour(null, 9, new Thread());
        testFour(null, 9, new Thread());
        testFour(objects, 1, new StringBuffer());
        testFour(objects, 1, new Thread());
        testFour(objects, 9, new StringBuffer());
        testFour(objects, 9, new Thread());
        testFour(threads, 1, new StringBuffer());
        testFour(threads, 1, new Thread());
        testFour(threads, 9, new StringBuffer());
        testFour(threads, 9, new Thread());
    }

}

This program prints:

throw[throw]=throw => ArrayReferenceThrow
throw[throw]=Thread => ArrayReferenceThrow
throw[1]=throw => ArrayReferenceThrow
throw[1]=Thread => ArrayReferenceThrow

null[throw]=throw => IndexThrow
null[throw]=StringBuffer => IndexThrow
null[1]=throw => RightHandSideThrow
null[1]=StringBuffer => NullPointerException

null[throw]=throw => IndexThrow
null[throw]=StringBuffer => IndexThrow
null[1]=throw => RightHandSideThrow
null[1]=StringBuffer => NullPointerException

null[throw]=throw => IndexThrow
null[throw]=Thread => IndexThrow
null[9]=throw => RightHandSideThrow
null[9]=Thread => NullPointerException

null[throw]=throw => IndexThrow
null[throw]=Thread => IndexThrow
null[9]=throw => RightHandSideThrow
null[9]=Thread => NullPointerException

Objects[throw]=throw => IndexThrow
Objects[throw]=StringBuffer => IndexThrow
Objects[1]=throw => RightHandSideThrow
Objects[1]=StringBuffer => Okay!

Objects[throw]=throw => IndexThrow
Objects[throw]=Thread => IndexThrow
Objects[1]=throw => RightHandSideThrow
Objects[1]=Thread => Okay!

Objects[throw]=throw => IndexThrow
Objects[throw]=StringBuffer => IndexThrow
Objects[9]=throw => RightHandSideThrow
Objects[9]=StringBuffer => IndexOutOfBoundsException

Objects[throw]=throw => IndexThrow
Objects[throw]=Thread => IndexThrow
Objects[9]=throw => RightHandSideThrow
Objects[9]=Thread => IndexOutOfBoundsException

Threads[throw]=throw => IndexThrow
Threads[throw]=StringBuffer => IndexThrow
Threads[1]=throw => RightHandSideThrow
Threads[1]=StringBuffer => ArrayStoreException

Threads[throw]=throw => IndexThrow
Threads[throw]=Thread => IndexThrow
Threads[1]=throw => RightHandSideThrow
Threads[1]=Thread => Okay!

Threads[throw]=throw => IndexThrow
Threads[throw]=StringBuffer => IndexThrow
Threads[9]=throw => RightHandSideThrow
Threads[9]=StringBuffer => IndexOutOfBoundsException

Threads[throw]=throw => IndexThrow
Threads[throw]=Thread => IndexThrow
Threads[9]=throw => RightHandSideThrow
Threads[9]=Thread => IndexOutOfBoundsException

The most interesting case of the lot is the one thirteenth from the end:

Threads[1]=StringBuffer => ArrayStoreException

which indicates that the attempt to store a reference to a StringBuffer into an array whose components are of type Thread throws an ArrayStoreException. The code is type-correct at compile time: the assignment has a left-hand side of type Object[] and a right-hand side of type Object. At run time, the first actual argument to method testFour is a reference to an instance of "array of Thread" and the third actual argument is a reference to an instance of class StringBuffer.


15.25.2 Compound Assignment Operators

All compound assignment operators require both operands to be of primitive type, except for +=, which allows the right-hand operand to be of any type if the left- hand operand is of type String.

A compound assignment expression of the form E1 op= E2 is equivalent to E1 = (T)((E1) op (E2)), where T is the type of E1, except that E1 is evaluated only once. Note that the implied cast to type T may be either an identity conversion (§5.1.1) or a narrowing primitive conversion (§5.1.3). For example, the following code is correct:

short x = 3;
x += 4.6;

and results in x having the value 7 because it is equivalent to:

short x = 3;
x = (short)(x + 4.6);

At run time, the expression is evaluated in one of two ways. If the left-hand operand expression is not an array access expression, then four steps are required:

  • First, the left-hand operand is evaluated to produce a variable. If this evaluation completes abruptly, then the assignment expression completes abruptly for the same reason; the right-hand operand is not evaluated and no assignment occurs.
  • Otherwise, the value of the left-hand operand is saved and then the right-hand operand is evaluated. If this evaluation completes abruptly, then the assignment expression completes abruptly for the same reason and no assignment occurs.
  • Otherwise, the saved value of the left-hand variable and the value of the right-hand operand are used to perform the binary operation indicated by the compound assignment operator. If this operation completes abruptly (the only possibility is an integer division by zero-see §15.16.2), then the assignment expression completes abruptly for the same reason and no assignment occurs.
  • Otherwise, the result of the binary operation is converted to the type of the left-hand variable and the result of the conversion is stored into the variable.

If the left-hand operand expression is an array access expression (§15.12), then many steps are required:

  • First, the array reference subexpression of the left-hand operand array access expression is evaluated. If this evaluation completes abruptly, then the assignment expression completes abruptly for the same reason; the index subexpression (of the left-hand operand array access expression) and the right-hand operand are not evaluated and no assignment occurs.
  • Otherwise, the index subexpression of the left-hand operand array access expression is evaluated. If this evaluation completes abruptly, then the assignment expression completes abruptly for the same reason and the right-hand operand is not evaluated and no assignment occurs.
  • Otherwise, if the value of the array reference subexpression is null, then no assignment occurs and a NullPointerException is thrown.
  • Otherwise, the value of the array reference subexpression indeed refers to an array. If the value of the index subexpression is less than zero, or greater than or equal to the length of the array, then no assignment occurs and an IndexOutOfBoundsException is thrown.
  • Otherwise, the value of the index subexpression is used to select a component of the array referred to by the value of the array reference subexpression. The value of this component is saved and then the right-hand operand is evaluated. If this evaluation completes abruptly, then the assignment expression completes abruptly for the same reason and no assignment occurs. (For a simple assignment operator, the evaluation of the right-hand operand occurs before the checks of the array reference subexpression and the index subexpression, but for a compound assignment operator, the evaluation of the right-hand operand occurs after these checks.)
  • Otherwise, consider the array component selected in the previous step, whose value was saved. This component is a variable; call its type S. Also, let T be the type of the left-hand operand of the assignment operator as determined at compile time.
    • If T is a primitive type, then S is necessarily the same as T.
      • The saved value of the array component and the value of the right-hand operand are used to perform the binary operation indicated by the compound assignment operator. If this operation completes abruptly (the only possibility is an integer division by zero-see §15.16.2), then the assignment expression completes abruptly for the same reason and no assignment occurs.
      • Otherwise, the result of the binary operation is converted to the type of the array component and the result of the conversion is stored into the array component.
    • If T is a reference type, then it must be String. Because class String is a final class, S must also be String. Therefore the run-time check that is sometimes required for the simple assignment operator is never required for a compound assignment operator.
      • The saved value of the array component and the value of the right-hand operand are used to perform the binary operation (string concatenation) indicated by the compound assignment operator (which is necessarily +=). If this operation completes abruptly, then the assignment expression completes abruptly for the same reason and no assignment occurs.
      • Otherwise, the String result of the binary operation is stored into the array component.

The rules for compound assignment to an array component are illustrated by the following example program:

class ArrayReferenceThrow extends RuntimeException { }

class IndexThrow extends RuntimeException { }

class RightHandSideThrow extends RuntimeException { }

class IllustrateCompoundArrayAssignment {

    static String[] strings = { "Simon", "Garfunkel" };

    static double[] doubles = { Math.E, Math.PI };

    static String[] stringsThrow() {
        throw new ArrayReferenceThrow();
    }

    static double[] doublesThrow() {
        throw new ArrayReferenceThrow();
    }

    static int indexThrow() { throw new IndexThrow(); }

    static String stringThrow() {
        throw new RightHandSideThrow();
    }

    static double doubleThrow() {
        throw new RightHandSideThrow();
    }

    static String name(Object q) {
        String sq = q.getClass().getName();
        int k = sq.lastIndexOf('.');
        return (k < 0) ? sq : sq.substring(k+1);
    }

    static void testEight(String[] x, double[] z, int j) {
        String sx = (x == null) ? "null" : "Strings";
        String sz = (z == null) ? "null" : "doubles";
        System.out.println();
        try {
            System.out.print(sx + "[throw]+=throw => ");
            x[indexThrow()] += stringThrow();
            System.out.println("Okay!");
        } catch (Throwable e) { System.out.println(name(e)); }
        try {
            System.out.print(sz + "[throw]+=throw => ");
            z[indexThrow()] += doubleThrow();
            System.out.println("Okay!");
        } catch (Throwable e) { System.out.println(name(e)); }

        try {
            System.out.print(sx + "[throw]+=\"heh\" => ");
            x[indexThrow()] += "heh";
            System.out.println("Okay!");
        } catch (Throwable e) { System.out.println(name(e)); }
        try {
            System.out.print(sz + "[throw]+=12345 => ");
            z[indexThrow()] += 12345;
            System.out.println("Okay!");
        } catch (Throwable e) { System.out.println(name(e)); }
        try {
            System.out.print(sx + "[" + j + "]+=throw => ");
            x[j] += stringThrow();
            System.out.println("Okay!");
        } catch (Throwable e) { System.out.println(name(e)); }
        try {
            System.out.print(sz + "[" + j + "]+=throw => ");
            z[j] += doubleThrow();
            System.out.println("Okay!");
        } catch (Throwable e) { System.out.println(name(e)); }
        try {
            System.out.print(sx + "[" + j + "]+=\"heh\" => ");
            x[j] += "heh";
            System.out.println("Okay!");
        } catch (Throwable e) { System.out.println(name(e)); }
        try {
            System.out.print(sz + "[" + j + "]+=12345 => ");
            z[j] += 12345;
            System.out.println("Okay!");
        } catch (Throwable e) { System.out.println(name(e)); }
    }

    public static void main(String[] args) {
        try {
            System.out.print("throw[throw]+=throw => ");
            stringsThrow()[indexThrow()] += stringThrow();
            System.out.println("Okay!");
        } catch (Throwable e) { System.out.println(name(e)); }
        try {
            System.out.print("throw[throw]+=throw => ");
            doublesThrow()[indexThrow()] += doubleThrow();
            System.out.println("Okay!");
        } catch (Throwable e) { System.out.println(name(e)); }
        try {
            System.out.print("throw[throw]+=\"heh\" => ");
            stringsThrow()[indexThrow()] += "heh";
            System.out.println("Okay!");
        } catch (Throwable e) { System.out.println(name(e)); }

        try {
            System.out.print("throw[throw]+=12345 => ");
            doublesThrow()[indexThrow()] += 12345;
            System.out.println("Okay!");
        } catch (Throwable e) { System.out.println(name(e)); }
        try {
            System.out.print("throw[1]+=throw => ");
            stringsThrow()[1] += stringThrow();
            System.out.println("Okay!");
        } catch (Throwable e) { System.out.println(name(e)); }
        try {
            System.out.print("throw[1]+=throw => ");
            doublesThrow()[1] += doubleThrow();
            System.out.println("Okay!");
        } catch (Throwable e) { System.out.println(name(e)); }
        try {
            System.out.print("throw[1]+=\"heh\" => ");
            stringsThrow()[1] += "heh";
            System.out.println("Okay!");
        } catch (Throwable e) { System.out.println(name(e)); }
        try {
            System.out.print("throw[1]+=12345 => ");
            doublesThrow()[1] += 12345;
            System.out.println("Okay!");
        } catch (Throwable e) { System.out.println(name(e)); }

        testEight(null, null, 1);
        testEight(null, null, 9);
        testEight(strings, doubles, 1);
        testEight(strings, doubles, 9);
    }

}

This program prints:

throw[throw]+=throw => ArrayReferenceThrow
throw[throw]+=throw => ArrayReferenceThrow
throw[throw]+="heh" => ArrayReferenceThrow
throw[throw]+=12345 => ArrayReferenceThrow
throw[1]+=throw => ArrayReferenceThrow
throw[1]+=throw => ArrayReferenceThrow
throw[1]+="heh" => ArrayReferenceThrow
throw[1]+=12345 => ArrayReferenceThrow

null[throw]+=throw => IndexThrow
null[throw]+=throw => IndexThrow
null[throw]+="heh" => IndexThrow
null[throw]+=12345 => IndexThrow
null[1]+=throw => NullPointerException
null[1]+=throw => NullPointerException
null[1]+="heh" => NullPointerException
null[1]+=12345 => NullPointerException

null[throw]+=throw => IndexThrow
null[throw]+=throw => IndexThrow
null[throw]+="heh" => IndexThrow
null[throw]+=12345 => IndexThrow
null[9]+=throw => NullPointerException
null[9]+=throw => NullPointerException
null[9]+="heh" => NullPointerException
null[9]+=12345 => NullPointerException

Strings[throw]+=throw => IndexThrow
doubles[throw]+=throw => IndexThrow
Strings[throw]+="heh" => IndexThrow
doubles[throw]+=12345 => IndexThrow
Strings[1]+=throw => RightHandSideThrow
doubles[1]+=throw => RightHandSideThrow
Strings[1]+="heh" => Okay!
doubles[1]+=12345 => Okay!

Strings[throw]+=throw => IndexThrow
doubles[throw]+=throw => IndexThrow
Strings[throw]+="heh" => IndexThrow
doubles[throw]+=12345 => IndexThrow
Strings[9]+=throw => IndexOutOfBoundsException
doubles[9]+=throw => IndexOutOfBoundsException
Strings[9]+="heh" => IndexOutOfBoundsException
doubles[9]+=12345 => IndexOutOfBoundsException

The most interesting cases of the lot are tenth and eleventh from the end:

Strings[1]+=throw => RightHandSideThrow
doubles[1]+=throw => RightHandSideThrow

They are the cases where a right-hand side that throws an exception actually gets to throw the exception; moreover, they are the only such cases in the lot. This demonstrates that the evaluation of the right-hand operand indeed occurs after the checks for a null array reference value and an out-of-bounds index value.

The following program illustrates the fact that the value of the left-hand side of a compound assignment is saved before the right-hand side is evaluated:

class Test {
    public static void main(String[] args) {
        int k = 1;
        int[] a = { 1 };
        k += (k = 4) * (k + 2);
        a[0] += (a[0] = 4) * (a[0] + 2);
        System.out.println("k==" + k + " and a[0]==" + a[0]);
    }
}

This program prints:

k==25 and a[0]==25

The value 1 of k is saved by the compound assignment operator += before its right-hand operand (k = 4) * (k + 2) is evaluated. Evaluation of this right-hand operand then assigns 4 to k, calculates the value 6 for k + 2, and then multiplies 4 by 6 to get 24. This is added to the saved value 1 to get 25, which is then stored into k by the += operator. An identical analysis applies to the case that uses a[0]. In short, the statements

k += (k = 4) * (k + 2);
a[0] += (a[0] = 4) * (a[0] + 2);

behave in exactly the same manner as the statements:

k = k + (k = 4) * (k + 2);
a[0] = a[0] + (a[0] = 4) * (a[0] + 2);


15.26 Expression

An Expression is any assignment expression:

Expression:

    AssignmentExpression

Unlike C and C++, the Java language has no comma operator.


15.27 Constant Expression

ConstantExpression:

    Expression

A compile-time constant expression is an expression denoting a value of primitive type or a String that is composed using only the following:

  • Literals of primitive type and literals of type String
  • Casts to primitive types and casts to type String
  • The unary operators +, -, ~, and ! (but not ++ or --)
  • The multiplicative operators *, /, and %
  • The additive operators + and -
  • The shift operators <<, >>, and >>>
  • The relational operators <, <=, >, and >= (but not instanceof)
  • The equality operators == and !=
  • The bitwise and logical operators &, ^, and |
  • The conditional-and operator && and the conditional-or operator ||
  • The ternary conditional operator ? :
  • Simple names that refer to final variables whose initializers are constant expressions
  • Qualified names of the form TypeName . Identifier that refer to final variables whose initializers are constant expressions

Compile-time constant expressions are used in case labels in switch statements (§14.9) and have a special significance for assignment conversion (§5.2).

Examples of constant expressions:

true
(short)(1*2*3*4*5*6)
Integer.MAX_VALUE / 2
2.0 * Math.PI
"The integer " + Long.MAX_VALUE + " is mighty big."

. . . when faces of the throng turned toward him and ambiguous eyes stared
into his, he assumed the most romantic of expressions . . .
--F. Scott Fitzgerald, This Side of Paradise (1920)


 16. Definite Assignment

CHAPTER 16

Definite Assignment

All the evolution we know of proceeds from the vague to the definite.
—Charles Pierce

Each local variable must have a definitely assigned value when any access of its value occurs. An access to its value consists of the simple name of the variable occurring anywhere in an expression except as the left-hand operand of the simple assignment operator =.

A Java compiler must carry out a specific conservative flow analysis to make sure that, for every access of a local variable, the local variable is definitely assigned before the access; otherwise a compile-time error must occur.

The remainder of this chapter is devoted to a precise explanation of the words "definitely assigned before". The idea is that an assignment to the local variable must occur on every possible execution path to the access from the beginning of the constructor, method, or static initializer that contains the access. The analysis takes into account the structure of statements and expressions; it also provides a special treatment of the expression operators !, &&, ||, and ? :, the operators &, |, ^, ==, and != with boolean operands, and boolean-valued constant expressions. For example, a Java compiler recognizes that k is definitely assigned before its access (as an argument of a method invocation) in the code:

{
    int k;
    if (v > 0 && (k = System.in.read()) >= 0)
        System.out.println(k);
}

because the access occurs only if the value of the expression:

v > 0 && (k = System.in.read()) >= 0

is true, and the value can be true only if the assignment to k is executed (more properly, evaluated). Similarly, a Java compiler will recognize that in the code:

{
    int k;
    while (true) {
        k = n;
        if (k >= 5) break;
        n = 6;
    }
    System.out.println(k);
}

the variable k is definitely assigned by the while statement because the condition expression true never has the value false, so only the break statement can cause the while statement to complete normally, and k is definitely assigned before the break statement.

Except for the special treatment of certain boolean operators and of boolean-valued constant expressions, the values of expressions are not taken into account in the flow analysis. For example, a Java compiler must produce a compile-time error for the code:

{
    int k;
    int n = 5;
    if (n > 2)
        k = 3;
    System.out.println(k); // k is not "definitely assigned" before this
}

even though the value of n is known at compile time, and in principle it can be known at compile time that the assignment to k will always be executed (more properly, evaluated). A Java compiler must operate according to the rules laid out in this section. The rules recognize only constant expressions; in this example, the expression n > 2 is not a constant expression as defined in §15.27.

As another example, a Java compiler will accept the code:

void flow(boolean flag) {
    int k;
    if (flag)
        k = 3;
    else
        k = 4;
    System.out.println(k);
}

as far as definite assignment of k is concerned, because the rules outlined in this section allow it to tell that k is assigned no matter whether the flag is true or false. But the rules do not accept the variation:

void flow(boolean flag) {
    int k;
    if (flag)
        k = 3;
    if (!flag)
        k = 4;
    System.out.println(k); // k is not "definitely assigned" before this
}

and so compiling this program must cause a compile-time error to occur.

In order to precisely specify all the cases of definite assignment, the rules in this section define two technical terms:

  • whether a local variable is definitely assigned before a statement or expression, and
  • whether a local variable is definitely assigned after a statement or expression.

In order to specify boolean-valued expressions, the latter notion is refined into two cases:

  • whether a local variable is definitely assigned after the expression when true, and
  • whether a local variable is definitely assigned after the expression when false.

Here when true and when false refer to the value of the expression. For example, the local variable k is definitely assigned a value after evaluation of the expression

a && ((k=m) > 5)

when the expression is true but not when the expression is false (because if a is false, then the assignment to k is not executed (more properly, evaluated)).

The statement "V is definitely assigned after X" (where V is a local variable and X is a statement or expression) means "V is definitely assigned after X if X completes normally". If X completes abruptly, the assignment may not have occurred, and the rules stated here take this into account. A peculiar consequence of this definition is that "V is definitely assigned after break;" is always true! Because a break statement never completes normally, it is vacuously true that V has been assigned a value if the break statement completes normally.

To shorten the rules, the customary abbreviation "iff" is used to mean "if and only if".

Let V be a local variable. Let a, b, c, and e be expressions. Let S and T be statements.


16.1 Definite Assignment and Expressions

See sections 16.1.1 through 16.1.16 for information on definite assignment and expressions.


16.1.1 Boolean Constant Expressions

V is definitely assigned after any constant expression whose value is true when false. V is definitely assigned after any constant expression whose value is false when true.

A constant expression whose value is true never has the value false, and a constant expression whose value is false never has the value true, these definitions are vacuously satisfied. They are helpful in analyzing expressions involving the boolean operators &&, ||, and ! ( §16.1.3, §16.1.4, §16.1.5).


16.1.2 Boolean-valued Expressions

For every boolean-valued expression:

  • If the expression has no subexpressions, V is definitely assigned after the expression iff V is definitely assigned before the expression. This case applies to literals and simple names.
  • Otherwise, V is definitely assigned after the expression iff V is definitely assigned after the expression when true and V is definitely assigned after the expression when false.


16.1.3 The Boolean Operator &&

  • V is definitely assigned after a && b when true iff V is definitely assigned after a when true or V is definitely assigned after b when true.
  • V is definitely assigned after a && b when false iff V is definitely assigned after a when false and V is definitely assigned after b when false.
  • V is definitely assigned before a iff V is definitely assigned before a && b.
  • V is definitely assigned before b iff V is definitely assigned after a when true.


16.1.4 The Boolean Operator ||

  • V is definitely assigned after a || b when true iff V is definitely assigned after a when true and V is definitely assigned after b when true.
  • V is definitely assigned after a || b when false iff V is definitely assigned after a when false or V is definitely assigned after b when false.
  • V is definitely assigned before a iff V is definitely assigned before a || b.
  • V is definitely assigned before b iff V is definitely assigned after a when false.


16.1.5 The Boolean Operator !

  • V is definitely assigned after !a when true iff V is definitely assigned after a when false.
  • V is definitely assigned after !a when false iff V is definitely assigned after a when true.
  • V is definitely assigned before a iff V is definitely assigned before !a.


16.1.6 The Boolean Operator &

  • V is definitely assigned after a & b when true iff V is definitely assigned after a when true or V is definitely assigned after b when true.
  • V is definitely assigned after a & b when false iff at least one of the following is true:
    • V is definitely assigned after b. (Note that if V is definitely assigned after a, it follows that V is definitely assigned after b.)
    • V is definitely assigned after a when false and V is definitely assigned after b when false.
  • V is definitely assigned before a iff V is definitely assigned before a & b.
  • V is definitely assigned before b iff V is definitely assigned after a.


16.1.7 The Boolean Operator |

  • V is definitely assigned after a | b when true iff at least one of the following is true:
    • V is definitely assigned after b. (Note that if V is definitely assigned after a, it follows that V is definitely assigned after b.)
    • V is definitely assigned after a when true and V is definitely assigned after b when true.
  • V is definitely assigned after a | b when false iff V is definitely assigned after a when false or V is definitely assigned after b when false.
  • V is definitely assigned before a iff V is definitely assigned before a | b.
  • V is definitely assigned before b iff V is definitely assigned after a.


16.1.8 The Boolean Operator ^

  • V is definitely assigned after a ^ b when true iff at least one of the following is true:
    • V is definitely assigned after b.
    • V is definitely assigned after a when true and V is definitely assigned after b when true.
    • V is definitely assigned after a when false and V is definitely assigned after b when false.
  • V is definitely assigned after a ^ b when false iff at least one of the following is true:
    • V is definitely assigned after b.
    • V is definitely assigned after a when true and V is definitely assigned after b when false.
    • V is definitely assigned after a when false and V is definitely assigned after b when true.
  • V is definitely assigned before a iff V is definitely assigned before a ^ b.
  • V is definitely assigned before b iff V is definitely assigned after a.


16.1.9 The Boolean Operator ==

  • V is definitely assigned after a == b when true iff at least one of the following is true:
    • V is definitely assigned after b.
    • V is definitely assigned after a when true and V is definitely assigned after b when false.
    • V is definitely assigned after a when false and V is definitely assigned after b when true.
  • V is definitely assigned after a == b when false iff at least one of the following is true:
    • V is definitely assigned after b.
    • V is definitely assigned after a when true and V is definitely assigned after b when true.
    • V is definitely assigned after a when false and V is definitely assigned after b when false.
  • V is definitely assigned before a iff V is definitely assigned before a == b.
  • V is definitely assigned before b iff V is definitely assigned after a.


16.1.10 The Boolean Operator !=

The rules for a != b are identical to the rules for a ^ b (§16.1.8).


16.1.11 The Boolean Operator ? :

Suppose that b and c are boolean-valued expressions.

  • V is definitely assigned after a ? b : c when true iff both of the following are true:
    • V is definitely assigned before b or V is definitely assigned after b when true.
    • V is definitely assigned before c or V is definitely assigned after c when true.
  • V is definitely assigned after a ? b : c when false iff both of the following are true:
    • V is definitely assigned before b or V is definitely assigned after b when false.
    • V is definitely assigned before c or V is definitely assigned after c when false.
  • V is definitely assigned before a iff V is definitely assigned before a ? b : c.
  • V is definitely assigned before b iff V is definitely assigned after a when true.
  • V is definitely assigned before c iff V is definitely assigned after a when false.


16.1.12 The Conditional Operator ? :

Suppose that b and c are expressions that are not boolean-valued.

  • V is definitely assigned after a ? b : c iff both of the following are true:
    • V is definitely assigned after b.
    • V is definitely assigned after c.
  • V is definitely assigned before a iff V is definitely assigned before a ? b : c.
  • V is definitely assigned before b iff V is definitely assigned after a when true.
  • V is definitely assigned before c iff V is definitely assigned after a when false.


16.1.13 Boolean Assignment Expressions

Suppose that an assignment expression a = b, a &= b, a |= b, or a ^= b is boolean- valued.

  • V is definitely assigned before a iff V is definitely assigned before the assignment expression.
  • V is definitely assigned before b iff V is definitely assigned after a.
  • V is definitely assigned after a = b when true iff either a is V or V is definitely assigned after the right-hand operand expression when true.
  • V is definitely assigned after a = b when false iff either a is V or V is definitely assigned after the right-hand operand expression when false.
  • V is definitely assigned after a &= b when true iff either a is V or V would be definitely assigned after a & b (in the same context) when true.
  • V is definitely assigned after a &= b when false iff either a is V or V would be definitely assigned after a & b (in the same context) when false.
  • V is definitely assigned after a |= b when true iff either a is V or V would be definitely assigned after a | b (in the same context) when true.
  • V is definitely assigned after a |= b when false iff either a is V or V would be definitely assigned after a | b (in the same context) when false.
  • V is definitely assigned after a ^= b when true iff either a is V or V would be definitely assigned after a ^ b (in the same context) when true.
  • V is definitely assigned after a ^= b when false iff either a is V or V would be definitely assigned after a ^ b (in the same context) when false.

Note that if a is V and V is not definitely assigned before a compound assignment such as a &= b, then a compile-time error will necessarily occur. The rules stated above include the disjunct "a is V" so that V will be considered to have been definitely assigned at later points in the code. Including the disjunct "a is V" does not affect the binary decision as to whether a program is acceptable or will result in a compile-time error, but it affects how many different points in the code may be regarded as erroneous, and so in practice it can improve the quality of error reporting.


16.1.14 Other Assignment Expressions

Suppose that an assignment expression a = b, a += b, a -= b, a *= b, a /= b, a %= b, a <<= b, a >>= b, a >>>= b, a &= b, a |= b, or a ^= b is not boolean-valued.

  • V is definitely assigned after the assignment expression iff either a is V or V is definitely assigned after b.
  • V is definitely assigned before a iff V is definitely assigned before the assignment expression.
  • V is definitely assigned before b iff V is definitely assigned after a.


16.1.15 Operators ++ and --

  • V is definitely assigned after a preincrement, predecrement, postincrement, or postdecrement expression iff either the operand expression is V or V is definitely assigned after the operand expression.
  • V is definitely assigned before the operand expression iff V is definitely assigned before the preincrement, predecrement, postincrement, or postdecrement expression.


16.1.16 Other Expressions

If an expression is not boolean-valued and is not a conditional-operator expression or assignment expression, the following rules apply:

  • If the expression has no subexpressions, V is definitely assigned after the expression iff V is definitely assigned before the expression. This case applies to literals, simple names, this, super, and null.
  • If the expression has subexpressions, V is definitely assigned after the expression iff V is definitely assigned after its rightmost immediate subexpression.

For any immediate subexpression y of an expression x, V is definitely assigned before y iff V is definitely assigned before x or one of the following situations is true:

  • y is the right-hand operand of a binary operator and V is definitely assigned after the left-hand operand.
  • x is an array reference, y is the subexpression within the brackets, and V is definitely assigned after the subexpression before the brackets.
  • x is a method invocation expression for an object; y is the first argument expression in the method invocation expression; there is a subexpression whose value is an object to the left of the dot, method name, and left parenthesis of the method invocation expression; and V is definitely assigned after this subexpression.
  • x is a method invocation expression or class instance creation expression; y is an argument expression, but not the first; and V is definitely assigned after the argument expression to the left of y.
  • x is an class instance creation expression; y is a dimension expression, but not the first; and V is definitely assigned after the dimension expression to the left of y.


16.2 Definite Assignment and Statements

See sections 16.2.1 through 16.2.13 for information on definite assignment and statements.


16.2.1 Empty Statements

  • V is definitely assigned after an empty statement iff it is definitely assigned before the empty statement.


16.2.2 Blocks

  • V is definitely assigned after an empty block iff it is definitely assigned before the empty block.
  • V is definitely assigned after a nonempty block iff it is definitely assigned after the last statement in the block.
  • V is definitely assigned before the first statement of the block iff it is definitely assigned before the block.
  • V is definitely assigned before any other statement S of the block iff it is definitely assigned after the statement immediately preceding S in the block.


16.2.3 Local Variable Declaration Statements

  • V is definitely assigned after a local variable declaration statement that contains no initializers iff it is definitely assigned before the local variable declaration statement.
  • V is definitely assigned after a local variable declaration statement that contains initializers iff either it is definitely assigned after the last initializer expression in the local variable declaration statement or the last initializer expression in the declaration is in the declarator that declares V.
  • V is definitely assigned before the first initializer expression iff it is definitely assigned before the local variable declaration statement.
  • V is definitely assigned before any other initializer expression e iff either it is definitely assigned after the initializer expression immediately preceding e in the local variable declaration statement or the initializer expression immediately preceding e in the local variable declaration statement is in the declarator that declares V.


16.2.4 Labeled Statements

  • V is definitely assigned after a labeled statement L:S (where L is a label) iff V is definitely assigned after S and V is definitely assigned before every break statement that may exit the labeled statement L:S.
  • V is definitely assigned before S iff V is definitely assigned before L:S.


16.2.5 Expression Statements

  • V is definitely assigned after an expression statement e; iff it is definitely assigned after e.
  • V is definitely assigned before e iff it is definitely assigned before e;.


16.2.6 if Statements

  • V is definitely assigned after if (e) S iff V is definitely assigned after S and V is definitely assigned after e when false.
  • V is definitely assigned before e iff V is definitely assigned before if (e) S. V is definitely assigned before S iff V is definitely assigned after e when true.
  • V is definitely assigned after if (e) S else T iff V is definitely assigned after S and V is definitely assigned after T.
  • V is definitely assigned before e iff V is definitely assigned before if (e) S else T. V is definitely assigned before S iff V is definitely assigned after e when true. V is definitely assigned before T iff V is definitely assigned after e when false.


16.2.7 switch Statements

  • V is definitely assigned after a switch statement iff both of the following are true:
    • Either the switch block is empty or V is definitely assigned after the last statement of the switch block.
    • V is definitely assigned before every break statement that may exit the switch statement.
  • V is definitely assigned before the switch expression iff V is definitely assigned before the switch statement.
  • V is definitely assigned before a statement or local variable declaration statement S in the switch block iff at least one of the following is true:
    • V is definitely assigned after the switch expression.
    • S is not labeled by a case or default label and V is definitely assigned after the preceding statement.


16.2.8 while Statements

  • V is definitely assigned after while (e) S iff V is definitely assigned after e when false and V is definitely assigned before every break statement that may exit the while statement.
  • V is definitely assigned before e iff V is definitely assigned before the while statement.
  • V is definitely assigned before S iff V is definitely assigned after e when true.


16.2.9 do Statements

  • V is definitely assigned after do S while (e); iff V is definitely assigned after e when false and V is definitely assigned before every break statement that may exit the do statement.
  • V is definitely assigned before S iff V is definitely assigned before the do statement.
  • V is definitely assigned before e iff V is definitely assigned after S and V is definitely assigned before every continue statement that may exit the body of the do statement.


16.2.10 for Statements

  • V is definitely assigned after a for statement iff both of the following are true:
    • Either a condition expression is not present or V is definitely assigned after the condition expression when false.
    • V is definitely assigned before every break statement that may exit the for statement.
  • V is definitely assigned before the initialization part of the for statement iff V is definitely assigned before the for statement.
  • V is definitely assigned before the condition part of the for statement iff V is definitely assigned after the initialization part of the for statement.
  • V is definitely assigned before the contained statement iff either of the following is true:
    • A condition expression is present and V is definitely assigned after the condition expression when true.
    • No condition expression is present and V is definitely assigned after the initialization part of the for statement.
  • V is definitely assigned before the incrementation part of the for statement iff V is definitely assigned after the contained statement and V is definitely assigned before every continue statement that may exit the body of the for statement.

16.2.10.1 Initialization Part

  • If the initialization part of the for statement is a local variable declaration statement, the rules of §16.2.3 apply.
  • Otherwise, if the initialization part is empty, then V is definitely assigned after the initialization part iff V is definitely assigned before the initialization part.
  • Otherwise, three rules apply:
    • V is definitely assigned after the initialization part iff V is definitely assigned after the last expression statement in the initialization part.
    • V is definitely assigned before the first expression statement in the initialization part iff V is definitely assigned before the initialization part.
    • V is definitely assigned before an expression statement E other than the first in the initialization part iff V is definitely assigned after the expression statement immediately preceding E.

16.2.10.2 Incrementation Part

  • If the incrementation part of the for statement is empty, then V is definitely assigned after the incrementation part iff V is definitely assigned before the incrementation part.
  • Otherwise, three rules apply:
    • V is definitely assigned after the incrementation part iff V is definitely assigned after the last expression statement in the incrementation part.
    • V is definitely assigned before the first expression statement in the incrementation part iff V is definitely assigned before the incrementation part.
    • V is definitely assigned before an expression statement E other than the first in the incrementation part iff V is definitely assigned after the expression statement immediately preceding E.


16.2.11 break, continue, return, and throw Statements

  • By convention, we say that V is definitely assigned after any break, continue, return, or throw statement. The notion that a variable is "definitely assigned after" a statement or expression really means "is definitely assigned after the statement or expression completes normally". Because a break, continue, return, or throw statement never completes normally, it vacuously satisfies this notion.
  • In a return statement with an expression or a throw statement, V is definitely assigned before the expression iff V is definitely assigned before the return or throw statement.


16.2.12 synchronized Statements

  • V is definitely assigned after synchronized (e) S iff V is definitely assigned after S.
  • V is definitely assigned before e iff V is definitely assigned before the statement synchronized (e) S.
  • V is definitely assigned before S iff V is definitely assigned after e.


16.2.13 try Statements

  • V is definitely assigned after a try statement iff one of the following is true:
    • V is definitely assigned after the try block and V is definitely assigned after every catch block in the try statement.
    • The try statement has a finally block and V is definitely assigned after the finally block.
  • V is definitely assigned before the try block iff V is definitely assigned before the try statement.
  • V is definitely assigned before a catch block iff V is definitely assigned before the try statement.

V is definitely assigned before a finally block iff V is definitely assigned before the try statement.

I resolved to assign Bartleby a corner by the folding doors . . .
—Herman Melville, Bartleby, the Scrivener (1853)

It does not strike me that there is anything definite about that.
—Herman Melville, Bartleby, the Scrivener (1853)


 17. Threads and Locks

CHAPTER 17

Threads and Locks

And oft-times in the most forbidding den
Of solitude, with love of science strong,
How patiently the yoke of thought they bear;
How subtly glide its finest threads along!
—William Wordsworth, Monks and Schoolmen,in Ecclesiastical Sonnets (1822)

While most of the discussion in the preceding chapters is concerned only with the behavior of Java code as executed a single statement or expression at a time, that is, by a single thread, each Java Virtual Machine can support many threads of execution at once. These threads independently execute Java code that operates on Java values and objects residing in a shared main memory. Threads may be supported by having many hardware processors, by time-slicing a single hardware processor, or by time-slicing many hardware processors.

Java supports the coding of programs that, though concurrent, still exhibit deterministic behavior, by providing mechanisms for synchronizing the concurrent activity of threads. To synchronize threads, Java uses monitors, which are a high-level mechanism for allowing only one thread at a time to execute a region of code protected by the monitor. The behavior of monitors is explained in terms of locks; there is a lock associated with each object.

The synchronized statement (§14.17) performs two special actions relevant only to multithreaded operation: (1) after computing a reference to an object but before executing its body, it locks a lock associated with the object, and (2) after execution of the body has completed, either normally or abruptly, it unlocks that same lock. As a convenience, a method may be declared synchronized; such a method behaves as if its body were contained in a synchronized statement.

The methods wait (§20.1.6, §20.1.7, §20.1.8), notify (§20.1.9), and notifyAll (§20.1.10) of class Object support an efficient transfer of control from one thread to another. Rather than simply "spinning" (repeatedly locking and unlocking an object to see whether some internal state has changed), which consumes computational effort, a thread can suspend itself using wait until such time as another thread awakens it using notify. This is especially appropriate in situations where threads have a producer-consumer relationship (actively cooperating on a common goal) rather than a mutual exclusion relationship (trying to avoid conflicts while sharing a common resource).

As a thread executes code, it carries out a sequence of actions. A thread may use the value of a variable or assign it a new value. (Other actions include arithmetic operations, conditional tests, and method invocations, but these do not involves variables directly.) If two or more concurrent threads act on a shared variable, there is a possibility that the actions on the variable will produce timing-dependent results. This dependence on timing is inherent in concurrent programming, producing one of the few places in Java where the result of executing a program is not determined solely by this specification.

Each thread has a working memory, in which it may keep copies of the values of variables from the main memory that is shared between all threads. To access a shared variable, a thread usually first obtains a lock and flushes its working memory. This guarantees that shared values will be thereafter be loaded from the shared main memory to the threads working memory. When a thread unlocks a lock it guarantees the values it holds in its working memory will be written back to the main memory.

This chapter explains the interaction of threads with the main memory, and thus with each other, in terms of certain low-level actions. There are rules about the order in which these actions may occur. These rules impose constraints on any implementation of Java, and a Java programmer may rely on the rules to predict the possible behaviors of a concurrent Java program. The rules do, however, intentionally give the implementor certain freedoms; the intent is to permit certain standard hardware and software techniques that can greatly improve the speed and efficiency of concurrent code.

Briefly put, these are the important consequences of the rules:

  • Proper use of synchronization constructs will allow reliable transmission of values or sets of values from one thread to another through shared variables.
  • When a thread uses the value of a variable, the value it obtains is in fact a value stored into the variable by that thread or by some other thread. This is true even if the program does not contain code for proper synchronization. For example, if two threads store references to different objects into the same reference value, the variable will subsequently contain a reference to one object or the other, not a reference to some other object or a corrupted reference value. (There is a special exception for long and double values; see §17.4.)
  • In the absence of explicit synchronization, a Java implementation is free to update the main memory in an order that may be surprising. Therefore the programmer who prefers to avoid surprises should use explicit synchronization.


17.1 Terminology and Framework

A variable is any location within a Java program that may be stored into. This includes not only class variables and instance variables but also components of arrays. Variables are kept in a main memory that is shared by all threads. Because it is impossible for one thread to access parameters or local variables of another thread, it doesn't matter whether parameters and local variables are thought of as residing in the shared main memory or in the working memory of the thread that owns them.

Every thread has a working memory in which it keeps its own working copy of variables that it must use or assign. As the thread executes a Java program, it operates on these working copies. The main memory contains the master copy of every variable. There are rules about when a thread is permitted or required to transfer the contents of its working copy of a variable into the master copy or vice versa

The main memory also contains locks; there is one lock associated with each object. Threads may compete to acquire a lock.

For the purposes of this chapter, the verbs use, assign, load, store, lock, and unlock name actions that a thread can perform. The verbs read, write, lock, and unlock name actions that the main memory subsystem can perform. Each of these actions is atomic (indivisible).

A use or assign action is a tightly coupled interaction between a thread's execution engine and the thread's working memory. A lock or unlock action is a tightly coupled interaction between a thread's execution engine and the main memory. But the transfer of data between the main memory and a thread's working memory is loosely coupled. When data is copied from the main memory to a working memory, two actions must occur: a read action performed by the main memory followed some time later by a corresponding load action performed by the working memory. When data is copied from a working memory to the main memory, two actions must occur: a store action performed by the working memory followed some time later by a corresponding write action performed by the main memory. There may be some transit time between main memory and a working memory, and the transit time may be different for each transaction; thus actions initiated by a thread on different variables may viewed by another thread as occurring in a different order. For each variable, however, the actions in main memory on behalf of any one thread are performed in the same order as the corresponding actions by that thread. (This is explained in greater detail below.)

A single Java thread issues a stream of use, assign, lock, and unlock actions as dictated by the semantics of the Java program it is executing. The underlying Java implementation is then required additionally to perform appropriate load, store, read, and write actions so as to obey a certain set of constraints, explained below. If the Java implementation correctly follows these rules and the Java application programmer follows certain other rules of programming, then data can be reliably transferred between threads through shared variables. The rules are designed to be "tight" enough to make this possible but "loose" enough to allow hardware and software designers considerable freedom to improve speed and throughput through such mechanisms as registers, queues, and caches.

Here are the detailed definitions of each of the actions:

  • A use action (by a thread) transfers the contents of the thread's working copy of a variable to the thread's execution engine. This action is performed whenever a thread executes a virtual machine instruction that uses the value of a variable.
  • An assign action (by a thread) transfers a value from the thread's execution engine into the thread's working copy of a variable. This action is performed whenever a thread executes a virtual machine instruction that assigns to a variable.
  • A read action (by the main memory) transmits the contents of the master copy of a variable to a thread's working memory for use by a later load action.
  • A load action (by a thread) puts a value transmitted from main memory by a read action into the thread's working copy of a variable.
  • A store action (by a thread) transmits the contents of the thread's working copy of a variable to main memory for use by a later write action.
  • A write action (by the main memory) puts a value transmitted from the thread's working memory by a store action into the master copy of a variable in main memory.
  • A lock action (by a thread tightly synchronized with main memory) causes a thread to acquire one claim on a particular lock.
  • An unlock action (by a thread tightly synchronized with main memory) causes a thread to release one claim on a particular lock.

Thus the interaction of a thread with a variable over time consists of a sequence of use, assign, load, and store actions. Main memory performs a read action for every load and a write action for every store. A thread's interactions with a lock over time consists of a sequence of lock and unlock actions. All the globally visible behavior of a thread thus comprises all the thread's actions on variables and locks.


17.2 Execution Order

The rules of execution order constrain the order in which certain events may occur. There are four general constraints on the relationships among actions:

  • The actions performed by any one thread are totally ordered; that is, for any two actions performed by a thread, one action precedes the other.
  • The actions performed by the main memory for any one variable are totally ordered; that is, for any two actions performed by the main memory on the same variable, one action precedes the other.
  • The actions performed by the main memory for any one lock are totally ordered; that is, for any two actions performed by the main memory on the same lock, one action precedes the other.
  • It is not permitted for an action to follow itself.

The last rule may seem trivial, but it does need to be stated separately and explicitly for completeness. Without it, it would be possible to propose a set of actions by two or more threads and precedence relationships among the actions that would satisfy all the other rules but would require an action to follow itself.

Threads do not interact directly; they communicate only through the shared main memory. The relationships between the actions of a thread and the actions of main memory are constrained in three ways:

  • Each lock or unlock action is performed jointly by some thread and the main memory.
  • Each load action by a thread is uniquely paired with a read action by the main memory such that the load action follows the read action.
  • Each store action by a thread is uniquely paired with a write action by the main memory such that the write action follows the store action.

Most of the rules in the following sections further constrain the order in which certain actions take place. A rule may state that one action must precede or follow some other action. Note that this relationship is transitive: if action A must precede action B, and B must precede C, then A must precede C. The programmer must remember that these rules are the only constraints on the ordering of actions; if no rule or combination of rules implies that action A must precede action B, then a Java implementation is free to perform action B before action A, or to perform action B concurrently with action A. This freedom can be the key to good performance. Conversely, an implementation is not required to take advantage of all the freedoms given it.

In the rules that follow, the phrasing "B must intervene between A and C" means that action B must follow action A and precede action C.


17.3 Rules about Variables

Let T be a thread and V be a variable. There are certain constraints on the actions performed by T with respect to V:

  • An use or assign by T of V is permitted only when dictated by execution by T of the Java program according to the standard Java execution model. For example, an occurrence of V as an operand of the + operator requires that a single use action occur on V; an occurrence of V as the left-hand operand of the assignment operator = requires that a single assign action occur. All use and assign actions by a given thread must occur in the order specified by the program being executed by the thread. If the following rules forbid T to perform a required use as its next action, it may be necessary for T to perform a load first in order to make progress.
  • A store action by T on V must intervene between an assign by T of V and a subsequent load by T of V. (Less formally: a thread is not permitted to lose its most recent assign.)
  • An assign action by T on V must intervene between a load or store by T of V and a subsequent store by T of V. (Less formally: a thread is not permitted to write data from its working memory back to main memory for no reason.)
  • After a thread is created, it must perform an assign or load action on a variable before performing a use or store action on that variable. (Less formally: a new thread starts with an empty working memory.)
  • After a variable is created, every thread must perform an assign or load action on that variable before performing a use or store action on that variable. (Less formally: a new variable is created only in main memory and is not initially in any thread's working memory.)

Provided that all the constraints above and below are obeyed, a load or store action may be issued at any time by any thread on any variable, at the whim of the implementation.

There are also certain constraints on the read and write actions performed by main memory:

  • For every load action performed by any thread T on its working copy of a variable V, there must be a corresponding preceding read action by the main memory on the master copy of V, and the load action must put into the working copy the data transmitted by the corresponding read action.
  • For every store action performed by any thread T on its working copy of a variable V, there must be a corresponding following write action by the main memory on the master copy of V, and the write action must put into the master copy the data transmitted by the corresponding store action.
  • Let action A be a load or store by thread T on variable V, and let action P be the corresponding read or write by the main memory on variable V. Similarly, let action B be some other load or store by thread T on that same variable V, and let action Q be the corresponding read or write by the main memory on variable V. If A precedes B, then P must precede Q. (Less formally: actions on the master copy of any given variable on behalf of a thread are performed by the main memory in exactly the order that the thread requested.)

Note that this last rule applies only to actions by a thread on the same variable. However, there is a more stringent rule for volatile variables (§17.7).


17.4 Nonatomic Treatment of double and long Variables

If a double or long variable is not declared volatile, then for the purposes of load, store, read, and write actions they are treated as if they were two variables of 32 bits each: wherever the rules require one of these actions, two such actions are performed, one for each 32-bit half. The manner in which the 64 bits of a double or long variable are encoded into two 32-bit quantities is implementation-dependent.

This matters only because a read or write of a double or long variable may be handled by an actual main memory as two 32-bit read or write actions that may be separated in time, with other actions coming between them. Consequently, if two threads concurrently assign distinct values to the same shared non-volatile double or long variable, a subsequent use of that variable may obtain a value that is not equal to either of the assigned values, but some implementation-dependent mixture of the two values.

An implementation is free to implement load, store, read, and write actions for double and long values as atomic 64-bit actions; in fact, this is strongly encouraged. The model divides them into 32-bit halves for the sake of several currently popular microprocessors that fail to provide efficient atomic memory transactions on 64-bit quantities. It would have been simpler for Java to define all memory transactions on single variables as atomic; this more complex definition is a pragmatic concession to current hardware practice. In the future this concession may be eliminated. Meanwhile, programmers are cautioned always to explicitly synchronize access to shared double and long variables.


17.5 Rules about Locks

By the pricking of my thumbs,
Something wicked this way comes.
Open, locks,
Whoever knocks!
—William Shakespeare, Macbeth, Act IV, scene i

Let T be a thread and L be a lock. There are certain constraints on the actions performed by T with respect to L:

  • A lock action by T on L may occur only if, for every thread S other than T, the number of preceding unlock actions by S on L equals the number of preceding lock actions by S on L. (Less formally: only one thread at a time is permitted to lay claim to a lock, and moreover a thread may acquire the same lock multiple times and doesn't relinquish ownership of it until a matching number of unlock actions have been performed.)
  • An unlock action by thread T on lock L may occur only if the number of preceding unlock actions by T on L is strictly less than the number of preceding lock actions by T on L. (Less formally: a thread is not permitted to unlock a lock it doesn't own.)

With respect to a lock, the lock and unlock actions performed by all the threads are performed in some total sequential order. This total order must be consistent with the total order on the actions of each thread.


17.6 Rules about the Interaction of Locks and Variables

Let T be any thread, let V be any variable, and let L be any lock. There are certain constraints on the actions performed by T with respect to V and L:

  • Between an assign action by T on V and a subsequent unlock action by T on L, a store action by T on V must intervene; moreover, the write action corresponding to that store must precede the unlock action, as seen by main memory. (Less formally: if a thread is to perform an unlock action on any lock, it must first copy all assigned values in its working memory back out to main memory.)
  • Between a lock action by T on L and a subsequent use or store action by T on a variable V, an assign or load action on V must intervene; moreover, if it is a load action, then the read action corresponding to that load must follow the lock action, as seen by main memory. (Less formally: a lock action acts as if it flushes all variables from the thread's working memory; before use they must be assigned or loaded from main memory .)


17.7 Rules for Volatile Variables

If a variable is declared volatile, then additional constraints apply to the actions of each thread. Let T be a thread and let V and W be volatile variables.

  • An use action by T on V is permitted only if the previous action by T on V was load, and a load action by T on V is permitted only if the next action by T on V is use. The use action is said to be "associated" with the read action that corresponds to the load.
  • A store action by T on V is permitted only if the previous action by T on V was assign, and an assign action by T on V is permitted only if the next action by T on V is store. The assign action is said to be "associated" with the write action that corresponds to the store.
  • Let action A be a use or assign by thread T on variable V, let action F be the load or store associated with A, and let action P be the read or write of V that corresponds to F. Similarly, let action B be a use or assign by thread T on variable W, let action G be the load or store associated with B, and let action Q be the read or write of V that corresponds to G. If A precedes B, then P must precede Q. (Less formally: actions on the master copies of volatile variables on behalf of a thread are performed by the main memory in exactly the order that the thread requested.)


17.8 Prescient Store Actions

If a variable is not declared volatile, then the rules in the previous sections are relaxed slightly to allow store actions to occur earlier than would otherwise be permitted. The purpose of this relaxation is to allow optimizing Java compilers to perform certain kinds of code rearrangement that preserve the semantics of properly synchronized programs but might be caught in the act of performing memory actions out of order by programs that are not properly synchronized.

Suppose that a store by T of V would follow a particular assign by T of V according to the rules of the previous sections, with no intervening load or assign by T of V. Then that store action would send to the main memory the value that the assign action put into the working memory of thread T. The special rule allows the store action to instead occur before the assign action, if the following restrictions are obeyed:

  • If the store action occurs, the assign is bound to occur. (Remember, these are restrictions on what actually happens, not on what a thread plans to do. No fair performing a store and then throwing an exception before the assign occurs!)
  • No lock action intervenes between the relocated store and the assign.
  • No load of V intervenes between the relocated store and the assign.
  • No other store of V intervenes between the relocated store and the assign.
  • The store action sends to the main memory the value that the assign action will put into the working memory of thread T.

This last property inspires us to call such an early store action prescient: it has to know ahead of time, somehow, what value will be stored by the assign that it should have followed. In practice, optimized compiled code will compute such values early (which is permitted if, for example, the computation has no side effects and throws no exceptions), store them early (before entering a loop, for example), and keep them in working registers for later use within the loop.


17.9 Discussion

Any association between locks and variables is purely conventional. Locking any lock conceptually flushes all variables from a thread's working memory, and unlocking any lock forces the writing out to main memory of all variables that the thread has assigned. That a lock may be associated with a particular object or a class is purely a convention. In some applications, it may be appropriate always to lock an object before accessing any of its instance variables, for example; synchronized methods are a convenient way to follow this convention. In other applications, it may suffice to use a single lock to synchronize access to a large collection of objects.

If a thread uses a particular shared variable only after locking a particular lock and before the corresponding unlocking of that same lock, then the thread will read the shared value of that variable from main memory after the lock action, if necessary, and will copy back to main memory the value most recently assigned to that variable before the unlock action. This, in conjunction with the mutual exclusion rules for locks, suffices to guarantee that values are correctly transmitted from one thread to another through shared variables.

The rules for volatile variables effectively require that main memory be touched exactly once for each use or assign of a volatile variable by a thread, and that main memory be touched in exactly the order dictated by the thread execution semantics. However, such memory actions are not ordered with respect to read and write actions on nonvolatile variables.


17.10 Example: Possible Swap

Consider a class that has class variables a and b and methods hither and yon:

class Sample {
    int a = 1, b = 2;
    void hither() {
        a = b;
    }
    void yon() {
        b = a;
    }
}

Now suppose that two threads are created, and that one thread calls hither while the other thread calls yon. What is the required set of actions and what are the ordering constraints?

Let us consider the thread that calls hither. According to the rules, this thread must perform an use of b followed by an assign of a. That is the bare minimum required to execute a call to the method hither.

Now, the first action on variable b by the thread cannot be use. But it may be assign or load. An assign to b cannot occur because the program text does not call for such an assign action, so a load of b is required. This load action by the thread in turn requires a preceding read action for b by the main memory.

The thread may optionally store the value of a after the assign has occurred. If it does, then the store action in turn requires a following write action for a by the main memory.

The situation for the thread that calls yon is similar, but with the roles of a and b exchanged.

The total set of actions may be pictured as follows:

Here an arrow from action A to action B indicates that A must precede B.

In what order may the actions by the main memory occur? The only constraint is that it is not possible both for the write of a to precede the read of a and for the write of b to precede the read of b, because the causality arrows in the diagram would form a loop so that an action would have to precede itself, which is not allowed. Assuming that the optional store and write actions are to occur, there are three possible orderings in which the main memory might legitimately perform its actions. Let ha and hb be the working copies of a and b for the hither thread, let ya and yb be the working copies for the yon thread, and let ma and mb be the master copies in main memory. Initially ma=1 and mb=2. Then the three possible orderings of actions and the resulting states are as follows:

  • write a [image] read a, read b [image] write b (then ha=2, hb=2, ma=2, mb=2, ya=2, yb=2)
  • read a [image] write a, write b [image] read b (then ha=1, hb=1, ma=1, mb=1, ya=1, yb=1)
  • read a [image] write a, read b [image] write b (then ha=2, hb=2, ma=2, mb=1, ya=1, yb=1)

Thus the net result might be that, in main memory, b is copied into a, a is copied into b, or the values of a and b are swapped; moreover, the working copies of the variables might or might not agree. It would be incorrect, of course, to assume that any one of these outcomes is more likely than another. This is one place in which the behavior of a Java program is necessarily timing-dependent.

Of course, an implementation might also choose not to perform the store and write actions, or only one of the two pairs, leading to yet other possible results.

Now suppose that we modify the example to use synchronized methods:

class SynchSample {
    int a = 1, b = 2;
    synchronized void hither() {
        a = b;
    }
    synchronized void yon() {
        b = a;
    }
}

Let us again consider the thread that calls hither. According to the rules, this thread must perform a lock action (on the class object for class SynchSample) before the body of method hither is executed. This is followed by a use of b and then an assign of a. Finally, an unlock action on the class object must be performed after the body of method hither completes. That is the bare minimum required to execute a call to the method hither.

As before, a load of b is required, which in turn requires a preceding read action for b by the main memory. Because the load follows the lock action, the corresponding read must also follow the lock action.

Because an unlock action follows the assign of a, a store action on a is mandatory, which in turn requires a following write action for a by the main memory. The write must precede the unlock action.

The situation for the thread that calls yon is similar, but with the roles of a and b exchanged.

The total set of actions may be pictured as follows:

The lock and unlock actions provide further constraints on the order of actions by the main memory; the lock action by one thread cannot occur between the lock and unlock actions of the other thread. Moreover, the unlock actions require that the store and write actions occur. It follows that only two sequences are possible:

  • write a [image] read a, read b [image] write b (then ha=2, hb=2, ma=2, mb=2, ya=2, yb=2)
  • read a [image] write a, write b [image] read b (then ha=1, hb=1, ma=1, mb=1, ya=1, yb=1)

While the resulting state is timing-dependent, it can be seen that the two threads will necessarily agree on the values of a and b.


17.11 Example: Out-of-Order Writes

This example is similar to that in the preceding section, except that one method assigns to both variables and the other method reads both variables. Consider a class that has class variables a and b and methods to and fro:

class Simple {
    int a = 1, b = 2;
    void to() {
        a = 3;
        b = 4;
    }
    void fro() {
        System.out.println("a= " + a + ", b=" + b);
    }
}

Now suppose that two threads are created, and that one thread calls to while the other thread calls fro. What is the required set of actions and what are the ordering constraints?

Let us consider the thread that calls to. According to the rules, this thread must perform an assign of a followed by an assign of b. That is the bare minimum required to execute a call to the method to. Because there is no synchronization, it is at the option of the implementation whether or not to store the assigned values back to main memory! Therefore the thread that calls fro may obtain either 1 or 3 for the value of a, and independently may obtain either 2 or 4 for the value of b.

Now suppose that to is synchronized but fro is not:

class SynchSimple {
    int a = 1, b = 2;
    synchronized void to() {
        a = 3;
        b = 4;
    }
    void fro() {
        System.out.println("a= " + a + ", b=" + b);
    }
}

In this case the method to will be forced to store the assigned values back to main memory before the unlock action at the end of the method. The method fro must, of course, use a and b (in that order) and so must load values for a and b from main memory.

The total set of actions may be pictured as follows:

Here an arrow from action A to action B indicates that A must precede B.

In what order may the actions by the main memory occur? Note that the rules do not require that write a occur before write b; neither do they require that read a occur before read b. Also, even though method to is synchronized, method fro is not synchronized, so there is nothing to prevent the read actions from occurring between the lock and unlock actions. (The point is that declaring one method synchronized does not of itself make that method behave as if it were atomic.)

As a result, the method fro could still obtain either 1 or 3 for the value of a, and independently could obtain either 2 or 4 for the value of b. In particular, fro might observe the value 1 for a and 4 for b. Thus, even though to does an assign to a and then an assign to b, the write actions to main memory may be observed by another thread to occur as if in the opposite order.

Finally, suppose that to and fro are both synchronized:

class SynchSynchSimple {
    int a = 1, b = 2;
    synchronized void to() {
        a = 3;
        b = 4;
    }
    synchronized void fro() {
        System.out.println("a= " + a + ", b=" + b);
    }
}

In this case, the actions of method fro cannot be interleaved with the actions of method to, and so fro will print either "a=1, b=2" or "a=3, b=4".


17.12 Threads

They plant dead trees for living, and the dead
They string together with a living thread . . .
But in no hush they string it . . . With a laugh, . . .
They bring the telephone and telegraph.
—Robert Frost, The Line-gang (1920)

Threads are created and managed by the built-in classes Thread (§20.20) and ThreadGroup (§20.21). Creating a Thread object creates a thread and that is the only way to create a thread. When the thread is created, it is not yet active; it begins to run when its start method (§20.20.14) is called.

Every thread has a priority. When there is competition for processing resources, threads with higher priority are generally executed in preference to threads with lower priority. Such preference is not, however, a guarantee that the highest priority thread will always be running, and thread priorities cannot be used to reliably implement mutual exclusion.


17.13 Locks and Synchronization

There is a lock associated with every object. The Java language does not provide a way to perform separate lock and unlock actions; instead, they are implicitly performed by high-level constructs that arrange always to pair such actions correctly. (The Java Virtual Machine, however, provides separate monitorenter and monitorexit instructions that implement the lock and unlock actions.)

The synchronized statement (§14.17) computes a reference to an object; it then attempts to perform a lock action on that object and does not proceed further until the lock action has successfully completed. (A lock action may be delayed because the rules about locks can prevent the main memory from participating until some other thread is ready to perform one or more unlock actions.) After the lock action has been performed, the body of the synchronized statement is executed. If execution of the body is ever completed, either normally or abruptly, an unlock action is automatically performed on that same lock.

A synchronized method (§8.4.3.5) automatically performs a lock action when it is invoked; its body is not executed until the lock action has successfully completed. If the method is an instance method, it locks the lock associated with the instance for which it was invoked (that is, the object that will be known as this during execution of the body of the method). If the method is static, it locks the lock associated with the Class object that represents the class in which the method is defined. If execution of the method's body is ever completed, either normally or abruptly, an unlock action is automatically performed on that same lock.

Best practice is that if a variable is ever to be assigned by one thread and used or assigned by another, then all accesses to that variable should be enclosed in synchronized methods or synchronized statements.

Java does not prevent, nor require detection of, deadlock conditions. Programs where threads hold (directly or indirectly) locks on multiple objects should use conventional techniques for deadlock avoidance, creating higher-level locking primitives that don't deadlock, if necessary.


17.14 Wait Sets and Notification

Every object, in addition to having an associated lock, has an associated wait set, which is a set of threads. When an object is first created, its wait set is empty.

Wait sets are used by the methods wait (§20.1.6, §20.1.7, §20.1.8), notify (§20.1.9), and notifyAll (§20.1.10) of class Object. These methods also interact with the scheduling mechanism for threads (§20.20).

The method wait should be called for an object only when the current thread (call it T) has already locked the object's lock. Suppose that thread T has in fact performed N lock actions that have not been matched by unlock actions. The wait method then adds the current thread to the wait set for the object, disables the current thread for thread scheduling purposes, and performs N unlock actions to relinquish the lock. The thread T then lies dormant until one of three things happens:

  • Some other thread invokes the notify method for that object and thread T happens to be the one arbitrarily chosen as the one to notify.
  • Some other thread invokes the notifyAll method for that object.
  • If the call by thread T to the wait method specified a timeout interval, the specified amount of real time has elapsed.

The thread T is then removed from the wait set and re-enabled for thread scheduling. It then locks the object again (which may involve competing in the usual manner with other threads); once it has gained control of the lock, it performs [image] additional lock actions and then returns from the invocation of the wait method. Thus, on return from the wait method, the state of the object's lock is exactly as it was when the wait method was invoked.

The notify method should be called for an object only when the current thread has already locked the object's lock. If the wait set for the object is not empty, then some arbitrarily chosen thread is removed from the wait set and re-enabled for thread scheduling. (Of course, that thread will not be able to proceed until the current thread relinquishes the object's lock.)

The notifyAll method should be called for an object only when the current thread has already locked the object's lock. Every thread in the wait set for the object is removed from the wait set and re-enabled for thread scheduling. (Of course, those threads will not be able to proceed until the current thread relinquishes the object's lock.)

These pearls of thought in Persian gulfs were bred,
Each softly lucent as a rounded moon;
The diver Omar plucked them from their bed,
Fitzgerald strung them on an English thread.
—James Russell Lowell, in a copy of Omar Khayyam


 18. Documentation Comments

CHAPTER 18

Documentation Comments

The view that documentation is something that is
added to a program after it has been commissioned
seems to be wrong in principle, and counterproductive in practice.
Instead, documentation must be regarded as an
integral part of the process of design and coding.
—C. A. R. Hoare, Hints on Programming Language Design (1973)

Java programs can include documentation in their source code, in special documentation comments (§3.7). Such comments can appear before each class or interface declaration and before each method, constructor, or field declaration. Hypertext web pages can then be produced automatically from the source code of the program and these documentation comments.

This chapter gives an informal description of documentation comments. A complete formal specification would require a detailed description of those parts of the Hypertext Markup Language (HTML) that can be used within the documentation comments, which is beyond the scope of this specification.


18.1 The Text of a Documentation Comment

The text of a documentation comment consists of the characters between the /** that begins the comment and the */ that ends it. The text is divided into one or more lines. On each of these lines, leading * characters are ignored; for lines other than the first, blanks and tabs preceding the initial * characters are also discarded.

So, for example, in the comment:

/**XYZ
  ** Initialize to pre-trial defaults.
  123*/

the text of the comment has three lines. The first line consists of the text "XYZ"; the second line consists of the text " Initialize to pre-trial defaults." and the third line consists of the text "123"


18.2 HTML in a Documentation Comment

Text in a documentation comment may use HTML markers for formatting, with the exception that the specific markers <H1>, <H2>, <H3>, <H4>, <H5>, <H6>, and <HR> are reserved for use by the documentation generator and should not be used in the text. A complete description of HTML is available from the web site http://www.w3.org/ and also through the Internet documentation database at http://www.internic.net/, where the document "Hypertext Markup Language -Version 2.0" by T. Berners-Lee and D. Connolly may be found as RFC1866.


18.3 Summary Sentence and General Description

The first sentence of each documentation comment should be a summary sentence, containing a concise but complete description of the declared entity. This sentence ends at the first period that is followed by a blank, tab, or line terminator, or at the first tagline (as defined below). This simple rule means that a first sentence such as:

This is a simulation of Prof. Knuth's MIX computer.

will not work properly, because the period after the abbreviation "Prof" ends the first sentence, as far as the Java documentation comment processor is concerned. Take care to avoid such difficulties.

Sentences following the summary sentence but preceding the first tagged paragraph (if any) form the general description part of the documentation comment.


18.4 Tagged Paragraphs

A line of a documentation comment that begins with the character @ followed by one of a few special keywords starts a tagged paragraph. The tagged paragraph also includes any following lines up to, but not including, either the first line of the next tagged paragraph or the end of the documentation comment.

Tagged paragraphs identify certain information that has a routine structure, such as the intended purpose of each parameter of a method, in a form that the documentation comment processor can easily marshal into standard typographical formats for purposes of presentation and cross-reference.

Different kinds of tagged paragraphs are available for class and interface declarations and for method, field, and constructor declarations.


18.4.1 The @see Tag

The following are examples of @see paragraphs, which may be used in any documentation comment to indicate a cross-reference to a class, interface, method, constructor, field, or URL:

@see java.lang.String
@see String
@see java.io.InputStream;
@see String#equals
@see java.lang.Object#wait(int)
@see java.io.RandomAccessFile#RandomAccessFile(File, String)
@see Character#MAX_RADIX
@see <a href="spec.html">Java Spec</a>

The character # separates the name of a class from the name of one of its fields, methods, or constructors. One of several overloaded methods or constructors may be selected by including a parenthesized list of argument types after the method or constructor name.

A documentation comment may contain more than one @see tag.


18.4.2 The @author Tag

The following are examples of @author taglines, which may be used in documentation comments for class and interface declarations:

@author Mary Wollstonecraft
@author Hildegard von Bingen
@author Dorothy Parker

The information in an @author paragraph has no special internal structure.

A documentation comment may contain more than one @author tag. Alternatively, a single @author paragraph may mention several authors:

@author Jack Kent, Peggy Parish, Crockett Johnson,
    James Marshall, Marjorie Weinman Sharmat,
    Robert McCloskey, and Madeleine L'Engle

However, we recommend specifying one author per @author paragraph, which allows the documentation processing tool to provide the correct punctuation in all circumstances.


18.4.3 The @version Tag

The following is an example of a @version paragraph, which may be used in documentation comments for class and interface declarations:

@version 493.0.1beta

The information in a @version paragraph has no special internal structure.

A documentation comment may contain at most one @version tag.


18.4.4 The @param Tag

The following are examples of @param paragraphs, which may be used in documentation comments for method and constructor declarations:

@param file the file to be searched
@param pattern
    the pattern to be matched during the search
@param count      the number of lines to print for each match

The information in a @param paragraph should consist of the name of the parameter followed by a short description.

A documentation comment may contain more than one @param tag. The usual convention is that if any @param paragraphs are present in a documentation comment, then there should be one @param paragraph for each parameter of the method or constructor, and the @param paragraphs should appear in the order in which the parameters are declared.


18.4.5 The @return Tag

The following is an example of a @return paragraph, which may be used in documentation comments for declarations of methods whose result type is not void:

@return the number of widgets that pass the quality test

The information in a @return paragraph has no special internal structure. The usual convention is that it consists of a short description of the returned value.

A documentation comment may contain at most one @return tag.


18.4.6 The @exception Tag

The following is an example of an @exception paragraph, which may be used in documentation comments for method and constructor declarations:

@exception IndexOutOfBoundsException
                the matrix is too large
@exception UnflangedWidgetException the widget does not
                have a flange, or its flange has size zero
@exception java.io.FileNotFoundException the file
                does not exist

The information in an @exception paragraph should consist of the name of an exception class (which may be a simple name or a qualified name) followed by a short description of the circumstances that cause the exception to be thrown.

A documentation comment may contain more than one @exception tag.


18.5 Example

Here, as an example, is a version of the source code for the class Object of the package java.lang, including its documentation comments.

/*
 * @(#)Object.java 1.37 96/06/26
 *
 * Copyright (c) 1994, 1995, 1996 Sun Microsystems, Inc.
 * All Rights Reserved.
 *
 * Permission to use, copy, modify, and distribute this
 * software and its documentation for NON-COMMERCIAL purposes
 * and without fee is hereby granted provided that this
 * copyright notice appears in all copies. Please refer to
 * the file "copyright.html" for further important copyright
 * and licensing information.
 *
 * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE
 * SUITABILITY OF THE SOFTWARE, EITHER EXPRESS OR IMPLIED,
 * INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR
 * NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
 * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR
 * DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES.
 */

package java.lang;

/**
 * The root of the Class hierarchy.  Every Class in the
 * system has Object as its ultimate parent.  Every variable
 * and method defined here is available in every Object.
 * @see				Class
 * @version				1.37, 26 Jun 1996
 */

public class Object {
    /**
     * Returns the Class of this Object. Java has a runtime
     * representation for classes--a descriptor of type Class
     * --which the method getClass() returns for any Object.
     */
    public final native Class getClass();

    /**
     * Returns a hashcode for this Object.
     * Each Object in the Java system has a hashcode.
     * The hashcode is a number that is usually different
     * for different Objects. It is used when storing Objects
     * in hashtables.
     * Note: hashcodes can be negative as well as positive.
     * @see				java.util.Hashtable
     */
    public native int hashCode();

    /**
     * Compares two Objects for equality.
     * Returns a boolean that indicates whether this Object
     * is equivalent to the specified Object. This method is
     * used when an Object is stored in a hashtable.
     * @param				obj			the Object to compare with
     * @return				true if these Objects are equal;
     * 					false otherwise.
     * @see				java.util.Hashtable
     */
    public boolean equals(Object obj) {
        return (this == obj);
    }

    /**
     * Creates a clone of the object. A new instance is
     * allocated and a bitwise clone of the current object
     * is placed in the new object.
     * @return				a clone of this Object.
     * @exception					OutOfMemoryError If there is not enough
     * 						memory.
     * @exception					CloneNotSupportedException Object
     * 						explicitly does not want to be
     * 						cloned, or it does not support
     * 						the Cloneable interface.
     */
    protected native Object clone()
        throws CloneNotSupportedException;

    /**
     * Returns a String that represents this Object.
     * It is recommended that all subclasses override
     * this method.
     */
    public String toString() {
        return getClass().getName() + "@" +
            Integer.toHexString(hashCode());
    }

    /**
     * Notifies a single waiting thread on a change in
     * condition of another thread. The thread effecting
     * the change notifies the waiting thread using notify().
     * Threads that want to wait for a condition to change
     * before proceeding can call wait(). <p>
     * <em>The method notify() can be called only by the
     * thread that is the owner of the current object's
     * monitor lock.</em>
     *
     * @exception					IllegalMonitorStateException If the
     * 						current thread is not the owner
     * 						of the Object's monitor lock.
     * @see				Object#wait
     * @see				Object#notifyAll
     */
    public final native void notify();

    /**
     * Notifies all the threads waiting for a condition to
     * change. Threads that are waiting are generally waiting
     * for another thread to change some condition. Thus, the
     * thread effecting a change that more than one thread is
     * waiting for notifies all the waiting threads using
     * the method notifyAll(). Threads that want to wait for
     * a condition to change before proceeding can call
     * wait(). <p>
     * <em>The method notifyAll() can be called only by the
     * thread that is the owner of the current object's
     * monitor lock.</em>
     *
     * @exception					IllegalMonitorStateException If the
     * 						current thread is not the owner
     * 						of the Object's monitor lock.
     * @see				Object#wait
     * @see				Object#notify
     */
    public final native void notifyAll();

    /**
     * Causes a thread to wait until it is notified or the
     * specified timeout expires. <p>
     * <em>The method wait(millis) can be called only by
     * the thread that is the owner of the current object's
     * monitor lock.</em>
     *
     * @param 				millis			the maximum time to wait,
     * 								in milliseconds
     * @exception					IllegalMonitorStateException If the
     * 						current thread is not the owner
     * 						of the Object's monitor lock.
     * @exception 					InterruptedException Another thread has
     * 						interrupted this thread.
     */
    public final native void wait(long millis)
        throws InterruptedException;

    /**
     * More accurate wait.
     * <em>The method wait(millis, nanos) can be called only
     * by the thread that is the owner of the current
     * object's monitor lock.</em>
     *
     * @param millis						the maximum time to wait,
     * 							in milliseconds
     * @param nano						additional time to wait,
     * 							in nanoseconds
     * 							(range 0-999999)
     * @exception					IllegalMonitorStateException If the
     * 						current thread is not the owner
     * 						of the Object's monitor lock.
     * @exception 					InterruptedException Another thread has
     * 						interrupted this thread.
     */
    public final void wait(long millis, int nanos)
        throws InterruptedException
    {
        if (nanos >= 500000 || (nanos != 0 && millis==0))
            timeout++;
        wait(timeout);
    }

    /**
     * Causes a thread to wait forever until it is notified.
     * <p>
     * <em>The method wait() can be called only by the
     * thread that is the owner of the current object's
     * monitor lock.</em>
     *

     * @exception					IllegalMonitorStateException If the
     * 						current thread is not the owner
     * 						of the Object's monitor lock.
     * @exception 					InterruptedException Another thread has
     * 						interrupted this thread.
     */
    public final void wait() throws InterruptedException {
        wait(0);
    }

    /**
     * Code to perform when this object is garbage collected.
     * The default is that nothing needs to be performed.
     *
     * Any exception thrown by a finalize method causes the
     * finalization to halt.  But otherwise, it is ignored.
     */
    protected void finalize() throws Throwable { }

}

From this source code, the javadoc tool produced the following HTML file, which is available for browsing at http://java.sun.com/Series/, our Java Series web site:

<!--NewPage-->

<html>

<head>

<!-- Generated by javadoc on Wed Jun 26 11:40:38 EDT 1996 -->

<a name="_top_"></a>

<title>

  Class java.lang.Object

</title>

</head>

<body>

<pre>

<a href="packages.html">All Packages</a>  <a href="tree.html">Class Hierarchy¬
</a>  <a href="Package-java.lang.html">This Package</a>  <a href="java.lang.N¬
umber.html#_top_">Previous</a>  <a href="java.lang.OutOfMemoryError.html#_top¬
_">Next</a>  <a href="AllNames.html">Index</a></pre>

<hr>

<h1>

  Class java.lang.Object

</h1>

<pre>

java.lang.Object

</pre>

<hr>

<dl>

  <dt> public class <b>Object</b>

</dl>

The root of the Class hierarchy.  Every Class in the

system has Object as its ultimate parent.  Every variable

and method defined here is available in every Object.

<dl>

  <dt> <b>Version:</b>

  <dd> 1.37, 26 Jun 1996

    <dt> <b>See Also:</b>

    <dd> <a href="java.lang.Class.html#_top_">Class</a>

</dl>

<hr>

<a name="index"></a>

<h2>

  <img src="images/constructor-index.gif" width=275 height=38 alt="Constructo¬
r Index">

</h2>

<dl>

  <dt> <img src="images/yellow-ball-small.gif" width=6 height=6 alt=" o ">

    <a href="#Object()"><b>Object</b></a>()

  <dd>

</dl>

<h2>

  <img src="images/method-index.gif" width=207 height=38 alt="Method Index">

</h2>

<dl>

  <dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">

    <a href="#clone()"><b>clone</b></a>()

  <dd> Creates a clone of the object.

  <dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">

    <a href="#equals(java.lang.Object)"><b>equals</b></a>(Object)

  <dd> Compares two Objects for equality.

  <dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">

    <a href="#finalize()"><b>finalize</b></a>()

  <dd> Code to perform when this object is garbage collected.

  <dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">

    <a href="#getClass()"><b>getClass</b></a>()

  <dd> Returns the Class of this Object.

  <dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">

    <a href="#hashCode()"><b>hashCode</b></a>()

  <dd> Returns a hashcode for this Object.

  <dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">

    <a href="#notify()"><b>notify</b></a>()

  <dd> Notifies a single waiting thread on a change in

condition of another thread.

  <dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">

    <a href="#notifyAll()"><b>notifyAll</b></a>()

  <dd> Notifies all the threads waiting for a condition to

change.

  <dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">

    <a href="#toString()"><b>toString</b></a>()

  <dd> Returns a String that represents this Object.

  <dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">

    <a href="#wait()"><b>wait</b></a>()

  <dd> Causes a thread to wait forever until it is notified.

  <dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">

    <a href="#wait(long)"><b>wait</b></a>(long)

  <dd> Causes a thread to wait until it is notified or the

specified timeout expires.

  <dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">

    <a href="#wait(long, int)"><b>wait</b></a>(long, int)

  <dd> More accurate wait.

</dl>

<a name="constructors"></a>

<h2>

  <img src="images/constructors.gif" width=231 height=38 alt="Constructors">

</h2>

<a name="Object"></a>

<a name="Object()"><img src="images/yellow-ball.gif" width=12 height=12 alt="¬
o "></a>

<b>Object</b>

<pre>

  public Object()

</pre>

<a name="methods"></a>

<h2>

  <img src="images/methods.gif" width=151 height=38 alt="Methods">

</h2>

<a name="getClass()"><img src="images/red-ball.gif" width=12 height=12 alt=" ¬
o "></a>

<a name="getClass"><b>getClass</b></a>

<pre>

  public final <a href="java.lang.Class.html#_top_">Class</a> getClass()

</pre>

<dl>

  <dd> Returns the Class of this Object. Java has a runtime

representation for classes--a descriptor of type Class

--which the method getClass() returns for any Object.

</dl>

<a name="hashCode()"><img src="images/red-ball.gif" width=12 height=12 alt=" ¬
o "></a>

<a name="hashCode"><b>hashCode</b></a>

<pre>

  public int hashCode()

</pre>

<dl>

  <dd> Returns a hashcode for this Object.

Each Object in the Java system has a hashcode.

The hashcode is a number that is usually different

for different Objects. It is used when storing Objects

in hashtables.

Note: hashcodes can be negative as well as positive.

  <dl>

    <dt> <b>See Also:</b>

    <dd> <a href="java.util.Hashtable.html#_top_">Hashtable</a>

  </dl>

</dl>

<a name="equals(java.lang.Object)"><img src="images/red-ball.gif" width=12 he¬
ight=12 alt=" o "></a>

<a name="equals"><b>equals</b></a>

<pre>

  public boolean equals(<a href="#_top_">Object</a> obj)

</pre>

<dl>

  <dd> Compares two Objects for equality.

Returns a boolean that indicates whether this Object

is equivalent to the specified Object. This method is

used when an Object is stored in a hashtable.

  <dl>

    <dt> <b>Parameters:</b>

    <dd> obj - the Object to compare with

    <dt> <b>Returns:</b>

    <dd> true if these Objects are equal;

            false otherwise.

    <dt> <b>See Also:</b>

    <dd> <a href="java.util.Hashtable.html#_top_">Hashtable</a>

  </dl>

</dl>

<a name="clone()"><img src="images/red-ball.gif" width=12 height=12 alt=" o "¬
></a>

<a name="clone"><b>clone</b></a>

<pre>

  protected <a href="#_top_">Object</a> clone() throws <a href="java.lang.Clo¬
neNotSupportedException.html#_top_">CloneNotSupportedException</a>

</pre>

<dl>

  <dd> Creates a clone of the object. A new instance is

allocated and a bitwise clone of the current object

is placed in the new object.

  <dl>

    <dt> <b>Returns:</b>

    <dd> a clone of this Object.

    <dt> <b>Throws:</b> <a href="java.lang.OutOfMemoryError.html#_top_">OutOf¬
MemoryError</a>

    <dd> If there is not enough

            memory.

    <dt> <b>Throws:</b> <a href="java.lang.CloneNotSupportedException.html#_t¬
op_">CloneNotSupportedException</a>

    <dd> Object

            explicitly does not want to be

            cloned, or it does not support

            the Cloneable interface.

  </dl>

</dl>

<a name="toString()"><img src="images/red-ball.gif" width=12 height=12 alt=" ¬
o "></a>

<a name="toString"><b>toString</b></a>

<pre>

  public <a href="java.lang.String.html#_top_">String</a> toString()

</pre>

<dl>

  <dd> Returns a String that represents this Object.

It is recommended that all subclasses override

this method.

</dl>

<a name="notify()"><img src="images/red-ball.gif" width=12 height=12 alt=" o ¬
"></a>

<a name="notify"><b>notify</b></a>

<pre>

  public final void notify()

</pre>

<dl>

  <dd> Notifies a single waiting thread on a change in

condition of another thread. The thread effecting

the change notifies the waiting thread using notify().

Threads that want to wait for a condition to change

before proceeding can call wait(). <p>

<em>The method notify() can be called only by the

thread that is the owner of the current object's

monitor lock.</em>

  <dl>

    <dt> <b>Throws:</b> <a href="java.lang.IllegalMonitorStateException.html#¬
_top_">IllegalMonitorStateException</a>

    <dd> If the

            current thread is not the owner

            of the Object's monitor lock.

    <dt> <b>See Also:</b>

    <dd> <a href="#wait">wait</a>, <a href="#notifyAll">notifyAll</a>

  </dl>

</dl>

<a name="notifyAll()"><img src="images/red-ball.gif" width=12 height=12 alt="¬
o "></a>

<a name="notifyAll"><b>notifyAll</b></a>

<pre>

  public final void notifyAll()

</pre>

<dl>

  <dd> Notifies all the threads waiting for a condition to

change. Threads that are waiting are generally waiting

for another thread to change some condition. Thus, the

thread effecting a change that more than one thread is

waiting for notifies all the waiting threads using

the method notifyAll(). Threads that want to wait for

a condition to change before proceeding can call

wait(). <p>

<em>The method notifyAll() can be called only by the

thread that is the owner of the current object's

monitor lock.</em>

  <dl>

    <dt> <b>Throws:</b> <a href="java.lang.IllegalMonitorStateException.html#¬
_top_">IllegalMonitorStateException</a>

    <dd> If the

            current thread is not the owner

            of the Object's monitor lock.

    <dt> <b>See Also:</b>

    <dd> <a href="#wait">wait</a>, <a href="#notify">notify</a>

  </dl>

</dl>

<a name="wait(long)"><img src="images/red-ball.gif" width=12 height=12 alt=" ¬
o "></a>

<a name="wait"><b>wait</b></a>

<pre>

  public final void wait(long millis) throws <a href="java.lang.InterruptedEx¬
ception.html#_top_">InterruptedException</a>

</pre>

<dl>

  <dd> Causes a thread to wait until it is notified or the

specified timeout expires. <p>

<em>The method wait(millis) can be called only by

the thread that is the owner of the current object's

monitor lock.</em>

  <dl>

    <dt> <b>Parameters:</b>

    <dd> millis - the maximum time to wait,

                in milliseconds

    <dt> <b>Throws:</b> <a href="java.lang.IllegalMonitorStateException.html#¬
_top_">IllegalMonitorStateException</a>

    <dd> If the

            current thread is not the owner

            of the Object's monitor lock.

    <dt> <b>Throws:</b> <a href="java.lang.InterruptedException.html#_top_">I¬
nterruptedException</a>

    <dd> Another thread has

            interrupted this thread.

  </dl>

</dl>

<a name="wait(long, int)"><img src="images/red-ball.gif" width=12 height=12 a¬
lt=" o "></a>

<a name="wait"><b>wait</b></a>

<pre>

  public final void wait(long millis,

                         int nanos) throws <a href="java.lang.InterruptedExce¬
ption.html#_top_">InterruptedException</a>

</pre>

<dl>

  <dd> More accurate wait.

<em>The method wait(millis, nanos) can be called only

by the thread that is the owner of the current

object's monitor lock.</em>

  <dl>

    <dt> <b>Parameters:</b>

    <dd> millis - the maximum time to wait,

                in milliseconds

    <dd> nano - additional time to wait,

                in nanoseconds

                (range 0-999999)

    <dt> <b>Throws:</b> <a href="java.lang.IllegalMonitorStateException.html#¬
_top_">IllegalMonitorStateException</a>

    <dd> If the

            current thread is not the owner

            of the Object's monitor lock.

    <dt> <b>Throws:</b> <a href="java.lang.InterruptedException.html#_top_">I¬
nterruptedException</a>

    <dd> Another thread has

            interrupted this thread.

  </dl>

</dl>

<a name="wait()"><img src="images/red-ball.gif" width=12 height=12 alt=" o ">¬
</a>

<a name="wait"><b>wait</b></a>

<pre>

  public final void wait() throws <a href="java.lang.InterruptedException.htm¬
l#_top_">InterruptedException</a>

</pre>

<dl>

  <dd> Causes a thread to wait forever until it is notified.

<p>

<em>The method wait() can be called only by the

thread that is the owner of the current object's

monitor lock.</em>

  <dl>

    <dt> <b>Throws:</b> <a href="java.lang.IllegalMonitorStateException.html#¬
_top_">IllegalMonitorStateException</a>

    <dd> If the

            current thread is not the owner

            of the Object's monitor lock.

    <dt> <b>Throws:</b> <a href="java.lang.InterruptedException.html#_top_">I¬
nterruptedException</a>

    <dd> Another thread has

            interrupted this thread.

  </dl>

</dl>

<a name="finalize()"><img src="images/red-ball.gif" width=12 height=12 alt=" ¬
o "></a>

<a name="finalize"><b>finalize</b></a>

<pre>

  protected void finalize() throws <a href="java.lang.Throwable.html#_top_">T¬
hrowable</a>

</pre>

<dl>

  <dd> Code to perform when this object is garbage collected.

The default is that nothing needs to be performed.

Any exception thrown by a finalize method causes the

finalization to halt.  But otherwise, it is ignored.

</dl>

<hr>

<pre>

<a href="packages.html">All Packages</a>  <a href="tree.html">Class Hierarchy¬
</a>  <a href="Package-java.lang.html">This Package</a>  <a href="java.lang.N¬
umber.html#_top_">Previous</a>  <a href="java.lang.OutOfMemoryError.html#_top¬
_">Next</a>  <a href="AllNames.html">Index</a></pre>

</body>

</html>

Many of the lines in this HTML file are far too long to fit onto these pages. We have used the character "¬" at the end of a line to indicate that the following line of text on the page is part of the same line in the generated file.

This generated HTML file is meant only as an example, not as a specification of the behavior of the javadoc tool, which may be changed over time to improve the HTML presentation of the documentation information.

Very few facts are able to tell their own story,
without comments to bring out their meaning.
—John Stuart Mill, On Liberty (1869)


 19. LALR(1) Grammar

CHAPTER 19

LALR(1) Grammar

This chapter presents a grammar for Java. The grammar has been mechanically checked to insure that it is LALR(1).

The grammar for Java presented piecemeal in the preceding chapters is much better for exposition, but it cannot be parsed left-to-right with one token of lookahead because of certain syntactic peculiarities, some of them inherited from C and C++. These problems and the solutions adopted for the LALR(1) grammar are presented below, followed by the grammar itself.


19.1 Grammatical Difficulties

There are five problems with the grammar presented in preceding chapters.


19.1.1 Problem #1: Names Too Specific

Consider the two groups of productions:

PackageName:

    Identifier

    PackageName . Identifier

TypeName:

    Identifier

    PackageName . Identifier

and:

MethodName:

    Identifier

    AmbiguousName . Identifier

AmbiguousName:

    Identifier

    AmbiguousName . Identifier

Now consider the partial input:

class Problem1 { int m() { hayden.

When the parser is considering the token hayden, with one-token lookahead to symbol ".", it cannot yet tell whether hayden should be a PackageName that qualifies a type name, as in:

hayden.Dinosaur rex = new Hayden.Dinosaur(2);

or an AmbiguousName that qualifies a method name, as in:

hayden.print("Dinosaur Rex!");

Therefore, the productions shown above result in a grammar that is not LALR(1). There are also other problems with drawing distinctions among different kinds of names in the grammar.

The solution is to eliminate the nonterminals PackageName, TypeName, ExpressionName, MethodName, and AmbiguousName, replacing them all with a single nonterminal Name:

Name:

    SimpleName

    QualifiedName

SimpleName:

    Identifier

QualifiedName:

    Name . Identifier

A later stage of compiler analysis then sorts out the precise role of each name or name qualifier.

For related reasons, these productions in §4.3:

ClassOrInterfaceType:

    ClassType

    InterfaceType

ClassType:

    TypeName

InterfaceType:

    TypeName

were changed to:

ClassOrInterfaceType:

    Name

ClassType:

    ClassOrInterfaceType

InterfaceType:

    ClassOrInterfaceType


19.1.2 Problem #2: Modifiers Too Specific

Consider the two groups of productions:

FieldDeclaration:

    FieldModifiersopt Type VariableDeclarators ;

FieldModifiers:

    FieldModifier

    FieldModifiers FieldModifier

FieldModifier: one of

    public protected private

    final static transient volatile

and:

MethodHeader:

    MethodModifiersopt ResultType MethodDeclarator Throwsopt

MethodModifiers:

    MethodModifier

    MethodModifiers MethodModifier

MethodModifier: one of

    public protected private

    static

    abstract final native synchronized

Now consider the partial input:

class Problem2 { public static int

When the parser is considering the token static, with one-token lookahead to symbol int-or, worse yet, considering the token public with lookahead to static-it cannot yet tell whether this will be a field declaration such as:

public static int maddie = 0;

or a method declaration such as:

public static int maddie(String art) { return art.length(); }

Therefore, the parser cannot tell with only one-token lookahead whether static (or, similarly, public) should be reduced to FieldModifier or MethodModifier. Therefore, the productions shown above result in a grammar that is not LALR(1). There are also other problems with drawing distinctions among different kinds of modifiers in the grammar.

While not all contexts provoke the problem, the simplest solution is to combine all contexts in which such modifiers are used, eliminating all six of the nonterminals ClassModifiers (§8.1.2), FieldModifiers (§8.3.1), MethodModifiers (§8.4.3), ConstructorModifiers (§8.6.3), InterfaceModifiers (§9.1.2), and ConstantModifiers (§9.3) from the grammar, replacing them all with a single nonterminal Modifiers:

Modifiers:

    Modifier

    Modifiers Modifier

Modifier: one of

    public protected private

    static

    abstract final native synchronized transient volatile

A later stage of compiler analysis then sorts out the precise role of each modifier and whether it is permitted in a given context.


19.1.3 Problem #3: Field Declaration versus Method Declaration

Consider the two productions (shown after problem #2 has been corrected):

FieldDeclaration:

    Modifiersopt Type VariableDeclarators ;

and:

MethodHeader:

    Modifiersopt ResultType MethodDeclarator Throwsopt

where ResultType is defined as:

ResultType:

    Type

    void

Now consider the partial input:

class Problem3 { int julie

Note that, in this simple example, no Modifiers are present. When the parser is considering the token int, with one-token lookahead to symbol julie, it cannot yet tell whether this will be a field declaration such as:

int julie = 14;

or a method declaration such as:

int julie(String art) { return art.length(); }

Therefore, after the parser reduces int to the nonterminal Type, it cannot tell with only one-token lookahead whether Type should be further reduced to ResultType (for a method declaration) or left alone (for a field declaration). Therefore, the productions shown above result in a grammar that is not LALR(1).

The solution is to eliminate the ResultType production and to have separate alternatives for MethodHeader:

MethodHeader:

    Modifiersopt Type MethodDeclarator Throwsopt

    Modifiersopt void MethodDeclarator Throwsopt

This allows the parser to reduce int to Type and then leave it as is, delaying the decision as to whether a field declaration or method declaration is in progress.


19.1.4 Problem #4: Array Type versus Array Access

Consider the productions (shown after problem #1 has been corrected):

ArrayType:

    Type [ ]

and:

ArrayAccess:

    Name [ Expression ]

    PrimaryNoNewArray [ Expression ]

Now consider the partial input:

class Problem4 { Problem4() { peter[

When the parser is considering the token peter, with one-token lookahead to symbol [, it cannot yet tell whether peter will be part of a type name, as in:

peter[] team;

or part of an array access, as in:

peter[3] = 12;

Therefore, after the parser reduces peter to the nonterminal Name, it cannot tell with only one-token lookahead whether Name should be reduced ultimately to Type (for an array type) or left alone (for an array access). Therefore, the productions shown above result in a grammar that is not LALR(1).

The solution is to have separate alternatives for ArrayType:

ArrayType:

    PrimitiveType [ ]

    Name [ ]

    ArrayType [ ]

This allows the parser to reduce peter to Name and then leave it as is, delaying the decision as to whether an array type or array access is in progress.


19.1.5 Problem #5: Cast versus Parenthesized Expression

Consider the production:

CastExpression:

    ( PrimitiveType ) UnaryExpression

    ( ReferenceType ) UnaryExpressionNotPlusMinus

Now consider the partial input:

class Problem5 { Problem5() { super((matthew)

When the parser is considering the token matthew, with one-token lookahead to symbol ), it cannot yet tell whether (matthew) will be a parenthesized expression, as in:

super((matthew), 9);

or a cast, as in:

super((matthew)baz, 9);

Therefore, after the parser reduces matthew to the nonterminal Name, it cannot tell with only one-token lookahead whether Name should be further reduced to PostfixExpression and ultimately to Expression (for a parenthesized expression) or to ClassOrInterfaceType and then to ReferenceType (for a cast). Therefore, the productions shown above result in a grammar that is not LALR(1).

The solution is to eliminate the use of the nonterminal ReferenceType in the definition of CastExpression, which requires some reworking of both alternatives to avoid other ambiguities:

CastExpression:

    ( PrimitiveType Dimsopt ) UnaryExpression

    ( Expression ) UnaryExpressionNotPlusMinus

    ( Name Dims ) UnaryExpressionNotPlusMinus

This allows the parser to reduce matthew to Expression and then leave it there, delaying the decision as to whether a parenthesized expression or a cast is in progress. Inappropriate variants such as:

(int[])+3

and:

(matthew+1)baz

must then be weeded out and rejected by a later stage of compiler analysis.

The remaining sections of this chapter constitute a LALR(1) grammar for Java syntax, in which the five problems described above have been solved.


19.2 Grammar from §2.3: The Syntactic Grammar

19.2 Grammar from §2.3: The Syntactic Grammar §2.3

Goal:

    CompilationUnit


19.3 Grammar from §3: Lexical Structure

19.3 Grammar from §3: Lexical Structure §3

Literal:

    IntegerLiteral

    FloatingPointLiteral

    BooleanLiteral

    CharacterLiteral

    StringLiteral

    NullLiteral


19.4 Grammar from §4: Types, Values, and Variables

19.4 Grammar from §4: Types, Values, and Variables §4

Type:

    PrimitiveType

    ReferenceType

PrimitiveType:

    NumericType

    boolean

NumericType:

    IntegralType

    FloatingPointType

IntegralType: one of

    byte short int long char

FloatingPointType: one of

    float double

ReferenceType:

    ClassOrInterfaceType

    ArrayType

ClassOrInterfaceType:

    Name

ClassType:

    ClassOrInterfaceType

InterfaceType:

    ClassOrInterfaceType

ArrayType:

    PrimitiveType [ ]

    Name [ ]

    ArrayType [ ]


19.5 Grammar from §6: Names

19.5 Grammar from §6: Names §6

Name:

    SimpleName

    QualifiedName

SimpleName:

    Identifier

QualifiedName:

    Name . Identifier


19.6 Grammar from §7: Packages

19.6 Grammar from §7: Packages §7

CompilationUnit:

    PackageDeclarationopt ImportDeclarationsopt TypeDeclarationsopt

ImportDeclarations:

    ImportDeclaration

    ImportDeclarations ImportDeclaration

TypeDeclarations:

    TypeDeclaration

    TypeDeclarations TypeDeclaration

PackageDeclaration:

    package Name ;

ImportDeclaration:

    SingleTypeImportDeclaration

    TypeImportOnDemandDeclaration

SingleTypeImportDeclaration:

    import Name ;

TypeImportOnDemandDeclaration:

    import Name . * ;

TypeDeclaration:

    ClassDeclaration

    InterfaceDeclaration

    ;


19.7 Productions Used Only in the LALR(1) Grammar

Modifiers:

    Modifier

    Modifiers Modifier

Modifier: one of

    public protected private

    static

    abstract final native synchronized transient volatile


19.8 Grammar from §8: Classes

19.8 Grammar from §8: Classes §8


19.8.1 Grammar from §8.1: Class Declaration

19.8.1 Grammar from §8.1: Class Declaration §8.1

ClassDeclaration:

    Modifiersopt class Identifier Superopt Interfacesopt ClassBody

Super:

    extends ClassType

Interfaces:

    implements InterfaceTypeList

InterfaceTypeList:

    InterfaceType

    InterfaceTypeList , InterfaceType

ClassBody:

    { ClassBodyDeclarationsopt }

ClassBodyDeclarations:

    ClassBodyDeclaration

    ClassBodyDeclarations ClassBodyDeclaration

ClassBodyDeclaration:

    ClassMemberDeclaration

    StaticInitializer

    ConstructorDeclaration

ClassMemberDeclaration:

    FieldDeclaration

    MethodDeclaration


19.8.2 Grammar from §8.3: Field Declarations

19.8.2 Grammar from §8.3: Field Declarations §8.3

FieldDeclaration:

    Modifiersopt Type VariableDeclarators ;

VariableDeclarators:

    VariableDeclarator

    VariableDeclarators , VariableDeclarator

VariableDeclarator:

    VariableDeclaratorId

    VariableDeclaratorId = VariableInitializer

VariableDeclaratorId:

    Identifier

    VariableDeclaratorId [ ]

VariableInitializer:

    Expression

    ArrayInitializer


19.8.3 Grammar from §8.4: Method Declarations

19.8.3 Grammar from §8.4: Method Declarations §8.4

MethodDeclaration:

    MethodHeader MethodBody

MethodHeader:

    Modifiersopt Type MethodDeclarator Throwsopt

    Modifiersopt void MethodDeclarator Throwsopt

MethodDeclarator:

    Identifier ( FormalParameterListopt )

    MethodDeclarator [ ]

FormalParameterList:

    FormalParameter

    FormalParameterList , FormalParameter

FormalParameter:

    Type VariableDeclaratorId

Throws:

    throws ClassTypeList

ClassTypeList:

    ClassType

    ClassTypeList , ClassType

MethodBody:

    Block

    ;


19.8.4 Grammar from §8.5: Static Initializers

19.8.4 Grammar from §8.5: Static Initializers §8.5

StaticInitializer:

    static Block


19.8.5 Grammar from §8.6: Constructor Declarations

19.8.5 Grammar from §8.6: Constructor Declarations §8.6

ConstructorDeclaration:

    Modifiersopt ConstructorDeclarator Throwsopt ConstructorBody

ConstructorDeclarator:

    SimpleName ( FormalParameterListopt )

ConstructorBody:

    { ExplicitConstructorInvocationopt BlockStatementsopt }

ExplicitConstructorInvocation:

    this ( ArgumentListopt ) ;

    super ( ArgumentListopt ) ;


19.9 Grammar from §9: Interfaces

19.9 Grammar from §9: Interfaces §9


19.9.1 Grammar from §9.1: Interface Declarations

19.9.1 Grammar from §9.1: Interface Declarations §9.1

InterfaceDeclaration:

    Modifiersopt interface Identifier ExtendsInterfacesopt InterfaceBody

ExtendsInterfaces:

    extends InterfaceType

    ExtendsInterfaces , InterfaceType

InterfaceBody:

    { InterfaceMemberDeclarationsopt }

InterfaceMemberDeclarations:

    InterfaceMemberDeclaration

    InterfaceMemberDeclarations InterfaceMemberDeclaration

InterfaceMemberDeclaration:

    ConstantDeclaration

    AbstractMethodDeclaration

ConstantDeclaration:

    FieldDeclaration

AbstractMethodDeclaration:

    MethodHeader ;


19.10 Grammar from §10: Arrays

19.10 Grammar from §10: Arrays §10

ArrayInitializer:

    { VariableInitializersopt ,opt }

VariableInitializers:

    VariableInitializer

    VariableInitializers , VariableInitializer


19.11 Grammar from §14: Blocks and Statements

19.11 Grammar from §14: Blocks and Statements §14

Block:

    { BlockStatementsopt }

BlockStatements:

    BlockStatement

    BlockStatements BlockStatement

BlockStatement:

    LocalVariableDeclarationStatement

    Statement

LocalVariableDeclarationStatement:

    LocalVariableDeclaration ;

LocalVariableDeclaration:

    Type VariableDeclarators

Statement:

    StatementWithoutTrailingSubstatement

    LabeledStatement

    IfThenStatement

    IfThenElseStatement

    WhileStatement

    ForStatement

StatementNoShortIf:

    StatementWithoutTrailingSubstatement

    LabeledStatementNoShortIf

    IfThenElseStatementNoShortIf

    WhileStatementNoShortIf

    ForStatementNoShortIf

StatementWithoutTrailingSubstatement:

    Block

    EmptyStatement

    ExpressionStatement

    SwitchStatement

    DoStatement

    BreakStatement

    ContinueStatement

    ReturnStatement

    SynchronizedStatement

    ThrowStatement

    TryStatement

EmptyStatement:

    ;

LabeledStatement:

    Identifier : Statement

LabeledStatementNoShortIf:

    Identifier : StatementNoShortIf

ExpressionStatement:

    StatementExpression ;

StatementExpression:

    Assignment

    PreIncrementExpression

    PreDecrementExpression

    PostIncrementExpression

    PostDecrementExpression

    MethodInvocation

    ClassInstanceCreationExpression

IfThenStatement:

    if ( Expression ) Statement

IfThenElseStatement:

    if ( Expression ) StatementNoShortIf else Statement

IfThenElseStatementNoShortIf:

    if ( Expression ) StatementNoShortIf else StatementNoShortIf

SwitchStatement:

    switch ( Expression ) SwitchBlock

SwitchBlock:

    { SwitchBlockStatementGroupsopt SwitchLabelsopt }

SwitchBlockStatementGroups:

    SwitchBlockStatementGroup

    SwitchBlockStatementGroups SwitchBlockStatementGroup

SwitchBlockStatementGroup:

    SwitchLabels BlockStatements

SwitchLabels:

    SwitchLabel

    SwitchLabels SwitchLabel

SwitchLabel:

    case ConstantExpression :

    default :

WhileStatement:

    while ( Expression ) Statement

WhileStatementNoShortIf:

    while ( Expression ) StatementNoShortIf

DoStatement:

    do Statement while ( Expression ) ;

ForStatement:

    for ( ForInitopt ; Expressionopt ; ForUpdateopt )

        Statement

ForStatementNoShortIf:

    for ( ForInitopt ; Expressionopt ; ForUpdateopt )

        StatementNoShortIf

ForInit:

    StatementExpressionList

    LocalVariableDeclaration

ForUpdate:

    StatementExpressionList

StatementExpressionList:

    StatementExpression

    StatementExpressionList , StatementExpression

BreakStatement:

    break Identifieropt ;

ContinueStatement:

    continue Identifieropt ;

ReturnStatement:

    return Expressionopt ;

ThrowStatement:

    throw Expression ;

SynchronizedStatement:

    synchronized ( Expression ) Block

TryStatement:

    try Block Catches

    try Block Catchesopt Finally

Catches:

    CatchClause

    Catches CatchClause

CatchClause:

    catch ( FormalParameter ) Block

Finally:

    finally Block


19.12 Grammar from §15: Expressions

19.12 Grammar from §15: Expressions §15

Primary:

    PrimaryNoNewArray

    ArrayCreationExpression

PrimaryNoNewArray:

    Literal

    this

    ( Expression )

    ClassInstanceCreationExpression

    FieldAccess

    MethodInvocation

    ArrayAccess

ClassInstanceCreationExpression:

    new ClassType ( ArgumentListopt )

ArgumentList:

    Expression

    ArgumentList , Expression

ArrayCreationExpression:

    new PrimitiveType DimExprs Dimsopt

    new ClassOrInterfaceType DimExprs Dimsopt

DimExprs:

    DimExpr

    DimExprs DimExpr

DimExpr:

    [ Expression ]

Dims:

    [ ]

    Dims [ ]

FieldAccess:

    Primary . Identifier

    super . Identifier

MethodInvocation:

    Name ( ArgumentListopt )

    Primary . Identifier ( ArgumentListopt )

    super . Identifier ( ArgumentListopt )

ArrayAccess:

    Name [ Expression ]

    PrimaryNoNewArray [ Expression ]

PostfixExpression:

    Primary

    Name

    PostIncrementExpression

    PostDecrementExpression

PostIncrementExpression:

    PostfixExpression ++

PostDecrementExpression:

    PostfixExpression --

UnaryExpression:

    PreIncrementExpression

    PreDecrementExpression

    + UnaryExpression

    - UnaryExpression

    UnaryExpressionNotPlusMinus

PreIncrementExpression:

    ++ UnaryExpression

PreDecrementExpression:

    -- UnaryExpression

UnaryExpressionNotPlusMinus:

    PostfixExpression

    ~ UnaryExpression

    ! UnaryExpression

    CastExpression

CastExpression:

    ( PrimitiveType Dimsopt ) UnaryExpression

    ( Expression ) UnaryExpressionNotPlusMinus

    ( Name Dims ) UnaryExpressionNotPlusMinus

MultiplicativeExpression:

    UnaryExpression

    MultiplicativeExpression * UnaryExpression

    MultiplicativeExpression / UnaryExpression

    MultiplicativeExpression % UnaryExpression

AdditiveExpression:

    MultiplicativeExpression

    AdditiveExpression + MultiplicativeExpression

    AdditiveExpression - MultiplicativeExpression

ShiftExpression:

    AdditiveExpression

    ShiftExpression << AdditiveExpression

    ShiftExpression >> AdditiveExpression

    ShiftExpression >>> AdditiveExpression

RelationalExpression:

    ShiftExpression

    RelationalExpression < ShiftExpression

    RelationalExpression > ShiftExpression

    RelationalExpression <= ShiftExpression

    RelationalExpression >= ShiftExpression

    RelationalExpression instanceof ReferenceType

EqualityExpression:

    RelationalExpression

    EqualityExpression == RelationalExpression

    EqualityExpression != RelationalExpression

AndExpression:

    EqualityExpression

    AndExpression & EqualityExpression

ExclusiveOrExpression:

    AndExpression

    ExclusiveOrExpression ^ AndExpression

InclusiveOrExpression:

    ExclusiveOrExpression

    InclusiveOrExpression | ExclusiveOrExpression

ConditionalAndExpression:

    InclusiveOrExpression

    ConditionalAndExpression && InclusiveOrExpression

ConditionalOrExpression:

    ConditionalAndExpression

    ConditionalOrExpression || ConditionalAndExpression

ConditionalExpression:

    ConditionalOrExpression

    ConditionalOrExpression ? Expression : ConditionalExpression

AssignmentExpression:

    ConditionalExpression

    Assignment

Assignment:

    LeftHandSide AssignmentOperator AssignmentExpression

LeftHandSide:

    Name

    FieldAccess

    ArrayAccess

AssignmentOperator: one of

    = *= /= %= += -= <<= >>= >>>= &= ^= |=

Expression:

    AssignmentExpression

ConstantExpression:

    Expression


 20. The Package java.lang

CHAPTER 20

The Package java.lang

The java.lang package contains classes that are fundamental to the design of the Java language. The most important classes are Object, which is the root of the class hierarchy, and Class, instances of which represent classes at run time.

Frequently it is necessary to represent a value of primitive type as if it were an object. The wrapper classes Boolean, Character, Integer, Long, Float, and Double serve this purpose. An object of type Double, for example, contains a field whose type is double, representing that value in such a way that a reference to it can be stored in a variable of reference type. These classes also provide a number of methods for converting among primitive values, as well as supporting such standard methods as equals and hashCode.

The class Math provides commonly used mathematical functions such as sine, cosine, and square root. The classes String and StringBuffer similarly provide commonly used operations on character strings.

Classes ClassLoader, Process, Runtime, SecurityManager, and System provide "system operations" that manage the dynamic loading of classes, creation of external processes, host environment inquiries such as the time of day, and enforcement of security policies.

Class Throwable encompasses objects that may be thrown by the throw statement (§14.16). Subclasses of Throwable represent errors and exceptions.

The hierarchy of classes defined in package java.lang is as follows.

Object §20.1
 interface Cloneable §20.2
    Class §20.3
    Boolean §20.4
    Character §20.5
    Number §20.6
        Integer §20.7
        Long §20.8
        Float §20.9
        Double §20.10
    Math §20.11
    String §20.12
    StringBuffer §20.13
    ClassLoader §20.14
    Process §20.15
    Runtime §20.16
    SecurityManager §20.17
    System §20.18
    interface Runnable §20.19
    Thread §20.20
    ThreadGroup §20.21
    Throwable §20.22
        Error
            LinkageError
                ClassCircularityError
                ClassFormatError
                ExceptionInInitializerError
                IncompatibleClassChangeError
                    AbstractMethodError
                    IllegalAccessError
                    InstantiationError
                    NoSuchFieldError
                    NoSuchMethodError
                NoClassDefFoundError
                UnsatisfiedLinkError
                VerifyError
            VirtualMachineError
                InternalError
                OutOfMemoryError
                StackOverflowError
                UnknownError
            ThreadDeath
        Exception
            ClassNotFoundException
            CloneNotSupportedException
            IllegalAccessException
            InstantiationException
            InterruptedException
            RuntimeException
                ArithmeticException
                ArrayStoreException
                ClassCastException
                IllegalArgumentException
                    IllegalThreadStateException
                    NumberFormatException
                IllegalMonitorStateException
                IndexOutOfBoundsException
                NegativeArraySizeException
                NullPointerException
                SecurityException


20.1 The Class java.lang.Object

The class Object is the single root of the class hierarchy. All objects, including arrays, implement the methods of this class.

public class Object {
    public final Class getClass();
    public String toString();
    public boolean equals(Object obj);
    public int hashCode();
    protected Object clone()
        throws CloneNotSupportedException;
    public final void wait()

        throws IllegalMonitorStateException,

            InterruptedException;
    public final void wait(long millis)

        throws IllegalMonitorStateException,

            InterruptedException;
    public final void wait(long millis, int nanos)

        throws IllegalMonitorStateException,
            InterruptedException;
    public final void notify()
        throws IllegalMonitorStateException;
    public final void notifyAll()
        throws IllegalMonitorStateException;
    protected void finalize()

        throws Throwable;
}

20.1.1 public final Class getClass()

This method returns a reference to the unique object of type Class (§20.3) that represents the class of this object. That Class object is the object that is locked by static synchronized methods of the represented class.

20.1.2 public String toString()

The general contract of toString is that it returns a string that "textually represents" this object. The idea is to provide a concise but informative representation that will be useful to a person reading it.

The toString method defined by class Object returns a string consisting of the name of the class of which the object is an instance, a commercial at character '@', and the unsigned hexadecimal representation of the hashcode of the object. In other words, this method returns a string equal to the value of:

getClass().getName() + '@' + Integer.toHexString(hashCode())

Overridden by Class (§20.3), Boolean (§20.4), Character (§20.5), Integer (§20.7), Long (§20.8), Float (§20.9), Double (§20.10), String (§20.12), StringBuffer (§20.13), Thread (§20.20), ThreadGroup (§20.21), Throwable (§20.22.4), and Bitset (§21.2).

20.1.3 public boolean equals(Object obj)

This method indicates whether some other object is "equal to" this one.

The general contract of equals is that it implements an equivalence relation:

  • It is reflexive: for any reference value x, x.equals(x) should return true.
  • It is symmetric: for any reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
  • It is transitive: for any reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
  • It is consistent: for any reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used by x and y in equals comparisons is modified.
  • For any non-null reference value x, x.equals(null) should return false.

The equals method defined by class Object implements the most discriminating possible equivalence relation on objects; that is, for any reference values x and y, ((Object)x).equals(y) returns true if and only if x and y refer to the same object.

Overridden by Boolean (§20.4), Character (§20.5), Integer (§20.7), Long (§20.8), Float (§20.9), Double (§20.10), String (§20.12), and Bitset (§21.2).

20.1.4 public int hashCode()

This method is supported principally for the benefit of hash tables such as those provided by the Java library class java.util.Hashtable (§21.5).

The general contract of hashCode is as follows:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, hashCode must consistently return the same integer. The integer may be positive, negative, or zero. This integer does not, however, have to remain consistent from one Java application to another, or from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals method (§20.1.3), then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the equals method (§20.1.3), then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hashtables.

As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the Java language.)

Overridden by Boolean (§20.4), Character (§20.5), Integer (§20.7), Long (§20.8), Float (§20.9), Double (§20.10), String (§20.12), and Bitset (§21.2).

20.1.5 protected Object clone()
throws CloneNotSupportedException

The general contract of clone is that it creates and returns a copy of this object. The precise meaning of "copy" may depend on the class of the object. The general intent is that, for any object x, the expression:

x.clone() != x

will be true, and that the expression:

x.clone.getClass() == x.getClass()

will be true, but these are not absolute requirements. While it is typically the case that:

x.clone.equals(x)

will be true, this is not an absolute requirement. Copying an object will typically entail creating a new instance of its class, but it also may require copying of internal data structures as well.

The method clone for class Object performs a specific cloning operation. First, if the class of this object does not implement the interface Cloneable, then a CloneNotSupportedException is thrown. Note that all arrays are considered to implement the interface Cloneable. Otherwise, this method creates a new instance of the class of this object and initializes all its fields with exactly the contents of the corresponding fields of this object, as if by assignment; the contents of the fields are not themselves cloned. Thus, this method performs a "shallow copy" of this object, not a "deep copy" operation.

The class Object does not itself implement the interface Cloneable, so calling the clone method on an object whose class is Object will result in throwing an exception at run time. The clone method is implemented by the class Object as a convenient, general utility for subclasses that implement the interface Cloneable, possibly also overriding the clone method, in which case the overriding definition can refer to this utility definition by the call:

super.clone()

20.1.6 public final void wait()
throws IllegalMonitorStateException, InterruptedException

This method causes the current thread to wait until some other thread invokes the notify method (§20.1.9) or the notifyAll method (§20.1.10) for this object.

In other words, this method behaves exactly as if it simply performs the call wait(0) (§20.1.7).

20.1.7 public final void wait(long millis)
throws IllegalMonitorStateException, InterruptedException

This method causes the current thread to wait until either some other thread invokes the notify method (§20.1.9) or the notifyAll method (§20.1.10) for this object, or a certain amount of real time has elapsed.

This method may be called only when the current thread is already synchronized on this object. If the current thread does not own the lock on this object, an IllegalMonitorStateException is thrown.

This method causes the current thread (call it T) to place itself in the wait set (§17.14) for this object and then to relinquish any and all synchronization claims on this object. Thread T becomes disabled for thread scheduling purposes and lies dormant until one of four things happens:

  • Some other thread invokes the notify method for this object and thread T happens to be arbitrarily chosen as the thread to be awakened.
  • Some other thread invokes the notifyAll method for this object.
  • Some other thread interrupts (§20.20.31) thread T.
  • The specified amount of real time has elapsed, more or less. The amount of real time, measured in milliseconds, is given by millis. If millis is zero, however, then real time is not taken into consideration and the thread simply waits until notified.

The thread T is then removed from the wait set for this object and re-enabled for thread scheduling. It then competes in the usual manner with other threads for the right to synchronize on the object; once it has gained control of the object, all its synchronization claims on the object are restored to the status quo ante-that is, to the situation as of the time that the wait method was invoked. Thread T then returns from the invocation of the wait method. Thus, on return from the wait method, the synchronization state of the object and of thread T is exactly as it was when the wait method was invoked.

If the current thread is interrupted (§20.20.31) by another thread while it is waiting, then an InterruptedException is thrown. This exception is not thrown until the lock status of this object has been restored as described above.

Note that the wait method, as it places the current thread into the wait set for this object, unlocks only this object; any other objects on which the current thread may be synchronized remain locked while the thread waits.

20.1.8 public final void wait(long millis, int nanos)
throws IllegalMonitorStateException, InterruptedException

This method causes the current thread to wait until either some other thread invokes the notify method (§20.1.9) or the notifyAll method (§20.1.10) for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed.

The amount of real time, measured in nanoseconds, is given by:

1000000*millis+nanos

In all other respects, this method does the same thing as the method wait of one argument (§20.1.7). In particular, wait(0, 0) means the same thing as wait(0).

20.1.9 public final void notify()
throws IllegalMonitorStateException

If any threads are waiting (§20.1.7) on this object, one of them is chosen to be awakened. The choice is arbitrary and at the discretion of the implementation.

The notify method may be called only when the current thread is already synchronized on this object. If the current thread does not own the lock on this object, an IllegalMonitorStateException is thrown.

The awakened thread will not be able to proceed until the current thread relinquishes the lock on this object. The awakened thread will compete in the usual manner with any other threads that might be actively competing to synchronize on this object; for example, the awakened thread enjoys no reliable privilege or disadvantage in being the next thread to lock this object.

20.1.10 public final void notifyAll()
throws IllegalMonitorStateException

All the threads waiting (§20.1.7) on this object are awakened.

The notifyAll method may be called only when the current thread is already synchronized on this object. If the current thread does not own the lock on this object, an IllegalMonitorStateException is thrown.

The awakened threads will not be able to proceed until the current thread relinquishes the lock on this object. The awakened threads will compete in the usual manner with any other threads that might be actively competing to synchronize on this object; for example, the awakened threads enjoy no reliable privilege or disadvantage in being the next thread to lock this object.

20.1.11 protected void finalize() throws Throwable

The general contract of finalize is that it is invoked if and when the Java Virtual Machine has determined that there is no longer any means by which this object can be accessed by any thread that has not yet died (§12.7), except as a result of an action taken by the finalization of some other object or class which is ready to be finalized. The finalize method may take any action, including making this object available again to other threads; the usual purpose of finalize, however, is to perform cleanup actions before the object is irrevocably discarded. For example, the finalize method for an object that represents an input/output connection might perform explicit I/O transactions to break the connection before the object is permanently discarded.

The finalize method of class Object performs no special action; it simply returns normally. Subclasses of Object may override this definition.

Java does not guarantee which thread will invoke the finalize method for any given object. It is guaranteed, however, that the thread that invokes finalize will not be holding any user-visible synchronization locks when finalize is invoked. If an uncaught exception is thrown by the finalize method, the exception is ignored and finalization of that object terminates.

After the finalize method has been invoked for an object, no further action is taken until the Java Virtual Machine has again determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, including possible actions by other objects or classes which are ready to be finalized, at which point the object may be discarded.

The finalize method is never invoked more than once by a Java Virtual Machine for any given object.


20.2 The Interface java.lang.Cloneable

The Cloneable interface should be implemented by any class that is intended to support or override the method clone (§20.1.5).

public interface Cloneable { }

The interface Cloneable declares no methods.

I am disappointed in Japp. He has no method!
—Agatha Christie, The Mysterious Affair at Styles (1920), Chapter 8


20.3 The Class java.lang.Class

Instances of the class Class represent classes and interfaces in a way that can be manipulated by a running Java program. Every array also belongs to a class represented by a Class object that is shared among all arrays with the same element type and number of dimensions.

There is no public constructor for the class Class. The Java Virtual Machine automatically constructs Class objects as classes are loaded; such objects cannot be created by user programs.

public final class Class {
    public String toString();
    public String getName();
    public boolean isInterface();
    public Class getSuperclass();
    public Class[] getInterfaces();
    public Object newInstance()
        throws InstantiationException, IllegalAccessException;
    public static Class forName(String className)

        throws ClassNotFoundException;
    public ClassLoader getClassLoader();
}

20.3.1 public String toString()

If this Class object represents a class (which may be a declared class or an array class), a string is returned consisting of the word class, a space, and the name of the class as returned by the getName method (§20.3.2). If this Class object represents an interface, a string is returned consisting of the word interface, a space, and the name of the interface as returned by the getName method.

In other words, this method returns a string equal to the value of:

(isInterface() ? "interface " : "class ") + getName()

Overrides the toString method of Object (§20.1.2).

20.3.2 public String getName()

The fully qualified name of the class or interface represented by this Class object is returned as a String. For example:

new Object().getClass().getName()

returns "java.lang.Object".

If this class object represents a class of arrays, then the name consists of the name of the element type in Java signature format, preceded by one or more "[" characters representing the depth of array nesting. For example:

(new Object[3]).getClass().getName()

returns "[Ljava.lang.Object;" and:

(new int[3][4][5][6][7][8][9]).getClass().getName()

returns "[[[[[[[I". The encoding of element type names is as follows:

B				byte
C				char
D				double
F				float
I				int
J				long
Lclassname;				class or interface
S				short
Z				boolean

A class or interface name classname is given in fully qualified form as shown in the example above. For a full description of type descriptors see the chapter on the format of class files in the Java Virtual Machine Specification.

20.3.3 public boolean isInterface()

If this Class object represents an interface, true is returned. If this Class object represents a class, false is returned.

20.3.4 public Class getSuperclass()

If this Class object represents any class other than the class Object, then the Class that represents the superclass of that class is returned. If this Class object is the one that represents the class Object, or if it represents an interface, null is returned. If this Class object represents an array class, then the Class that represents class Object is returned.

20.3.5 public Class[] getInterfaces()

This method returns an array of objects that represent interfaces. The array may be empty.

If this Class object represents a class, the array contains objects representing all interfaces directly implemented by the class. The order of the interface objects in the array corresponds to the order of the interface names in the implements clause of the declaration of the class represented by this Class object. For example, given the class declaration:

class Shimmer implements FloorWax, DessertTopping { ... }

suppose the value of s is an instance of Shimmer; the value of the expression:

s.getClass().getInterfaces()[0]

is the Class object that represents interface FloorWax; and the value of:

s.getClass().getInterfaces()[1]

is the Class object that represents interface DessertTopping.

If this Class object represents an interface, the array contains objects representing all interfaces directly extended by the interface-that is, the immediate superinterfaces of the interface. The order of the interface objects in the array corresponds to the order of the interface names in the extends clause of the declaration of the interface represented by this Class object.

20.3.6 public Object newInstance()
throws InstantiationException, IllegalAccessException

This method creates and returns a new instance of the class represented by this Class object. This is done exactly as if by a class instance creation expression (§15.8) with an empty argument list; for example, if t is the Class object that represents class Thread, then t.newInstance() does exactly the same thing as new Thread(). If evaluation of such a class instance creation expression would complete abruptly, then the call to the newInstance method will complete abruptly for the same reason. See also §11.5.1.2 for more on InstantiationException.

20.3.7 public ClassLoader getClassLoader()

This method returns a reference to the class loader (§20.14) that loaded this class. If this class has no class loader, then null is returned.

20.3.8 public static Class forName(String className)
throws ClassNotFoundException

Given the fully-qualified name of a class as a string, this method attempts to locate, load, and link the class (§12.2). If it succeeds, then a reference to the Class object for the class is returned. If it fails, then a ClassNotFoundException is thrown.


20.4 The Class java.lang.Boolean

Objects of type Boolean represent primitive values of type boolean.

public final class Boolean {
    public static final Boolean TRUE = new Boolean(true);
    public static final Boolean FALSE = new Boolean(false);
    public Boolean(boolean value);
    public Boolean(String s);
    public String toString();
    public boolean equals(Object obj);
    public int hashCode();
    public boolean booleanValue();
    public static Boolean valueOf(String s);
    public static boolean getBoolean(String name);
}

20.4.1 public static final Boolean TRUE = new Boolean(true);

The constant value of this field is a Boolean object corresponding to the primitive value true.

20.4.2 public static final Boolean FALSE = new Boolean(false);

The constant value of this field is a Boolean object corresponding to the primitive value false.

20.4.3 public Boolean(boolean value)

This constructor initializes a newly created Boolean object so that it represents the primitive value that is the argument.

20.4.4 public Boolean(String s)

This constructor initializes a newly created Boolean object so that it represents true if and only if the argument is not null and is equal, ignoring case, to the string "true".

Examples:

new Boolean("True") produces a Boolean object that represents true.
new Boolean("yes") produces a Boolean object that represents false.

20.4.5 public boolean booleanValue()

The primitive boolean value represented by this Boolean object is returned.

20.4.6 public String toString()

If this Boolean object represents true, a string equal to "true" is returned. If this Boolean object represents false, a string equal to "false" is returned.

Overrides the toString method of Object (§20.1.2).

20.4.7 public boolean equals(Object obj)

The result is true if and only if the argument is not null and is a Boolean object that represents the same boolean value as this Boolean object.

Overrides the equals method of Object (§20.1.3).

20.4.8 public int hashCode()

If this Boolean object represents true, the integer 1231 is returned. If this Boolean object represents false, the integer 1237 is returned.

Overrides the hashCode method of Object (§20.1.4).

20.4.9 public static boolean valueOf(String s)

The result is true if and only if the argument is not null and is equal, ignoring case, to the string "true".

Example: Boolean.valueOf("True") returns true.

Example: Boolean.valueOf("yes") returns false.

20.4.10 public static boolean getBoolean(String name)

The result is true if and only if the value of the system property (§20.18.9) named by the argument is equal, ignoring case, to the string "true".

This above all: to thine own self be true,
And it must follow, as the night the day,
Thou canst not then be false to any man.
—William Shakespeare, Hamlet, Act I, scene iii


20.5 The Class java.lang.Character

Here is the whole set! a character dead at every word.
—Richard Brinsley Sheridan, The School for Scandal, Act 2, scene 2

Objects of type Character represent primitive values of type char.

public final class Character {
    public static final char MIN_VALUE = '\u0000';
    public static final char MAX_VALUE = '\uffff';
    public static final int MIN_RADIX = 2;
    public static final int MAX_RADIX = 36;
    public Character(char value);
    public String toString();
    public boolean equals(Object obj);
    public int hashCode();
    public char charValue();
    public static boolean isDefined(char ch);
    public static boolean isLowerCase(char ch);
    public static boolean isUpperCase(char ch);
    public static boolean isTitleCase(char ch);
    public static boolean isDigit(char ch);
    public static boolean isLetter(char ch);
    public static boolean isLetterOrDigit(char ch);
    public static boolean isJavaLetter(char ch);
    public static boolean isJavaLetterOrDigit(char ch);)
    public static boolean isSpace(char ch);
    public static char toLowerCase(char ch);
    public static char toUpperCase(char ch);
    public static char toTitleCase(char ch);
    public static int digit(char ch, int radix);
    public static char forDigit(int digit, int radix);
}

Many of the methods of class Character are defined in terms of a "Unicode attribute table" that specifies a name for every defined Unicode character as well as other possible attributes, such as a decimal value, an uppercase equivalent, a lowercase equivalent, and/or a titlecase equivalent. Prior to Java 1.1, these methods were internal to the Java compiler and based on Unicode 1.1.5, as described here. The most recent versions of these methods should be used in Java compilers that are to run on Java systems that do not yet include these methods.

The Unicode 1.1.5 attribute table is available on the World Wide Web as:

ftp://unicode.org/pub/MappingTables/UnicodeData-1.1.5.txt

However, this file contains a few errors. The term "Unicode attribute table" in the following sections refers to the contents of this file after the following corrections have been applied:

  • The following entries should have titlecase mappings as shown here:

    03D0;GREEK BETA SYMBOL;Ll;0;L;;;;;N;GREEK SMALL LETTER CURLED BETA;;0392;;0392

    03D1;GREEK THETA SYMBOL;Ll;0;L;;;;;N;GREEK SMALL LETTER SCRIPT THETA;;0398;;0398

    03D5;GREEK PHI SYMBOL;Ll;0;L;;;;;N;GREEK SMALL LETTER SCRIPT PHI;;03A6;;03A6

    03D6;GREEK PI SYMBOL;Ll;0;L;;;;;N;GREEK SMALL LETTER OMEGA PI;;03A0;;03A0

    03F0;GREEK KAPPA SYMBOL;Ll;0;L;;;;;N;GREEK SMALL LETTER SCRIPT KAPPA;;039A;;039A

    03F1;GREEK RHO SYMBOL;Ll;0;L;;;;;N;GREEK SMALL LETTER TAILED RHO;;03A1;;03A1

  • The following entries should have numeric values as shown here:

    FF10;FULLWIDTH DIGIT ZERO;Nd;0;EN;0030;0;0;0;N;;;;;

    FF11;FULLWIDTH DIGIT ONE;Nd;0;EN;0031;1;1;1;N;;;;;

    FF12;FULLWIDTH DIGIT TWO;Nd;0;EN;0032;2;2;2;N;;;;;

    FF13;FULLWIDTH DIGIT THREE;Nd;0;EN;0033;3;3;3;N;;;;;

    FF14;FULLWIDTH DIGIT FOUR;Nd;0;EN;0034;4;4;4;N;;;;;

    FF15;FULLWIDTH DIGIT FIVE;Nd;0;EN;0035;5;5;5;N;;;;;

    FF16;FULLWIDTH DIGIT SIX;Nd;0;EN;0036;6;6;6;N;;;;;

    FF17;FULLWIDTH DIGIT SEVEN;Nd;0;EN;0037;7;7;7;N;;;;;

    FF18;FULLWIDTH DIGIT EIGHT;Nd;0;EN;0038;8;8;8;N;;;;;

    FF19;FULLWIDTH DIGIT NINE;Nd;0;EN;0039;9;9;9;N;;;;;

  • The following entries should have no lowercase equivalents:

    03DA;GREEK LETTER STIGMA;Lu;0;L;;;;;N;GREEK CAPITAL LETTER STIGMA;;;;

    03DC;GREEK LETTER DIGAMMA;Lu;0;L;;;;;N;GREEK CAPITAL LETTER DIGAMMA;;;;

    03DE;GREEK LETTER KOPPA;Lu;0;L;;;;;N;GREEK CAPITAL LETTER KOPPA;;;;

    03E0;GREEK LETTER SAMPI;Lu;0;L;;;;;N;GREEK CAPITAL LETTER SAMPI;;;;

  • This entry should have uppercase and titlecase equivalents as shown here:

    03C2;GREEK SMALL LETTER FINAL SIGMA;Ll;0;L;;;;;N;;;03A3;;03A3

It is anticipated that these problems will be corrected for Unicode version 2.0.

Java 1.1 will include the methods defined here, either based on Unicode 1.1.5 or, we hope, updated versions of the methods that use the newer Unicode 2.0. The character attribute table for Unicode 2.0 is currently available on the World Wide Web as the file:

ftp://unicode.org/pub/MappingTables/UnicodeData-2.0.12.txt

If you are implementing a Java compiler or system, please refer to the page:

http://java.sun.com/Series/

which will be updated with information about the Unicode-dependent methods.

The biggest change in Unicode 2.0 is a complete rearrangement of the Korean Hangul characters. There are numerous smaller improvements as well.

It is our intention that Java will track Unicode as it evolves over time. Given that full Unicode support is just emerging in the marketplace, and that changes in Unicode are in areas which are not yet widely used, this should cause minimal problems and further Java's goal of worldwide language support.

20.5.1 public static final char MIN_VALUE = '\u0000';

The constant value of this field is the smallest value of type char.

[This field is scheduled for introduction in Java version 1.1.]

20.5.2 public static final char MAX_VALUE = '\uffff';

The constant value of this field is the smallest value of type char.

[This field is scheduled for introduction in Java version 1.1.]

20.5.3 public static final int MIN_RADIX = 2;

The constant value of this field is the smallest value permitted for the radix argument in radix-conversion methods such as the digit method (§20.5.23), the forDigit method (§20.5.24), and the toString method of class Integer (§20.7).

20.5.4 public static final int MAX_RADIX = 36;

The constant value of this field is the largest value permitted for the radix argument in radix-conversion methods such as the digit method (§20.5.23), the forDigit method (§20.5.24), and the toString method of class Integer (§20.7).

20.5.5 public Character(char value)

This constructor initializes a newly created Character object so that it represents the primitive value that is the argument.

20.5.6 public String toString()

The result is a String whose length is 1 and whose sole component is the primitive char value represented by this Character object.

Overrides the toString method of Object (§20.1.2).

20.5.7 public boolean equals(Object obj)

The result is true if and only if the argument is not null and is a Character object that represents the same char value as this Character object.

Overrides the equals method of Object (§20.1.3).

20.5.8 public int hashCode()

The result is the primitive char value represented by this Character object, cast to type int.

Overrides the hashCode method of Object (§20.1.4).

20.5.9 public char charValue()

The primitive char value represented by this Character object is returned.

20.5.10 public static boolean isDefined(char ch)

The result is true if and only if the character argument is a defined Unicode character.

A character is a defined Unicode character if and only if at least one of the following is true:

  • It has an entry in the Unicode attribute table.
  • It is not less than \u3040 and not greater than \u9FA5.
  • It is not less than \uF900 and not greater than \uFA2D.

It follows, then, that for Unicode 1.1.5 as corrected above, the defined Unicode characters are exactly those with codes in the following list, which contains both single codes and inclusive ranges: 0000-01F5, 01FA-0217, 0250-02A8, 02B0-02DE, 02E0-02E9, 0300-0345, 0360-0361, 0374-0375, 037A, 037E, 0384-038A, 038C, 038E-03A1, 03A3-03CE, 03D0-03D6, 03DA, 03DC, 03DE, 03E0, 03E2-03F3, 0401-040C, 040E-044F, 0451-045C, 045E-0486, 0490-04C4, 04C7-04C8, 04CB-04CC, 04D0-04EB, 04EE-04F5, 04F8-04F9, 0531-0556, 0559-055F, 0561-0587, 0589, 05B0-05B9, 05BB-05C3, 05D0-05EA, 05F0-05F4, 060C, 061B, 061F, 0621-063A, 0640-0652, 0660-066D, 0670-06B7, 06BA-06BE, 06C0-06CE, 06D0-06ED, 06F0-06F9, 0901-0903, 0905-0939, 093C-094D, 0950-0954, 0958-0970, 0981-0983, 0985-098C, 098F-0990, 0993-09A8, 09AA-09B0, 09B2, 09B6-09B9, 09BC, 09BE-09C4, 09C7-09C8, 09CB-09CD, 09D7, 09DC-09DD, 09DF-09E3, 09E6-09FA, 0A02, 0A05-0A0A, 0A0F-0A10, 0A13-0A28, 0A2A-0A30, 0A32-0A33, 0A35-0A36, 0A38-0A39, 0A3C, 0A3E-0A42, 0A47-0A48, 0A4B-0A4D, 0A59-0A5C, 0A5E, 0A66-0A74, 0A81-0A83, 0A85-0A8B, 0A8D, 0A8F-0A91, 0A93-0AA8, 0AAA-0AB0, 0AB2-0AB3, 0AB5-0AB9, 0ABC-0AC5, 0AC7-0AC9, 0ACB-0ACD, 0AD0, 0AE0, 0AE6-0AEF, 0B01-0B03, 0B05-0B0C, 0B0F-0B10, 0B13-0B28, 0B2A-0B30, 0B32-0B33, 0B36-0B39, 0B3C-0B43, 0B47-0B48, 0B4B-0B4D, 0B56-0B57, 0B5C-0B5D, 0B5F-0B61, 0B66-0B70, 0B82-0B83, 0B85-0B8A, 0B8E-0B90, 0B92-0B95, 0B99-0B9A, 0B9C, 0B9E-0B9F, 0BA3-0BA4, 0BA8-0BAA, 0BAE-0BB5, 0BB7-0BB9, 0BBE-0BC2, 0BC6-0BC8, 0BCA-0BCD, 0BD7, 0BE7-0BF2, 0C01-0C03, 0C05-0C0C, 0C0E-0C10, 0C12-0C28, 0C2A-0C33, 0C35-0C39, 0C3E-0C44, 0C46-0C48, 0C4A-0C4D, 0C55-0C56, 0C60-0C61, 0C66-0C6F, 0C82-0C83, 0C85-0C8C, 0C8E-0C90, 0C92-0CA8, 0CAA-0CB3, 0CB5-0CB9, 0CBE-0CC4, 0CC6-0CC8, 0CCA-0CCD, 0CD5-0CD6, 0CDE, 0CE0-0CE1, 0CE6-0CEF, 0D02-0D03, 0D05-0D0C, 0D0E-0D10, 0D12-0D28, 0D2A-0D39, 0D3E-0D43, 0D46-0D48, 0D4A-0D4D, 0D57, 0D60-0D61, 0D66-0D6F, 0E01-0E3A, 0E3F-0E5B, 0E81-0E82, 0E84, 0E87-0E88, 0E8A, 0E8D, 0E94-0E97, 0E99-0E9F, 0EA1-0EA3, 0EA5, 0EA7, 0EAA-0EAB, 0EAD-0EB9, 0EBB-0EBD, 0EC0-0EC4, 0EC6, 0EC8-0ECD, 0ED0-0ED9, 0EDC-0EDD, 10A0-10C5, 10D0-10F6, 10FB, 1100-1159, 115F-11A2, 11A8-11F9, 1E00-1E9A, 1EA0-1EF9, 1F00-1F15, 1F18-1F1D, 1F20-1F45, 1F48-1F4D, 1F50-1F57, 1F59, 1F5B, 1F5D, 1F5F-1F7D, 1F80-1FB4, 1FB6-1FC4, 1FC6-1FD3, 1FD6-1FDB, 1FDD-1FEF, 1FF2-1FF4, 1FF6-1FFE, 2000-202E, 2030-2046, 206A-2070, 2074-208E, 20A0-20AA, 20D0-20E1, 2100-2138, 2153-2182, 2190-21EA, 2200-22F1, 2300, 2302-237A, 2400-2424, 2440-244A, 2460-24EA, 2500-2595, 25A0-25EF, 2600-2613, 261A-266F, 2701-2704, 2706-2709, 270C-2727, 2729-274B, 274D, 274F-2752, 2756, 2758-275E, 2761-2767, 2776-2794, 2798-27AF, 27B1-27BE, 3000-3037, 303F, 3041-3094, 3099-309E, 30A1-30FE, 3105-312C, 3131-318E, 3190-319F, 3200-321C, 3220-3243, 3260-327B, 327F-32B0, 32C0-32CB, 32D0-32FE, 3300-3376, 337B-33DD, 33E0-33FE, 3400-9FA5, F900-FA2D, FB00-FB06, FB13-FB17, FB1E-FB36, FB38-FB3C, FB3E, FB40-FB41, FB43-FB44, FB46-FBB1, FBD3-FD3F, FD50-FD8F, FD92-FDC7, FDF0-FDFB, FE20-FE23, FE30-FE44, FE49-FE52, FE54-FE66, FE68-FE6B, FE70-FE72, FE74, FE76-FEFC, FEFF, FF01-FF5E, FF61-FFBE, FFC2-FFC7, FFCA-FFCF, FFD2-FFD7, FFDA-FFDC, FFE0-FFE6, FFE8-FFEE, FFFD.

[This method is scheduled for introduction in Java version 1.1, either as defined here, or updated for Unicode 2.0; see §20.5.]

20.5.11 public static boolean isLowerCase(char ch)

The result is true if and only if the character argument is a lowercase character.

A character is considered to be lowercase if and only if all of the following are true:

  • The character ch is not in the range \u2000 through \u2FFF.
  • The Unicode attribute table does not specify a mapping to lowercase for this character (the purpose of this requirement is to exclude titlecase characters).
  • At least one of the following is true:
    • The Unicode attribute table specifies a mapping to uppercase for this character.
    • The name for the character in the Unicode attribute table contains the words SMALL LETTER or the words SMALL LIGATURE.

It follows, then, that for Unicode 1.1.5 as corrected above, the lowercase Unicode characters are exactly those with codes in the following list, which contains both single codes and inclusive ranges: 0061-007A, 00DF-00F6, 00F8-00FF, 0101-0137 (odds only), 0138-0148 (evens only), 0149-0177 (odds only), 017A-017E (evens only), 017F-0180, 0183, 0185, 0188, 018C-018D, 0192, 0195, 0199-019B, 019E, 01A1-01A5 (odds only), 01A8, 01AB, 01AD, 01B0, 01B4, 01B6, 01B9-01BA, 01BD, 01C6, 01C9, 01CC-01DC (evens only), 01DD-01EF (odds only), 01F0, 01F3, 01F5, 01FB-0217 (odds only), 0250-0261, 0263-0269, 026B-0273, 0275, 0277-027F, 0282-028E, 0290-0293, 029A, 029D-029E, 02A0, 02A3-02A8, 0390, 03AC-03CE, 03D0-03D1, 03D5-03D6, 03E3-03EF (odds only), 03F0-03F1, 0430-044F, 0451-045C, 045E-045F, 0461-0481 (odds only), 0491-04BF (odds only), 04C2, 04C4, 04C8, 04CC, 04D1-04EB (odds only), 04EF-04F5 (odds only), 04F9, 0561-0587, 1E01-1E95 (odds only), 1E96-1E9A, 1EA1-1EF9 (odds only), 1F00-1F07, 1F10-1F15, 1F20-1F27, 1F30-1F37, 1F40-1F45, 1F50-1F57, 1F60-1F67, 1F70-1F7D, 1F80-1F87, 1F90-1F97, 1FA0-1FA7, 1FB0-1FB4, 1FB6-1FB7, 1FC2-1FC4, 1FC6-1FC7, 1FD0-1FD3, 1FD6-1FD7, 1FE0-1FE7, 1FF2-1FF4, 1FF6-1FF7, FB00-FB06, FB13-FB17, FF41-FF5A.

Of the first 128 Unicode characters, exactly 26 are considered to be lowercase:

abcdefghijklmnopqrstuvwxyz

[This specification for the method isLowerCase is scheduled for introduction in Java version 1.1, either as defined here, or updated for Unicode 2.0; see §20.5. In previous versions of Java, this method returns false for all arguments larger than \u00FF.]

20.5.12 public static boolean isUpperCase(char ch)

The result is true if and only if the character argument is an uppercase character.

A character is considered to be uppercase if and only if all of the following are true:

  • The character ch is not in the range \u2000 through \u2FFF.
  • The Unicode attribute table does not specify a mapping to uppercase for this character (the purpose of this requirement is to exclude titlecase characters).
  • At least one of the following is true:
    • The Unicode attribute table specifies a mapping to lowercase for this character.
    • The name for the character in the Unicode attribute table contains the words CAPITAL LETTER or the words CAPITAL LIGATURE.

It follows, then, that for Unicode 1.1.5 as corrected above, the uppercase Unicode characters are exactly those with codes in the following list, which contains both single codes and inclusive ranges: 0041-005A, 00C0-00D6, 00D8-00DE, 0100-0136 (evens only), 0139-0147 (odds only), 014A-0178 (evens only), 0179-017D (odds only), 0181-0182, 0184, 0186, 0187, 0189-018B, 018E-0191, 0193-0194, 0196-0198, 019C-019D, 019F-01A0, 01A2, 01A4, 01A7, 01A9, 01AC, 01AE, 01AF, 01B1-01B3, 01B5, 01B7, 01B8, 01BC, 01C4, 01C7, 01CA, 01CD-01DB (odds only), 01DE-01EE (evens only), 01F1, 01F4, 01FA-0216 (evens only), 0386, 0388-038A, 038C, 038E, 038F, 0391-03A1, 03A3-03AB, 03E2-03EE (evens only), 0401-040C, 040E-042F, 0460-0480 (evens only), 0490-04BE (evens only), 04C1, 04C3, 04C7, 04CB, 04D0-04EA (evens only), 04EE-04F4 (evens only), 04F8, 0531-0556, 10A0-10C5, 1E00-1E94 (evens only), 1EA0-1EF8 (evens only), 1F08-1F0F, 1F18-1F1D, 1F28-1F2F, 1F38-1F3F, 1F48-1F4D, 1F59-1F5F (odds only), 1F68-1F6F, 1F88-1F8F, 1F98-1F9F, 1FA8-1FAF, 1FB8-1FBC, 1FC8-1FCC, 1FD8-1FDB, 1FE8-1FEC, 1FF8-1FFC, FF21-FF3A.

Of the first 128 Unicode characters, exactly 26 are considered to be uppercase:

ABCDEFGHIJKLMNOPQRSTUVWXYZ

[This specification for the method isUpperCase is scheduled for introduction in Java version 1.1, either as defined here, or updated for Unicode 2.0; see §20.5. In previous versions of Java, this method returns false for all arguments larger than \u00FF.]

20.5.13 public static boolean isTitleCase(char ch)

The result is true if and only if the character argument is a titlecase character.

The notion of "titlecase" was introduced into Unicode to handle a peculiar situation: there are single Unicode characters whose appearance in each case looks exactly like two ordinary Latin letters. For example, there is a single Unicode character `LJ' (\u01C7) that looks just like the characters `L' and `J' put together. There is a corresponding lowercase letter `lj' (\u01C9) as well. These characters are present in Unicode primarily to allow one-to-one translations from the Cyrillic alphabet, as used in Serbia, for example, to the Latin alphabet. Now suppose the word "LJUBINJE" (which has six characters, not eight, because two of them are the single Unicode characters `LJ' and `NJ', perhaps produced by one-to-one translation from the Cyrillic) is to be written as part of a book title, in capitals and lowercase. The strategy of making the first letter uppercase and the rest lowercase results in "LJubinje"-most unfortunate. The solution is that there must be a third form, called a titlecase form. The titlecase form of `LJ' is `Lj' (\u01C8) and the titlecase form of `NJ' is `Nj'. A word for a book title is then best rendered by converting the first letter to titlecase if possible, otherwise to uppercase; the remaining letters are then converted to lowercase.

A character is considered to be titlecase if and only if both of the following are true:

  • The character ch is not in the range \u2000 through \u2FFF.
  • The Unicode attribute table specifies a mapping to uppercase and a mapping to lowercase for this character.

There are exactly four Unicode 1.1.5 characters for which isTitleCase returns true:

\u01C5	    LATIN CAPITAL LETTER D WITH SMALL LETTER Z WITH CARON
\u01C8	    LATIN CAPITAL LETTER L WITH SMALL LETTER J
\u01CB	    LATIN CAPITAL LETTER N WITH SMALL LETTER J
\u01F2	    LATIN CAPITAL LETTER D WITH SMALL LETTER Z

[This method is scheduled for introduction in Java version 1.1, either as defined here, or updated for Unicode 2.0; see §20.5.]

20.5.14 public static boolean isDigit(char ch)

The result is true if and only if the character argument is a digit.

A character is considered to be a digit if and only if both of the following are true:

  • The character ch is not in the range \u2000 through \u2FFF.
  • The name for the character in the Unicode attribute table contains the word DIGIT.

The digits are those characters with the following codes:

0030-0039	ISO-Latin-1 (and ASCII) digits ('0'-'9')
0660-0669	Arabic-Indic digits
06F0-06F9	Eastern Arabic-Indic digits
0966-096F	Devanagari digits
09E6-09EF	Bengali digits
0A66-0A6F	Gurmukhi digits
0AE6-0AEF	Gujarati digits
0B66-0B6F	Oriya digits
0BE7-0BEF	Tamil digits (there are only nine of these-no zero digit)
0C66-0C6F	Telugu digits
0CE6-0CEF	Kannada digits
0D66-0D6F	Malayalam digits
0E50-0E59	Thai digits
0ED0-0ED9	Lao digits
FF10-FF19	Fullwidth digits

Of the first 128 Unicode characters, exactly 10 are considered to be digits:

0123456789

[This specification for the method isDigit is scheduled for introduction in Java version 1.1, either as defined here, or updated for Unicode 2.0; see §20.5. In previous versions of Java, this method returns false for all arguments larger than \u00FF.]

20.5.15 public static boolean isLetter(char ch)

The result is true if and only if the character argument is a letter.

A character is considered to be a letter if and only if it is a letter or digit (§20.5.16) but is not a digit (§20.5.14).

[This method is scheduled for introduction in Java version 1.1, either as defined here, or updated for Unicode 2.0; see §20.5.]

20.5.16 public static boolean isLetterOrDigit(char ch)

The result is true if and only if the character argument is a letter-or-digit.

A character is considered to be a letter-or-digit if and only if it is a defined Unicode character (§20.5.10) and its code lies in one of the following ranges:

0030-0039	ISO-Latin-1 (and ASCII) digits ('0'-'9')
0041-005A	ISO-Latin-1 (and ASCII) uppercase Latin letters ('A'-'Z')
0061-007A	ISO-Latin-1 (and ASCII) lowercase Latin letters ('a'-'z')
00C0-00D6	ISO-Latin-1 supplementary letters
00D8-00F6	ISO-Latin-1 supplementary letters
00F8-00FF	ISO-Latin-1 supplementary letters
0100-1FFF	Latin extended-A, Latin extended-B, IPA extensions,
spacing modifier letters, combining diacritical marks, basic
Greek, Greek symbols and Coptic, Cyrillic, Armenian,
Hebrew extended-A, Basic Hebrew, Hebrew extended-B,
Basic Arabic, Arabic extended, Devanagari, Bengali,
Gurmukhi, Gujarati, Oriya, Tamil, Telugu, Kannada,
Malayalam, Thai, Lao, Basic Georgian, Georgian extended,
Hanguljamo, Latin extended additional, Greek extended
3040-9FFF	Hiragana, Katakana, Bopomofo, Hangul compatibility
Jamo, CJK miscellaneous, enclosed CJK characters and
months, CJK compatibility, Hangul, Hangul
supplementary-A, Hangul supplementary-B, CJK unified
ideographs
F900-FDFF	CJK compatibility ideographs, alphabetic presentation
forms, Arabic presentation forms-A
FE70-FEFE	Arabic presentation forms-B
FF10-FF19	Fullwidth digits
FF21-FF3A	Fullwidth Latin uppercase
FF41-FF5A	Fullwidth Latin lowercase
FF66-FFDC	Halfwidth Katakana and Hangul

It follows, then, that for Unicode 1.1.5 as corrected above, the Unicode letters and digits are exactly those with codes in the following list, which contains both single codes and inclusive ranges:

0030-0039, 0041-005A, 0061-007A, 00C0-00D6, 00D8-00F6, 00F8-01F5, 01FA-0217, 0250-02A8, 02B0-02DE, 02E0-02E9, 0300-0345, 0360-0361, 0374-0375, 037A, 037E, 0384-038A, 038C, 038E, 038F-03A1, 03A3-03CE, 03D0-03D6, 03DA-03E2, 03DA, 03DC, 03DE, 03E0, 03E2-03F3, 0401-040C, 040E-044F, 0451-045C, 045E-0486, 0490-04C4, 04C7-04C8, 04CB-04CC, 04D0-04EB, 04EE-04F5, 04F8-04F9, 0531-0556, 0559-055F, 0561-0587, 0589, 05B0-05B9, 05BB-05C3, 05D0-05EA, 05F0-05F4, 060C, 061B, 061F, 0621, 0622-063A, 0640-0652, 0660-066D, 0670-06B7, 06BA-06BE, 06C0-06CE, 06D0-06ED, 06F0-06F9, 0901-0903, 0905-0939, 093C-094D, 0950-0954, 0958-0970, 0981-0983, 0985-098C, 098F-0990, 0993-09A8, 09AA-09B0, 09B2, 09B6-09B9, 09BC, 09BE, 09BF-09C4, 09C7-09C8, 09CB-09CD, 09D7, 09DC-09DD, 09DF-09E3, 09E6-09FA, 0A02, 0A05-0A0A, 0A0F-0A10, 0A13-0A28, 0A2A-0A30, 0A32-0A33, 0A35-0A36, 0A38-0A39, 0A3C, 0A3E, 0A3F-0A42, 0A47-0A48, 0A4B-0A4D, 0A59-0A5C, 0A5E, 0A66-0A74, 0A81-0A83, 0A85-0A8B, 0A8D, 0A8F, 0A90-0A91, 0A93-0AA8, 0AAA-0AB0, 0AB2-0AB3, 0AB5-0AB9, 0ABC-0AC5, 0AC7-0AC9, 0ACB-0ACD, 0AD0, 0AE0, 0AE6-0AEF, 0B01-0B03, 0B05-0B0C, 0B0F-0B10, 0B13-0B28, 0B2A-0B30, 0B32-0B33, 0B36-0B39, 0B3C-0B43, 0B47-0B48, 0B4B-0B4D, 0B56-0B57, 0B5C-0B5D, 0B5F-0B61, 0B66-0B70, 0B82-0B83, 0B85-0B8A, 0B8E-0B90, 0B92-0B95, 0B99-0B9A, 0B9C, 0B9E, 0B9F, 0BA3-0BA4, 0BA8-0BAA, 0BAE-0BB5, 0BB7-0BB9, 0BBE-0BC2, 0BC6-0BC8, 0BCA-0BCD, 0BD7, 0BE7-0BF2, 0C01-0C03, 0C05-0C0C, 0C0E-0C10, 0C12-0C28, 0C2A-0C33, 0C35-0C39, 0C3E-0C44, 0C46-0C48, 0C4A-0C4D, 0C55-0C56, 0C60-0C61, 0C66-0C6F, 0C82-0C83, 0C85-0C8C, 0C8E-0C90, 0C92-0CA8, 0CAA-0CB3, 0CB5-0CB9, 0CBE-0CC4, 0CC6-0CC8, 0CCA-0CCD, 0CD5-0CD6, 0CDE, 0CE0, 0CE1, 0CE6-0CEF, 0D02-0D03, 0D05-0D0C, 0D0E-0D10, 0D12-0D28, 0D2A-0D39, 0D3E-0D43, 0D46-0D48, 0D4A-0D4D, 0D57, 0D60-0D61, 0D66-0D6F, 0E01-0E3A, 0E3F-0E5B, 0E81-0E82, 0E84, 0E87-0E88, 0E8A, 0E8D, 0E94-0E97, 0E99-0E9F, 0EA1-0EA3, 0EA5, 0EA7, 0EAA-0EAB, 0EAD-0EB9, 0EBB-0EBD, 0EC0-0EC4, 0EC6, 0EC8, 0EC9-0ECD, 0ED0-0ED9, 0EDC-0EDD, 10A0-10C5, 10D0-10F6, 10FB, 1100-1159, 115F-11A2, 11A8-11F9, 1E00-1E9A, 1EA0-1EF9, 1F00-1F15, 1F18-1F1D, 1F20-1F45, 1F48-1F4D, 1F50-1F57, 1F59, 1F5B, 1F5D, 1F5F-1F7D, 1F80-1FB4, 1FB6-1FC4, 1FC6-1FD3, 1FD6-1FDB, 1FDD-1FEF, 1FF2-1FF4, 1FF6-1FFE, 3041-3094, 3099-309E, 30A1-30FE, 3105-312C, 3131-318E, 3190-319F, 3200-321C, 3220-3243, 3260-327B, 327F-32B0, 32C0-32CB, 32D0-32FE, 3300-3376, 337B-33DD, 33E0-33FE, 3400-9FA5, F900-FA2D, FB00-FB06, FB13-FB17, FB1E-FB36, FB38-FB3C, FB3E, FB40, FB41, FB43, FB44, FB46, FB47-FBB1, FBD3-FD3F, FD50-FD8F, FD92-FDC7, FDF0-FDFB, FE70-FE72, FE74, FE76, FE77-FEFC, FF10-FF19, FF21-FF3A, FF41-FF5A, FF66-FFBE, FFC2-FFC7, FFCA-FFCF, FFD2-FFD7, FFDA-FFDC.

[This method is scheduled for introduction in Java version 1.1, either as defined here, or updated for Unicode 2.0; see §20.5.]

20.5.17 public static boolean isJavaLetter(char ch)

The result is true if and only if the character argument is a character that can begin a Java identifier.

A character is considered to be a Java letter if and only if it is a letter (§20.5.15) or is the dollar sign character '$' (\u0024) or the underscore ("low line") character '_' (\u005F).

[This method is scheduled for introduction in Java version 1.1, either as defined here, or updated for Unicode 2.0; see §20.5.]

20.5.18 public static boolean isJavaLetterOrDigit(char ch)

The result is true if and only if the character argument is a character that can occur in a Java identifier after the first character.

A character is considered to be a Java letter-or-digit if and only if it is a letter-or-digit (§20.5.16) or is the dollar sign character '$' (\u0024) or the underscore ("low line") character '_' (\u005F).

[This method is scheduled for introduction in Java version 1.1, either as defined here, or updated for Unicode 2.0; see §20.5.]

20.5.19 public static boolean isSpace(char ch)

The result is true if the argument ch is one of the following characters:

'\t'		\u0009			HT		HORIZONTAL TABULATION
'\n'		\u000A			LF		LINE FEED (also known as NEW LINE)
'\f'		\u000C			FF		FORM FEED
'\r'		\u000D			CR		CARRIAGE RETURN
' '		\u0020			SP		SPACE

Otherwise, the result is false.

20.5.20 public static char toLowerCase(char ch)

If the character ch has a lowercase equivalent specified in the Unicode attribute table, then that lowercase equivalent character is returned. Otherwise, the argument ch is returned.

The lowercase equivalents specified in the Unicode attribute table, for Unicode 1.1.5 as corrected above, are as follows, where character codes to the right of arrows are the lowercase equivalents of character codes to the left of arrows: 0041-005A [image] 0061-007A, 00C0-00D6 [image] 00E0-00F6, 00D8-00DE [image] 00F8-00FE, 0100-012E [image] 0101-012F (evens to odds), 0132-0136 [image] 0133-0137 (evens to odds), 0139-0147 [image] 013A-0148 (odds to evens), 014A-0176 [image] 014B-0177 (evens to odds), 0178 [image] 00FF, 0179-017D [image] 017A-017E (odds to evens), 0181 [image] 0253, 0182 [image] 0183, 0184 [image] 0185, 0186 [image] 0254, 0187 [image] 0188, 018A [image] 0257, 018B [image] 018C, 018E [image] 0258, 018F [image] 0259, 0190 [image] 025B, 0191 [image] 0192, 0193 [image] 0260, 0194 [image] 0263, 0196 [image] 0269, 0197 [image] 0268, 0198 [image] 0199, 019C [image] 026F, 019D [image] 0272, 01A0-01A4 [image] 01A1-01A5 (evens to odds), 01A7 [image] 01A8, 01A9 [image] 0283, 01AC [image] 01AD, 01AE [image] 0288, 01AF [image] 01B0, 01B1 [image] 028A, 01B2 [image] 028B, 01B3 [image] 01B4, 01B5 [image] 01B6, 01B7 [image] 0292, 01B8 [image] 01B9, 01BC [image] 01BD, 01C4 [image] 01C6, 01C5 [image] 01C6, 01C7 [image] 01C9, 01C8 [image] 01C9, 01CA [image] 01CC, 01CB-01DB [image] 01CC-01DC (odds to evens), 01DE-01EE [image] 01DF-01EF (evens to odds), 01F1 [image] 01F3, 01F2 [image] 01F3, 01F4 [image] 01F5, 01FA-0216 [image] 01FB-0217 (evens to odds), 0386 [image] 03AC, 0388-038A [image] 03AD-03AF, 038C [image] 03CC, 038E [image] 03CD, 038F [image] 03CE, 0391-03A1 [image] 03B1-03C1, 03A3-03AB [image] 03C3-03CB, 03E2-03EE [image] 03E3-03EF (evens to odds), 0401-040C [image] 0451-045C, 040E [image] 045E, 040F [image] 045F, 0410-042F [image] 0430-044F, 0460-0480 [image] 0461-0481 (evens to odds), 0490-04BE [image] 0491-04BF (evens to odds), 04C1 [image] 04C2, 04C3 [image] 04C4, 04C7 [image] 04C8, 04CB [image] 04CC, 04D0-04EA [image] 04D1-04EB (evens to odds), 04EE-04F4 [image] 04EF-04F5 (evens to odds), 04F8 [image] 04F9, 0531-0556 [image] 0561-0586, 10A0-10C5 [image] 10D0-10F5, 1E00-1E94 [image] 1E01-1E95 (evens to odds), 1EA0-1EF8 [image] 1EA1-1EF9 (evens to odds), 1F08-1F0F [image] 1F00-1F07, 1F18-1F1D [image] 1F10-1F15, 1F28-1F2F [image] 1F20-1F27, 1F38-1F3F [image] 1F30-1F37, 1F48-1F4D [image] 1F40-1F45, 1F59 [image] 1F51, 1F5B [image] 1F53, 1F5D [image] 1F55, 1F5F [image] 1F57, 1F68-1F6F [image] 1F60-1F67, 1F88-1F8F [image] 1F80-1F87, 1F98-1F9F [image] 1F90-1F97, 1FA8-1FAF [image] 1FA0-1FA7, 1FB8 [image] 1FB0, 1FB9 [image] 1FB1, 1FBA [image] 1F70, 1FBB [image] 1F71, 1FBC [image] 1FB3, 1FC8-1FCB [image] 1F72-1F75, 1FCC [image] 1FC3, 1FD8 [image] 1FD0, 1FD9 [image] 1FD1, 1FDA [image] 1F76, 1FDB [image] 1F77, 1FE8 [image] 1FE0, 1FE9 [image] 1FE1, 1FEA [image] 1F7A, 1FEB [image] 1F7B, 1FEC [image] 1FE5, 1FF8 [image] 1F78, 1FF9 [image] 1F79, 1FFA [image] 1F7C, 1FFB [image] 1F7D, 1FFC [image] 1FF3, 2160-216F [image] 2170-217F, 24B6-24CF [image] 24D0-24E9, FF21-FF3A [image] FF41-FF5A.

Note that the method isLowerCase (§20.5.11) will not necessarily return true when given the result of the toLowerCase method.

[This specification for the method toLowerCase is scheduled for introduction in Java version 1.1, either as defined here, or updated for Unicode 2.0; see §20.5. In previous versions of Java, this method returns its argument for all arguments larger than \u00FF.]

20.5.21 public static char toUpperCase(char ch)

If the character ch has an uppercase equivalent specified in the Unicode attribute table, then that uppercase equivalent character is returned. Otherwise, the argument ch is returned.

The uppercase equivalents specified in the Unicode attribute table for Unicode 1.1.5 as corrected above, are as follows, where character codes to the right of arrows are the uppercase equivalents of character codes to the left of arrows:

0061-007A [image] 0041-005A, 00E0-00F6 [image] 00C0-00D6, 00F8-00FE [image] 00D8-00DE, 00FF [image] 0178, 0101-012F [image] 0100-012E (odds to evens), 0133-0137 [image] 0132-0136 (odds to evens), 013A-0148 [image] 0139-0147 (evens to odds), 014B-0177 [image] 014A-0176 (odds to evens), 017A-017E [image] 0179-017D (evens to odds), 017F [image] 0053, 0183-0185 [image] 0182-0184 (odds to evens), 0188 [image] 0187, 018C [image] 018B, 0192 [image] 0191, 0199 [image] 0198, 01A1-01A5 [image] 01A0-01A4 (odds to evens), 01A8 [image] 01A7, 01AD [image] 01AC, 01B0 [image] 01AF, 01B4 [image] 01B3, 01B6 [image] 01B5, 01B9 [image] 01B8, 01BD [image] 01BC, 01C5 [image] 01C4, 01C6 [image] 01C4, 01C8 [image] 01C7, 01C9 [image] 01C7, 01CB [image] 01CA, 01CC [image] 01CA, 01CE-01DC [image] 01CD-01DB (evens to odds), 01DF-01EF [image] 01DE-01EE (odds to evens), 01F2 [image] 01F1, 01F3 [image] 01F1, 01F5 [image] 01F4, 01FB-0217 [image] 01FA-0216 (odds to evens), 0253 [image] 0181, 0254 [image] 0186, 0257 [image] 018A, 0258 [image] 018E, 0259 [image] 018F, 025B [image] 0190, 0260 [image] 0193, 0263 [image] 0194, 0268 [image] 0197, 0269 [image] 0196, 026F [image] 019C, 0272 [image] 019D, 0283 [image] 01A9, 0288 [image] 01AE, 028A [image] 01B1, 028B [image] 01B2, 0292 [image] 01B7, 03AC [image] 0386, 03AD-03AF [image] 0388-038A, 03B1-03C1 [image] 0391-03A1, 03C2 [image] 03A3, 03C3-03CB [image] 03A3-03AB, 03CC [image] 038C, 03CD [image] 038E, 03CE [image] 038F, 03D0 [image] 0392, 03D1 [image] 0398, 03D5 [image] 03A6, 03D6 [image] 03A0, 03E3-03EF [image] 03E2-03EE (odds to evens), 03F0 [image] 039A, 03F1 [image] 03A1, 0430-044F [image] 0410-042F, 0451-045C [image] 0401-040C, 045E [image] 040E, 045F [image] 040F, 0461-0481 [image] 0460-0480 (odds to evens), 0491-04BF [image] 0490-04BE (odds to evens), 04C2 [image] 04C1, 04C4 [image] 04C3, 04C8 [image] 04C7, 04CC [image] 04CB, 04D1-04EB [image] 04D0-04EA (odds to evens), 04EF-04F5 [image] 04EE-04F4 (odds to evens), 04F9 [image] 04F8, 0561-0586 [image] 0531-0556, 1E01-1E95 [image] 1E00-1E94 (odds to evens), 1EA1-1EF9 [image] 1EA0-1EF8 (odds to evens), 1F00-1F07 [image] 1F08-1F0F, 1F10-1F15 [image] 1F18-1F1D, 1F20-1F27 [image] 1F28-1F2F, 1F30-1F37 [image] 1F38-1F3F, 1F40-1F45 1F48-1F4D, 1F51 1F59, 1F53 1F5B, 1F55 1F5D, 1F57 1F5F, 1F60-1F67 1F68-1F6F, 1F70 1FBA, 1F71 1FBB, 1F72-1F75 1FC8-1FCB, 1F76 1FDA, 1F77 1FDB, 1F78 1FF8, 1F79 1FF9, 1F7A 1FEA, 1F7B 1FEB, 1F7C 1FFA, 1F7D 1FFB, 1F80-1F87 1F88-1F8F, 1F90-1F97 1F98-1F9F, 1FA0-1FA7 1FA8-1FAF, 1FB0 1FB8, 1FB1 1FB9, 1FB3 1FBC, 1FC3 1FCC, 1FD0 1FD8, 1FD1 1FD9, 1FE0 1FE8, 1FE1 1FE9, 1FE5 1FEC, 1FF3 1FFC, 2170-217F 2160-216F, 24D0-24E9 24B6-24CF, FF41-FF5A FF21-FF3A.

Note that the method isUpperCase (§20.5.12) will not necessarily return true when given the result of the toUpperCase method.

[This specification for the method toUpperCase is scheduled for introduction in Java version 1.1, either as defined here, or updated for Unicode 2.0; see §20.5. In previous versions of Java, this method returns its argument for all arguments larger than \u00FE. Note that although \u00FF is a lowercase character, its uppercase equivalent is \u0178; toUpperCase in versions of Java prior to version 1.1 simply do not consistently handle or use Unicode character codes above \u00FF.]

20.5.22 public static char toTitleCase(char ch)

If the character ch has a titlecase equivalent specified in the Unicode attribute table, then that titlecase equivalent character is returned; otherwise, the argument ch is returned.

Note that the method isTitleCase (§20.5.13) will not necessarily return true when given the result of the toTitleCase method. The Unicode attribute table always has the titlecase attribute equal to the uppercase attribute for characters that have uppercase equivalents but no separate titlecase form.

Example: Character.toTitleCase('a') returns 'A'

Example: Character.toTitleCase('Q') returns 'Q'

Example: Character.toTitleCase('lj') returns 'Lj' where 'lj' is the Unicode character \u01C9 and 'Lj' is its titlecase equivalent character \u01C8.

[This method is scheduled for introduction in Java version 1.1.]

20.5.23 public static int digit(char ch, int radix)

Returns the numeric value of the character ch considered as a digit in the specified radix. If the value of radix is not a valid radix, or the character ch is not a valid digit in the specified radix, then -1 is returned.

A radix is valid if and only if its value is not less than Character.MIN_RADIX (§20.5.3) and not greater than Character.MAX_RADIX (§20.5.4).

A character is a valid digit if and only if one of the following is true:

  • The method isDigit returns true for the character, and the decimal digit value of the character, as specified in the Unicode attribute table, is less than the specified radix. In this case, the decimal digit value is returned.
  • The character is one of the uppercase Latin letters 'A'-'Z' (\u0041-\u005A) and its code is less than radix+'A'-10. In this case ch-'A'+10 is returned.
  • The character is one of the lowercase Latin letters 'a'-'z' (\u0061-\u007A) and its code is less than radix+'a'-10. In this case ch-'a'+10 is returned.

[This specification for the method digit is scheduled for introduction in Java version 1.1, either as defined here, or updated for Unicode 2.0; see §20.5. In previous versions of Java, this method returns -1 for all character codes larger than \u00FF.]

20.5.24 public static char forDigit(int digit, int radix)

Returns a character that represents the given digit in the specified radix. If the value of radix is not a valid radix, or the value of digit is not a valid digit in the specified radix, the null character '\u0000' is returned.

A radix is valid if and only if its value is not less than Character.MIN_RADIX (§20.5.3) and not greater than Character.MAX_RADIX (§20.5.4).

A digit is valid if and only if it is nonnegative and less than the radix.

If the digit is less than 10, then the character value '0'+digit is returned; otherwise, 'a'+digit-10 is returned. Thus, the digits produced by forDigit, in increasing order of value, are the ASCII characters:

0123456789abcdefghijklmnopqrstuvwxyz

(these are '\u0030' through '\u0039' and '\u0061' through '\u007a'). If uppercase letters are desired, the toUpperCase method may be called on the result:

Character.toUpperCase(Character.forDigit(digit, radix))


20.6 The Class java.lang.Number

The abstract class Number has subclasses Integer, Long, Float, and Double which wrap primitive types, defining abstract methods to convert the represented numeric value to int, long, float, and double.

public abstract class Number {
    public abstract int intValue();
    public abstract long longValue();
    public abstract float floatValue();
    public abstract double doubleValue();
}

20.6.1 public abstract int intValue()

The general contract of the intValue method is that it returns the numeric value represented by this Number object after converting it to type int.

Overridden by Integer (§20.7.8), Long (§20.8.8), Float (§20.9.12), and Double (§20.10.11).

20.6.2 public abstract long longValue()

The general contract of the longValue method is that it returns the numeric value represented by this Number object after converting it to type long.

Overridden by Integer (§20.7.9), Long (§20.8.9), Float (§20.9.13), and Double (§20.10.12).

20.6.3 public abstract float floatValue()

The general contract of the floatValue method is that it returns the numeric value represented by this Number object after converting it to type float.

Overridden by Integer (§20.7.10), Long (§20.8.10), Float (§20.9.14), and Double (§20.10.13).

20.6.4 public abstract double doubleValue()

The general contract of the doubleValue method is that it returns the numeric value represented by this Number object after converting it to type double.

Overridden by Integer (§20.7.11), Long (§20.8.11), Float (§20.9.15), and Double (§20.10.14).


20.7 The Class java.lang.Integer

public final class Integer extends Number {
    public static final int MIN_VALUE = 0x80000000;
    public static final int MAX_VALUE = 0x7fffffff;
    public Integer(int value);
    public Integer(String s)

        throws NumberFormatException;
    public String toString();
    public boolean equals(Object obj);
    public int hashCode();
    public int intValue();
    public long longValue();
    public float floatValue();
    public double doubleValue();
    public static String toString(int i);
    public static String toString(int i, int radix);
    public static String toHexString(long i);
    public static String toOctalString(long i);
    public static String toBinaryString(long i);
    public static int parseInt(String s)

        throws NumberFormatException;
    public static int parseInt(String s, int radix)

        throws NumberFormatException;
    public static Integer valueOf(String s)

        throws NumberFormatException;
    public static Integer valueOf(String s, int radix)

        throws NumberFormatException;
    public static Integer getInteger(String nm);
    public static Integer getInteger(String nm, int val);
    public static Integer getInteger(String nm, Integer val);
}

20.7.1 public static final int MIN_VALUE = 0x80000000;

The constant value of this field is -2147483648, the lowest value of type int.

20.7.2 public static final int MAX_VALUE = 0x7fffffff;

The constant value of this field is 2147483647, the highest value of type int.

20.7.3 public Integer(int value)

This constructor initializes a newly created Integer object so that it represents the primitive value that is the argument.

20.7.4 public Integer(String s) throws NumberFormatException

This constructor initializes a newly created Integer object so that it represents the integer represented by the string in decimal form. The string is converted to an int in exactly the manner used by the parseInt method (§20.7.18) for radix 10.

20.7.5 public String toString()

The integer value represented by this Integer object is converted to signed decimal representation and returned as a string, exactly as if the integer value were given as an argument to the toString method that takes one argument (§20.7.12).

Overrides the toString method of Object (§20.1.2).

20.7.6 public boolean equals(Object obj)

The result is true if and only if the argument is not null and is an Integer object that represents the same int value as this Integer object.

Overrides the equals method of Object (§20.1.3).

20.7.7 public int hashCode()

The result is the primitive int value represented by this Integer object.

Overrides the hashCode method of Object (§20.1.4).

20.7.8 public int intValue()

The int value represented by this Integer object is returned.

Overrides the intValue method of Number (§20.6.1).

20.7.9 public long longValue()

The int value represented by this Integer object is converted (§5.1.2) to type long and the result of the conversion is returned.

Overrides the longValue method of Number (§20.6.2).

20.7.10 public float floatValue()

The int value represented by this Integer object is converted (§5.1.2) to type float and the result of the conversion is returned.

Overrides the floatValue method of Number (§20.6.3).

20.7.11 public double doubleValue()

The int value represented by this Integer object is converted (§5.1.2) to type double and the result of the conversion is returned.

Overrides the doubleValue method of Number (§20.6.4).

20.7.12 public static String toString(int i)

The argument is converted to signed decimal representation and returned as a string, exactly as if the argument and the radix 10 were given as arguments to the toString method that takes two arguments (§20.7.13).

20.7.13 public static String toString(int i, int radix)

The first argument is converted to a signed representation in the radix specified by the second argument; this representation is returned as a string.

If the radix is smaller than Character.MIN_RADIX (§20.5.3) or larger than Character.MAX_RADIX (§20.5.4), then the value 10 is used instead.

If the first argument is negative, the first character of the result will be the character '-' ('\u002d'). If the first argument is not negative, no sign character appears in the result.

The remaining characters of the result represent the magnitude of the first argument. If the magnitude is zero, it is represented by a single zero character '0' ('\u0030'); otherwise, the first character of the representation of the magnitude will not be the zero character.The following ASCII characters are used as digits:

0123456789abcdefghijklmnopqrstuvwxyz

These are '\u0030' through '\u0039' and '\u0061' through '\u007a'. If the radix is N, then the first N of these characters are used as radix-N digits in the order shown. Thus, the digits for hexadecimal (radix 16) are 0123456789abcdef. If uppercase letters are desired, the toUpperCase method (§20.12.36) of class String may be called on the result:

Integer.toString(n, 16).toUpperCase()

20.7.14 public static String toHexString(int i)

The argument is converted to an unsigned representation in hexadecimal radix (base 16); this representation is returned as a string.

The result represents the unsigned magnitude of the argument. This equals the argument plus [image] if the argument is negative; otherwise, it equals the argument.

If the unsigned magnitude is zero, it is represented by a single zero character '0' ('\u0030'); otherwise, the first character of the representation of the unsigned magnitude will not be the zero character. The following characters are used as hexadecimal digits:

0123456789abcdef

These are the characters '\u0030' through '\u0039' and '\u0061' through '\u0066'. If uppercase letters are desired, the toUpperCase method (§20.12.36) of class String may be called on the result:

Long.toHexString(n).toUpperCase()

20.7.15 public static String toOctalString(int i)

The argument is converted to an unsigned representation in octal radix (base 8); this representation is returned as a string.

The result represents the unsigned magnitude of the argument. This equals the argument plus [image] if the argument is negative; otherwise, it equals the argument.

If the unsigned magnitude is zero, it is represented by a single zero character '0' ('\u0030'); otherwise, the first character of the representation of the unsigned magnitude will not be the zero character. The octal digits are:

01234567

These are the characters '\u0030' through '\u0037'.

20.7.16 public static String toBinaryString(int i)

The argument is converted to an unsigned representation in binary radix (base 2); this representation is returned as a string.

The result represents the unsigned magnitude of the argument. This equals the argument plus [image] if the argument is negative; otherwise, it equals the argument.

If the unsigned magnitude is zero, it is represented by a single zero character '0' ('\u0030'); otherwise, the first character of the representation of the unsigned magnitude will not be the zero character. The characters '0' ('\u0030') and '1' ('\u0031') are used as binary digits.

20.7.17 public static int parseInt(String s)
throws NumberFormatException

The argument is interpreted as representing a signed decimal integer. The components of the string must all be decimal digits, except that the first character may be '-' ('\u002d') to indicate a negative value. The resulting integer value is returned, exactly as if the argument and the radix 10 were given as arguments to the parseInt method that takes two arguments (§20.7.18).

20.7.18 public static int parseInt(String s, int radix)
throws NumberFormatException

The first argument is interpreted as representing a signed integer in the radix specified by the second argument. The components of the string must all be digits of the specified radix (as determined by whether Character.digit (§20.5.23) returns a nonnegative value), except that the first character may be '-' ('\u002d') to indicate a negative value. The resulting integer value is returned.

An exception of type NumberFormatException is thrown if any of the following situations occurs:

  • The first argument is null or is a string of length zero.
  • The radix is either smaller than Character.MIN_RADIX (§20.5.3) or larger than Character.MAX_RADIX (§20.5.4).
  • Any character of the string is not a digit of the specified radix, except that the first character may be a minus sign '-' ('\u002d') provided that the string is longer than length 1.
  • The integer value represented by the string is not a value of type int.

Examples:

parseInt("0", 10) returns 0
parseInt("473", 10) returns 473
parseInt("-0", 10) returns 0
parseInt("-FF", 16) returns -255
parseInt("1100110", 2) returns 102
parseInt("2147483647", 10) returns 2147483647
parseInt("-2147483648", 10) returns -2147483648
parseInt("2147483648", 10) throws a NumberFormatException
parseInt("99", 8) throws a NumberFormatException
parseInt("Kona", 10) throws a NumberFormatException
parseInt("Kona", 27) returns 411787

20.7.19 public static Integer valueOf(String s)
throws NumberFormatException

The argument is interpreted as representing a signed decimal integer, exactly as if the argument were given to the parseInt method that takes one argument (§20.7.17). The result is an Integer object that represents the integer value specified by the string.

In other words, this method returns an Integer object equal to the value of:

new Integer(Integer.parseInt(s))

20.7.20 public static Integer valueOf(String s, int radix)
throws NumberFormatException

The first argument is interpreted as representing a signed integer in the radix specified by the second argument, exactly as if the arguments were given to the parseInt method that takes two arguments (§20.7.18). The result is an Integer object that represents the integer value specified by the string.

In other words, this method returns an Integer object equal to the value of:

new Integer(Integer.parseInt(s, radix))

20.7.21 public static Integer getInteger(String nm)

The first argument is treated as the name of a system property to be obtained as if by the method System.getProperty (§20.18.9). The string value of this property is then interpreted as an integer value and an Integer object representing this value is returned. If there is no property of the specified name, or if the property does not have the correct numeric format, then null is returned.

In other words, this method returns an Integer object equal to the value of:

getInteger(nm, null)

20.7.22 public static Integer getInteger(String nm, int val)

The first argument is treated as the name of a system property to be obtained as if by the method System.getProperty (§20.18.9). The string value of this property is then interpreted as an integer value and an Integer object representing this value is returned. If the property does not have the correct numeric format, then an Integer object that represents the value of the second argument is returned.

In other words, this method returns an Integer object equal to the value of:

getInteger(nm, new Integer(val))

but in practice it may be implemented in a manner such as:

Integer result = getInteger(nm, null);
return (result == null) ? new Integer(val) : result;

to avoid the unnecessary allocation of an Integer object when the default value is not needed.

20.7.23 public static Integer getInteger(String nm, Integer val)

The first argument is treated as the name of a system property to be obtained as if by the method System.getProperty (§20.18.9). The string value of this property is then interpreted as an integer value and an Integer object representing this value is returned.

  • If the property value begins with the two ASCII characters 0x or the ASCII character #, not followed by a minus sign, then the rest of it is parsed as a hexadecimal integer exactly as for the method Integer.valueOf (§20.7.20) with radix 16.
  • If the property value begins with the ASCII character 0 followed by another character, it is parsed as an octal integer exactly as for the method Integer.valueOf (§20.7.20) with radix 8.
  • Otherwise, the property value is parsed as a decimal integer exactly as for the method Integer.valueOf (§20.7.20) with radix 10.

The second argument serves as a default value. If there is no property of the specified name, or if the property does not have the correct numeric format, then the second argument is returned.


20.8 The Class java.lang.Long

public final class Long extends Number {
    public static final long MIN_VALUE = 0x8000000000000000L;
    public static final long MAX_VALUE = 0x7fffffffffffffffL;
    public Long(long value);
    public Long(String s)

        throws NumberFormatException;
    public String toString();
    public boolean equals(Object obj);
    public int hashCode();
    public int intValue();
    public long longValue();
    public float floatValue();
    public double doubleValue();
    public static String toString(long i);
    public static String toString(long i, int radix);
    public static String toHexString(long i);
    public static String toOctalString(long i);
    public static String toBinaryString(long i);
    public static long parseLong(String s)

        throws NumberFormatException;
    public static long parseLong(String s, int radix)

        throws NumberFormatException;
    public static Long valueOf(String s)

        throws NumberFormatException;
    public static Long valueOf(String s, int radix)

        throws NumberFormatException;
    public static Long getLong(String nm);
    public static Long getLong(String nm, long val);
    public static Long getLong(String nm, Long val);
}

20.8.1 public static final long MIN_VALUE = 0x8000000000000000L;

The constant value of this field is the lowest value of type long.

20.8.2 public static final long MAX_VALUE = 0x7fffffffffffffffL;

The constant value of this field is the highest value of type long.

20.8.3 public Long(long value)

This constructor initializes a newly created Long object so that it represents the primitive value that is the argument.

20.8.4 public Long(String s) throws NumberFormatException

This constructor initializes a newly created Long object so that it represents the integer represented by the string in decimal form. The string is converted to a long value in exactly the manner used by the parseLong method (§20.8.17) for radix 10.

20.8.5 public String toString()

The long integer value represented by this Long object is converted to signed decimal representation and returned as a string, exactly as if the integer value were given as an argument to the toString method that takes one argument (§20.7.12).

Overrides the toString method of Object (§20.1.2).

20.8.6 public boolean equals(Object obj)

The result is true if and only if the argument is not null and is a Long object that represents the same long value as this Long object.

Overrides the equals method of Object (§20.1.3).

20.8.7 public int hashCode()

The result is the exclusive OR of the two halves of the primitive long value represented by this Long object. That is, the hashcode is the value of the expression:

(int)(this.longValue()^(this.longValue()>>>32))

Overrides the hashCode method of Object (§20.1.4).

20.8.8 public int intValue()

The long value represented by this Long object is converted (§5.1.3) to type int and the result of the conversion is returned.

Overrides the intValue method of Number (§20.6.1).

20.8.9 public long longValue()

The long value represented by this Long object is returned.

Overrides the longValue method of Number (§20.6.2).

20.8.10 public float floatValue()

The long value represented by this Long object is converted (§5.1.2) to type float and the result of the conversion is returned.

Overrides the floatValue method of Number (§20.6.3).

20.8.11 public double doubleValue()

The long value represented by this Long object is converted (§5.1.2) to type double and the result of the conversion is returned.

Overrides the doubleValue method of Number (§20.6.4).

20.8.12 public static String toString(long i)

The argument is converted to signed decimal representation and returned as a string, exactly as if the argument and the radix 10 were given as arguments to the toString method that takes two arguments (§20.8.13).

20.8.13 public static String toString(long i, int radix)

The first argument is converted to a signed representation in the radix specified by the second argument; this representation is returned as a string.

If the radix is smaller than Character.MIN_RADIX (§20.5.3) or larger than Character.MAX_RADIX (§20.5.4), then the value 10 is used instead.

If the first argument is negative, the first character of the result will be the character '-' ('\u002d'). If the first argument is not negative, no sign character appears in the result.

The remaining characters of the result represent the magnitude of the first argument. If the magnitude is zero, it is represented by a single zero character '0' ('\u0030'); otherwise, the first character of the representation of the magnitude will not be the zero character. The following ASCII characters are used as digits:

0123456789abcdefghijklmnopqrstuvwxyz

These are '\u0030' through '\u0039' and '\u0061' through '\u007a'. If the radix is N, then the first N of these characters are used as radix-N digits in the order shown. Thus, the digits for hexadecimal (radix 16) are 0123456789abcdef. If uppercase letters are desired, the toUpperCase method (§20.12.36) of class String may be called on the result:

Long.toString(n, 16).toUpperCase()

20.8.14 public static String toHexString(long i)

The argument is converted to an unsigned representation in hexadecimal radix (base 16); this representation is returned as a string.

The result represents the unsigned magnitude of the argument. This equals the argument plus [image] if the argument is negative; otherwise, it equals the argument.

If the unsigned magnitude is zero, it is represented by a single zero character '0' ('\u0030'); otherwise, the first character of the representation of the unsigned magnitude will not be the zero character. The following characters are used as hexadecimal digits:

0123456789abcdef

These are the characters '\u0030' through '\u0039' and '\u0061' through '\u0066'. If uppercase letters are desired, the toUpperCase method (§20.12.36) of class String may be called on the result:

Long.toHexString(n).toUpperCase()

20.8.15 public static String toOctalString(long i)

The argument is converted to an unsigned representation in octal radix (base 8); this representation is returned as a string.

The result represents the unsigned magnitude of the argument. This equals the argument plus [image] if the argument is negative; otherwise, it equals the argument.

If the unsigned magnitude is zero, it is represented by a single zero character '0' ('\u0030'); otherwise, the first character of the representation of the unsigned magnitude will not be the zero character. The following characters are used as octal digits:

01234567

These are the characters '\u0030' through '\u0037'.

20.8.16 public static String toBinaryString(long i)

The argument is converted to an unsigned representation in binary radix (base 2); this representation is returned as a string.

The result represents the unsigned magnitude of the argument. This equals the argument plus [image] if the argument is negative; otherwise, it equals the argument.

If the unsigned magnitude is zero, it is represented by a single zero character '0' ('\u0030'); otherwise, the first character of the representation of the unsigned magnitude will not be the zero character. The characters '0' ('\u0030') and '1' ('\u0031') are used as binary digits.

20.8.17 public static long parseLong(String s)
throws NumberFormatException

The argument is interpreted as representing a signed decimal integer. The components of the string must all be decimal digits, except that the first character may be '-' ('\u002d') to indicate a negative value. The resulting long value is returned, exactly as if the argument and the radix 10 were given as arguments to the parseLong method that takes two arguments (§20.8.18).

Note that neither L nor l is permitted to appear at the end of the string as a type indicator, as would be permitted in Java source code (§3.10.1).

20.8.18 public static long parseLong(String s, int radix)
throws NumberFormatException

The first argument is interpreted as representing a signed integer in the radix specified by the second argument. The components of the string must all be digits of the specified radix (as determined by whether Character.digit (§20.5.23) returns a nonnegative value), except that the first character may be '-' ('\u002d') to indicate a negative value. The resulting long value is returned.

Note that neither L nor l is permitted to appear at the end of the string as a type indicator, as would be permitted in Java source code (§3.10.1)-except that either L or l may appear as a digit for a radix greater than 22.

An exception of type NumberFormatException is thrown if any of the following situations occurs:

  • The first argument is null or is a string of length zero.
  • The radix is either smaller than Character.MIN_RADIX (§20.5.3) or larger than Character.MAX_RADIX (§20.5.4).
  • The first character of the string is not a digit of the specified radix and is not a minus sign '-' ('\u002d').
  • The first character of the string is a minus sign and the string is of length 1.
  • Any character of the string after the first is not a digit of the specified radix.
  • The integer value represented by the string cannot be represented as a value of type long.

Examples:

parseLong("0", 10) returns 0L
parseLong("473", 10) returns 473L
parseLong("-0", 10) returns 0L
parseLong("-FF", 16) returns -255L
parseLong("1100110", 2) returns 102L
parseLong("99", 8) throws a NumberFormatException
parseLong("Hazelnut", 10) throws a NumberFormatException
parseLong("Hazelnut", 36) returns 1356099454469L

20.8.19 public static Long valueOf(String s)
throws NumberFormatException

The argument is interpreted as representing a signed decimal integer, exactly as if the argument were given to the parseLong method that takes one argument (§20.8.17). The result is a Long object that represents the integer value specified by the string.

In other words, this method returns a Long object equal to the value of:

new Long(Long.parseLong(s))

20.8.20 public static Long valueOf(String s, int radix)
throws NumberFormatException

The first argument is interpreted as representing a signed integer in the radix specified by the second argument, exactly as if the arguments were given to the parseLong method that takes two arguments (§20.8.18). The result is a Long object that represents the integer value specified by the string.

In other words, this method returns a Long object equal to the value of:

new Long(Long.parseLong(s, radix))

20.8.21 public static Long getLong(String nm)

The first argument is treated as the name of a system property to be obtained as if by the method System.getProperty (§20.18.9). The string value of this property is then interpreted as an integer value and a Long object representing this value is returned. If there is no property of the specified name, or if the property does not have the correct numeric format, then null is returned.

In other words, this method returns a Long object equal to the value of:

getLong(nm, null)

20.8.22 public static Long getLong(String nm, long val)

The first argument is treated as the name of a system property to be obtained as if by the method System.getProperty (§20.18.9). The string value of this property is then interpreted as an integer value and a Long object representing this value is returned. If there is no property of the specified name, or if the property does not have the correct numeric format, then a Long object that represents the value of the second argument is returned.

In other words, this method returns a Long object equal to the value of:

getLong(nm, new Long(val))

but in practice it may be implemented in a manner such as:

Long result = getLong(nm, null);
return (result == null) ? new Long(val) : result;

to avoid the unnecessary allocation of a Long object when the default value is not needed.

20.8.23 public static Long getLong(String nm, Long val)

The first argument is treated as the name of a system property to be obtained as if by the method System.getProperty (§20.18.9). The string value of this property is then interpreted as an integer value and a Long object representing this value is returned.

  • If the property value begins with the two ASCII characters 0x or the ASCII character #, not followed by a minus sign, then the rest of it is parsed as a hexadecimal integer exactly as for the method Long.valueOf (§20.7.20) with radix 16.
  • If the property value begins with the character 0 followed by another character, it is parsed as an octal integer exactly as for the method Long.valueOf (§20.7.20) with radix 8.
  • Otherwise the property value is parsed as a decimal integer exactly as for the method Long.valueOf (§20.7.20) with radix 10.

Note that, in every case, neither L nor l is permitted to appear at the end of the property value as a type indicator, as would be permitted in Java source code (§3.10.1).

The second argument serves as a default value. If there is no property of the specified name, or if the property does not have the correct numeric format, then the second argument is returned.


20.9 The Class java.lang.Float

public final class Float extends Number {
    public static final float MIN_VALUE = 1.4e-45f;
    public static final float MAX_VALUE = 3.4028235e+38f;
    public static final float NEGATIVE_INFINITY = -1.0f/0.0f;
    public static final float POSITIVE_INFINITY = 1.0f/0.0f;
    public static final float NaN = 0.0f/0.0f;
    public Float(float value);
    public Float(double value);
    public Float(String s)
        throws NumberFormatException;
    public String toString();
    public boolean equals(Object obj);
    public int hashCode();
    public int intValue();
    public long longValue();
    public float floatValue();
    public double doubleValue();
    public static String toString(float f);
    public static Float valueOf(String s)
        throws NullPointerException, NumberFormatException;
    public boolean isNaN();
    public static boolean isNaN(float v);
    public boolean isInfinite();
    public static boolean isInfinite(float v);
    public static int floatToIntBits(float value);
    public static float intBitsToFloat(int bits);
}

20.9.1 public static final float MIN_VALUE = 1.4e-45f;

The constant value of this field is the smallest positive nonzero value of type float. It is equal to the value returned by Float.intBitsToFloat(0x1).

20.9.2 public static final float MAX_VALUE = 3.4028235e+38f;

The constant value of this field is the largest positive finite value of type float. It is equal to the value returned by Float.intBitsToFloat(0x7f7fffff).

20.9.3 public static final float NEGATIVE_INFINITY =
-1.0f/0.0f;

The constant value of this field is the negative infinity of type float. It is equal to the value returned by Float.intBitsToFloat(0xff800000).

20.9.4 public static final float POSITIVE_INFINITY =
1.0f/0.0f;

The constant value of this field is the positive infinity of type float. It is equal to the value returned by Float.intBitsToFloat(0x7f800000).

20.9.5 public static final float NaN = 0.0f/0.0f;

The constant value of this field is the Not-a-Number value of type float. It is equal to the value returned by Float.intBitsToFloat(0x7fc00000).

20.9.6 public Float(float value)

This constructor initializes a newly created Float object so that it represents the primitive value that is the argument.

20.9.7 public Float(double value)

This constructor initializes a newly created Float object so that it represents the result of narrowing (§5.1.3) the argument from type double to type float.

20.9.8 public Float(String s) throws NumberFormatException

This constructor initializes a newly created Float object so that it represents the floating-point value of type float represented by the string. The string is converted to a float value in exactly the manner used by the valueOf method (§20.9.17).

20.9.9 public String toString()

The primitive float value represented by this Float object is converted to a string exactly as if by the method toString of one argument (§20.9.16).

Overrides the toString method of Object (§20.1.2).

20.9.10 public boolean equals(Object obj)

The result is true if and only if the argument is not null and is a Float object that represents the same float value as this Float object. For this purpose, two float values are considered to be the same if and only if the method floatToIntBits (§20.9.22) returns the same int value when applied to each. Note that even though the == operator returns false if both operands are NaN, this equals method will return true if this Float object and the argument are both Float objects that represent NaN. On the other hand, even though the == operator returns true if one operand is positive zero and the other is negative zero, this equals method will return false if this Float object and the argument represent zeroes of different sign. This definition allows hashtables to operate properly.

Overrides the equals method of Object (§20.1.3).

20.9.11 public int hashCode()

The result is the integer bit representation, exactly as produced by the method floatToIntBits (§20.9.22), of the primitive float value represented by this Float object.

Overrides the hashCode method of Object (§20.1.4).

20.9.12 public int intValue()

The float value represented by this Float object is converted (§5.1.3) to type int and the result of the conversion is returned.

Overrides the intValue method of Number (§20.6.1).

20.9.13 public long longValue()

The float value represented by this Float object is converted (§5.1.3) to type long and the result of the conversion is returned.

Overrides the longValue method of Number (§20.6.2).

20.9.14 public float floatValue()

The float value represented by this Float object is returned.

Overrides the floatValue method of Number (§20.6.3).

20.9.15 public double doubleValue()

The float value represented by this Float object is converted (§5.1.2) to type double and the result of the conversion is returned.

Overrides the doubleValue method of Number (§20.6.4).

20.9.16 public static String toString(float f)

The argument is converted to a readable string format as follows. All characters and characters in strings mentioned below are ASCII characters.

  • If the argument is NaN, the result is the string "NaN".
  • Otherwise, the result is a string that represents the sign and magnitude (absolute value) of the argument. If the sign is negative, the first character of the result is '-' ('\u002d'); if the sign is positive, no sign character appears in the result. As for the magnitude m:
    • If m is infinity, it is represented by the characters "Infinity"; thus, positive infinity produces the result "Infinity" and negative infinity produces the result "-Infinity".
    • If m is zero, it is represented by the characters "0.0"; thus, negative zero produces the result "-0.0" and positive zero produces the result "0.0".
    • If m is greater than or equal to [image] but less than [image], then it is represented as the integer part of m, in decimal form with no leading zeroes, followed by '.' (\u002E), followed by one or more decimal digits representing the fractional part of m.
    • If m is less than [image] or not less than [image], then it is represented in so-called "computerized scientific notation." Let n be the unique integer such that [image]; then let a be the mathematically exact quotient of m and [image] so that [image]. The magnitude is then represented as the integer part of a, as a single decimal digit, followed by '.' (\u002E), followed by decimal digits representing the fractional part of a, followed by the letter 'E' (\u0045), followed by a representation of n as a decimal integer, as produced by the method Integer.toString of one argument (§20.7.12).

How many digits must be printed for the fractional part of m or a? There must be at least one digit to represent the fractional part, and beyond that as many, but only as many, more digits as are needed to uniquely distinguish the argument value from adjacent values of type float. That is, suppose that x is the exact mathematical value represented by the decimal representation produced by this method for a finite nonzero argument f. Then f must be the float value nearest to x; or, if two float values are equally close to x, then f must be one of them and the least significant bit of the significand of f must be 0.

[This specification for the method toString is scheduled for introduction in Java version 1.1. In previous versions of Java, this method produces Inf instead of Infinity for infinite values. Also, it renders finite values in the same form as the %g format of the printf function in the C programming language, which can lose precision because it produces at most six digits after the decimal point.]

20.9.17 public static Float valueOf(String s)
throws NullPointerException, NumberFormatException

The string s is interpreted as the representation of a floating-point value and a Float object representing that value is created and returned.

If s is null, then a NullPointerException is thrown.

Leading and trailing whitespace (§20.5.19) characters in s are ignored. The rest of s should constitute a FloatValue as described by the lexical syntax rules:

FloatValue:

    Signopt Digits . Digitsopt ExponentPartopt

    Signopt . Digits ExponentPartopt

where Sign, Digits, and ExponentPart are as defined in §3.10.2. If it does not have the form of a FloatValue, then a NumberFormatException is thrown. Otherwise, it is regarded as representing an exact decimal value in the usual "computerized scientific notation"; this exact decimal value is then conceptually converted to an "infinitely precise" binary value that is then rounded to type float by the usual round-to-nearest rule of IEEE 754 floating-point arithmetic. Finally, a new object of class Float is created to represent this float value.

Note that neither F nor f is permitted to appear in s as a type indicator, as would be permitted in Java source code (§3.10.1).

20.9.18 public boolean isNaN()

The result is true if and only if the value represented by this Float object is NaN.

20.9.19 public static boolean isNaN(float v)

The result is true if and only if the value of the argument is NaN.

20.9.20 public boolean isInfinite()

The result is true if and only if the value represented by this Float object is positive infinity or negative infinity.

20.9.21 public static boolean isInfinite(float v)

The result is true if and only if the value of the argument is positive infinity or negative infinity.

20.9.22 public static int floatToIntBits(float value)

The result is a representation of the floating-point argument according to the IEEE 754 floating-point "single format" bit layout:

  • Bit 31 (the bit that is selected by the mask 0x80000000) represents the sign of the floating-point number.
  • Bits 30-23 (the bits that are selected by the mask 0x7f800000) represent the exponent.
  • Bits 22-0 (the bits that are selected by the mask 0x007fffff) represent the significand (sometimes called the mantissa) of the floating-point number.
  • If the argument is positive infinity, the result will be 0x7f800000.
  • If the argument is negative infinity, the result will be 0xff800000.
  • If the argument is NaN, the result will be 0x7fc00000.

In all cases, the result is an integer that, when given to the intBitsToFloat method (§20.9.23), will produce a floating-point value equal to the argument to floatToIntBits.

20.9.23 public static float intBitsToFloat(int bits)

The argument is considered to be a representation of a floating-point value according to the IEEE 754 floating-point "single format" bit layout. That floating-point value is returned as the result.

  • If the argument is 0x7f800000, the result will be positive infinity.
  • If the argument is 0xff800000, the result will be negative infinity.
  • If the argument is any value in the range 0x7f800001 through 0x7fffffff or in the range 0xff800001 through 0xffffffff, the result will be NaN. (All IEEE 754 NaN values are, in effect, lumped together by the Java language into a single value called NaN.)
  • In all other cases, let s, e, and m be three values that can be computed from the argument:

int s = ((bits >> 31) == 0) ? 1 : -1;
int e = ((bits >> 23) & 0xff);
int m = (e == 0) ?
        (bits & 0x7fffff) << 1 :
        (bits & 0x7fffff) | 0x800000;

Then the floating-point result equals the value of the mathematical expression [image].


20.10 The Class java.lang.Double

public final class Double extends Number {
    public static final double MIN_VALUE =

            5e-324;
    public static final double MAX_VALUE =
              1.7976931348623157e+308;
    public static final double NEGATIVE_INFINITY = -1.0/0.0;
    public static final double POSITIVE_INFINITY = 1.0/0.0;
    public static final double NaN = 0.0/0.0;
    public Double(double value);
    public Double(String s)

        throws NumberFormatException;
    public String toString();
    public boolean equals(Object obj);
    public int hashCode();
    public int intValue();
    public long longValue();
    public float floatValue();
    public double doubleValue();
    public static String toString(double d);
    public static Double valueOf(String s)

        throws NullPointerException, NumberFormatException;
    public boolean isNaN();
    public static boolean isNaN(double v);
    public boolean isInfinite();
    public static boolean isInfinite(double v);
    public static long doubleToLongBits(double value);
    public static double longBitsToDouble(long bits);
}

20.10.1 public static final double MIN_VALUE = 5e-324;

The constant value of this field is the smallest positive nonzero value of type double. It is equal to the value returned by Double.longBitsToDouble(0x1L).

20.10.2 public static final double MAX_VALUE = 1.7976931348623157e+308;

The constant value of this field is the largest positive finite value of type double. It is equal to the returned by:

Double.longBitsToDouble(0x7fefffffffffffffL)

20.10.3 public static final double NEGATIVE_INFINITY = -1.0/0.0;

The constant value of this field is the negative infinity of type double. It is equal to the value returned by Double.longBitsToDouble(0xfff0000000000000L).

20.10.4 public static final double POSITIVE_INFINITY = 1.0/0.0;

The constant value of this field is the positive infinity of type double. It is equal to the value returned by Double.longBitsToDouble(0x7ff0000000000000L).

20.10.5 public static final double NaN = 0.0/0.0;

The constant value of this field is the Not-a-Number of type double. It is equal to the value returned by Double.longBitsToDouble(0x7ff8000000000000L).

20.10.6 public Double(double value)

This constructor initializes a newly created Double object so that it represents the primitive value that is the argument.

20.10.7 public Double(String s)
throws NumberFormatException

This constructor initializes a newly created Double object so that it represents the floating-point value of type double represented by the string. The string is converted to a double value in exactly the manner used by the valueOf method (§20.9.17).

20.10.8 public String toString()

The primitive double value represented by this Double object is converted to a string exactly as if by the method toString of one argument (§20.10.15).

Overrides the toString method of Object (§20.1.2).

20.10.9 public boolean equals(Object obj)

The result is true if and only if the argument is not null and is a Double object that represents the same double value as this Double object. For this purpose, two double values are considered to be the same if and only if the method doubleToLongBits (§20.10.21) returns the same long value when applied to each. Note that even though the == operator returns false if both operands are NaN, this equals method will return true if this Double object and the argument are both Double objects that represent NaN. On the other hand, even though the == operator returns true if one operand is positive zero and the other is negative zero, this equals method will return false if this Double object and the argument represent zeroes of different sign. This allows hashtables to operate properly.

Overrides the equals method of Object (§20.1.3).

20.10.10 public int hashCode()

The result is the exclusive OR of the two halves of the long integer bit representation, exactly as produced by the method doubleToLongBits (§20.10.21), of the primitive double value represented by this Double object. That is, the hashcode is the value of the expression:

(int)(v^(v>>>32))

where v is defined by:

long v = Double.doubleToLongBits(this.longValue());

Overrides the hashCode method of Object (§20.1.4).

20.10.11 public int intValue()

The double value represented by this Double object is converted (§5.1.3) to type int and the result of the conversion is returned.

Overrides the intValue method of Number (§20.6.1).

20.10.12 public long longValue()

The double value represented by this Double object is converted (§5.1.3) to type long and the result of the conversion is returned.

Overrides the longValue method of Number (§20.6.2).

20.10.13 public float floatValue()

The double value represented by this Double object is converted (§5.1.3) to type float and the result of the conversion is returned.

Overrides the floatValue method of Number (§20.6.3).

20.10.14 public double doubleValue()

The double value represented by this Double object is returned.

Overrides the doubleValue method of Number (§20.6.4).

20.10.15 public static String toString(double d)

The argument is converted to a readable string format as follows. All characters mentioned below are ASCII characters.

  • If the argument is NaN, the result is the string "NaN".
  • Otherwise, the result is a string that represents the sign and magnitude (absolute value) of the argument. If the sign is negative, the first character of the result is '-' ('\u002d'); if the sign is positive, no sign character appears in the result. As for the magnitude m:
    • If m is infinity, it is represented by the characters "Infinity"; thus, positive infinity produces the result "Infinity" and negative infinity produces the result "-Infinity".
    • If m is zero, it is represented by the characters "0.0"; thus, negative zero produces the result "-0.0" and positive zero produces the result "0.0".
    • If m is greater than or equal to [image] but less than [image], then it is represented as the integer part of m, in decimal form with no leading zeroes, followed by '.' (\u002E), followed by one or more decimal digits representing the fractional part of m.
    • If m is less than [image] or not less than [image], then it is represented in so-called "computerized scientific notation." Let n be the unique integer such that [image]; then let a be the mathematically exact quotient of m and [image] so that [image]. The magnitude is then represented as the integer part of a, as a single decimal digit, followed by '.' (\u002E), followed by decimal digits representing the fractional part of a, followed by the letter 'E' (\u0045), followed by a representation of n as a decimal integer, as produced by the method Integer.toString of one argument (§20.7.12).

How many digits must be printed for the fractional part of m or a? There must be at least one digit to represent the fractional part, and beyond that as many, but only as many, more digits as are needed to uniquely distinguish the argument value from adjacent values of type double. That is, suppose that x is the exact mathematical value represented by the decimal representation produced by this method for a finite nonzero argument d. Then d must be the double value nearest to x; or if two double values are equally close to x, then d must be one of them and the least significant bit of the significand of d must be 0.

[This specification for the method toString is scheduled for introduction in Java version 1.1. In previous versions of Java, this method produces Inf instead of Infinity for infinite values. Also, it rendered finite values in the same form as the %g format of the printf function in the C programming language, which can lose information because it produces at most six digits after the decimal point.]

20.10.16 public static Double valueOf(String s)
throws NullPointerException, NumberFormatException

The string s is interpreted as the representation of a floating-point value and a Double object representing that value is created and returned.

If s is null, then a NullPointerException is thrown.

Leading and trailing whitespace (§20.5.19) characters in s are ignored. The rest of s should constitute a FloatValue as described by the lexical syntax rule:

FloatValue:

    Signopt Digits . Digitsopt ExponentPartopt

    Signopt . Digits ExponentPartopt

where Sign, Digits, and ExponentPart are as defined in §3.10.2. If it does not have the form of a FloatValue, then a NumberFormatException is thrown. Otherwise, it is regarded as representing an exact decimal value in the usual "computerized scientific notation"; this exact decimal value is then conceptually converted to an "infinitely precise" binary value that is then rounded to type double by the usual round-to-nearest rule of IEEE 754 floating-point arithmetic. Finally, a new object of class Double is created to represent the double value.

Note that neither D nor d is permitted to appear in s as a type indicator, as would be permitted in Java source code (§3.10.1).

20.10.17 public boolean isNaN()

The result is true if and only if the value represented by this Double object is NaN.

20.10.18 public static boolean isNaN(double v)

The result is true if and only if the value of the argument is NaN.

20.10.19 public boolean isInfinite()

The result is true if and only if the value represented by this Double object is positive infinity or negative infinity.

20.10.20 public static boolean isInfinite(double v)

The result is true if and only if the value of the argument is positive infinity or negative infinity.

20.10.21 public static long doubleToLongBits(double value)

The result is a representation of the floating-point argument according to the IEEE 754 floating-point "double format" bit layout:

  • Bit 63 (the bit that is selected by the mask 0x8000000000000000L) represents the sign of the floating-point number.
  • Bits 62-52 (the bits that are selected by the mask 0x7ff0000000000000L) represent the exponent.
  • Bits 51-0 (the bits that are selected by the mask 0x000fffffffffffffL) represent the significand (sometimes called the mantissa) of the floating-point number.
  • If the argument is positive infinity, the result will be 0x7ff0000000000000L.
  • If the argument is negative infinity, the result will be 0xfff0000000000000L.
  • If the argument is NaN, the result will be 0x7ff8000000000000L.

In all cases, the result is a long integer that, when given to the longBitsToDouble method (§20.10.22), will produce a floating-point value equal to the argument to doubleToLongBits.

20.10.22 public static double longBitsToDouble(long bits)

The argument is considered to be a representation of a floating-point value according to the IEEE 754 floating-point "double format" bit layout. That floating-point value is returned as the result.

  • If the argument is 0x7f80000000000000L, the result will be positive infinity.
  • If the argument is 0xff80000000000000L, the result will be negative infinity.
  • If the argument is any value in the range 0x7ff0000000000001L through 0x7fffffffffffffffL or in the range 0xfff0000000000001L through 0xffffffffffffffffL, the result will be NaN. (All IEEE 754 NaN values are, in effect, lumped together by the Java language into a single value called NaN.)
  • In all other cases, let s, e, and m be three values that can be computed from the argument:

int s = ((bits >> 63) == 0) ? 1 : -1;
int e = (int)((bits >> 52) & 0x7ffL);
long m = (e == 0) ?
        (bits & 0xfffffffffffffL) << 1 :
        (bits & 0xfffffffffffffL) | 0x10000000000000L;

Then the floating-point result equals the value of the mathematical expression [image].

Let beeves and home-bred kine partake
The sweets of Burn-mill meadow;
The swan on still St. Mary's Lake
Float double, swan and shadow!
—William Wordsworth, Yarrow Unvisited (1803)


20.11 The Class java.lang.Math

Oh, back to the days that were free from care in the 'Ology 'varsity shop,
With nothing to do but analyse air in an anemometrical top,
Or the differentiation of the trigonometrical pow'rs
Of the constant pi that made me sigh in those happy days of ours!
—I. W. Litchfield, Take Me Back to Tech (1885)

The class Math contains useful basic numerical constants and methods.

public final class Math {
    public static final double E = 2.7182818284590452354;
    public static final double PI = 3.14159265358979323846;
    public static double sin(double a);
    public static double cos(double a);
    public static double tan(double a);
    public static double asin(double a);
    public static double acos(double a);
    public static double atan(double a);
    public static double atan2(double a, double b);
    public static double exp(double a);
    public static double log(double a);
    public static double sqrt(double a);
    public static double pow(double a, double b);
    public static double IEEEremainder(double f1, double f2);
    public static double ceil(double a);
    public static double floor(double a);
    public static double rint(double a);
    public static int round(float a);
    public static long round(double a);
    public static double random();
    public static int abs(int a);
    public static long abs(long a);
    public static float abs(float a);
    public static double abs(double a);
    public static int min(int a, int b);
    public static long min(long a, long b);
    public static float min(float a, float b);
    public static double min(double a, double b);
    public static int max(int a, int b);
    public static long max(long a, long b);
    public static float max(float a, float b);
    public static double max(double a, double b);
}

To ensure portability of Java programs, the specifications of many of the numerical functions in this package require that they produce the same results as certain published algorithms. These algorithms are available from the well-known network library netlib as the package fdlibm ("Freely Distributable Math Library"). These algorithms, which are written in the C programming language, are to be understood as if executed in Java execution order with all floating-point operations following the rules of Java floating-point arithmetic.

The network library may be found at http://netlib.att.com/ on the World Wide Web; then perform a keyword search for fdlibm. The library may also be retrieved by E-mail; to begin the process, send a message containing the line:

send index from fdlibm

to netlib@research.att.com. The Java math library is defined with respect to the version of fdlibm dated 95/01/04. Where fdlibm provides more than one definition for a function (such as acos), the "IEEE754 core function" version is to be used (residing in a file whose name begins with the letter e).

A complete and self-contained description of the algorithms to be used for these functions will be provided in a future version of this specification. It is also anticipated that the algorithms will be coded in Java to provide a reference implementation that is not tied to fdlibm.

20.11.1 public static final double E = 2.7182818284590452354;

The constant value of this field is the double value that is closer than any other to e, the base of the natural logarithms.

20.11.2 public static final double PI = 3.14159265358979323846;

The constant value of this field is the double value that is closer than any other to [image], the ratio of the circumference of a circle to its diameter.

20.11.3 public static double sin(double a)

This method computes an approximation to the sine of the argument, using the sin algorithm as published in fdlibm (see the introduction to this section).

Special cases:

  • If the argument is NaN or an infinity, then the result is NaN.
  • If the argument is positive zero, then the result is positive zero; if the argument is negative zero, then the result is negative zero.

20.11.4 public static double cos(double a)

This method computes an approximation to the cosine of the argument, using the cos algorithm as published in fdlibm (see the introduction to this section).

Special case:

  • If the argument is NaN or an infinity, then the result is NaN.

20.11.5 public static double tan(double a)

This method computes an approximation to the tangent of the argument, using the tan algorithm as published in fdlibm (see the introduction to this section).

Special cases:

  • If the argument is NaN or an infinity, then the result is NaN.
  • If the argument is positive zero, then the result is positive zero; if the argument is negative zero, then the result is negative zero.

20.11.6 public static double asin(double a)

This method computes an approximation to the arc sine of the argument, using the asin algorithm as published in fdlibm (see the introduction to this section).

Special cases:

  • If the argument is NaN or its absolute value is greater than 1, then the result is NaN.
  • If the argument is positive zero, then the result is positive zero; if the argument is negative zero, then the result is negative zero.

20.11.7 public static double acos(double a)

This method computes an approximation to the arc cosine of the argument, using the acos algorithm as published in fdlibm (see the introduction to this section).

Special case:

  • If the argument is NaN or its absolute value is greater than 1, then the result is NaN.

20.11.8 public static double atan(double a)

This method computes an approximation to the arc tangent of the argument, using the atan algorithm as published in fdlibm (see the introduction to this section).

Special cases:

  • If the argument is NaN, then the result is NaN.
  • If the argument is positive zero, then the result is positive zero; if the argument is negative zero, then the result is negative zero.

20.11.9 public static double atan2(double y, double x)

This method computes an approximation to the arc tangent of the quotient [image] of the arguments, using the atan2 algorithm as published in fdlibm (see the introduction to this section).

Special cases:

  • If either argument is NaN, then the result is NaN.
  • If the first argument is positive zero and the second argument is positive, or the first argument is positive and finite and the second argument is positive infinity, then the result is positive zero.
  • If the first argument is negative zero and the second argument is positive, or the first argument is negative and finite and the second argument is positive infinity, then the result is negative zero.
  • If the first argument is positive zero and the second argument is negative, or the first argument is positive and finite and the second argument is negative infinity, then the result is the double value closest to [image].
  • If the first argument is negative zero and the second argument is negative, or the first argument is negative and finite and the second argument is negative infinity, then the result is the double value closest to [image].
  • If the first argument is positive and the second argument is positive zero or negative zero, or the first argument is positive infinity and the second argument is finite, then the result is the double value closest to [image].
  • If the first argument is negative and the second argument is positive zero or negative zero, or the first argument is negative infinity and the second argument is finite, then the result is the double value closest to [image].
  • If both arguments are positive infinity, then the result is the double value closest to [image].
  • If the first argument is positive infinity and the second argument is negative infinity, then the result is the double value closest to [image].
  • If the first argument is negative infinity and the second argument is positive infinity, then the result is the double value closest to [image].
  • If both arguments are negative infinity, then the result is the double value closest to [image].

20.11.10 public static double exp(double a)

This method computes an approximation to the exponential function of the argument (e raised to the power of the argument, where e is the base of the natural logarithms (§20.11.1)), using the exp algorithm as published in fdlibm (see the introduction to this section).

Special cases:

  • If the argument is NaN, then the result is NaN.
  • If the argument is positive infinity, then the result is positive infinity.
  • If the argument is negative infinity, then the result is positive zero.

20.11.11 public static double log(double a)

This method computes an approximation to the natural logarithm of the argument, using the log algorithm as published in fdlibm (see the introduction to this section).

Special cases:

  • If the argument is NaN or less than zero, then the result is NaN.
  • If the argument is positive infinity, then the result is positive infinity.
  • If the argument is positive zero or negative zero, then the result is negative infinity.

20.11.12 public static double sqrt(double a)

Whan that Aprill with his shoures soote
The droghte of March hath perced to the roote . . .
—Geoffrey Chaucer (1328-1400), The Canterbury Tales, General Prologue

This method computes an approximation to the square root of the argument.

Special cases:

  • If the argument is NaN or less than zero, then the result is NaN.
  • If the argument is positive infinity, then the result is positive infinity.
  • If the argument is positive zero or negative zero, then the result is the same as the argument.

Otherwise, the result is the double value closest to the true mathematical square root of the argument value.

20.11.13 public static double pow(double a, double b)

This method computes an approximation to the mathematical operation of raising the first argument to the power of the second argument, using the pow algorithm as published in fdlibm (see the introduction to this section).

Special cases:

  • If the second argument is positive or negative zero, then the result is 1.0.
  • If the second argument is 1.0, then the result is the same as the first argument.
  • If the second argument is NaN, then the result is NaN.
  • If the first argument is NaN and the second argument is nonzero, then the result is NaN.
  • If the absolute value of the first argument is greater than 1 and the second argument is positive infinity, or the absolute value of the first argument is less than 1 and the second argument is negative infinity, then the result is positive infinity.
  • If the absolute value of the first argument is greater than 1 and the second argument is negative infinity, or the absolute value of the first argument is less than 1 and the second argument is positive infinity, then the result is positive zero.
  • If the absolute value of the first argument equals 1 and the second argument is infinite, then the result is NaN.
  • If the first argument is positive zero and the second argument is greater than zero, or the first argument is positive infinity and the second argument is less than zero, then the result is positive zero.
  • If the first argument is positive zero and the second argument is less than zero, or the first argument is positive infinity and the second argument is greater than zero, then the result is positive infinity.
  • If the first argument is negative zero and the second argument is greater than zero but not a finite odd integer, or the first argument is negative infinity and the second argument is less than zero but not a finite odd integer, then the result is positive zero.
  • If the first argument is negative zero and the second argument is a positive finite odd integer, or the first argument is negative infinity and the second argument is a negative finite odd integer, then the result is negative zero.
  • If the first argument is negative zero and the second argument is less than zero but not a finite odd integer, or the first argument is negative infinity and the second argument is greater than zero but not a finite odd integer, then the result is positive infinity.
  • If the first argument is negative zero and the second argument is a negative finite odd integer, or the first argument is negative infinity and the second argument is a positive finite odd integer, then the result is negative infinity.
  • If the first argument is less than zero and the second argument is a finite even integer, then the result is equal to the result of raising the absolute value of the first argument to the power of the second argument.
  • If the first argument is less than zero and the second argument is a finite odd integer, then the result is equal to the negative of the result of raising the absolute value of the first argument to the power of the second argument.
  • If the first argument is finite and less than zero and the second argument is finite and not an integer, then the result is NaN.
  • If both arguments are integers, then the result is exactly equal to the mathematical result of raising the first argument to the power of the second argument if that result can in fact be represented exactly as a double value.

(In the foregoing descriptions, a floating-point value is considered to be an integer if and only if it is a fixed point of the method ceil (§20.11.15) or, which is the same thing, a fixed point of the method floor (§20.11.16). A value is a fixed point of a one-argument method if and only if the result of applying the method to the value is equal to the value.)

20.11.14 public static double IEEEremainder(double x, double y)

This method computes the remainder operation on two arguments as prescribed by the IEEE 754 standard: the remainder value is mathematically equal to [image] where [image] is the mathematical integer closest to the exact mathematical value of the quotient [image]; if two mathematical integers are equally close to [image] then n is the integer that is even. If the remainder is zero, its sign is the same as the sign of the first argument.

Special cases:

  • If either argument is NaN, or the first argument is infinite, or the second argument is positive zero or negative zero, then the result is NaN.
  • If the first argument is finite and the second argument is infinite, then the result is the same as the first argument.

20.11.15 public static double ceil(double a)

The result is the smallest (closest to negative infinity) double value that is not less than the argument and is equal to a mathematical integer.

Special cases:

  • If the argument value is already equal to a mathematical integer, then the result is the same as the argument.
  • If the argument is NaN or an infinity or positive zero or negative zero, then the result is the same as the argument.
  • If the argument value is less than zero but greater than -1.0, then the result is negative zero.

Note that the value of Math.ceil(x) is exactly the value of -Math.floor(-x).

20.11.16 public static double floor(double a)

The result is the largest (closest to positive infinity) double value that is not greater than the argument and is equal to a mathematical integer.

Special cases:

  • If the argument value is already equal to a mathematical integer, then the result is the same as the argument.
  • If the argument is NaN or an infinity or positive zero or negative zero, then the result is the same as the argument.

20.11.17 public static double rint(double a)

The result is the double value that is closest in value to the argument and is equal to a mathematical integer. If two double values that are mathematical integers are equally close to the value of the argument, the result is the integer value that is even.

Special cases:

  • If the argument value is already equal to a mathematical integer, then the result is the same as the argument.
  • If the argument is NaN or an infinity or positive zero or negative zero, then the result is the same as the argument.

20.11.18 public static int round(float a)

Round numbers are always false.
—Samuel Johnson (1709-1784)

The result is rounded to an integer by adding [image], taking the floor of the result, and casting the result to type int.

In other words, the result is equal to the value of the expression:

(int)Math.floor(a + 0.5f)

Special cases:

  • If the argument is NaN, the result is 0.
  • If the argument is negative infinity, or indeed any value less than or equal to the value of Integer.MIN_VALUE (§20.7.1), the result is equal to the value of Integer.MIN_VALUE.
  • If the argument is positive infinity, or indeed any value greater than or equal to the value of Integer.MAX_VALUE (§20.7.2), the result is equal to the value of Integer.MAX_VALUE.

20.11.19 public static long round(double a)

The result is rounded to an integer by adding [image], taking the floor of the result, and casting the result to type long.

In other words, the result is equal to the value of the expression:

(long)Math.floor(a + 0.5d)

Special cases:

  • If the argument is NaN, the result is 0.
  • If the argument is negative infinity, or indeed any value less than or equal to the value of Long.MIN_VALUE (§20.7.1), the result is equal to the value of Long.MIN_VALUE.
  • If the argument is positive infinity, or indeed any value greater than or equal to the value of Long.MAX_VALUE (§20.7.2), the result is equal to the value of Long.MAX_VALUE.

20.11.20 public static double random()

The result is a double value with positive sign, greater than or equal to zero but less than 1.0, chosen pseudorandomly with (approximately) uniform distribution from that range.

When this method is first called, it creates a single new pseudorandom-number generator, exactly as if by the expression

new java.util.Random()

This new pseudorandom-number generator is used thereafter for all calls to this method and is used nowhere else.

This method is properly synchronized to allow correct use by more than one thread. However, if many threads need to generate pseudorandom numbers at a great rate, it may reduce contention for each thread to have its own pseudorandom number generator.

20.11.21 public static int abs(int a)

The result is the absolute value of the argument, if possible.

If the argument is not negative, the argument is returned.

If the argument is negative, the negation of the argument is returned. Note that if the argument is equal to the value of Integer.MIN_VALUE (§20.7.1), the most negative representable int value, the result will be that same negative value.

20.11.22 public static long abs(long a)

The result is the absolute value of the argument, if possible.

If the argument is not negative, the argument is returned.

If the argument is negative, the negation of the argument is returned. Note that if the argument is equal to the value of Long.MIN_VALUE (§20.8.1), the most negative representable long value, the result will be that same negative value.

20.11.23 public static float abs(float a)

The argument is returned with its sign changed to be positive.

Special cases:

  • If the argument is positive zero or negative zero, the result is positive zero.
  • If the argument is infinite, the result is positive infinity.
  • If the argument is NaN, the result is NaN.

In other words, the result is equal to the value of the expression:

Float.intBitsToFloat(0x7fffffff & Float.floatToIntBits(a))

[This specification for the method abs is scheduled for introduction in Java version 1.1. In previous versions of Java, abs(-0.0f) returns -0.0f, which is not correct.]

20.11.24 public static double abs(double a)

The argument is returned with its sign changed to be positive.

Special cases:

  • If the argument is positive zero or negative zero, the result is positive zero.
  • If the argument is infinite, the result is positive infinity.
  • If the argument is NaN, the result is NaN.

In other words, the result is equal to the value of the expression:

Double.longBitsToDouble((Double.doubleToLongBits(a)<<1)>>>1)

[This specification for the method abs is scheduled for introduction in Java version 1.1. In previous versions of Java, abs(-0.0d) returns -0.0d, which is not correct.]

20.11.25 public static int min(int a, int b)

E duobus malis minimum eligendum.
—Marcus Tullius Cicero (106-43 B. C.), De officiis, iii

The result is the smaller of the two arguments-that is, the one closer to the value of Integer.MIN_VALUE (§20.7.1). If the arguments have the same value, the result is that same value.

20.11.26 public static long min(long a, long b)

Of harmes two the lesse is for to cheese.
—Geoffrey Chaucer (1328-1400), Troilus and Criseyde, Book ii

The result is the smaller of the two arguments-that is, the one closer to the value of Long.MIN_VALUE (§20.8.1). If the arguments have the same value, the result is that same value.

20.11.27 public static float min(float a, float b)

Of two evils, the less is always to be chosen.
—Thomas a Kempis (1380-1471), Imitation of Christ, Book iii, chapter 12

The result is the smaller of the two arguments-that is, the one closer to negative infinity. If the arguments have the same value, the result is that same value.

Special cases:

  • If one argument is positive zero and the other is negative zero, the result is negative zero.
  • If either argument is NaN, the result is NaN.

[This specification for the method min is scheduled for introduction in Java version 1.1. In previous versions of Java, min(0.0f, -0.0f) returns 0.0f, which is not correct.]

20.11.28 public static double min(double a, double b)

Of two evils I have chose the least.
—Matthew Prior (1664-1721), Imitation of Horace

The result is the smaller of the two arguments-that is, the one closer to negative infinity. If the arguments have the same value, the result is that same value.

Special cases:

  • If one argument is positive zero and the other is negative zero, the result is negative zero.
  • If either argument is NaN, the result is NaN.

[This specification for the method min is scheduled for introduction in Java version 1.1. In previous versions of Java, min(0.0d, -0.0d) returns 0.0d, which is not correct.]

20.11.29 public static int max(int a, int b)

The result is the larger of the two arguments-that is, the one closer to the value of Integer.MAX_VALUE (§20.7.2). If the arguments have the same value, the result is that same value.

20.11.30 public static long max(long a, long b)

The result is the larger of the two arguments-that is, the one closer to the value of Long.MAX_VALUE (§20.8.2). If the arguments have the same value, the result is that same value.

20.11.31 public static float max(float a, float b)

The result is the larger of the two arguments-that is, the one closer to positive infinity. If the arguments have the same value, the result is that same value.

Special cases:

  • If one argument is positive zero and the other is negative zero, the result is positive zero.
  • If either argument is NaN, the result is NaN.

[This specification for the method max is scheduled for introduction in Java version 1.1. In previous versions of Java, max(-0.0f, 0.0f) returns -0.0f, which is not correct.]

20.11.32 public static double max(double a, double b)

The result is the larger of the two arguments-that is, the one closer to positive infinity. If the arguments have the same value, the result is that same value.

Special cases:

  • If one argument is positive zero and the other is negative zero, the result is positive zero.
  • If either argument is NaN, the result is NaN.

[This specification for the method max is scheduled for introduction in Java version 1.1. In previous versions of Java, max(-0.0d, 0.0d) returns -0.0d, which is not correct.].

In mathematics he was greater
Than Tycho Brahe or Erra Pater
For he, by geometric scale,
Could take the size of pots of ale;
Resolve, by sines and tangents straight
Whether bread or butter wanted weight;
And wisely tell what hour o' the day
The clock does strike, by algebra.
—Samuel Butler, Hudibras, Part I, canto i


20.12 The Class java.lang.String

An object of type String, once created, is immutable. It represents a fixed-length sequence of characters. Compare this to the class StringBuffer (§20.13), which represents a modifiable, variable-length sequence of characters.

The class String has methods for examining individual characters of the sequence, for comparing strings, for searching strings, for extracting substrings, for creating a copy of a string with all characters translated to uppercase or to lowercase, and so on.

public final class String {
    public String();
    public String(String value)
        throws NullPointerException;
    public String(StringBuffer buffer)
        throws NullPointerException;
    public String(char[] value)
        throws NullPointerException;
    public String(char[] value, int offset, int count)
        throws NullPointerException, IndexOutOfBoundsException;
    public String(byte[] ascii, int hibyte)
        throws NullPointerException;
    public String(byte[] ascii, int hibyte,
            int offset, int count)
        throws NullPointerException, IndexOutOfBoundsException;
    public String toString();
    public boolean equals(Object anObject);
    public int hashCode();
    public int length();
    public char charAt(int index);
    public void getChars(int srcBegin, int srcEnd,
            char dst[], int dstBegin)

        throws NullPointerException, IndexOutOfBoundsException;
    public void getBytes(int srcBegin, int srcEnd,
            byte dst[], int dstBegin)
        throws NullPointerException, IndexOutOfBoundsException;
    public char[] toCharArray();
    public boolean equalsIgnoreCase(String anotherString);
    public int compareTo(String anotherString)
        throws NullPointerException;
    public boolean regionMatches(int toffset, String other,

            int ooffset, int len)
        throws NullPointerException;
    public boolean regionMatches(boolean ignoreCase, int toffset,

            String other, int ooffset, int len)
        throws NullPointerException;
    public boolean startsWith(String prefix)
        throws NullPointerException;
    public boolean startsWith(String prefix, int toffset)
        throws NullPointerException;
    public boolean endsWith(String suffix)
        throws NullPointerException;
    public int indexOf(int ch);
    public int indexOf(int ch, int fromIndex);
    public int indexOf(String str)
        throws NullPointerException;
    public int indexOf(String str, int fromIndex)
        throws NullPointerException;
    public int lastIndexOf(int ch);
    public int lastIndexOf(int ch, int fromIndex);
    public int lastIndexOf(String str)
        throws NullPointerException;
    public int lastIndexOf(String str, int fromIndex)
        throws NullPointerException;
    public String substring(int beginIndex);
    public String substring(int beginIndex, int endIndex);
    public String concat(String str)
        throws NullPointerException;
    public String replace(char oldChar, char newChar);
    public String toLowerCase();
    public String toUpperCase();
    public String trim();
    public static String valueOf(Object obj);
    public static String valueOf(char[] data)
        throws NullPointerException;
    public static String valueOf(char[] data,
            int offset, int count)
        throws NullPointerException, IndexOutOfBoundsException;
    public static String valueOf(boolean b);
    public static String valueOf(char c);
    public static String valueOf(int i);
    public static String valueOf(long l);
    public static String valueOf(float f);
    public static String valueOf(double d);
    public String intern();
}

20.12.1 public String()

This constructor initializes a newly created String object so that it represents an empty character sequence.

20.12.2 public String(String value)

This constructor initializes a newly created String object so that it represents the same sequence of characters as the argument; in other words, the newly created string is a copy of the argument string.

20.12.3 public String(StringBuffer buffer)
throws NullPointerException

This constructor initializes a newly created String object so that it represents the sequence of characters that is currently contained in the StringBuffer argument (§20.13). The contents of the string buffer are copied; subsequent modification of the string buffer does not affect the newly created string.

If buffer is null, then a NullPointerException is thrown.

20.12.4 public String(char[] data)
throws NullPointerException

This constructor initializes a newly created String object so that it represents the sequence of characters currently contained in the character array argument. The contents of the character array are copied; subsequent modification of the character array does not affect the newly created string.

If data is null, then a NullPointerException is thrown.

20.12.5 public String(char[] data, int offset, int count)
throws NullPointerException, IndexOutOfBoundsException

This constructor initializes a newly created String object so that it represents the sequence of characters currently contained in a subarray of the character array argument. The offset argument is the index of the first character of the subarray and the count argument specifies the length of the subarray. The contents of the subarray are copied; subsequent modification of the character array does not affect the newly created string.

If data is null, then a NullPointerException is thrown.

If offset is negative, or count is negative, or offset+count is larger than data.length, then an IndexOutOfBoundsException is thrown.

20.12.6 public String(byte[] ascii, int hibyte)
throws NullPointerException

This constructor initializes a newly created String object so that it represents a sequence of characters constructed from an array of 8-bit integer values. Each character c in the result string is constructed from the corresponding element b of the byte array in such a way that:

c == ((hibyte & 0xff) << 8) | (b & 0xff)

If ascii is null, then a NullPointerException is thrown.

20.12.7 public String(byte[] ascii, int hibyte,
int offset, int count)
throws NullPointerException,
IndexOutOfBoundsException

This constructor initializes a newly created String object so that it represents the sequence of characters constructed from a subarray of an array of 8-bit integer values. The offset argument is the index of the first byte of the subarray and the count argument specifies the length of the subarray. Each character c in the result string is constructed from the corresponding element b of the byte subarray in such a way that:

c == ((hibyte & 0xff) << 8) | (b & 0xff)

If ascii is null, then a NullPointerException is thrown.

If offset is negative, or count is negative, or offset+count is larger than ascii.length, then an IndexOutOfBoundsException is thrown.

20.12.8 public String toString()

A reference to this object (which is, after all, already a String) is returned.

Overrides the toString method of Object (§20.1.2).

20.12.9 public boolean equals(Object anObject)

The result is true if and only if the argument is not null and is a String object that represents the same sequence of characters as this String object.

Overrides the equals method of Object (§20.1.3).

See also the methods equalsIgnoreCase (§20.12.16) and compareTo (§20.12.17).

20.12.10 public int hashCode()

The hashcode for a String object is computed in one of two ways, depending on its length. Let n be the length (§20.12.11) of the character sequence and let [image] mean the character with index i.

  • If [image], then the hashcode is computed as
    using int arithmetic.
  • If [image], then the hashcode is computed as
    using int arithmetic, where [image] and [image], sampling only eight or nine characters of the string.

Overrides the hashCode method of Object (§20.1.4).

20.12.11 public int length()

The length of the sequence of characters represented by this String object is returned.

20.12.12 public char charAt(int index)
throws IndexOutOfBoundsException

This method returns the character indicated by the index argument within the sequence of characters represented by this String. The first character of the sequence is at index 0, the next at index 1, and so on, as for array indexing. If the index argument is negative or not less than the length (§20.12.11) of this string, then an IndexOutOfBoundsException is thrown.

20.12.13 public void getChars(int srcBegin, int srcEnd,
char dst[], int dstBegin)
throws NullPointerException,
IndexOutOfBoundsException

Characters are copied from this String object into the destination character array dst. The first character to be copied is at index srcBegin; the last character to be copied is at index srcEnd-1 (thus the total number of characters to be copied is srcEnd-srcBegin). The characters are copied into the subarray of dst starting at index dstBegin and ending at index dstbegin+(srcEnd-srcBegin)-1.

If dst is null, then a NullPointerException is thrown.

An IndexOutOfBoundsException is thrown if any of the following is true:

  • srcBegin is negative
  • srcBegin is greater than srcEnd
  • srcEnd is greater than the length of this String
  • dstBegin is negative
  • dstBegin+(srcEnd-srcBegin) is larger than dst.length

20.12.14 public void getBytes(int srcBegin, int srcEnd,
byte dst[], int dstBegin)
throws NullPointerException,
IndexOutOfBoundsException

Characters are copied from this String object into the destination byte array dst. Each byte receives only the eight low-order bits of the corresponding character. The eight high-order bits of each character are not copied and do not participate in the transfer in any way. The first character to be copied is at index srcBegin; the last character to be copied is at index srcEnd-1 (thus the total number of characters to be copied is srcEnd-srcBegin). The characters, converted to bytes, are copied into the subarray of dst starting at index dstBegin and ending at index dstbegin+(srcEnd-srcBegin)-1.

If dst is null, then a NullPointerException is thrown.

An IndexOutOfBoundsException is thrown if any of the following is true:

  • srcBegin is negative
  • srcBegin is greater than srcEnd
  • srcEnd is greater than the length of this String
  • dstBegin is negative
  • dstBegin+(srcEnd-srcBegin) is larger than dst.length

20.12.15 public char[] toCharArray()

A new character array is created and returned. The length of the array is equal to the length (§20.12.11) of this String object. The array is initialized to contain the character sequence represented by this String object.

20.12.16 public boolean equalsIgnoreCase(String anotherString)

The result is true if and only if the argument is not null and is a String object that represents the same sequence of characters as this String object, where case is ignored.

Two characters are considered the same, ignoring case, if at least one of the following is true:

  • The two characters are the same (as compared by the == operator).
  • Applying the method Character.toUppercase (§20.5.21) to each character produces the same result.
  • Applying the method Character.toLowercase (§20.5.20) to each character produces the same result.

Two sequences of characters are the same, ignoring case, if the sequences have the same length and corresponding characters are the same, ignoring case.

See also the method equals (§20.12.9).

20.12.17 public int compareTo(String anotherString)
throws NullPointerException

The character sequence represented by this String object is compared lexicographically to the character sequence represented by the argument string. The result is a negative integer if this String object lexicographically precedes the argument string. The result is a positive integer if this String object lexicographically follows the argument string. The result is zero if the strings are equal; compareTo returns 0 exactly when the equals method (§20.12.9) would return true.

If anotherString is null, then a NullPointerException is thrown.

This is the definition of lexicographic ordering. If two strings are different, then either they have different characters at some index that is a valid index for both strings, or their lengths are different, or both. If they have different characters at one or more index positions, let k be the smallest such index; then the string whose character at position k has the smaller value, as determined by using the < operator, lexicographically precedes the other string. In this case, compareTo returns the difference of the two character values at position k in the two strings- that is, the value:

this.charAt(k)-anotherString.charAt(k)

If there is no index position at which they differ, then the shorter string lexicographically precedes the longer string. In this case, compareTo returns the difference of the lengths of the strings-that is, the value:

this.length()-anotherString.length()

20.12.18 public boolean regionMatches(int toffset,
String other, int ooffset, int len)
throws NullPointerException

A substring of this String object is compared to a substring of the argument other. The result is true if these substrings represent identical character sequences. The substring of this String object to be compared begins at index toffset and has length len. The substring of other to be compared begins at index ooffset and has length len. The result is false if and only if at least one of the following is true:

  • toffset is negative.
  • ooffset is negative.
  • toffset+len is greater than the length of this String object.
  • ooffset+len is greater than the length of the other argument.
  • There is some nonnegative integer k less than len such that: this.charAt(toffset+k) != other.charAt(ooffset+k)

If other is null, then a NullPointerException is thrown.

20.12.19 public boolean regionMatches(boolean ignoreCase,
int toffset, String other, int ooffset, int len)
throws NullPointerException

A substring of this String object is compared to a substring of the argument other. The result is true if these substrings represent character sequences that are the same, ignoring case if and only if ignoreCase is true. The substring of this String object to be compared begins at index toffset and has length len. The substring of other to be compared begins at index ooffset and has length len. The result is false if and only if at least one of the following is true:

  • toffset is negative.
  • ooffset is negative.
  • toffset+len is greater than the length of this String object.
  • ooffset+len is greater than the length of the other argument.
  • There is some nonnegative integer k less than len such that: this.charAt(toffset+k) != other.charAt(ooffset+k)
  • ignoreCase is true and there is some nonnegative integer k less than len such that:

Character.toLowerCase(this.charAt(toffset+k)) !=
    Character.toLowerCase(other.charAt(ooffset+k))

    and:

Character.toUpperCase(this.charAt(toffset+k)) !=
    Character.toUpperCase(other.charAt(ooffset+k))

If other is null, then a NullPointerException is thrown.

20.12.20 public boolean startsWith(String prefix)
throws NullPointerException

The result is true if and only if the character sequence represented by the argument is a prefix of the character sequence represented by this String object.

If prefix is null, a NullPointerException is thrown.

Note that the result will be true if the argument is an empty string or is equal to this String object as determined by the equals method (§20.12.9).

20.12.21 public boolean startsWith(String prefix, int toffset)
throws NullPointerException

The result is true if and only if the character sequence represented by the argument is a prefix of the substring of this String object starting at index toffset.

If prefix is null, then a NullPointerException is thrown.

The result is false if toffset is negative or greater than the length of this String object; otherwise, the result is the same as the result of the expression

this.subString(toffset).startsWith(prefix)

20.12.22 public boolean endsWith(String suffix)
throws NullPointerException

The result is true if and only if the character sequence represented by the argument is a suffix of the character sequence represented by this String object.

If suffix is null, then a NullPointerException is thrown.

Note that the result will be true if the argument is an empty string or is equal to this String object as determined by the equals method (§20.12.9).

20.12.23 public int indexOf(int ch)

If a character with value ch occurs in the character sequence represented by this String object, then the index of the first such occurrence is returned-that is, the smallest value k such that:

this.charAt(k) == ch

is true. If no such character occurs in this string, then -1 is returned.

20.12.24 public int indexOf(int ch, int fromIndex)

If a character with value ch occurs in the character sequence represented by this String object at an index no smaller than fromIndex, then the index of the first such occurrence is returned-that is, the smallest value k such that:

(this.charAt(k) == ch) && (k >= fromIndex)

is true. If no such character occurs in this string at or after position fromIndex, then -1 is returned.

There is no restriction on the value of fromIndex. If it is negative, it has the same effect as if it were zero: this entire string may be searched. If it is greater than the length of this string, it has the same effect as if it were equal to the length of this string: -1 is returned.

20.12.25 public int indexOf(String str)
throws NullPointerException

If the string str occurs as a substring of this String object, then the index of the first character of the first such substring is returned-that is, the smallest value k such that:

this.startsWith(str, k)

is true. If str does not occur as a substring of this string, then -1 is returned.

If str is null, a NullPointerException is thrown.

20.12.26 public int indexOf(String str, int fromIndex)
throws NullPointerException

If the string str occurs as a substring of this String object starting at an index no smaller than fromIndex, then the index of the first character of the first such substring is returned-that is, the smallest value k such that:

this.startsWith(str, k) && (k >= fromIndex)

is true. If str does not occur as a substring of this string at or after position fromIndex, then -1 is returned.

There is no restriction on the value of fromIndex. If it is negative, it has the same effect as if it were zero: this entire string may be searched. If it is greater than the length of this string, it has the same effect as if it were equal to the length of this string: -1 is returned.

If str is null, a NullPointerException is thrown.

20.12.27 public int lastIndexOf(int ch)

If a character with value ch occurs in the character sequence represented by this String object, then the index of the last such occurrence is returned-that is, the largest value k such that:

this.charAt(k) == ch

is true. If no such character occurs in this string, then -1 is returned.

20.12.28 public int lastIndexOf(int ch, int fromIndex)

If a character with value ch occurs in the character sequence represented by this String object at an index no larger than fromIndex, then the index of the last such occurrence is returned-that is, the largest value k such that:

(this.charAt(k) == ch) && (k <= fromIndex)

is true. If no such character occurs in this string at or before position fromIndex, then -1 is returned.

There is no restriction on the value of fromIndex. If it is greater than or equal to the length of this string, it has the same effect as if it were equal to one less than the length of this string: this entire string may be searched. If it is negative, it has the same effect as if it were -1: -1 is returned.

20.12.29 public int lastIndexOf(String str)
throws NullPointerException

If the string str occurs as a substring of this String object, then the index of the first character of the last such substring is returned-that is, the largest value k such that:

this.startsWith(str, k)

is true. If str does not occur as a substring of this string, then -1 is returned.

If str is null, a NullPointerException is thrown.

20.12.30 public int lastIndexOf(String str, int fromIndex)
throws NullPointerException

If the string str occurs as a substring of this String object starting at an index no larger than fromIndex, then the index of the first character of the last such substring is returned-that is, the largest value k such that:

this.startsWith(str, k) && (k <= fromIndex)

is true. If str does not occur as a substring of this string at or before position fromIndex, then -1 is returned.

There is no restriction on the value of fromIndex. If it is greater than the length of this string, it has the same effect as if it were equal to the length of this string: this entire string may be searched. If it is negative, it has the same effect as if it were -1: -1 is returned.

If str is null, a NullPointerException is thrown.

20.12.31 public String substring(int beginIndex)
throws IndexOutOfBoundsException

The result is a newly created String object that represents a subsequence of the character sequence represented by this String object; this subsequence begins with the character at position beginIndex and extends to the end of the character sequence.

If beginIndex is negative or larger than the length of this String object, then an IndexOutOfBoundsException is thrown.

Examples:

"unhappy".substring(2) returns "happy"

"Harbison".substring(3) returns "bison"

"emptiness".substring(9) returns "" (an empty string)

20.12.32 public String substring(int beginIndex, int endIndex)
throws IndexOutOfBoundsException

The result is a newly created String object that represents a subsequence of the character sequence represented by this String object; this subsequence begins with the character at position beginIndex and ends with the character at position endIndex-1. Thus, the length of the subsequence is endIndex-beginIndex.

If beginIndex is negative, or endIndex is larger than the length of this String object, or beginIndex is larger than endIndex, then this method throws an IndexOutOfBoundsException.

Examples:

"hamburger".substring(4, 8) returns "urge"

"smiles".substring(1, 5) returns "mile"

20.12.33 public String concat(String str)
throws NullPointerException

If the length of the argument string is zero, then a reference to this String object is returned. Otherwise, a new String object is created, representing a character sequence that is the concatenation of the character sequence represented by this String object and the character sequence represented by the argument string.

Examples:

"cares".concat("s") returns "caress"
"to".concat("get").concat("her") returns "together"

If str is null, a NullPointerException is thrown.

20.12.34 public String replace(char oldChar, char newChar)

If the character oldChar does not occur in the character sequence represented by this String object, then a reference to this String object is returned. Otherwise, a new String object is created that represents a character sequence identical to the character sequence represented by this String object, except that every occurrence of oldChar is replaced by an occurrence of newChar.

Examples:

"mesquite in your cellar".replace('e', 'o')
                    returns "mosquito in your collar"
"the war of baronets".replace('r', 'y')
                    returns "the way of bayonets"
"sparring with a purple porpoise".replace('p', 't')
                    returns "starring with a turtle tortoise"
"JonL".replace('q', 'x') returns "JonL" (no change)

20.12.35 public String toLowerCase()

If this String object does not contain any character that is mapped to a different character by the method Character.toLowerCase (§20.5.20), then a reference to this String object is returned. Otherwise, this method creates a new String object that represents a character sequence identical in length to the character sequence represented by this String object, with every character equal to the result of applying the method Character.toLowerCase to the corresponding character of this String object.

Examples:

"French Fries".toLowerCase() returns "french fries"
"          ".toLowerCase() returns "          "

20.12.36 public String toUpperCase()

If this String object does not contain any character that is mapped to a different character by the method Character.toUpperCase (§20.5.21), then a reference to this String object is returned. Otherwise, this method creates a new String object representing a character sequence identical in length to the character sequence represented by this String object and with every character equal to the result of applying the method Character.toUpperCase to the corresponding character of this String object.

Examples:

"Fahrvergnügen".toUpperCase() returns "FAHRVERGNÜGEN"

"Visit Ljubinje!".toUpperCase() returns "VISIT LJUBINJE!"

20.12.37 public String trim()

If this String object represents an empty character sequence, or the first and last characters of character sequence represented by this String object both have codes greater than \u0020 (the space character), then a reference to this String object is returned.

Otherwise, if there is no character with a code greater than \u0020 in the string, then a new String object representing an empty string is created and returned.

Otherwise, let k be the index of the first character in the string whose code is greater than \u0020, and let m be the index of the last character in the string whose code is greater than \u0020. A new String object is created, representing the substring of this string that begins with the character at index k and ends with the character at index m-that is, the result of this.substring(k, m+1).

This method may be used to trim whitespace (§20.5.19) from the beginning and end of a string; in fact, it trims all ASCII control characters as well.

20.12.38 public static String valueOf(Object obj)

If the argument is null, then a string equal to "null" is returned. Otherwise, the value of obj.toString() is returned. See the toString method (§20.1.2).

20.12.39 public static String valueOf(char[] data)
throws NullPointerException

A string is created and returned. The string represents the sequence of characters currently contained in the character array argument. The contents of the character array are copied; subsequent modification of the character array does not affect the newly created string.

20.12.40 public static String valueOf(char[] data,
int offset, int count)
throws NullPointerException,
IndexOutOfBoundsException

A string is created and returned. The string represents the sequence of characters currently contained in a subarray of the character array argument. The offset argument is the index of the first character of the subarray and the count argument specifies the length of the subarray. The contents of the subarray are copied; subsequent modification of the character array does not affect the newly created string.

If data is null, then a NullPointerException is thrown.

If offset is negative, or count is negative, or offset+count is larger than data.length, then an IndexOutOfBoundsException is thrown.

20.12.41 public static String valueOf(boolean b)

A string representation of b is returned.

If the argument is true, the string "true" is returned.

If the argument is false, the string "false" is returned.

20.12.42 public static String valueOf(char c)

A string is created and returned. The string contains one character, equal to c.

20.12.43 public static String valueOf(int i)

A string is created and returned. The string is computed exactly as if by the method Integer.toString of one argument (§20.7.12).

20.12.44 public static String valueOf(long l)

A string is created and returned. The string is computed exactly as if by the method Long.toString of one argument (§20.8.12).

20.12.45 public static String valueOf(float f)

A string is created and returned. The string is computed exactly as if by the method Float.toString of one argument (§20.9.16).

20.12.46 public static String valueOf(double d)

A string is created and returned. The string is computed exactly as if by the method Double.toString of one argument (§20.10.15).

20.12.47 public String intern()

A pool of strings, initially empty, is maintained privately by the class String.

When the intern method is invoked, if the pool already contains a string equal to this String object as determined by the equals method (§20.12.9), then the string from the pool is returned. Otherwise, this String object is added to the pool and a reference to this String object is returned.

It follows that for any two strings s and t, s.intern() == t.intern() is true if and only if s.equals(t) is true.

All literal strings and string-valued constant expressions are interned (§3.10.5).


20.13 The Class java.lang.StringBuffer

A string buffer is like a String (§20.12), but can be modified. At any point in time it contains some particular sequence of characters, but the length and content of the sequence can be changed through certain method calls.

public class StringBuffer {
    public StringBuffer();
    public StringBuffer(int length)

        throws NegativeArraySizeException;
    public StringBuffer(String str);
    public String toString();
    public int length();
    public void setLength(int newLength)
        throws IndexOutOfBoundsException;
    public int capacity();
    public void ensureCapacity(int minimumCapacity);
    public char charAt(int index)
        throws IndexOutOfBoundsException;
    public void setCharAt(int index, char ch)
        throws IndexOutOfBoundsException;
    public void getChars(int srcBegin, int srcEnd,
            char[] dst, int dstBegin)

        throws NullPointerException, IndexOutOfBoundsException;
    public StringBuffer append(Object obj);
    public StringBuffer append(String str);
    public StringBuffer append(char[] str)
        throws NullPointerException;
    public StringBuffer append(char[] str, int offset, int len)
        throws NullPointerException, IndexOutOfBoundsException;
    public StringBuffer append(boolean b);
    public StringBuffer append(char c);
    public StringBuffer append(int i);
    public StringBuffer append(long l);
    public StringBuffer append(float f);
    public StringBuffer append(double d);
    public StringBuffer insert(int offset, Object obj)
        throws IndexOutOfBoundsException;
    public StringBuffer insert(int offset, String str)
        throws IndexOutOfBoundsException;
    public StringBuffer insert(int offset, char[] str)
        throws NullPointerException, IndexOutOfBoundsException;
    public StringBuffer insert(int offset, boolean b)
        throws IndexOutOfBoundsException;
    public StringBuffer insert(int offset, char c)
        throws IndexOutOfBoundsException;
    public StringBuffer insert(int offset, int i)
        throws IndexOutOfBoundsException;
    public StringBuffer insert(int offset, long l)
        throws IndexOutOfBoundsException;
    public StringBuffer insert(int offset, float f)
        throws IndexOutOfBoundsException;
    public StringBuffer insert(int offset, double d)
        throws IndexOutOfBoundsException;
    public StringBuffer reverse();
}

A string buffer has a capacity. As long as the length of the character sequence contained in the string buffer does not exceed the capacity, it is not necessary to create a new internal buffer array.

String buffers are safe for use by multiple threads. The methods are synchronized where necessary so that all the operations on any particular instance behave as if they occur in some serial order that is consistent with the order of the method calls made by each of the individual threads involved.

String buffers can be used by a compiler to implement the binary string concatenation operator + (§15.17.1). For example, suppose k has type int and a has type Object. Then the expression:

k + "/" + a

can be compiled as if it were the expression:

new StringBuffer().append(k).append("/").

                                        append(a).toString()

which creates a new string buffer (initially empty), appends the string representation of each operand to the string buffer in turn, and then converts the contents of the string buffer to a string. Overall, this avoids creating many temporary strings.

The principal operations on a StringBuffer are the append and insert methods, which are overloaded so as to accept data of any type. Each effectively converts a given datum to a string and then adds the characters of that string to the contents of the string buffer. The append method always adds these characters at the end of the buffer; the insert method adds the characters at a specified point.

For example, if z refers to a string buffer object whose current contents are the characters "start", then the method call z.append("le") would alter the string buffer to contain the characters "startle", but z.insert(4, "le") would alter the string buffer to contain the characters "starlet".

In general, if sb refers to an instance of a StringBuffer, then sb.append(x) has the same effect as sb.insert(sb.length(), x).

20.13.1 public StringBuffer()

This constructor initializes a newly created StringBuffer object so that it initially represents an empty character sequence and has capacity 16.

20.13.2 public StringBuffer(int length)
throws NegativeArraySizeException

This constructor initializes a newly created StringBuffer object so that it initially represents an empty character sequence, but has the capacity specified by the argument.

If the argument is negative, a NegativeArraySizeException is thrown.

20.13.3 public StringBuffer(String str)

This constructor initializes a newly created StringBuffer object so that it represents the same sequence of characters as the argument; in other words, the initial contents of the string buffer is a copy of the argument string. The initial capacity of the string buffer is 16 plus the length of the argument string.

20.13.4 public String toString()

A new String object is created and initialized to contain the character sequence currently represented by the string buffer; the new String is then returned. Any subsequent changes to the string buffer do not affect the contents of the returned string.

Implementation advice: This method can be coded so as to create a new String object without allocating new memory to hold a copy of the character sequence. Instead, the string can share the memory used by the string buffer. Any subsequent operation that alters the content or capacity of the string buffer must then make a copy of the internal buffer at that time. This strategy is effective for reducing the amount of memory allocated by a string concatenation operation (§15.17.1) when it is implemented using a string buffer.

Overrides the toString method of Object (§20.1.2).

20.13.5 public int length()

This method returns the length of the sequence of characters currently represented by this StringBuffer object.

20.13.6 public int capacity()

The current capacity of this StringBuffer object is returned.

20.13.7 public void ensureCapacity(int minimumCapacity)

If the current capacity of this StringBuffer object is less than the argument, then a new internal buffer is created with greater capacity. The new capacity will be the larger of:

  • the minimumCapacity argument
  • twice the old capacity, plus 2

If the minimumCapacity argument is nonpositive, this method takes no action and simply returns.

20.13.8 public void setLength(int newLength)
throws IndexOutOfBoundsException

This string buffer is altered to represent a new character sequence whose length is specified by the argument. For every nonnegative index k less than newLength, the character at index k in the new character sequence is the same as the character at index k in the old sequence if k is less than the length of the old character sequence; otherwise, it is the null character '\u0000'. This method also calls the ensureCapacity method (§20.13.7) with argument newLength.

If the argument is negative, an IndexOutOfBoundsException is thrown.

20.13.9 public char charAt(int index)
throws IndexOutOfBoundsException

The specified character of the sequence currently represented by the string buffer, as indicated by the index argument, is returned. The first character of the sequence is at index 0, the next at index 1, and so on, as for array indexing.

If the index argument is negative or not less than the current length (§20.13.5) of the string buffer, an IndexOutOfBoundsException is thrown.

20.13.10 public void setCharAt(int index, char ch)
throws IndexOutOfBoundsException

The string buffer is altered to represent a new character sequence that is identical to the old character sequence, except that it contains the character ch at position index.

If the index argument is negative or not less than the current length (§20.13.5) of the string buffer, an IndexOutOfBoundsException is thrown.

20.13.11 public void getChars(int srcBegin, int srcEnd,
char[] dst, int dstBegin)
throws NullPointerException,
IndexOutOfBoundsException

Characters are copied from this StringBuffer object into the destination array dst. The first character to be copied is at index srcBegin; the last character to be copied is at index srcEnd-1 (thus, the total number of characters to be copied is srcEnd-srcBegin). The characters are copied into the subarray of dst starting at index dstBegin and ending at index dstbegin+(srcEnd-srcBegin)-1.

If dst is null, then a NullPointerException is thrown.

Otherwise, if any of the following is true, an IndexOutOfBoundsException is thrown and the destination is not modified:

  • The srcBegin argument is negative.
  • The srcBegin argument is greater than the srcEnd argument.
  • srcEnd is greater than this.length(), the current length of this string buffer.
  • dstBegin+srcEnd-srcBegin is greater than dst.length.

20.13.12 public StringBuffer append(Object obj)

The argument is converted to a string as if by the method String.valueOf (§20.12.38) and the characters of that string are then appended (§20.13.13) to this StringBuffer object. A reference to this StringBuffer object is returned.

20.13.13 public StringBuffer append(String str)

The characters of the String argument are appended, in order, to the contents of this string buffer, increasing the length of this string buffer by the length of the argument. If str is null, then the four characters "null" are appended to this string buffer. The method ensureCapacity (§20.13.7) is first called with this new string buffer length as its argument. A reference to this StringBuffer object is returned.

Let n be the length of the old character sequence, the one contained in the string buffer just prior to execution of the append method. Then the character at index k in the new character sequence is equal to the character at index k in the old character sequence, if k is less than n; otherwise, it is equal to the character at index k-n in the argument str.

20.13.14 public StringBuffer append(char[] str)
throws NullPointerException

The characters of the array argument are appended, in order, to the contents of this string buffer, increasing the length of this string buffer by the length of the argument. The method ensureCapacity (§20.13.7) is first called with this new string buffer length as its argument. A reference to this StringBuffer object is returned.

The overall effect is exactly as if the argument were converted to a string by the method String.valueOf (§20.12.39) and the characters of that string were then appended (§20.13.13) to this StringBuffer object.

20.13.15 public StringBuffer append(char[] str,
int offset, int len)
throws NullPointerException,
IndexOutOfBoundsException

Characters of the character array str, starting at index offset, are appended, in order, to the contents of this string buffer, increasing the length of this string buffer by len. The method ensureCapacity (§20.13.7) is first called with this new string buffer length as its argument. A reference to this StringBuffer object is returned.

The overall effect is exactly as if the arguments were converted to a string by the method String.valueOf of three arguments (§20.12.40) and the characters of that string were then appended (§20.13.13) to this StringBuffer object.

20.13.16 public StringBuffer append(boolean b)

The argument is converted to a string as if by the method String.valueOf (§20.12.41) and the characters of that string are then appended (§20.13.13) to this StringBuffer object. A reference to this StringBuffer object is returned.

20.13.17 public StringBuffer append(char c)

The argument is appended to the contents of this string buffer, increasing the length of this string buffer by 1. The method ensureCapacity (§20.13.7) is first called with this new string buffer length as its argument. A reference to this StringBuffer object is returned.

The overall effect is exactly as if the argument were converted to a string by the method String.valueOf (§20.12.42) and the character in that string were then appended (§20.13.13) to this StringBuffer object.

20.13.18 public StringBuffer append(int i)

The argument is converted to a string as if by the method String.valueOf (§20.12.43) and the characters of that string are then appended (§20.13.13) to this StringBuffer object. A reference to this StringBuffer object is returned.

20.13.19 public StringBuffer append(long l)

The argument is converted to a string as if by the method String.valueOf (§20.12.44) and the characters of that string are then appended (§20.13.13) to this StringBuffer object. A reference to this StringBuffer object is returned.

20.13.20 public StringBuffer append(float f)

The argument is converted to a string as if by the method String.valueOf (§20.12.45) and the characters of that string are then appended (§20.13.13) to this StringBuffer object. A reference to this StringBuffer object is returned.

20.13.21 public StringBuffer append(double d)

The argument is converted to a string as if by the method String.valueOf (§20.12.46) and the characters of that string are then appended (§20.13.13) to this StringBuffer object. A reference to this StringBuffer object is returned.

20.13.22 public StringBuffer insert(int offset, Object obj)
throws IndexOutOfBoundsException

The argument is converted to a string as if by the method String.valueOf (§20.12.38) and the characters of that string are then inserted (§20.13.23) into this StringBuffer object at the position indicated by offset. A reference to this StringBuffer object is returned.

20.13.23 public StringBuffer insert(int offset, String str)
throws IndexOutOfBoundsException

The characters of the String argument are inserted, in order, into the string buffer at the position indicated by offset, moving up any characters originally above that position and increasing the length of the string buffer by the length of the argument. If str is null, then the four characters "null" are inserted into this string buffer. The method ensureCapacity (§20.13.7) is first called with this new string buffer length as its argument. A reference to this StringBuffer object is returned.

Let n be the length of the old character sequence, the one contained in the string buffer just prior to execution of the append method. Then the character at index k in the new character sequence is equal to:

  • the character at index k in the old character sequence, if k is less than offset
  • the character at index k-offset in the argument str, if k is not less than offset but is less than offset+str.length()
  • the character at index k-str.length() in the old character sequence, if k is not less than offset+str.length()

20.13.24 public StringBuffer insert(int offset, char[] str)
throws NullPointerException,
IndexOutOfBoundsException

The characters of the array argument, taken in order, are inserted into this string buffer, increasing the length of the string buffer by the length of the argument. The method ensureCapacity (§20.13.7) is first called with this new string buffer length as its argument. A reference to this StringBuffer object is returned.

The overall effect is exactly as if the argument were converted to a string by the method String.valueOf (§20.12.39) and the characters of that string were then inserted (§20.13.23) into this StringBuffer object at the position indicated by offset.

Note that while the StringBuffer class provides an append method that takes an offset, a character array, and two other arguments (§20.13.15), it does not currently provide an insert method that takes an offset, a character array, and two other arguments.

20.13.25 public StringBuffer insert(int offset, boolean b)
throws IndexOutOfBoundsException

The argument is converted to a string as if by the method String.valueOf (§20.12.41) and the characters of that string are then inserted (§20.13.23) into this StringBuffer object at the position indicated by offset. A reference to this StringBuffer object is returned.

20.13.26 public StringBuffer insert(int offset, char c)
throws IndexOutOfBoundsException

The argument is inserted into the contents of this string buffer at the position indicated by offset, increasing the length of this string buffer by 1. The method ensureCapacity (§20.13.7) is first called with this new string buffer length as its argument. A reference to this StringBuffer object is returned.

The overall effect is exactly as if the argument were converted to a string by the method String.valueOf (§20.12.42) and the character in that string were then inserted (§20.13.23) into this StringBuffer object at the position indicated by offset.

20.13.27 public StringBuffer insert(int offset, int i)
throws IndexOutOfBoundsException

The argument is converted to a string as if by the method String.valueOf (§20.12.43) and the characters of that string are then inserted (§20.13.23) into this StringBuffer object at the position indicated by offset. A reference to this StringBuffer object is returned.

20.13.28 public StringBuffer insert(int offset, long l)
throws IndexOutOfBoundsException

The argument is converted to a string as if by the method String.valueOf (§20.12.44) and the characters of that string are inserted (§20.13.23) into this StringBuffer object at the position indicated by offset. A reference to this StringBuffer object is returned.

20.13.29 public StringBuffer insert(int offset, float f)
throws IndexOutOfBoundsException

The argument is converted to a string as if by the method String.valueOf (§20.12.45) and the characters of that string are then inserted (§20.13.23) into this StringBuffer object at the position indicated by offset. A reference to this StringBuffer object is returned.

20.13.30 public StringBuffer insert(int offset, double d)
throws IndexOutOfBoundsException

The argument is converted to a string as if by the method String.valueOf (§20.12.46) and the characters of that string are then inserted (§20.13.23) into this StringBuffer object at the position indicated by offset. A reference to this StringBuffer object is returned.

20.13.31 public StringBuffer reverse()

The character sequence contained in this StringBuffer object is replaced by the reverse of that sequence. A reference to this StringBuffer object is returned.

Let n be the length of the old character sequence, the one contained in the string buffer just prior to execution of the reverse method. Then the character at index k in the new character sequence is equal to the character at index n-k-1 in the old character sequence.


20.14 The Class java.lang.ClassLoader

A class loader is an object that is responsible for loading classes. Given the name of a class, it should attempt to locate or generate data that constitutes a definition for the class. A typical strategy is to transform the name into a file name and then read a "class file" of that name from a file system.

Every Class object contains a reference to the ClassLoader that defined it (§20.3.7). Whenever executable Java code needs to use a class that has not yet been loaded, the loadClass method is invoked for the class loader of the class containing the code in question.

Class objects for array classes are not created by class loaders, but are created automatically as required by the Java runtime. The class loader for an array class, as returned by the getClassLoader method of class Class (§20.3.7), is the same as the class loader for its element type; if the element type is a primitive type, then the array class has no class loader.

Class loaders may typically be used by security managers (§20.17) to indicate security domains: two classes may considered to be "friendly" or "related" to each other only if they were defined by the same class loader.

public abstract class ClassLoader {
    protected ClassLoader()

        throws SecurityException;
    protected abstract Class loadClass(String name,
              boolean resolve)

        throws ClassNotFoundException;
    protected final Class defineClass(byte data[],
              int offset, int length)

        throws NullPointerException, IndexOutOfBoundsException,
            ClassFormatError;
    protected final void resolveClass(Class c);
    protected final Class findSystemClass(String name)

        throws ClassNotFoundException;
}

20.14.1 protected ClassLoader() throws SecurityException

This constructor is invoked for every newly created class loader. Because the class ClassLoader is abstract, it is not possible to create a new instance of the class ClassLoader itself; however, every constructor for a subclass of ClassLoader necessarily invokes this constructor, explicitly or implicitly, directly or indirectly.

All this constructor does is to enforce a security check: if there is a security manager, its checkCreateClassLoader method (§20.17.10) is called.

20.14.2 protected abstract Class loadClass(String name,
boolean link)
throws ClassNotFoundException

Every subclass of ClassLoader that is not itself abstract must provide an implementation of the method loadClass.

The general contract of loadClass is that, given the name of a class, it either returns the Class object for the class or throws a ClassNotFoundException.

If a Class object is to be returned and link is true, then the Class object should be linked (§12.3, §20.14.4) before it is returned.

In most cases, it is wise for a subclass of ClassLoader (§20.14) to implement the loadClass method as a synchronized method.

20.14.3 protected final Class defineClass(byte data[],
int offset, int length)
throws NullPointerException, IndexOutOfBoundsException, ClassFormatError

This method may be used by a class loader to define a new class.

The bytes in the array data in positions offset through offset+length-1 should have the format of a valid class file as defined by the Java Virtual Machine Specification.

If data is null, then a NullPointerException is thrown.

An IndexOutOfBoundsException is thrown if any of the following are true:

  • offset is negative
  • length is negative
  • offset+length is greater than data.length

If the indicated bytes of data do not constitute a valid class definition, then a ClassFormatError is thrown. Otherwise, this method creates and returns a Class object as described by the data bytes

20.14.4 protected final void resolveClass(Class c)
throws NullPointerException

This (misleadingly named) method may be used by a class loader to link (§12.3, §20.14.4) a class.

If c is null, then a NullPointerException is thrown.

If the Class object c has already been linked, then this method simply returns.

Otherwise, the class is linked as described in §12.3.

20.14.5 protected final Class findSystemClass(String name)
throws ClassNotFoundException

This method may be used by a class loader to locate a class that has no class loader. This includes built-in classes such as java.lang.Object, as well as classes that the host implementation may keep in, for example, a local file system.

Given the name of a class, this method, like the loadClass method, either returns the Class object for the class or throws a ClassNotFoundException.


20.15 The Class java.lang.Process

The method exec (§20.16.3) of class Runtime returns a reference to a Process object. The class Process provides methods for performing input from the process, performing output to the process, waiting for the process to complete, checking the exit status of the process, and destroying (killing) the process.

Dropping the last reference to a Process instance, thus allowing the Process object to be reclaimed, does not automatically kill the associated process.

There is no requirement that a process represented by a Process object execute asynchronously or concurrently with respect to the Java process that owns the Process object.

public abstract class Process {
    public abstract OutputStream getOutputStream();
    public abstract InputStream getInputStream();
    public abstract InputStream getErrorStream();
    public abstract int waitFor()

        throws InterruptedException;
    public abstract int exitValue()

        throws IllegalThreadStateException;
    public abstract void destroy();
}

20.15.1 public abstract OutputStream getOutputStream()

This method returns an OutputStream. Output to the stream is piped into the standard input stream of the process represented by this Process object.

Implementation note: It is a good idea for the output stream to be buffered.

20.15.2 public abstract InputStream getInputStream()

This method returns an InputStream. The stream obtains data piped from the standard output stream of the process represented by this Process object.

Implementation note: It is a good idea for the input stream to be buffered.

20.15.3 public abstract InputStream getErrorStream()

This method returns an InputStream. The stream obtains data piped from the error output stream of the process represented by this Process object.

Implementation note: It is a good idea for the input stream to be buffered.

20.15.4 public abstract int waitFor()
throws InterruptedException

This method causes the current thread to wait, if necessary, until the process represented by this Process object has terminated. Then the exit value of the process is returned. By convention, the value 0 indicates normal termination.

If the current thread is interrupted (§20.20.31) by another thread while it is waiting, then the wait is ended and an InterruptedException is thrown.

20.15.5 public abstract int exitValue()
throws IllegalThreadStateException

If the process represented by this Process object has not yet terminated, then an IllegalThreadStateException is thrown. Otherwise, the exit value of the process is returned. By convention, the value 0 indicates normal termination.

20.15.6 public abstract void destroy()

The process represented by this Process object is forcibly terminated.

It was my hint to speak—such was the process.
—William Shakespeare, Othello, Act I, scene iii


20.16 The Class java.lang.Runtime

public class Runtime {
    public static Runtime getRuntime();
    public void exit(int status);
    public Process exec(String command)

        throws IOException, SecurityException;
    public Process exec(String command, String envp[])

        throws IOException, SecurityException;
    public Process exec(String cmdarray[])

        throws IOException, SecurityException;
    public Process exec(String cmdarray[], String envp[])

        throws IOException, SecurityException;
    public long totalMemory();
    public long freeMemory();
    public void gc();
    public void runFinalization();
    public void traceInstructions(boolean on);
    public void traceMethodCalls(boolean on);
    public void load(String filename)
        throws SecurityException, UnsatisfiedLinkError;
    public void loadLibrary(String libname)
        throws SecurityException, UnsatisfiedLinkError;
    public InputStream getLocalizedInputStream(InputStream in);
    public OutputStream

        getLocalizedOutputStream(OutputStream out);
}

20.16.1 public static Runtime getRuntime()

This method returns the current Runtime object. Most of the methods of class Runtime are instance methods and must be invoked with respect to the current runtime object.

20.16.2 public void exit(int status)
throws SecurityException

First, if there is a security manager, its checkExit method (§20.17.13) is called with the status value as its argument.

This method terminates the currently running Java Virtual Machine. The argument serves as a status code; by convention, a nonzero status code indicates abnormal termination.

This method never returns normally.

See also the method exit (§20.18.11) of class System, which is the conventional and convenient means of invoking this method.

20.16.3 public Process exec(String command)
throws IOException, SecurityException,
IndexOutOfBoundsException

The command argument is parsed into tokens and then executed as a command in a separate process. The token parsing is done by a StringTokenizer (§21.10) created by the call:

new StringTokenizer(command)

with no further modification of the character categories.

This method behaves exactly as if it performs the call:

exec(command, null)

See §20.16.4.

20.16.4 public Process exec(String command, String envp[])
throws IOException, SecurityException,
IndexOutOfBoundsException

The command argument is parsed into tokens and then executed as a command in a separate process with an environment specified by envp. The token parsing is done by a StringTokenizer (§21.10) created by the call:

new StringTokenizer(command)

with no further modification of the character categories.

This method breaks the command string into tokens and creates a new array cmdarray containing the tokens in the order that they were produced by the string tokenizer; it then behaves exactly as if it performs the call:

exec(cmdarray, envp)

See §20.16.6.

20.16.5 public Process exec(String cmdarray[])
throws IOException, SecurityException,
NullPointerException, IndexOutOfBoundsException

The command specified by the tokens in cmdarray is executed as a command in a separate process.

This method behaves exactly as if it performs the call:

exec(cmdarray, null)

See §20.16.6.

20.16.6 public Process exec(String cmdarray[], String envp[])
throws IOException, SecurityException,
NullPointerException, IndexOutOfBoundsException

First, if there is a security manager, its checkExec method (§20.17.14) is called with the first component of the array cmdarray as its argument.

If cmdarray is null, a NullPointerException is thrown. If cmdarray is an empty array (has length 0), an IndexOutOfBoundsException is thrown.

Given an array of strings cmdarray, representing the tokens of a command line, and an array of strings envp, representing an "environment" that defines system properties, this method creates a new process in which to execute the specified command and returns a Process object (§20.15) representing the new process.

20.16.7 public long totalMemory()

The total amount of memory currently available for current and future created objects, measured in bytes, is returned. The value returned by this method may vary over time, depending on the host environment.

Note that the amount of memory required to hold an object of any given type may be implementation-dependent.

20.16.8 public long freeMemory()

An approximation to the total amount of memory currently available for future created objects, measured in bytes, is returned. This value is always less than the current value returned by the totalMemory method. Calling the gc method may increase the value returned by freeMemory.

20.16.9 public void gc()

Calling this method suggests that the Java Virtual Machine expend effort toward recycling discarded objects in order to make the memory they currently occupy available for quick reuse. When control returns from the method call, the Java Virtual Machine has made a best effort to recycle all discarded objects. (The name gc stands for "garbage collector.")

The Java runtime system will perform this recycling process automatically as needed, in a separate thread, if the gc method is not invoked explicitly.

See also the method gc (§20.18.12) of class System, which is the conventional and convenient means of invoking this method.

20.16.10 public void runFinalization()

Calling this method suggests that the Java Virtual Machine expend effort toward running the finalize methods of objects that have been found to be discarded but whose finalize methods have not yet been run. When control returns from the method call, the Java Virtual Machine has made a best effort to complete all outstanding finalizations.

The Java runtime system will perform the finalization process automatically as needed, in a separate thread, if the runFinalization method is not invoked explicitly.

See also the method runFinalization (§20.18.13) of class System, which is the conventional and convenient means of invoking this method.

20.16.11 public void traceInstructions(boolean on)

Calling this method with argument true suggests that the Java Virtual Machine emit debugging information for every instruction it executes. The format of this information, and the file or other output stream to which it is emitted, depends on the host environment.

Calling this method with argument false suggests that the Java Virtual Machine cease emitting per-instruction debugging information.

20.16.12 public void traceMethodCalls(boolean on)

Calling this method with argument true suggests that the Java Virtual Machine emit debugging information for every method call it executes. The format of this information, and the file or other output stream to which it is emitted, depends on the host environment.

Calling this method with argument false suggests that the Java Virtual Machine cease emitting per-call debugging information.

20.16.13 public void loadLibrary(String libname)

First, if there is a security manager, its checkLink method (§20.17.17) is called with the libname as its argument.

A file containing native code is loaded from the local file system from a place where library files are conventionally obtained. The details of this process are implementation-dependent.

See also the method loadLibrary (§20.18.15) of class System, which is the conventional and convenient means of invoking this method. If native methods are to be used in the implementation of a class, a standard strategy is to put the native code in a library file (call it LibFile) and then to put a static initializer:

static { System.loadLibrary("LibFile"); }

within the class declaration. When the class is loaded and initialized (§12.4), the necessary native code implementation for the native methods will then be loaded as well.

20.16.14 public void load(String filename)

First, if there is a security manager, its checkLink method (§20.17.17) is called with the filename as its argument.

This is similar to the method loadLibrary (§20.16.13), but accepts a general file name as an argument rather than just a library name, allowing any file of native code to be loaded.

See also the method load (§20.18.14) of class System, which is the conventional and convenient means of invoking this method.

20.16.15 public InputStream
getLocalizedInputStream(InputStream in)

This method takes an InputStream (§22.3) and returns an InputStream equivalent to the argument in all respects except that it is localized: as data is read from the stream, it is automatically converted from the local format to Unicode. If the argument is already a localized stream, then it will be returned as the result.

20.16.16 public OutputStream
getLocalizedOutputStream(OutputStream out)

This method takes an OutputStream (§22.15) and returns an OutputStream equivalent to the argument in all respects except that it is localized: as data is written to the stream, it is automatically converted from Unicode to the local format. If the argument is already a localized stream, then it will be returned as the result.


20.17 The Class java.lang.SecurityManager

public abstract class SecurityManager {
    protected boolean inCheck;
    protected SecurityManager()

        throws SecurityException;
    protected Class[] getClassContext();
    protected int classDepth(String name);
    protected boolean inClass(String name);
    protected ClassLoader currentClassLoader();
    protected int classLoaderDepth();
    protected boolean inClassLoader();
    public boolean getInCheck();
    public void checkCreateClassLoader()

        throws SecurityException;
    public void checkAccess(Thread t)

        throws SecurityException;
    public void checkAccess(ThreadGroup g)

        throws SecurityException;
    public void checkExit(int status)

        throws SecurityException;
    public void checkExec(String cmd)

        throws SecurityException;
    public void checkPropertiesAccess()

        throws SecurityException;
    public void checkPropertyAccess(String key)

        throws SecurityException;
    public void checkLink(String libname)

        throws SecurityException;
    public void checkRead(int fd)

        throws SecurityException;
    public void checkRead(String file)

        throws SecurityException;
    public void checkWrite(int fd)

        throws SecurityException;
    public void checkWrite(String file)

        throws SecurityException;
    public void checkDelete(String file)

        throws SecurityException;
    public void checkConnect(String host, int port)

        throws SecurityException;
    public void checkListen(int port)

        throws SecurityException;
    public void checkAccept(String host, int port)

        throws SecurityException;
    public void checkSetFactory()

        throws SecurityException;
    public boolean checkTopLevelWindow()

        throws SecurityException;
    public void checkPackageAccess(String packageName)

        throws SecurityException;
    public void checkPackageDefinition(String packageName)

        throws SecurityException;
}

A running Java program may have a security manager, which is an instance of class SecurityManager. The current security manager is the one returned by the method invocation System.getSecurityManager() (§20.18.4).

The SecurityManager class contains a large number of methods whose names begin with "check". They are called by various methods throughout the Java libraries before those methods perform certain sensitive operations. The invocation of such a check method typically looks like this:

SecurityManager security = System.getSecurityManager();
if (security != null) {
    security.checkXXX(arguments);
}

The security manager is thereby given an opportunity to prevent completion of the operation by throwing an exception. The usual convention is that a security manager checking routine simply returns if the operation is permitted, or throws a SecurityException if the operation is not permitted. In one case, namely checkTopLevelWindow (§20.17.27), the checking routine must return a boolean value to indicate one of two levels of permission.

20.17.1 protected boolean inCheck = false;

By convention, this field should be assigned the value true whenever a security check is in progress. This matters when one of the checking routines needs to call outside code to do its work. Outside code can then use the method getInCheck (§20.17.9) to test the status of this flag.

20.17.2 protected SecurityManager()
throws SecurityException

This constructor checks to see whether a security manager has already been installed (§20.18.5); if so, creation of another security manager is not permitted, and so a SecurityException is thrown.

20.17.3 protected Class[] getClassContext()

This utility method for security managers scans the execution stack for the current thread and returns an array with one component for each stack frame. The component at position 0 corresponds to the top of the stack. If a component is a Class object, then the corresponding stack frame is for an invocation of a method of the class represented by that Class object.

20.17.4 protected int classDepth(String name)

This utility method for security managers searches the execution stack for the current thread to find the most recently invoked method whose execution has not yet completed and whose class has name as its fully qualified name. If such a method is found, its distance from the top of the stack is returned as a nonnegative integer; otherwise, -1 is returned.

20.17.5 protected boolean inClass(String name)

This utility method for security managers searches the execution stack for the current thread to find the most recently invoked method whose execution has not yet completed and whose class has name as its fully qualified name. If such a method is found, true is returned; otherwise, false is returned.

20.17.6 protected ClassLoader currentClassLoader()

This utility method for security managers searches the execution stack for the current thread to find the most recently invoked method whose execution has not yet completed and whose class was created by a class loader (§20.14). If such a method is found, a reference to the ClassLoader object for its class is returned; otherwise, null is returned.

20.17.7 protected int classLoaderDepth()

This utility method for security managers searches the execution stack for the current thread to find the most recently invoked method whose execution has not yet completed and whose class was created by a class loader (§20.14). If such a method is found, its distance from the top of the stack is returned as a nonnegative integer; otherwise, -1 is returned.

20.17.8 protected boolean inClassLoader()

This utility method for security managers searches the execution stack for the current thread to find the most recently invoked method whose execution has not yet completed and whose class was created by a class loader (§20.14). If such a method is found, true is returned; otherwise false is returned.

20.17.9 public boolean getInCheck()

The value of the inCheck field (§20.17.1) is returned.

20.17.10 public void checkCreateClassLoader()
throws SecurityException

The general contract of this method is that it should throw a SecurityException if creation of a class loader is not permitted.

This method is invoked for the current security manager (§20.18.4) by the constructor for class ClassLoader (§20.14.1).

The checkCreateClassLoader method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if a class loader creation operation is to be permitted with a security manager installed.

20.17.11 public void checkAccess(Thread t)
throws SecurityException

The general contract of this method is that it should throw a SecurityException if an operation that would modify the thread t is not permitted.

This method is invoked for the current security manager (§20.18.4) by method checkAccess (§20.20.12) of class Thread.

The checkAccess method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if a thread modification operation is to be permitted with a security manager installed.

20.17.12 public void checkAccess(ThreadGroup g)
throws SecurityException

The general contract of this method is that it should throw a SecurityException if an operation that would modify the thread group g is not permitted.

This method is invoked for the current security manager (§20.18.4) by method checkAccess (§20.21.4) of class ThreadGroup.

The checkAccess method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if a thread group modification operation is to be permitted with a security manager installed.

20.17.13 public void checkExit(int status)
throws SecurityException

The general contract of this method is that it should throw a SecurityException if an exit operation that would terminate the running Java Virtual Machine is not permitted.

This method is invoked for the current security manager (§20.18.4) by method exit (§20.16.2) of class Runtime.

The checkExit method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if the exit operation is to be permitted with a security manager installed.

20.17.14 public void checkExec(String cmd)
throws SecurityException

The general contract of this method is that it should throw a SecurityException if a command exec operation is not permitted. The argument cmd is the name of the command to be executed.

This method is invoked for the current security manager (§20.18.4) by method exec (§20.16.6) of class Runtime.

The checkExec method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if a command exec operation is to be permitted with a security manager installed.

20.17.15 public void checkPropertiesAccess()
throws SecurityException

The general contract of this method is that it should throw a SecurityException if getting or setting the system properties data structure is not permitted.

This method is invoked for the current security manager (§20.18.4) by the methods getProperties (§20.18.7) and setProperties (§20.18.8) of class System.

The checkPropertiesAccess method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if a properties access operation is to be permitted with a security manager installed.

20.17.16 public void checkPropertyAccess(String key)
throws SecurityException

The general contract of this method is that it should throw a SecurityException if getting the value of the system property named by the key is not permitted.

This method is invoked for the current security manager (§20.18.4) by the methods getProperty of one argument (§20.18.9) and getProperty of two arguments (§20.18.10) of class System.

The checkPropertyAccess method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if accessing the value of a system property is to be permitted with a security manager installed.

20.17.17 public void checkLink(String libname)
throws SecurityException

The general contract of this method is that it should throw a SecurityException if dynamic linking of the specified library code file is not permitted. The argument may be a simple library name or a complete file name.

This method is invoked for the current security manager (§20.18.4) by methods load (§20.16.14) and loadLibrary (§20.16.13) of class Runtime.

The checkLink method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if a dynamic code linking operation is to be permitted with a security manager installed.

20.17.18 public void checkRead(int fd)
throws SecurityException

The general contract of this method is that it should throw a SecurityException if creating an input stream using the specified file descriptor is not permitted.

This method is invoked for the current security manager (§20.18.4) by one constructor for java.io.FileInputStream (§22.4.3).

The checkRead method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if creating an input stream from an existing file descriptor is to be permitted with a security manager installed.

20.17.19 public void checkRead(String file)
throws SecurityException

The general contract of this method is that it should throw a SecurityException if reading the specified file or directory, or examining associated file-system information, or testing for its existence, is not permitted.

This method is invoked for the current security manager (§20.18.4) by two constructors for java.io.FileInputStream (§22.4.1, §22.4.2); by two constructors for java.io.RandomAccessFile (§22.23.1, §22.23.2); and by methods exists (§22.24.16), canRead (§22.24.17), isFile (§22.24.19), isDirectory (§22.24.20), lastModified (§22.24.21), length (§22.24.22), list with no arguments (§22.24.25), and list with one argument (§22.24.26) of the class java.io.File.

The checkRead method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if read access to a file is to be permitted with a security manager installed.

20.17.20 public void checkWrite(int fd)
throws SecurityException

The general contract of this method is that it should throw a SecurityException if creating an output stream using the specified file descriptor is not permitted.

This method is invoked for the current security manager (§20.18.4) by one constructor for java.io.FileOutputStream (§22.16.3).

The checkWrite method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if creating an output stream from an existing file descriptor is to be permitted with a security manager installed.

20.17.21 public void checkWrite(String file)
throws SecurityException

The general contract of this method is that it should throw a SecurityException if writing, modifying, creating (for output), or renaming the specified file or directory is not permitted.

This method is invoked for the current security manager (§20.18.4) by two constructors for java.io.FileOutputStream (§22.16.1, §22.16.2); by two constructors for java.io.RandomAccessFile (§22.23.1, §22.23.2); and by methods canWrite (§22.24.18), mkdir (§22.24.23), and renameTo (§22.24.27) of class java.io.File.

The checkWrite method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if write access to a file is to be permitted with a security manager installed.

20.17.22 public void checkDelete(String file)
throws SecurityException

The general contract of this method is that it should throw a SecurityException if deleting the specified file is not permitted.

This method is invoked for the current security manager (§20.18.4) by method delete (§22.24.28) of class java.io.File.

The checkDelete method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if a file deletion operation is to be permitted with a security manager installed.

20.17.23 public void checkConnect(String host, int port)
throws SecurityException

The general contract of this method is that it should throw a SecurityException if connecting to the indicated port of the indicated network host is not permitted.

This method is invoked for the current security manager (§20.18.4) by two constructors for class java.net.Socket, methods send and receive of class java.net.DatagramSocket, and methods getByName and getAllByName of class java.net.InetAddress. (These classes are not documented in this specification. See The Java Application Programming Interface.)

The checkConnect method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if a network connection is to be permitted with a security manager installed.

20.17.24 public void checkListen(int port)
throws SecurityException

The general contract of this method is that it should throw a SecurityException if listening to the specified local network port is not permitted.

This method is invoked for the current security manager (§20.18.4) by the constructor of one argument for class java.net.DatagramSocket and by the constructors for class java.net.ServerSocket. (These classes are not documented in this specification. See The Java Application Programming Interface.)

The checkListen method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if listening to a local network port is to be permitted with a security manager installed.

20.17.25 public void checkAccept(String host, int port)
throws SecurityException

The general contract of this method is that it should throw a SecurityException if accepting a connection from the indicated port of the indicated network host is not permitted.

This method is invoked for the current security manager (§20.18.4) by method accept of class java.net.ServerSocket. (This class is not documented in this specification. See The Java Application Programming Interface.)

The checkAccept method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if accepting a network connection is to be permitted with a security manager installed.

20.17.26 public void checkSetFactory()
throws SecurityException

The general contract of this method is that it should throw a SecurityException if installing a "factory" for a socket, server socket, URL, or URL connection is not permitted.

This method is invoked for the current security manager (§20.18.4) by:

    method setSocketFactory of class java.net.ServerSocket
    method setSocketImplFactory of class java.net.Socket
    method setURLStreamHandlerFactory of class java.net.URL
    method setContentHandlerFactory of class java.net.URLConnection

(These classes are not documented in this specification. See The Java Application Programming Interface.)

The checkSetFactory method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if a factory installation operation is to be permitted with a security manager installed.

20.17.27 public boolean checkTopLevelWindow()
throws SecurityException

The general contract of this method is that it should throw a SecurityException if creation of a top-level window is not permitted. If creation of a top-level window is permitted, then this method should return false if the window ought to bear a clear warning that it is a window for an executable applet. A returned value of true means that the security manager places no restriction on window creation.

This method is invoked for the current security manager (§20.18.4) by the constructors for class java.awt.Window. (This class is not documented in this specification. See The Java Application Programming Interface.)

The checkTopLevelWindow method defined by class SecurityManager always returns false. A subclass must override this method if a window creation operation is to be unrestricted or forbidden with a security manager installed.

20.17.28 public void checkPackageAccess(String packageName)
throws SecurityException

The general contract of this method is that it should throw a SecurityException if the current applet is not permitted to access the package named by the argument. This method is intended for use by Java-capable web browsers.

The checkPackageAccess method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if package access by an applet is to be permitted with a security manager installed.

20.17.29 public void checkPackageDefinition(String packageName)
throws SecurityException

The general contract of this method is that it should throw a SecurityException if the current applet is not permitted to define a class (or interface) in the package named by the argument. This method is intended for use by Java-capable web browsers.

The checkPackageAccess method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if class definition by an applet is to be permitted with a security manager installed.


20.18 The Class java.lang.System

The System class contains a number of useful class variables and class methods. It cannot be instantiated. Among the facilities provided by the System class are standard input, output, and error output streams; access to externally defined "properties"; a means of loading files and libraries; and a utility method for quickly copying a portion of an array.

public final class System {
    public static InputStream in;
    public static PrintStream out;
    public static PrintStream err;
    public static SecurityManager getSecurityManager();
    public static void setSecurityManager(SecurityManager s)
        throws SecurityException;
    public static long currentTimeMillis();
    public static Properties getProperties()
        throws SecurityException;
    public static void setProperties(Properties props)
        throws SecurityException;
    public static String getProperty(String key)
        throws SecurityException;
    public static String getProperty(String key, String default)
        throws SecurityException;
    public static void exit(int status) throws SecurityException;
    public static void gc();
    public static void runFinalization();
    public static void load(String filename)
        throws SecurityException, UnsatisfiedLinkError;
    public static void loadLibrary(String libname)
        throws SecurityException, UnsatisfiedLinkError;
    public static void arraycopy(Object src, int srcOffset,
            Object dst, int dstOffset, int length)

        throws NullPointerException,
            ArrayStoreException, IndexOutOfBoundsException;
}

20.18.1 public static InputStream in;

The initial value of this variable is a "standard" input stream, already open and ready to supply input data. Typically, this corresponds to keyboard input or another input source specified by the host environment or user. Note that this field is not final, so its value may be updated if necessary.

20.18.2 public static PrintStream out;

The initial value of this variable is a "standard" output stream, already open and ready to accept output data. Typically, this corresponds to display output or another output destination specified by the host environment or user. Note that this field is not final, so its value may be updated if necessary.

For simple Java applications, a typical way to write a line of output data is:

System.out.println(data)

See the println method of class PrintStream (§22.22).

20.18.3 public static PrintStream err;

The initial value of this variable is a "standard" error output stream, already open and ready to accept output data. Typically, this corresponds to display output or another output destination specified by the host environment or user. By convention, this output stream is used to display error messages or other information that should come to the immediate attention of a user even if the principal output stream, the value of the variable out, has been redirected to a file or other destination that is typically not continuously monitored. Note that this field is not final, so its value may be updated if necessary.

20.18.4 public static SecurityManager getSecurityManager()

If a security manager has already been established for the currently running Java system, a reference to that security manager is returned. Otherwise, null is returned.

20.18.5 public static void setSecurityManager(SecurityManager s)
throws SecurityException

If a security manager has already been established for the currently running Java system, a SecurityException is thrown. Otherwise, the argument is established as the current security manager. If the argument is null and no security manager has been established, then no action is taken and the method simply returns normally.

20.18.6 public static long currentTimeMillis()

Returns the difference, measured in milliseconds, between the current time and the standard base time known as "the epoch," 00:00:00 GMT on January 1, 1970. See the description of the class Date (§21.3) for a discussion of slight discrepancies that may arise between "computer time" and UTC (Coordinated Universal Time).

20.18.7 public static Properties getProperties()
throws SecurityException

First, if there is a security manager, its checkPropertiesAccess method (§20.17.15) is called with no arguments.

The current set of system properties for use by the getProperty method is returned as a Properties object (§21.6). If there is no current set of system properties, a set of system properties is first created and initialized. This set of system properties always includes values for the following keys:

Key							Description of associated value
java.version							Java version number
java.vendor							Java-vendor-specific string
java.vendor.url							Java vendor URL
java.home							Java installation directory
java.class.version							Java class format version number
java.class.path							Java classpath
os.name							Operating system name
os.arch							Operating system architecture
os.version							Operating system version
file.separator							File separator (/ on UNIX)
path.separator							Path separator (: on UNIX)
line.separator							Line separator (\n on UNIX)
user.name							User account name
user.home							User home directory
user.dir							User's current working directory

Note that even if the security manager does not permit the getProperties operation, it may choose to permit the getProperty operation (§20.18.9).

20.18.8 public static void setProperties(Properties props)
throws SecurityException

First, if there is a security manager, its checkPropertiesAccess method (§20.17.15) is called with no arguments.

The argument becomes the current set of system properties for use by the getProperty method. See the class Properties (§21.6). If the argument is null, then the current set of system properties is forgotten.

20.18.9 public static String getProperty(String key)
throws SecurityException

First, if there is a security manager, its checkPropertyAccess method (§20.17.16) is called with the key as its argument.

If there is no current set of system properties, a set of system properties is first created and initialized in the same manner as for the getProperties method (§20.18.7).

The system property value associated with the specified key string is returned. If there is no property with that key, then null is returned.

20.18.10 public static String getProperty(String key,
String default)
throws SecurityException

First, if there is a security manager, its checkPropertyAccess method (§20.17.16) is called with the key as its argument.

If there is no current set of system properties, a set of system properties is first created and initialized in the same manner as for the getProperties method (§20.18.7).

The system property value associated with the specified key string is returned. If there is no property with that key, then the argument default is returned.

20.18.11 public static void exit(int status)
throws SecurityException

This method terminates the currently running Java Virtual Machine. The argument serves as a status code; by convention, a nonzero status code indicates abnormal termination.

This method never returns normally.

The call System.exit(n) is effectively equivalent to the call:

Runtime.getRuntime().exit(n)

For a more complete description, see the exit method of class Runtime (§20.16.2).

20.18.12 public static void gc()

Calling this method suggests that the Java Virtual Machine expend effort toward recycling discarded objects in order to make the memory they currently occupy available for quick reuse. When control returns from the method call, the Java Virtual Machine has made a best effort to recycle all discarded objects.

The call System.gc() is effectively equivalent to the call:

Runtime.getRuntime().gc()

For a more complete description, see the gc method of class Runtime (§20.16.9).

20.18.13 public static void runFinalization()

Calling this method suggests that the Java Virtual Machine expend effort toward running the finalization methods of objects that have been found to be discarded but whose finalization methods have not yet been run. When control returns from the method call, the Java Virtual Machine has made a best effort to complete all outstanding finalizations.

The call System.runFinalization() is effectively equivalent to the call:

Runtime.getRuntime().runFinalization()

For a more complete description, see the runFinalization method of class Runtime (§20.16.10).

20.18.14 public static void load(String filename)
throws SecurityException, UnsatisfiedLinkError

This method loads a code file with the specified file name from the local file system.

The call System.load(name) is effectively equivalent to the call:

Runtime.getRuntime().load(name)

For a more complete description, see the load method of class Runtime (§20.16.14).

20.18.15 public static void loadLibrary(String libname)
throws SecurityException, UnsatisfiedLinkError

This method loads a library code file with the specified library name from the local file system.

The call System.loadLibrary(name) is effectively equivalent to the call

Runtime.getRuntime().loadLibrary(name)

For a more complete description, see the loadLibrary method of class Runtime (§20.16.13).

20.18.16 public static void arraycopy(Object src, int srcOffset,
Object dst, int dstOffset, int length)
throws NullPointerException, ArrayStoreException,
IndexOutOfBoundsException

A subsequence of array components is copied from the source array referenced by src to the destination array referenced by dst. The number of components copied is equal to the length argument. The components at the positions srcOffset through srcOffset+length-1 in the source array are copied into the positions dstOffset through dstOffset+length-1, respectively, of the destination array.

If the src and dst arguments refer to the same array object, then copying is performed as if the components of the source array at positions srcOffset through srcOffset+length-1 were first copied to a temporary array of length length and then the contents of the temporary array were copied into positions dstOffset through dstOffset+length-1 of the destination array.

If dst is null, then a NullPointerException is thrown.

If src is null, then a NullPointerException is thrown and the destination array is not modified.

Otherwise, if any of the following is true, then an ArrayStoreException is thrown and the destination is not modified:

  • The src argument refers to an object that is not an array.
  • The dst argument refers to an object that is not an array.
  • The src argument and dst argument refer to arrays whose component types are different primitive types.
  • The src argument refers to an array of primitive component type and the dst argument refers to an array of reference component type.
  • The src argument refers to an array of reference component type and the dst argument refers to an array of primitive component type.

Otherwise, if any of the following is true, an IndexOutOfBoundsException is thrown and the destination is not modified:

  • The srcOffset argument is negative.
  • The dstOffset argument is negative.
  • The length argument is negative.
  • srcOffset+length is greater than src.length, the length of the src array.
  • dstOffset+length is greater than dst.length, the length of the dst array.

Otherwise, if the actual value of any component of the source array from position srcOffset through srcOffset+length-1 cannot be converted to the component type of the destination array by assignment conversion, then an ArrayStoreException is thrown. In this case, let k be the smallest nonnegative integer less than length such that src[srcOffset+k] cannot be converted to the component type of the destination array. When the exception is thrown, the source array components from positions srcOffset through srcOffset+k-1 have been copied to destination array positions dstOffset through dstOffset+k-1 and no other positions of the destination array will have been modified. (Because of the restrictions already itemized, this paragraph effectively applies only to the situation where both arrays have component types that are reference types.)


20.19 The Interface java.lang.Runnable

The Runnable interface should be implemented by any class whose instances are intended to be executed by a new thread. All that is required of such a class is that it implement a method of no arguments called run.

public interface Runnable {
    public abstract void run();
}

20.19.1 public abstract void run()

The general contract of the method run is that it may take any action whatsoever.

If an object implementing interface Runnable is used to create a thread (§20.20), then starting the thread will (normally) lead to the invocation of the object's run method in that separately executing thread.


20.20 The Class java.lang.Thread

A thread is a single sequential flow of control. Thread objects allow multithreaded Java programming; a single Java Virtual Machine can execute many threads in an interleaved or concurrent manner.

In the method descriptions that follow, it is very important to distinguish among "the current thread" (the thread executing the method), "this Thread" (the object for which the method was invoked), and "this thread" (the thread that is represented by the Thread object for which the method was invoked).

public class Thread implements Runnable {
    public final static int MIN_PRIORITY = 1;
    public final static int MAX_PRIORITY = 10;
    public final static int NORM_PRIORITY = 5;
    public Thread();
    public Thread(String name);
    public Thread(Runnable target);
    public Thread(Runnable target, String name);
    public Thread(ThreadGroup group, String name)
        throws SecurityException, IllegalThreadStateException;
    public Thread(ThreadGroup group, Runnable target)
        throws SecurityException, IllegalThreadStateException;
    public Thread(ThreadGroup group, Runnable target,
            String name)
        throws SecurityException, IllegalThreadStateException;
    public String toString();
    public void checkAccess();
    public void run();
    public void start()
        throws IllegalThreadStateException;
    public final void stop()
        throws SecurityException;
    public final void stop(Throwable o)
        throws SecurityException;
    public final void suspend()
        throws SecurityException;
    public final void resume()
        throws SecurityException;
    public void destroy();
    public final boolean isAlive();
    public void interrupt();
    public static boolean interrupted();
    public boolean isInterrupted();
    public final String getName();
    public final void setName(String name)
        throws SecurityException;
    public final ThreadGroup getThreadGroup();
    public final int getPriority();
    public final void setPriority(int newPriority)
        throws SecurityException, IllegalArgumentException;
    public final boolean isDaemon();
    public final void setDaemon(boolean on)
        throws SecurityException;
    public int countStackFrames();
    public final void join()
        throws InterruptedException;
    public final void join(long millis)
        throws InterruptedException;
    public final void join(long millis, int nanos)
        throws InterruptedException;
    public void interrupt();
    public boolean isInterrupted();
    public static boolean interrupted();
    public static Thread currentThread();
    public static int activeCount();															// deprecated
    public static int enumerate(Thread tarray[]);															// deprecated
    public static void dumpStack();
    public static void yield();
    public static void sleep(long millis)

        throws InterruptedException;
    public static void sleep(long millis, int nanos)

        throws InterruptedException;
}

When a new Thread object is created, the thread it represents is not yet active. It is activated when some other thread calls the start method (§20.20.14) of the Thread object. This causes the thread represented by the Thread object to invoke the run method (§20.20.13) of the Thread object. The newly activated thread then remains alive until it stops because one of five things occurs:

  • The initial invocation of the run method by the newly activated thread completes normally through a normal return from the run method.
  • The initial invocation of the run method by the newly activated thread completes abruptly because an exception was thrown.
  • The thread invokes the stop method (§20.20.15) of the Thread object (and the security manager (§20.17.11) approves execution of the stop operation).
  • Some other thread invokes the stop method of the Thread object (and the security manager (§20.17.11) approves execution of the stop operation).
  • Some thread invokes the exit method (§20.16.2) of class Runtime (and the security manager (§20.17.13) approves execution of the exit operation); this stops every thread being run by the Java Virtual Machine that is running the thread that invokes the exit method.

As a thread dies, the notifyAll method (§20.1.10) is invoked for the Thread object that represents it; this fact is important for the proper operation of the join methods (§20.20.28, §20.20.29, §20.20.30). A thread is also removed from its thread group as it dies. Once a thread has been stopped, it is no longer alive and it cannot be restarted.

A thread that is alive can be suspended and resumed. A suspended thread is considered to be alive, but it performs no work, makes no progress, executes no virtual machine instructions. Resumption restores a thread to the state of active execution. A thread is suspended when it or another thread calls the suspend method (§20.20.17) of the Thread object that represents it (and the security manager (§20.17.11) approves execution of the suspend operation). A thread is resumed when another thread calls the resume method (§20.20.18) of the Thread object that represents it (and the security manager (§20.17.11) approves execution of the resume operation).

Every thread has a priority. When there is competition for processing resources, threads with higher priority are generally executed in preference to threads with lower priority. Such preference is not, however, a guarantee that the highest priority thread will always be running, and thread priorities cannot be used to implement mutual exclusion. When code running in some thread creates a new Thread object, the newly created thread has its priority initially set equal to the priority of the creating thread. But the priority of a thread T may be changed at any time if some thread invokes the setPriority method of the Thread object that represents T (and the security manager (§20.17.11) approves execution of the setPriority operation).

Each thread may or may not be marked as a daemon. When code running in some thread creates a new Thread object, the newly created thread is a daemon thread if and only if the creating thread is a daemon. But the daemonhood of a thread T may be changed before it is activated if some other thread invokes the setDaemon method of the Thread object that represents T (and the security manager (§20.17.11) approves execution of the setDaemon operation).

When a Java Virtual Machine starts up, there is usually a single non-daemon thread, which typically begins by invoking the method main of some designated class. The Java Virtual Machine continues to execute threads according to the thread execution model until all threads that are not daemon threads have stopped.

There are two ways to create a new thread of execution. One is to declare some class to be a subclass of Thread; this subclass should override the run method of class Thread. An instance of the subclass can then be created and started. For example, consider code for a thread whose job is to compute primes larger than a stated value:

class PrimeThread extends Thread {

    long minPrime;

    PrimeThread(long minPrime) {
        this.minPrime = minPrime;
    }

    public void run() {
         // compute primes larger than minPrime
        ...
    }

}

The following code would then create a thread and start it running:

PrimeThread p = new PrimeThread(143);
p.start();

The other way to create a thread is to is to declare some class to implement the Runnable interface, which also requires that the class implement the run method. An instance of the class can then be created, used to create a Thread, and started. The same example in this other style looks like this:

class PrimeRun implements Runnable {

    long minPrime;

    PrimeRun(long minPrime) {
        this.minPrime = minPrime;
    }

    public void run() {
         // compute primes larger than minPrime
        ...
    }

}

The following code would then create a thread and start it running:

PrimeRun p = new PrimeRun(143);
new Thread(p).start();

Every thread has a name, which is a String, for identification purposes. More than one thread may have the same name. If a name is not specified when a thread is created, a new name is generated for it.

Every thread that has not yet been stopped belongs to a thread group (§20.21). A thread can always create a new thread in its own thread group. To create a thread in some other thread group requires the approval of the checkAccess method (§20.21.4) of that thread group, which forwards the decision to the security manager (§20.17.11).

20.20.1 public final static int MIN_PRIORITY = 1;

The constant value of this field is 1, the smallest allowed priority for a thread.

20.20.2 public final static int MAX_PRIORITY = 10;

The constant value of this field is 10, the largest allowed priority value for a thread.

20.20.3 public final static int NORM_PRIORITY = 5;

The constant value of this field is 5, the normal priority for a thread that is not a daemon.

20.20.4 public Thread()

This constructor initializes a newly created Thread object so that it has no separate run object, has a newly generated name, and belongs to the same thread group as the thread that is creating the new thread.

This constructor has exactly the same effect as the explicit constructor call this(null, null, gname) (§20.20.10), where gname is a newly generated name. Automatically generated names are of the form "Thread-"+n, where n is an integer.

20.20.5 public Thread(String name)

This constructor initializes a newly created Thread object so that it has no separate run object, has the specified name as its name, and belongs to the same thread group as the thread that is creating the new thread.

This constructor has exactly the same effect as the explicit constructor call this(null, null, name) (§20.20.10).

20.20.6 public Thread(Runnable runObject)

This constructor initializes a newly created Thread object so that it has the given runObject as its separate run object, has a newly generated name, and belongs to the same thread group as the thread that is creating the new thread.

This constructor has exactly the same effect as the explicit constructor call this(null, runObject, gname) (§20.20.10) where gname is a newly generated name. Automatically generated names are of the form "Thread-"+n where n is an integer.

20.20.7 public Thread(Runnable runObject, String name)

This constructor initializes a newly created Thread object so that it has the given runObject as its separate run object, has the specified name as its name, and belongs to the same thread group as the thread that is creating the new thread.

This constructor has exactly the same effect as the explicit constructor call this(null, runObject, name) (§20.20.10).

20.20.8 public Thread(ThreadGroup group, String name)
throws SecurityException, IllegalThreadStateException

First, if group is not null, the checkAccess method (§20.21.4) of that thread group is called with no arguments.

This constructor initializes a newly created Thread object so that it has no separate run object, has the specified name as its name, and belongs to the thread group referred to by group (but if group is null, then the new thread will belong to the same thread group as the thread that is creating the new thread).

If group is a ThreadGroup that has been destroyed by method destroy (§20.21.11), then an IllegalThreadStateException is thrown.

This constructor has exactly the same effect as the explicit constructor call Thread(group, null, name) (§20.20.10).

20.20.9 public Thread(ThreadGroup group, Runnable runObject)
throws SecurityException, IllegalThreadStateException

First, if group is not null, the checkAccess method (§20.21.4) of that thread group is called with no arguments.

This constructor initializes a newly created Thread object so that it has the given runObject as its separate run object, has a newly generated name, and belongs to the thread group referred to by group (but if group is null, then the new thread will belong to the same thread group as the thread that is creating the new thread).

If group is a ThreadGroup that has been destroyed by method destroy (§20.21.11), then an IllegalThreadStateException is thrown.

This constructor has exactly the same effect as the explicit constructor call this(group, runObject, gname) (§20.20.10) where gname is a newly generated name. Automatically generated names are of the form "Thread-"+n where n is an integer.

20.20.10 public Thread(ThreadGroup group, Runnable target,
String name)
throws SecurityException, IllegalThreadStateException

First, if group is not null, the checkAccess method (§20.21.4) of that thread group is called with no arguments; this may result in a SecurityException being thrown.

This constructor initializes a newly created Thread object so that it has the given runObject as its separate run object, has the specified name as its name, and belongs to the thread group referred to by group (but if group is null, then the new thread will belong to the same thread group as the thread that is creating the new thread).

If group is a ThreadGroup that has been destroyed by method destroy (§20.21.11), then an IllegalThreadStateException is thrown.

The priority of the newly created thread is set equal to the priority of the creating thread-that is, the currently running thread. The method setPriority (§20.20.23) may be used to change the priority to a new value.

The newly created thread is initially marked as being a daemon thread if and only if the thread creating it is a daemon thread. The method setDaemon (§20.20.25) may be used to change whether or not a thread is a daemon.

20.20.11 public String toString()

The returned value is a concatenation of the following seven strings:

  • "Thread["
  • The current name of the thread (§20.20.19)
  • ","
  • The current priority of the thread (§20.20.22), as a decimal numeral
  • ","
  • The name (§20.21.5) of the thread group (§20.20.21) that contains this thread
  • "]"

All literal characters mentioned above are from the ACSII subset of Unicode.

Overrides the toString method of Object (§20.1.3).

20.20.12 public void checkAccess() throws SecurityException

If there is a security manager, its checkAccess method (§20.17.11) is called with this Thread object as its argument. This may result in a SecurityException being thrown in the current thread,.

This method is called by methods stop of no arguments (§20.20.15), stop of one argument (§20.20.16), suspend (§20.20.17), resume (§20.20.18), setName (§20.20.20), setPriority (§20.20.23), and setDaemon (§20.20.25).

20.20.13 public void run()

The general contract of this method is that it should perform the intended action of the thread.

The run method of class Thread simply calls the run method of the separate run object, if there is one; otherwise, it does nothing.

20.20.14 public void start()
throws IllegalThreadStateException

Invoking this method causes this thread to begin execution; this thread calls the run method of this Thread object. The result is that two threads are running concurrently: the current thread (which returns from the call to the start method) and the thread represented by this Thread object (which executes its run method).

20.20.15 public final void stop()
throws SecurityException

First, the checkAccess method (§20.20.12) of this Thread object is called with no arguments. This may result in throwing a SecurityException (in the current thread).

This thread is forced to complete abnormally whatever it was doing and to throw a ThreadDeath object as an exception. For this purpose, this thread is resumed if it had been suspended, and is awakened if it had been asleep.

It is permitted to stop a thread that has not yet been started. If the thread is eventually started, it will immediately terminate.

User code should not normally try to catch ThreadDeath unless some extraordinary cleanup operation is necessary (note that the process of throwing a ThreadDeath exception will cause finally clauses of try statements to be executed before the thread officially dies). If a catch clause does catch a ThreadDeath object, it is important to rethrow the object so that the thread will actually die. The top-level error handler that reacts to otherwise uncaught exceptions will not print a message or otherwise signal or notify the user if the uncaught exception is an instance of ThreadDeath.

20.20.16 public final void stop(Throwable thr)
throws SecurityException, NullPointerException

First, the checkAccess method (§20.20.12) of this Thread object is called with no arguments. This may result in throwing a SecurityException (in the current thread).

If the argument thr is null, then a NullPointerException is thrown (in the current thread).

This thread is forced to complete abnormally whatever it was doing and to throw the Throwable object thr as an exception. For this purpose, this thread is resumed if it had been suspended, and is awakened if it had been asleep. This is an unusual action to take; normally, the stop method that takes no arguments (§20.20.15) should be used.

It is permitted to stop a thread that has not yet been started. If the thread is eventually started, it will immediately terminate.

20.20.17 public final void suspend()
throws SecurityException

First, the checkAccess method (§20.20.12) of this Thread object is called with no arguments. This may result in throwing a SecurityException (in the current thread).

If this thread is alive (§20.20.26), it is suspended and makes no further progress unless and until it is resumed. It is permitted to suspend a thread that is already in a suspended state; it remains suspended. Suspensions are not tallied; even if a thread is suspended more than once, only one call to resume is required to resume it.

20.20.18 public final void resume()
throws SecurityException

First, the checkAccess method (§20.20.12) of this Thread object is called with no arguments. This may result in throwing a SecurityException (in the current thread).

If this thread is alive (§20.20.26) but suspended, it is resumed and is permitted to make progress in its execution. It is permitted to resume a thread that has never been suspended or has already been resumed; it continues to make progress in its execution. Resumptions are not tallied; even if a thread is resumed more than once, only one call to suspend is required to suspend it.

20.20.19 public final String getName()

The current name of this Thread object is returned as a String.

20.20.20 public final void setName(String name)
throws SecurityException

First, the checkAccess method (§20.20.12) of this Thread object is called with no arguments. This may result in throwing a SecurityException (in the current thread).

The name of this Thread object is changed to be equal to the argument name.

20.20.21 public final ThreadGroup getThreadGroup()

If this thread is alive, this method returns a reference to the ThreadGroup object that represents the thread group to which this thread belongs. If this thread has died (has been stopped), this method returns null.

20.20.22 public final int getPriority()

The current priority of this Thread object is returned.

20.20.23 public final void setPriority(int newPriority)
throws SecurityException, IllegalArgumentException

First, the checkAccess method (§20.20.12) of this Thread object is called with no arguments. This may result in throwing a SecurityException (in the current thread).

If the newPriority argument is less than MIN_PRIORITY (§20.20.1) or greater than MAX_PRIORITY (§20.20.2), then an IllegalArgumentException is thrown.

Otherwise, the priority of this Thread object is set to the smaller of the specified newPriority and the maximum permitted priority (§20.21.12) of the thread's thread group (§20.20.21).

20.20.24 public final boolean isDaemon()

The result is true if and only if this thread is marked as a daemon thread.

20.20.25 public final void setDaemon(boolean on)
throws SecurityException, IllegalThreadStateException

First, the checkAccess method (§20.20.12) of this Thread object is called with no arguments. This may result in throwing a SecurityException (in the current thread).

If this thread is alive, an IllegalThreadStateException is thrown. Otherwise, this thread is marked as being a daemon thread if the argument is true, and as not being a daemon thread if the argument is false.

20.20.26 public final boolean isAlive()

The result is true if and only if this thread is alive (it has been started and has not yet died).

20.20.27 public int countStackFrames()

This method returns the number of Java Virtual Machine stack frames currently active for this thread.

20.20.28 public final void join() throws InterruptedException

This method causes the current thread to wait (using the wait method (§20.1.6) of class Object) until this thread is no longer alive.

If the current thread is interrupted (§20.20.31) by another thread while it is waiting, then the wait is ended and an InterruptedException is thrown.

20.20.29 public final void join(long millis)
throws InterruptedException

This method causes the current thread to wait (using the wait method (§20.1.7) of class Object) until either this thread is no longer alive or a certain amount of real time has elapsed, more or less.

The amount of real time, measured in milliseconds, is given by millis. If millis is zero, however, then real time is not taken into consideration and this method simply waits until this thread is no longer alive.

If the current thread is interrupted (§20.20.31) by another thread while it is waiting, then the wait is ended and an InterruptedException is thrown.

20.20.30 public final void join(long millis, int nanos)
throws InterruptedException

This method causes the current thread to wait (using the wait method (§20.1.8) of class Object) until either this thread is no longer alive or a certain amount of real time has elapsed, more or less.

The amount of real time, measured in nanoseconds, is given by:

1000000*millis+nanos

In all other respects, this method does the same thing as the method join of one argument (§20.20.29). In particular, join(0, 0) means the same thing as join(0).

If the current thread is interrupted (§20.20.31) by another thread while it is waiting, then the wait is ended and an InterruptedException is thrown.

20.20.31 public void interrupt()

An interrupt request is posted for this thread. This thread does not necessarily react immediately to the interrupt, however. If this thread is waiting, it is awakened and it then throws an InterruptedException.

[This method is scheduled for introduction in Java version 1.1.]

20.20.32 public boolean isInterrupted()

The result is true if and only if an interrupt request has been posted for this thread.

[This method is scheduled for introduction in Java version 1.1.]

20.20.33 public static boolean interrupted()

The result is true if and only if an interrupt request has been posted for the current thread.

[This method is scheduled for introduction in Java version 1.1.]

20.20.34 public static Thread currentThread()

The Thread object that represents the current thread is returned.

20.20.35 public static int activeCount()

This method returns the number of active threads in the thread group to which the current thread belongs. This count includes threads in subgroups of that thread group. This is the same as the value of the expression:

Threads.currentThread().getThreadGroup().activeCount()

[This method is deprecated for use in new code after Java version 1.1 becomes available. Instead, an expression equivalent to:

Threads.currentThread().getThreadGroup().allThreadsCount()

should be used. See the method allThreadsCount of class ThreadGroup.]

20.20.36 public static int enumerate(Thread tarray[])

The active threads in the thread group to which the current thread belongs, including threads in subgroups of that thread group, are enumerated and their Thread objects are put into the array tarray. The number of threads actually put into the array is returned. Call this value n; then the threads have been put into elements 0 through n-1 of tarray. If the number of threads exceeds the length of tarray, then some of the threads, tarray.length of them, are chosen arbitrarily and used to fill the array tarray.

[This method is deprecated for use in new code after Java version 1.1 becomes available. Instead, an expression equivalent to:

Threads.currentThread().getThreadGroup().allThreads()

should be used. See the method allThreads of class ThreadGroup.]

20.20.37 public static void dumpStack()

This is a utility method that makes it easy to print a stack dump for the current thread. It is equivalent in effect to:

new Exception("Stack trace").printStackTrace()

See the printStackTrace method (§20.22.6) of class Throwable.

20.20.38 public static void yield()

This method causes the current thread to yield, allowing the thread scheduler to choose another runnable thread for execution.

20.20.39 public static void sleep(long millis)
throws InterruptedException

This method causes the current thread to yield and not to be scheduled for further execution until a certain amount of real time has elapsed, more or less.

The amount of real time, measured in milliseconds, is given by millis.

If the current thread is interrupted (§20.20.31) by another thread while it is waiting, then the sleep is ended and an InterruptedException is thrown.

20.20.40 public static void sleep(long millis, int nanos)
throws InterruptedException

This method causes the current thread to yield and not to be scheduled for further execution until a certain amount of real time has elapsed, more or less.

The amount of real time, measured in nanoseconds, is given by:

1000000*millis+nanos

In all other respects, this method does the same thing as the method sleep of one argument (§20.20.39). In particular, sleep(0, 0) means the same thing as sleep(0).

If the current thread is interrupted (§20.20.31) by another thread while it is waiting, then the sleep is ended and an InterruptedException is thrown.


20.21 The Class java.lang.ThreadGroup

A thread group is a set of threads and thread groups. Every thread belongs to exactly one thread group, and every thread group but one (called the "system thread group") belongs to some other thread group. Thus thread groups form a tree with the system thread group at the root.

Thread groups provide a way to manage threads and to impose security boundaries; for example, a thread may always create a new thread within its own thread group, but creating a thread in another thread group requires the approval of the security manager (§20.17), as does the creation of a new thread group.

public class ThreadGroup {
    public ThreadGroup(String name)
        throws SecurityException;
    public ThreadGroup(ThreadGroup parent, String name)
        throws NullPointerExpression, SecurityException,
            IllegalThreadStateException;
    public String toString();
    public final void checkAccess();
    public final String getName();
    public final ThreadGroup getParent();
    public final boolean parentOf(ThreadGroup g);
    public final void stop()
        throws SecurityException;
    public final void suspend()
        throws SecurityException;
    public final void resume()
        throws SecurityException;
    public final void destroy()
        throws SecurityException, IllegalThreadStateException;
    public final int getMaxPriority();
    public final void setMaxPriority(int newMaxPriority)
        throws SecurityException, IllegalArgumentException;
    public final boolean isDaemon();
    public final void setDaemon(boolean daemon)
        throws SecurityException;
    public 	int threadsCount();
    public int allThreadsCount()		;
    public int groupsCount();
    public int allGroupsCount();
    public Thread[] threads();
    public ThreadGroup[] groups();
    public 	Thread[] allThreads();
    public 	ThreadGroup[] allGroups();
    public int activeCount();															// deprecated
    public int activeGroupCount();															// deprecated
    public int enumerate(Thread list[]);															// deprecated
    public int enumerate(Thread list[],															// deprecated
            boolean recurse);
    public int enumerate(ThreadGroup list[]);															// deprecated
    public int enumerate(ThreadGroup list[],															// deprecated
            boolean recurse);
    public void list();
    public void uncaughtException(Thread t, Throwable e);
}

Every thread group has a maximum priority. The priority of a thread cannot be set (§20.20.23) higher than the maximum priority of its thread group.

Each thread group may or may not be marked as a daemon. When a new ThreadGroup object is created, the newly created thread group is marked as a daemon thread group if and only if the thread group to which it belongs is currently a daemon thread group. But the daemonhood of a thread group G may be changed at any time by calling the setDaemon method of the ThreadGroup object that represents G (provided that the security manager (§20.17.12) approves execution of the setDaemon operation).

Every thread group has a name, which is a String, for identification purposes. More than one thread group may have the same name.

Creation of a thread group requires the approval of the checkAccess method (§20.21.4) of its proposed parent thread group, which forwards the decision to the security manager (§20.17.11).

20.21.1 public ThreadGroup(String name)
throws SecurityException

First, the checkAccess method (§20.21.4) of the thread group to which the current thread belongs is called with no arguments.

This constructor initializes a newly created ThreadGroup object so that it has the specified name as its name and belongs to the same thread group as the thread that is creating the new thread group.

This constructor has exactly the same effect as the explicit constructor call this(Thread.currentThread().getThreadGroup(), name) (§20.21.2).

20.21.2 public ThreadGroup(ThreadGroup parent, String name)
throws NullPointerExpression, SecurityException, IllegalThreadStateException

First, the checkAccess method (§20.21.4) of the parent thread group is called with no arguments.

If parent is null, then a NullPointerExpression is thrown. If parent is a ThreadGroup that has been destroyed by method destroy (§20.21.11), then an IllegalThreadStateException is thrown.

This constructor initializes a newly created ThreadGroup object so that it has the specified name as its name and belongs to the thread group represented by parent.

The maximum priority for the newly created thread group is set equal to the maximum priority of parent. The method setMaxPriority (§20.21.13) may be used to change the maximum priority to a lower value.

The newly created thread group is initially marked as being a daemon thread group if and only parent is a daemon thread group. The method setDaemon (§20.21.15) may be used to change whether or not a thread group is a daemon thread group.

20.21.3 public String toString()

The returned value is a concatenation of the following six strings:

  • The name of the class of this thread group object
  • "[name="
  • The name (§20.21.5) of this thread group
  • ",maxpri="
  • The current maximum priority (§20.21.12) for this thread group, as a decimal numeral
  • "]"

All literal characters mentioned above are from the ASCII subset of Unicode.

Overrides the toString method of Object (§20.1.3).

20.21.4 public final void checkAccess()

If there is a security manager, its checkAccess method (§20.17.12) is called with this ThreadGroup object as its argument. This may result in throwing, in the current thread, a SecurityException.

This method is called by methods stop (§20.21.8), suspend (§20.21.9), resume (§20.21.10), destroy (§20.21.11), setMaxPriority (§20.21.13), and setDaemon (§20.21.15).

20.21.5 public final String getName()

The current name of this ThreadGroup object is returned as a String.

20.21.6 public final ThreadGroup getParent()

This method returns the ThreadGroup object that represents the thread group to which this thread group belongs. If this thread group is the system thread group, which is at the root of the thread group hierarchy, then null is returned.

20.21.7 public final boolean parentOf(ThreadGroup g)

This method returns true if and only if either this thread group is g or this method is true when applied to the parent of g. In other words, this method says whether this thread group is an ancestor of g or perhaps g itself.

(This method arguably is misnamed; a more accurate, if clumsy and abstruse, name would be parentOfReflexiveTransitiveClosure.)

20.21.8 public final void stop() throws SecurityException

First, the checkAccess method (§20.21.4) of this ThreadGroup object is called with no arguments. This may result in a SecurityException being thrown (in the current thread).

Every thread in this thread group or any of its subgroups is stopped. More precisely, the method stop is called for every ThreadGroup and every Thread (§20.20.15) that belongs to this ThreadGroup.

20.21.9 public final void suspend() throws SecurityException

First, the checkAccess method (§20.21.4) of this ThreadGroup object is called with no arguments. This may result in a SecurityException being thrown (in the current thread).

Every thread in this thread group or any of its subgroups is suspended. More precisely, the method suspend is called for every ThreadGroup and every Thread (§20.20.17) that belongs to this ThreadGroup.

20.21.10 public final void resume() throws SecurityException

First, the checkAccess method (§20.21.4) of this ThreadGroup object is called with no arguments. This may result in a SecurityException being thrown (in the current thread).

Every thread in this thread group or any of its subgroups is resumed. More precisely, the method resume is called for every ThreadGroup and every Thread (§20.20.18) that belongs to this ThreadGroup.

20.21.11 public final void destroy()
throws SecurityException, IllegalThreadStateException

First, the checkAccess method (§20.21.4) of this ThreadGroup object is called with no arguments. This may result in a SecurityException being thrown (in the current thread).

This thread group is destroyed. If it has already been destroyed, or if any threads belong to it directly, then an IllegalThreadStateException is thrown. Otherwise, this method is called recursively for every thread group that belongs to this thread group, and this thread group is removed from its parent thread group.

A thread group that is currently marked as a daemon thread group is destroyed automatically if both of the following conditions are true:

  • A thread or thread group has just been removed from it (because the thread has died or the thread group has been destroyed).
  • The thread group now contains no more threads or thread groups.

20.21.12 public final int getMaxPriority()

The current maximum priority of this ThreadGroup object is returned.

20.21.13 public final void setMaxPriority(int newMaxPriority)
throws SecurityException, IllegalArgumentException

First, the checkAccess method (§20.21.4) of this ThreadGroup object is called with no arguments. This may result in a SecurityException being thrown (in the current thread).

If the newMaxPriority argument is less than MIN_PRIORITY (§20.20.1) or greater than MAX_PRIORITY (§20.20.2), then an IllegalArgumentException is thrown.

Otherwise, the priority of this ThreadGroup object is set to the smaller of the specified newMaxPriority and the maximum permitted priority (§20.21.12) of the parent of this thread group (§20.21.12). (If this thread group is the system thread group, which has no parent, then its maximum priority is simply set to newMaxPriority.) Then this method is called recursively, with newMaxPriority as its argument, for every thread group that belongs to this thread group.

20.21.14 public final boolean isDaemon()

The result is true if and only if this thread group is currently marked as a daemon thread group.

20.21.15 public final void setDaemon(boolean daemon)
throws SecurityException

First, the checkAccess method (§20.21.4) of this ThreadGroup object is called with no arguments. This may result in a SecurityException being thrown (in the current thread).

This thread group is marked as being a daemon thread group if the argument is true, and as not being a daemon thread group if the argument is false.

20.21.16 public int threadsCount()

This method returns the number of threads that directly belong to this thread group.

20.21.17 public int allThreadsCount()

This method returns the number of threads that belong to this thread group or to any of its subgroups.

20.21.18 public int groupsCount()

This method returns the number of thread groups that directly belong to this thread group.

20.21.19 public int allGroupsCount()

This method returns the number of thread groups that belong to this thread group or to any of its subgroups.

20.21.20 public Thread[] threads()

This method returns a newly created array containing the Thread objects for all threads that directly belong to this thread group.

20.21.21 public Thread[] allThreads()

This method returns a newly created array containing the Thread objects for all threads that belong to this thread group or to any of its subgroups.

20.21.22 public ThreadGroup[] groups()

This method returns a newly created array containing the ThreadGroup objects for all thread groups that directly belong to this thread group.

20.21.23 public ThreadGroup[] allGroups()

This method returns a newly created array containing the ThreadGroup objects for all thread groups that belong to this thread group or to any of its subgroups.

20.21.24 public int activeCount()

[This method is deprecated for use in new code after Java version 1.1 becomes available. Use the equivalent method allThreadsCount instead.]

20.21.25 public int activeGroupCount()

[This method is deprecated for use in new code after Java version 1.1 becomes available. Use the equivalent method allGroupsCount instead.]

20.21.26 public int enumerate(Thread list[])

[This method is deprecated for use in new code after Java version 1.1 becomes available. Use the method allThreads instead.]

20.21.27 public int enumerate(Thread list[], boolean recurse)

[This method is deprecated for use in new code after Java version 1.1 becomes available. Use the method threads or allThreads instead.]

20.21.28 public int enumerate(ThreadGroup list[])

[This method is deprecated for use in new code after Java version 1.1 becomes available. Use the method allGroups instead.]

20.21.29 public int enumerate(ThreadGroup list[], boolean recurse)

[This method is deprecated for use in new code after Java version 1.1 becomes available. Use the method groups or allGroups instead.]

20.21.30 public void list()

This method prints a detailed description of this thread group to the output stream System.out (§20.18.2). It is intended as a convenient utility for debugging.

The output is a series of lines; each line contains some space characters (for indentation) followed by the toString representation of one thread (§20.20.11) or one thread group (§20.21.3).

The first line gives the toString representation for this thread group, with no indentation spaces. Following lines are then generated by a recursive rule: whenever a line is printed for a thread group G with n leading spaces, it is immediately followed by one line for each thread that directly belongs to G, with [image] spaces of indentation; then one line is printed for each thread group that directly belongs to G, with [image] spaces of indentation, using the recursive case.

20.21.31 public void uncaughtException(Thread t, Throwable e)

The general contract of uncaughtException is that it is called whenever a thread that belongs directly to this thread group dies because an exception was thrown in that thread and not caught. The arguments are the Thread object for the thread in question and the Throwable object that was thrown. The uncaughtException method may then take any appropriate action.

The call to uncaughtException is performed by the thread that failed to catch the exception, so t is the current thread. The call to uncaughtException is the last action of the thread before it dies. If the call to uncaughtException itself results in an (uncaught) exception, this fact is ignored and the thread merely goes on to die.

The method uncaughtException defined by class ThreadGroup takes one of two actions. If this thread group has a parent thread group, then this method is invoked for that parent thread group, with the same arguments. If this thread group is the system thread group (which has no parent), then if the exception e is not an instance of ThreadDeath (§20.22), a stack trace (§20.22.6) for e is printed on the error output stream that is the value of the field System.err (§20.18.3).

Subclasses of ThreadGroup may override the uncaughtException method.


20.22 Classes for Exceptions and Errors

The throw statement (§14.16) is permitted to throw only instances of the class Throwable and its subclasses. Instances of two subclasses, Error and Exception, are conventionally used to indicate that exceptional situations have occurred. Typically, these instances are freshly created in the context of the exceptional situation so as to include relevant information (such as stack trace data).

The following list shows the hierarchical relationships of all the exception classes predefined in package java.lang by the Java language:

Throwable
    Error
        LinkageError
            ClassCircularityError
            ClassFormatError
            ExceptionInInitializerError

            IncompatibleClassChangeError
                AbstractMethodError
                IllegalAccessError
                InstantiationError
                NoSuchFieldError
                NoSuchMethodError
            NoClassDefFoundError
            UnsatisfiedLinkError
            VerifyError
        VirtualMachineError
            InternalError
            OutOfMemoryError
            StackOverflowError
            UnknownError
        ThreadDeath
    Exception
        ClassNotFoundException
        CloneNotSupportedException
        IllegalAccessException
        InstantiationException
        InterruptedException
        RuntimeException
            ArithmeticException
            ArrayStoreException
            ClassCastException
            IllegalArgumentException
                IllegalThreadStateException
                NumberFormatException
            IllegalMonitorStateException
            IndexOutOfBoundsException
            NegativeArraySizeException
            NullPointerException
            SecurityException

By convention, class Throwable and all its subclasses have two constructors, one that takes no arguments and one that takes a String argument that can be used to produce an error message. This is true of all the classes shown above, with one exception: ExceptionInInitializerError. These predefined classes otherwise have no new content; they merely inherit methods from class Throwable.

public class Throwable {
    public Throwable();
    public Throwable(String message);
    public String toString();
    public String getMessage();
    public Throwable fillInStackTrace();
    public void printStackTrace();
    public void printStackTrace(java.io.PrintStream s);
}

20.22.1 public Throwable()

This constructor initializes a newly created Throwable object with null as its error message string. Also, the method fillInStackTrace (§20.22.5) is called for this object.

20.22.2 public Throwable(String message)

This constructor initializes a newly created Throwable object by saving a reference to the error message string s for later retrieval by the getMessage method (§20.22.3). Also, the method fillInStackTrace (§20.22.5) is called for this object.

20.22.3 public String getMessage()

If this Throwable object was created with an error message string (§20.22.2), then a reference to that string is returned.

If this Throwable object was created with no error message string (§20.22.1), then null is returned.

20.22.4 public String toString()

If this Throwable object was created with an error message string (§20.22.2), then the result is the concatenation of three strings:

  • The name of the actual class of this object
  • ": " (a colon and a space)
  • The result of the getMessage method (§20.22.3) for this object

If this Throwable object was created with no error message string (§20.22.1), then the name of the actual class of this object is returned.

20.22.5 public Throwable fillInStackTrace()

This method records within this Throwable object information about the current state of the stack frames for the current thread.

20.22.6 public void printStackTrace()

This method prints a stack trace for this Throwable object on the error output stream that is the value of the field System.err (§20.18.3). The first line of output contains the result of the toString method (§20.22.4) for this object. Remaining lines represent data previously recorded by the method fillInStackTrace (§20.22.5). The format of this information depends on the implementation, but the following example may be regarded as typical:

java.lang.NullPointerException
    at MyClass.mash(MyClass.java:9)
    at MyClass.crunch(MyClass.java:6)
    at MyClass.main(MyClass.java:3)

This example was produced by running the program:

class MyClass {

    public static void main(String[] argv) {
        crunch(null);
    }

    static void crunch(int[] a) {
        mash(a);
    }

    static void mash(int[] b) {
        System.out.println(b[0]);
    }

}


20.23 The Class java.lang.ExceptionInInitializerError

An ExceptionInInitializerError is thrown to indicate that an exception occurred during evaluation of a static initializer or the initializer for a static variable (§12.4.2).

public class ExceptionInInitializerError
        extends RuntimeException {
    public ExceptionInInitializerError();
    public ExceptionInInitializerError(String s);
    public ExceptionInInitializerError(Throwable thrown);
    public Throwable getException();
}

20.23.1 public ExceptionInInitializerError()

This constructor initializes a newly created ExceptionInInitializerError with null as its error message string and with a no saved throwable object.

20.23.2 public ExceptionInInitializerError(String s)

This constructor initializes a newly created ExceptionInInitializerError by saving a reference to the error message string s for later retrieval by the getMessage method (§20.22.3). There is no saved throwable object.

20.23.3 public ExceptionInInitializerError(Throwable thrown)

This constructor initializes a newly created ExceptionInInitializerError by saving a reference to the Throwable object thrown for later retrieval by the getException method (§20.22.3). The error message string is set to null.

20.23.4 public Throwable getException(Throwable thrown)

The saved throwable object of this ExceptionInInitializerError is returned; null is returned if this ExceptionInInitializerError has no saved throwable object.


 21. The Package java.util

CHAPTER 21

The Package java.util

The java.util package contains various utility classes and interfaces.

Notable among these utilities is the Enumeration interface. An object that implements this interface will generate a series of items, delivering them on demand, one by one. Container classes such as Dictionary and Vector provide one or more methods that return an Enumeration.

A BitSet contains an indexed collection of bits that may be used to represent a set of nonnegative integers.

The class Date provides a convenient way to represent and manipulate time and date information. Dates may be constructed from a year, month, day of month, hour, minute, and second, and those six components, as well as the day of the week, may be extracted from a date. Time zones and daylight saving time are properly accounted for.

The abstract class Dictionary represents a collection of key-value pairs and allows a value to be fetched given the key. The class Hashtable is one concrete implementation of Dictionary. The class Properties extends Hashtable by allowing one table to provide default values for another and by providing standard means for reading entries from files and writing entries to files.

The class Observable provides a mechanism for notifying other objects, called "observers," whenever an Observable object is changed. An observer object may be any object that implements the Observer interface. (This notification mechanism is distinct from that provided by the wait and notify methods of class Object (§20.1) and is not connected with the thread scheduling mechanism.)

The class Random provides an extensive set of methods for pseudorandomly generating numeric values of various primitive types and with various distributions. Each instance of class Random is an independent pseudorandom generator.

A StringTokenizer provides an easy way to divide strings into tokens. The set of characters that delimit tokens is programmable. The tokenizing method is much simpler than the one used by the class java.io.StreamTokenizer. For example, a StringTokenizer does not distinguish among identifiers, numbers, and quoted strings; moreover, it does not recognize and skip comments.

The classes Vector and Stack are simple container classes that provide extensions to the capabilities of Java arrays. A Vector, unlike a Java array, can change its size, and many convenient methods are provided for adding, removing, and searching for items. A Stack is a Vector with additional operations such as push and pop.

The hierarchy of classes defined in package java.util is as follows. (Classes whose names are shown here in boldface are in package java.util; the others are in package java.lang and are shown here to clarify subclass relationships.)

Object	§20.1
    interface Enumeration	§21.1
    BitSet	§21.2
    Date	§21.3
    Dictionary	§21.4
        Hashtable	§21.5
            Properties	§21.6
    Observable	§21.7
    interface Observer	§21.8
    Random	§21.9
    StringTokenizer	§21.10
    Vector	§21.11
        Stack	§21.12
    Throwable	§20.22
        Exception
            RuntimeException
                EmptyStackException	§21.13
                NoSuchElementException	§21.14


21.1 The Interface java.util.Enumeration

An object that implements the Enumeration interface will generate a series of elements, one at a time. Successive calls to the nextElement method will return successive elements of the series.

public interface Enumeration {
    public boolean hasMoreElements();
    public Object nextElement() throws NoSuchElementException;
}

21.1.1 public boolean hasMoreElements()

The result is true if and only if this enumeration object has at least one more element to provide.

21.1.2 public Object nextElement()
throws NoSuchElementException

If this enumeration object has at least one more element to provide, such an element is returned; otherwise, a NoSuchElementException is thrown.

As an example, the following code prints every key in the hashtable ht and its length. The method keys returns an enumeration that will deliver all the keys, and we suppose that the keys are, in this case, known to be strings:

Enumeration e = ht.keys();
while (e.hasMoreElements()) {
    String key = (String)e.nextElement();
    System.out.println(key + " " + key.length());
}


21.2 The Class java.util.BitSet

'T is an old maxim in the schools,
That flattery's the food of fools;
Yet now and then your men of wit
Will condescend to take a bit.
—Jonathan Swift, Cadenus and Vanessa

A BitSet object is a set of bits that grows as needed. The bits of a BitSet are indexed by nonnegative integers. Each bit can be individually examined, set, or cleared. One BitSet may be used to modify the contents of another BitSet through logical AND, logical inclusive OR, and logical exclusive OR operations.

public final class BitSet implements Cloneable {
    public BitSet();
    public BitSet(int nbits);
    public String toString();
    public boolean equals(Object obj)
    public int hashCode();
    public Object clone();
    public boolean get(int bitIndex);
    public void set(int bitIndex);
    public void clear(int bitIndex);
    public void and(BitSet set);
    public void or(BitSet set);
    public void xor(BitSet set);
    public int size();
}

21.2.1 public BitSet()

This constructor initializes a newly created BitSet so that all bits are clear.

21.2.2 public BitSet(int nbits)

This constructor initializes a newly created BitSet so that all bits are clear. Enough space is reserved to explicitly represent bits with indices in the range 0 through nbits-1.

21.2.3 public String toString()

For every index for which this BitSet contains a bit in the set state, the decimal representation of that index is included in the result. Such indices are listed in order from lowest to highest, separated by ", " (a comma and a space) and surrounded by braces, resulting in the usual mathematical notation for a set of integers.

Overrides the toString method of Object (§20.1.2).

Example:

BitSet drPepper = new BitSet();

Now drPepper.toString() returns "{}".

drPepper.set(2);

Now drPepper.toString() returns "{2}".

drPepper.set(4);
drPepper.set(10);

Now drPepper.toString() returns "{2, 4, 10}".

21.2.4 public boolean equals(Object obj)

The result is true if and only if the argument is not null and is a BitSet object such that, for every nonnegative int index k:

((BitSet)obj).get(k) == this.get(k)

Overrides the equals method of Object (§20.1.3).

21.2.5 public int hashCode()

The hash code depends only on which bits have been set within this BitSet. The algorithm used to compute it may be described as follows.

Suppose the bits in the BitSet were to be stored in an array of long integers called, say, bits, in such a manner that bit k is set in the BitSet (for nonnegative values of k) if and only if the expression:

((k>>6) < bits.length) &&
                ((bits[k>>6] & (1L << (bit & 0x3F))) != 0)

is true. Then the following definition of the hashCode method would be a correct implementation of the actual algorithm:

public synchronized int hashCode() {
    long h = 1234;
    for (int i = bits.length; --i >= 0; ) {
        h ^= bits[i] * (i + 1);
    }
    return (int)((h >> 32) ^ h);
}

Note that the hash code value changes if the set of bits is altered.

Overrides the hashCode method of Object (§20.1.4).

21.2.6 public Object clone()

Cloning this BitSet produces a new BitSet that is equal to it.

Overrides the clone method of Object (§20.1.5).

21.2.7 public boolean get(int bit)

The result is true if the bit with index bit is currently set in this BitSet; otherwise, the result is false.

If bit is negative, an IndexOutOfBoundsException is thrown.

21.2.8 public void set(int bit)

The bit with index bit in this BitSet is changed to the "set" (true) state.

If bit is negative, an IndexOutOfBoundsException is thrown.

If bit is not smaller than the value that would be returned by the size method (§21.2.13), then the size of this BitSet is increased to be larger than bit.

21.2.9 public void clear(int bit)

The bit with index bit in this BitSet is changed to the "clear" (false) state.

If bit is negative, an IndexOutOfBoundsException is thrown.

If bit is not smaller than the value that would be returned by the size method (§21.2.13), then the size of this BitSet is increased to be larger than bit.

21.2.10 public void and(BitSet set)

This BitSet may be modified by clearing some of its bits. For every nonnegative int index k, bit k of this BitSet is cleared if bit k of set is clear.

21.2.11 public void or(BitSet set)

This BitSet may be modified by setting some of its bits. For every nonnegative int index k, bit k of this BitSet is set if bit k of set is set.

21.2.12 public void xor(BitSet set)

This BitSet may be modified by inverting some of its bits. For every nonnegative int index k, bit k of this BitSet is inverted if bit k of set is set.

21.2.13 public int size()

This method returns the number of bits of space actually in use by this BitSet to represent bit values.

At Mooneen he had leaped a place
So perilous that half the astonished meet
Had shut their eyes, and where was it
He rode a race without a bit?
—William Butler Yeats, In Memory of Major Robert Gregory (1919)


21.3 The Class java.util.Date

The class Date provides a system-independent abstraction of dates and times, to a millisecond precision. Dates may be constructed from a year, month, date (day of month), hour, minute, and second; those six components and the day of the week, may be extracted; and dates may be compared and converted to a readable string.

public class Date {
    public Date();
    public Date(long time);
    public Date(int year, int month, int date);
    public Date(int year, int month, int date,
            int hours, int minutes);
    public Date(int year, int month, int date,
            int hours, int minutes, int seconds);
    public Date(String s) throws IllegalArgumentException;
    public String toString();
    public boolean equals(Object obj);
    public int hashCode();
    public int getYear();
    public void setYear(int year);
    public int getMonth();
    public void setMonth(int month);
    public int getDate();
    public void setDate(int date);
    public int getDay();
    public int getHours();
    public void setHours(int hours);
    public int getMinutes();
    public void setMinutes(int minutes);
    public int getSeconds();
    public void setSeconds(int seconds);
    public long getTime();
    public void setTime(long time);
    public boolean before(Date when);
    public boolean after(Date when);
    public String toLocaleString();
    public String toGMTString();
    public int getTimezoneOffset();
    public static long UTC(int year, int month, int date,
            int hours, int minutes, int seconds);
    public static long parse(String s)
        throws IllegalArgumentException;
}

Examples:

  • To print today's date: System.out.println("today = " + new Date());
  • To find out the day of the week for some particular date, for example, January 16, 1963: new Date(63, 0, 16).getDay()

While the Date class is intended to reflect UTC (Coordinated Universal Time), it may not do so exactly, depending on the host environment of the Java system. Nearly all modern operating systems assume that 1 day = [image] = 86400 seconds in all cases. In UTC, however, about once every year or two there is an extra second, called a "leap second." The leap second is always added as the last second of the day, and nearly always on December 31 or June 30. For example, the last minute of the year 1995 was 61 seconds long, thanks to an added leap second.

Most computer clocks are currently not accurate enough to be able to reflect the leap-second distinction. Some computer standards are defined in terms of GMT (Greenwich Mean Time), which is equivalent to UT (Universal Time). GMT is the "civil" name for the standard; UT is the "scientific" name for the same standard. The distinction between UTC and UT is that UTC is based on an atomic clock and UT is based on astronomical observations, which for all practical purposes is an invisibly fine hair to split. Because the earth's rotation is not uniform-it slows down and speeds up in complicated ways-UT does not always flow uniformly. Leap seconds are introduced as needed into UTC so as to keep UTC within 0.9 seconds of UT1, which is a version of UT with certain corrections applied. There are other time and date systems as well; for example, the time scale used by GPS (the satellite-based Global Positioning System) is synchronized to UTC but is not adjusted for leap seconds. An interesting source of further information is the U. S. Naval Observatory, particularly the Directorate of Time at:

http://tycho.usno.navy.mil/

and their definitions of "Systems of Time" at:

http://tycho.usno.navy.mil/systime.html

In all methods of class Date that accept or return year, month, day of month, hours, minutes, and seconds values, the following representations are used:

  • A year y is represented by the integer [image].
  • A month is represented by an integer form 0 to 11; 0 is January, 1 is February, and so on; thus 11 is December.
  • A date (day of month) is represented by an integer from 1 to 31 in the usual manner.
  • An hour is represented by an integer from 0 to 23. Thus the hour from midnight to 1 AM is hour 0, and the hour from noon to 1 PM is hour 12.
  • A minute is represented by an integer from 0 to 59 in the usual manner.
  • A second is represented by an integer from 0 to 61. The values 60 and 61 will occur only for leap seconds, and even then only in Java implementations that actually track leap seconds correctly. Because of the manner in which leap seconds are currently introduced, it is extremely unlikely that two leap seconds will occur in the same minute, but this specification follows the date and time conventions for ISO C.

In all cases, arguments given to methods for these purposes need not fall within the indicated ranges; for example, a date may be specified as January 32 and will be interpreted as meaning February 1.

21.3.1 public Date()

This constructor initializes a newly created Date object so that it represents the instant of time that it was created, measured to the nearest millisecond.

21.3.2 public Date(long time)

This constructor initializes a newly created Date object so that it represents the instant of time that is time milliseconds after the standard base time known as "the epoch," namely 00:00:00 GMT on January 1, 1970. See also the method currentTimeMillis (§20.18.6) of class System.

21.3.3 public Date(int year, int month, int date)

This constructor initializes a newly created Date object so that it represents midnight at the beginning of the day specified by the year, month, and date arguments, in the local time zone. Thus, it has the same effect as the constructor call (§21.3.5):

Date(year, month, date, 0, 0, 0)

21.3.4 public Date(int year, int month, int date,
int hours, int minutes)

This constructor initializes a newly created Date object so that it represents the instant at the start of the minute specified by the year, month, date, hours, and minutes arguments, in the local time zone. Thus, it has the same effect as the constructor call (§21.3.5):

Date(year, month, date, hours, minutes, 0)

21.3.5 public Date(int year, int month, int date,
int hours, int minutes, int seconds)

This constructor initializes a newly created Date object so that it represents the instant at the start of the second specified by the year, month, date, hours, minutes, and seconds arguments, in the local time zone.

21.3.6 public Date(String s)
throws IllegalArgumentException

This constructor initializes a newly created Date object so that it represents the date and time indicated by the string s, which is interpreted as if by the parse method (§21.3.31).

21.3.7 public String toString()

This Date object is converted to a String of the form:

"dow mon dd hh:mm:ss zzz yyyy"

where:

  • dow is the day of the week (Sun, Mon, Tue, Wed, Thu, Fri, Sat).
  • mon is the month (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec).
  • dd is the day of the month (01 through 31), as two decimal digits.
  • hh is the hour of the day (00 through 23), as two decimal digits.
  • mm is the minute within the hour (00 through 59), as two decimal digits.
  • ss is the second within the minute (00 through 61), as two decimal digits.
  • zzz is the time zone (and may reflect daylight saving time). Standard time zone abbreviations include those recognized by the method parse (§21.3.31). If time zone information is not available, then zzz is empty-that is, it consists of no characters at all.
  • yyyy is the year, as four decimal digits.

See also methods toLocaleString (§21.3.27) and toGMTString (§21.3.28).

Overrides the toString method of Object (§20.1.2).

21.3.8 public boolean equals(Object obj)

The result is true if and only if the argument is not null and is a Date object that represents the same point in time, to the millisecond, as this Date object. Thus two Date objects are equal if and only if the getTime method (§21.3.23) returns the same long value from both.

Overrides the equals method of Object (§20.1.3).

21.3.9 public int hashCode()

The result is the exclusive OR of the two halves of the primitive long value returned by the getTime method (§21.3.23). That is, the hash code is the value of the expression:

(int)(this.getTime()^(this.getTime()>>>32))

Overrides the hashCode method of Object (§20.1.4).

21.3.10 public int getYear()

The returned value is the result of subtracting 1900 from the year that contains or begins with the instant in time represented by this Date object, as interpreted in the local time zone.

21.3.11 public void setYear(int year)

This Date object is modified so that it represents a point in time within the specified year, with the month, date, hour, minute, and second the same as before, as interpreted in the local time zone. (Of course, if the date was February 29, for example, and the year is set to a non-leap year, then the new date will be treated as if it were on March 1.)

21.3.12 public int getMonth()

The returned value is a number (0 through 11) representing the month that contains or begins with the instant in time represented by this Date object, as interpreted in the local time zone.

21.3.13 public void setMonth(int month)

This Date object is modified so that it represents a point in time within the specified month, with the year, date, hour, minute, and second the same as before, as interpreted in the local time zone. If the date was October 31, for example, and the month is set to June, then the new date will be treated as if it were on July 1, because June has only 30 days.

21.3.14 public int getDate()

The returned value is a number (1 through 31) representing day of the month that contains or begins with the instant in time represented by this Date object, as interpreted in the local time zone.

21.3.15 public void setDate(int date)

This Date object is modified so that it represents a point in time within the specified day of the month, with the year, month, hour, minute, and second the same as before, as interpreted in the local time zone.If the date was April 30, for example, and the date is set to 31, then it will be treated as if it were on May 1, because April has only 30 days.

21.3.16 public int getDay()

The returned value (0 = Sunday, 1 = Monday, 2 = Tuesday, 3 = Wednesday, 4 = Thursday, 5 = Friday, 6 = Saturday) represents the day of the week that contains or begins with the instant in time represented by this Date object, as interpreted in the local time zone.

21.3.17 public int getHours()

The returned value is a number (0 through 23) representing the hour within the day that contains or begins with the instant in time represented by this Date object, as interpreted in the local time zone.

21.3.18 public void setHours(int hours)

This Date object is modified so that it represents a point in time within the specified hour of the day, with the year, month, date, minute, and second the same as before, as interpreted in the local time zone.

21.3.19 public int getMinutes()

The returned value is a number (0 through 59) representing the minute within the hour that contains or begins with the instant in time represented by this Date object, as interpreted in the local time zone.

21.3.20 public void setMinutes(int minutes)

This Date object is modified so that it represents a point in time within the specified minute of the hour, with the year, month, date, hour, and second the same as before, as interpreted in the local time zone.

21.3.21 public int getSeconds()

The returned value is a number (0 through 61) representing the second within the minute that contains or begins with the instant in time represented by this Date object, as interpreted in the local time zone.

21.3.22 public void setSeconds(int seconds)

This Date object is modified so that it represents a point in time within the specified second of the minute, with the year, month, date, hour, and minute the same as before, as interpreted in the local time zone.

21.3.23 public long getTime()

This method returns the time represented by this Date object, represented as the distance, measured in milliseconds, of that time from the epoch (00:00:00 GMT on January 1, 1970).

21.3.24 public void setTime(long time)

This Date object is modified so that it represents a point in time that is time milliseconds after the epoch (00:00:00 GMT on January 1, 1970).

21.3.25 public boolean before(Date when)

The result is true if and only if the instant represented by this Date object is strictly earlier than the instant represented by when.

21.3.26 public boolean after(Date when)

The result is true if and only if the instant represented by this Date object is strictly later than the instant represented by when.

21.3.27 public String toLocaleString()

This Date object is converted to a String of an implementation-dependent form. The general intent is that the form should be familiar to the user of the Java application, wherever it may happen to be running. The intent is comparable to that of the %c format supported by the strftime function of ISO C.

See also methods toString (§21.3.7) and toGMTString (§21.3.28).

21.3.28 public String toGMTString()

This Date object is converted to a String of length 23 or 24 of the form:

"d mon yyyy hh:mm:ss GMT"

where:

  • d is the day of the month (1 through 31), as one or two decimal digits.
  • mon is the month (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec).
  • yyyy is the year, as four decimal digits.
  • hh is the hour of the day (00 through 23), as two decimal digits.
  • mm is the minute within the hour (00 through 59), as two decimal digits.
  • ss is the second within the minute (00 through 61), as two decimal digits.
  • GMT is exactly the ASCII letters "GMT" to indicate Greenwich Mean Time.

The result does not depend on the local time zone.

See also methods toString (§21.3.7) and toLocaleString (§21.3.27).

21.3.29 public int getTimezoneOffset()

This method returns the offset, measured in minutes, for the local time zone relative to UTC that is appropriate for the time represented by this Date object.

For example, in Massachusetts, five time zones west of Greenwich:

new Date(96, 1, 14).getTimezoneOffset() returns 300

because on February 14, 1996, standard time (Eastern Standard Time) is in use, which is offset five hours from UTC; but:

new Date(96, 5, 1).getTimezoneOffset() returns 240

because on May 1, 1996, daylight saving time (Eastern Daylight Time) is in use, which is offset only four hours from UTC.

This method produces the same result as if it computed:

(this.getTime() - UTC(this.getYear(),
                            this.getMonth(),
                            this.getDate(),
                            this.getHours(),
                            this.getMinutes(),
                            this.getSeconds())) / (60 * 1000)

21.3.30 public static long UTC(int year, int month, int date,
int hours, int minutes, int seconds)

The arguments are interpreted as a year, month, day of the month, hour of the day, minute within the hour, and second within the minute, exactly as for the Date constructor of six arguments (§21.3.5), except that the arguments are interpreted relative to UTC rather than to the local time zone. The time indicated is returned represented as the distance, measured in milliseconds, of that time from the epoch (00:00:00 GMT on January 1, 1970).

21.3.31 public static long parse(String s)
throws IllegalArgumentException

An attempt is made to interpret the string s as a representation of a date and time. If the attempt is successful, the time indicated is returned represented as the distance, measured in milliseconds, of that time from the epoch (00:00:00 GMT on January 1, 1970). If the attempt fails, an IllegalArgumentException is thrown.

The string s is processed from left to right, looking for data of interest.

Any material in s that is within the ASCII parenthesis characters ( and ) is ignored. Parentheses may be nested. Otherwise, the only characters permitted within s are these ASCII characters:

abcdefghijklmnopqrstuvwxyz
ABCDEFGHIJKLMNOPQRSTUVWXYZ
0123456789,+-:/

and whitespace characters (§20.5.19).

A consecutive sequence of decimal digits is treated as a decimal number:

  • If a number is preceded by + or - and a year has already been recognized, then the number is a time-zone offset. If the number is less than 24, it is an offset measured in hours. Otherwise, it is regarded as an offset in minutes, expressed in 24-hour time format without punctuation. A preceding + means an eastward offset and a preceding - means a westward offset. Time zone offsets are always relative to UTC (Greenwich). Thus, for example, -5 occurring in the string would mean "five hours west of Greenwich" and +0430 would mean "four hours and thirty minutes east of Greenwich." It is permitted for the string to specify GMT, UT, or UTC redundantly-for example, GMT-5 or utc+0430.
  • If a number is greater than 70, it is regarded as a year number. It must be followed by a space, comma, slash, or end of string. If it is greater than 1900, then 1900 is subtracted from it.
  • If the number is followed by a colon, it is regarded as an hour, unless an hour has already been recognized, in which case it is regarded as a minute.
  • If the number is followed by a slash, it is regarded as a month (it is decreased by 1 to produce a number in the range 0 to 11), unless a month has already been recognized, in which case it is regarded as a day of the month.
  • If the number is followed by whitespace, a comma, a hyphen, or end of string, then if an hour has been recognized but not a minute, it is regarded as a minute; otherwise, if a minute has been recognized but not a second, it is regarded as a second; otherwise, it is regarded as a day of the month.

A consecutive sequence of letters is regarded as a word and treated as follows:

  • A word that matches AM, ignoring case, is ignored (but the parse fails if an hour has not been recognized or is less than 1 or greater than 12).
  • A word that matches PM, ignoring case, adds 12 to the hour (but the parse fails if an hour has not been recognized or is less than 1 or greater than 12).
  • Any word that matches any prefix of SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, or SATURDAY, ignoring case, is ignored. For example, sat, Friday, TUE, and Thurs are ignored.
  • Otherwise, any word that matches any prefix of JANUARY, FEBRUARY, MARCH, APRIL, MAY, JUNE, JULY, AUGUST, SEPTEMBER, OCTOBER, NOVEMBER, or DECEMBER, ignoring case, and considering them in the order given here, is recognized as specifying a month and is converted to a number (0 to 11). For example, aug, Sept, april, and NOV are recognized as months. So is Ma, which is recognized as MARCH, not MAY.
  • Any word that matches GMT, UT, or UTC, ignoring case, is treated as referring to UTC.
  • Any word that matches EST, CST, MST, or PST, ignoring case, is recognized as referring to the time zone in North America that is five, six, seven, or eight hours west of Greenwich, respectively. Any word that matches EDT, CDT, MDT, or PDT, ignoring case, is recognized as referring to the same time zone, respectively, during daylight saving time. (In the future, this method may be upgraded to recognize other time zone designations.)

Once the entire string s has been scanned, it is converted to a time result in one of two ways. If a time zone or time-zone offset has been recognized, then the year, month, day of month, hour, minute, and second are interpreted in UTC (§21.3.30) and then the time-zone offset is applied. Otherwise, the year, month, day of month, hour, minute, and second are interpreted in the local time zone.


21.4 The Class java.util.Dictionary

A Dictionary is an object that associates elements with keys. Every key and every element is an object. In any one Dictionary, every key is associated at most one element. Given a Dictionary and a key, the associated element can be looked up.

public abstract class Dictionary {
    abstract public int size();
    abstract public boolean isEmpty();
    abstract public Object get(Object key)
        throws NullPointerException;
    abstract public Object put(Object key, Object element)
        throws NullPointerException;
    abstract public Object remove(Object key)
        throws NullPointerException;
    abstract public Enumeration keys();
    abstract public Enumeration elements();
}

As a rule, the equals method (§20.1.3) should be used by implementations of the class Dictionary to decide whether two keys are the same.

21.4.1 abstract public int size()

The general contract for the size method is that it returns the number of entries (distinct keys) in this dictionary.

21.4.2 abstract public boolean isEmpty()

The general contract for the isEmpty method is that the result is true if and only if this dictionary contains no entries.

21.4.3 abstract public Object get(Object key)
throws NullPointerException

The general contract for the isEmpty method is that if this dictionary contains an entry for the specified key, the associated element is returned; otherwise, null is returned.

If the key is null, a NullPointerException is thrown.

21.4.4 abstract public Object put(Object key, Object element)
throws NullPointerException

The general contract for the put method is that it adds an entry to this dictionary.

If this dictionary already contains an entry for the specified key, the element already in this dictionary for that key is returned, after modifying the entry to contain the new element.

If this dictionary does not already have an entry for the specified key, an entry is created for the specified key and element, and null is returned.

If the key or the element is null, a NullPointerException is thrown.

21.4.5 abstract public Object remove(Object key)
throws NullPointerException

The general contract for the remove method is that it removes an entry from this dictionary.

If this dictionary contains an entry for the specified key, the element in this dictionary for that key is returned, after removing the entry from this dictionary.

If this dictionary does not already have an entry for the specified key, null is returned.

If the key is null, a NullPointerException is thrown.

21.4.6 abstract public Enumeration keys()

The general contract for the keys method is that an Enumeration (§21.1) is returned that will generate all the keys for which this dictionary contains entries.

21.4.7 abstract public Enumeration elements()

The general contract for the elements method is that an Enumeration (§21.1) is returned that will generate all the elements contained in entries in this dictionary.


21.5 The Class java.util.Hashtable

. . . never did they seem to have new experiences in common . . . and the things they had for dissection—college, contemporary personality, and the like—they had hashed and rehashed for many a frugal conversational meal.
—F. Scott Fitzgerald, This Side of Paradise (1920)

The class Hashtable implements the abstract class Dictionary (§21.4), with some additional functionality.

public class Hashtable extends Dictionary implements Cloneable {
    public Hashtable(int initialCapacity, float loadFactor);
    public Hashtable(int initialCapacity);
    public Hashtable();
    public String toString();
    public Object clone();
    public int size();
    public boolean isEmpty();
    public Object get(Object key)
        throws NullPointerException;
    public Object put(Object key, Object value)
        throws NullPointerException;
    public Object remove(Object key)
        throws NullPointerException;
    public Enumeration keys();
    public Enumeration elements();
    public boolean contains(Object value);
    public boolean containsKey(Object key);
    protected void rehash();
    public void clear();
}

A Hashtable has two parameters that affect its efficiency: its capacity and its load factor. The load factor should be between 0.0 and 1.0. When the number of entries in the hashtable exceeds the product of the load factor and the current capacity, the capacity is increased, using the rehash method. Larger load factors use memory more efficiently at the expense of larger expected time per lookup. If many entries are to be made in a Hashtable, creating it with a sufficiently large capacity may allow the entries to be inserted more efficiently than letting it perform automatic rehashing as needed to grow the table.

21.5.1 public Hashtable(int initialCapacity, float loadFactor)

This constructor initializes a newly created Hashtable object so that its capacity is initialCapacity and its load factor is loadFactor. Initially, there are no entries in the table.

21.5.2 public Hashtable(int initialCapacity)

This constructor initializes a newly created Hashtable object so that its capacity is initialCapacity and its load factor is 0.75. Initially, there are no entries in the table.

21.5.3 public Hashtable()

This constructor initializes a newly created Hashtable object so that its load factor is 0.75. Initially, there are no entries in the table.

21.5.4 public String toString()

This Hashtable is represented in string form as a set of entries, enclosed in braces and separated by the ASCII characters ", " (comma and space). Each entry is rendered as the key, an equals sign =, and the associated element, where the toString method is used to convert the key and element to strings.

Overrides the toString method of Object (§21.2.3).

21.5.5 public Object clone()

A copy of this Hashtable is constructed and returned. All the structure of the hashtable itself is copied, but the keys and elements are not cloned.

Overrides the clone method of Object (§21.2.6).

21.5.6 public int size()

Implements the size method of Dictionary (§21.4.1).

21.5.7 public boolean isEmpty()

Implements the isEmpty method of Dictionary (§21.4.2).

21.5.8 public Object get(Object key)

Implements the get method of Dictionary (§21.4.3).

21.5.9 public Object put(Object key, Object value)

Implements the put method of Dictionary (§21.4.4).

21.5.10 public Object remove(Object key)

Implements the remove method of Dictionary (§21.4.5).

21.5.11 public Enumeration keys()

Implements the keys method of Dictionary (§21.4.6).

21.5.12 public Enumeration elements()

Implements the elements method of Dictionary (§21.4.7).

21.5.13 public boolean contains(Object value)

The result is true if and only if this Hashtable contains at least one entry for which the element is equal to value, as determined by the equals method (§20.1.3).

21.5.14 public boolean containsKey(Object key)

The result is true if and only if this Hashtable contains an entry for which the key is equal to key, as determined by the equals method (§20.1.3). In other words, this method produces the same result as the expression:

get(key) != null

21.5.15 protected void rehash()

This Hashtable is increased in capacity and reorganized internally, in order to accommodate and access its entries more efficiently.

21.5.16 public void clear()

The clear method removes all entries from this Hashtable.

Twelve sphered tables, by silk seats insphered,
High as the level of a man's breast rear'd
On libbard's paws, upheld the heavy gold
Of cups and goblets, and the store thrice told
Of Ceres' horn, and, in huge vessels, wine
Came from the gloomy tun with merry shine.
Thus loaded with a feast the tables stood . . .
—John Keats, Lamia Part II


21.6 The Class java.util.Properties

A Properties table is a kind of Hashtable with two functionality extensions and with the restriction that keys and elements must be strings. First, there are methods for reading entries into the table from an input stream and writing all the entries in the table to an output stream. Second, a Properties table may refer to another Properties table that provides default values. The getProperty method is much like the get method (§21.4.3), but if an entry is not found in this table, then the defaults table is searched (and that defaults table may itself refer to another defaults table, and so on, recursively).

public class Properties extends Hashtable {
    protected Properties defaults;
    public Properties();
    public Properties(Properties defaults);
    public String getProperty(String key);
    public String getProperty(String key, String defaultValue);
    public Enumeration propertyNames();
    public void load(InputStream in) throws IOException;
    public void save(OutputStream out, String header);
    public void list(PrintStream out);
}

21.6.1 protected Properties defaults;

If the defaults field is not null, it is another Properties table that provides default values for this Properties table.

21.6.2 public Properties()

This constructor initializes a newly created Properties table so that it has no defaults table. Initially, there are no entries in the newly created table.

21.6.3 public Properties(Properties defaults)

This constructor initializes a newly created Properties table so its defaults table is defaults. The argument defaults may be null, in which case the newly created Properties table will not have a defaults table. Initially, there are no entries in the newly created table.

21.6.4 public String getProperty(String key)

If there is an entry in this Properties table with key as its key, the associated element is returned. Otherwise, if this Properties table has a defaults table, then whatever its getProperty method returns is returned. Otherwise, null is returned.

21.6.5 public String getProperty(String key,
String defaultValue)

If there is an entry in this Properties table with key as its key, the associated element is returned. Otherwise, if this Properties table has a defaults table, then whatever its getProperty method returns is returned. Otherwise, defaultValue is returned.

21.6.6 public Enumeration propertyNames()

An Enumeration (§21.1) is returned that will generate all the keys for which this Properties table could supply an associated element. If this Properties table has a defaults table (§21.6.1), then keys for which the defaults table has entries are also supplied by the Enumeration, and so on, recursively; but no key is supplied by the Enumeration more than once.

21.6.7 public void load(InputStream in) throws IOException

Properties (key and element pairs) are read from the input stream:

Runtime.getRuntime().getLocalizedInputStream(in)

and added to this Properties table. See the getLocalizedInputStream method of Runtime (§20.16.15).

Every property occupies one line of the input stream. Each line is terminated by a line terminator (\n or \r or \r\n). Lines from the input stream are processed until end of file is reached on the input stream.

A line that contains only whitespace (§20.5.19) or whose first non-whitespace character is an ASCII # or ! is ignored (thus, # or ! indicate comment lines).

Every line other than a blank line or a comment line describes one property to be added to the table (except that if a line ends with \, then the following line is treated as a continuation line, as described below). The key consists of all the characters in the line starting with the first non-whitespace character and up to, but not including, the first ASCII =, :, or whitespace character. Any whitespace after the key is skipped; if the first non-whitespace character after the key is = or :, then it is ignored and any whitespace characters after it are also skipped. All remaining characters on the line become part of the associated element string. Within the element string (but not the key), the ASCII escape sequences \t, \n, \r, \\, \", \', \ (a backslash and a space), and \u xxxx are recognized and converted to single characters. Moreover, if the last character on the line is \, then the next line is treated as a continuation of the current line; the \ and line terminator are simply discarded, and any leading whitespace characters on the continuation line are also discarded and are not part of the element string.

As an example, each of the following four lines specifies the key "Truth" and the associated element value "Beauty":

Truth Beauty
Truth = Beauty
    Truth:Beauty
Truth			:Beauty

As another example, the following three lines specify a single property:

fruits				apple, banana, pear, \
                cantaloupe, watermelon, \
                kiwi, mango

The key is "fruit" and the associated element is:

"apple, banana, pear, cantaloupe, watermelon, kiwi, mango"

Note that a space appears before each \ so that a space will appear after each comma in the final result; the \, line terminator, and leading whitespace on the continuation line are merely discarded and are not replaced by one or more other characters.

As a third example, the line:

cheeses

specifies that the key is "cheeses" and the associated element is the empty string.

21.6.8 public void save(OutputStream out, String header)

All the properties (key and element pairs) in this Properties table are written to the output stream:

Runtime.getRuntime().getLocalizedOutputStream(out)

in a format suitable for loading into a Properties table using the load method (§21.6.7). See the getLocalizedOutputStream method of Runtime (§20.16.16).

Properties from the defaults table of this Properties table (if any) are not written out by this method.

If the header argument is not null, then an ASCII # character, the header string, and a newline are first written to the output stream. Thus, the header can serve as an identifying comment.

Next, a comment line is always written, consisting of an ASCII # character, the current date and time (as if produced by the toString method of Date (§21.3.7) for the current time), and a newline.

Then every entry in this Properties table is written out, one per line. For each entry the key string is written, then an ASCII =, then the associated element string. Each character of the element string is examined to see whether it should be rendered as an escape sequence. The ASCII characters \, tab, newline, and carriage return are written as \\, \t, \n, and \r, respectively. Characters less than \u0020 and characters greater than \u007E (if necessary, depending on the needs of the localized output stream) are written as \u xxxx for the appropriate hexadecimal value xxxx. Leading space characters, but not embedded or trailing space characters, are written with a preceding \.

21.6.9 public void list(PrintStream out)

Properties (key and element pairs) in this Properties table are written to the output stream out in a possibly abbreviated form that may be more convenient for use in debugging than the output of the save method. No header is written, and element values longer than 40 character are truncated to the first 37 characters, to which the characters "..." are appended. Thus, if the names of the keys are not too long, there is a fighting chance that each property will fit into the space of one line of a physical output device.


21.7 The Class java.util.Observable

Each instance of class Observable maintains a set of "observers" that are notified whenever the Observable object changes in some significant way. An observer may be any object that implements interface Observer (§21.8).

Note that this notification mechanism is has nothing to do with threads (§20.20) and is completely separate from the wait and notify mechanism of class Object (§20.1).

public class Observable {
    public void addObserver(Observer o);
    public void deleteObserver(Observer o);
    public void deleteObservers();
    public int countObservers();
    public void notifyObservers();
    public void notifyObservers(Object arg);
    protected void setChanged();
    protected void clearChanged();
    public boolean hasChanged();
}

When an observable object is newly created, its set of observers is empty.

Two observers are considered the same if and only if the equals method (§20.1.3) returns true for them.

21.7.1 public void addObserver(Observer o)

The observer o is added to this Observable object's set of observers, provided that it is not the same as some observer already in the set.

21.7.2 public void deleteObserver(Observer o)

The observer o is removed from this Observable object's set of observers.

21.7.3 public void deleteObservers()

All observers are removed from this Observable object's set of observers.

21.7.4 public int countObservers()

The number of observers in this Observable object's set of observers is returned.

21.7.5 public void notifyObservers()

If this Observable object has been marked as changed, this method causes all observers to be notified with null as the second argument; in other words, this method is equivalent to:

notifyObservers(null)

21.7.6 public void notifyObservers(Object arg)

If this Observable object has been marked as changed (§21.7.9), this method causes all observers to be notified with arg as the second argument. An observer is notified by calling its update method (§21.8.1) on two arguments: this Observable object and arg. The mark on this object is then cleared (§21.7.8).

21.7.7 protected void setChanged()

This Observable object is marked as having been changed; the hasChanged method will now return true.

21.7.8 protected void clearChanged()

This Observable object is marked as not having been changed; the hasChanged method will now return false.

21.7.9 public boolean hasChanged()

The result is true if and only if the setChanged method has been called for this Observable object more recently than either the clearChanged method or the notifyObservers method.


21.8 The Interface java.util.Observer

A class should implement the Observer interface if it is to be notified whenever an Observable object has been changed. See the Observable class (§21.7) for a discussion of how Observer objects are notified.

public interface Observer {
    public void update(Observable o, Object arg);
}

21.8.1 public void update(Observable o, Object arg)

When an Observable object has been changed and its notifyObservers method (§21.7.6) is called, every Observer object in its set of observers is notified by invoking its update method, passing it two arguments: the Observable object and another argument specified by the call to the notifyObservers method.


21.9 The Class java.util.Random

Oh, many a shaft at random sent
Finds mark the archer little meant!
And many a word at random spoken
May soothe, or wound, a heart that's broken!
—Sir Walter Scott, The Lady of the Lake, Canto V, stanza 18

Each instance of class Random serves as a separate, independent pseudorandom generator of primitive values.

public class Random {
    protected long seed;
    protected double nextNextGaussian;
    protected boolean haveNextNextGaussian = false;
    public Random();
    public Random(long seed);
    protected int next(int bits);
    public void setSeed(long seed);
    public int nextInt();
    public long nextLong();
    public float nextFloat();
    public double nextDouble();
    public double nextGaussian();
}

If two Random objects are created with the same seed and the same sequence of method calls is made for each, they will generate and return identical sequences of numbers in all Java implementations. In order to guarantee this property, particular algorithms are specified for the class Random. Java implementations must use all the algorithms shown here for the class Random, for the sake of absolute portability of Java code. However, subclasses of class Random are permitted use other algorithms, so long as they adhere to the general contracts for all the methods.

The algorithms implemented by class Random use three state variables, which are protected. They also use a protected utility method that on each invocation can supply up to up to 32 pseudorandomly generated bits.

21.9.1 protected long seed;

A variable used by method next (§21.9.7) to hold the state of the pseudorandom number generator.

21.9.2 protected double nextNextGaussian;

A variable used by method nextGaussian (§21.9.12) to hold a precomputed value to be delivered by that method the next time it is called.

21.9.3 p rotected boolean haveNextNextGaussian = false;

A variable used by method nextGaussian (§21.9.12) to keep track of whether it has precomputed and stashed away the next value to be delivered by that method.

21.9.4 public Random()

This constructor initializes a newly created Random number generator by using the current time of day (§20.18.6) as a seed.

public Random() { this(System.currentTimeMillis()); }

21.9.5 public Random(long seed)

This constructor initializes a newly created Random number generator by using the argument seed as a seed.

public Random(long seed) { setSeed(seed); }

21.9.6 public void setSeed(long seed)

The general contract of setSeed is that it alters the state of this random number generator object so as to be in exactly the same state as if it had just been created with the argument seed as a seed.

The method setSeed is implemented by class Random as follows:

synchronized public void setSeed(long seed) {
    this.seed = (seed ^ 0x5DEECE66DL) & ((1L << 48) - 1);
    haveNextNextGaussian = false;
}

The implementation of setSeed by class Random happens to use only 48 bits of the given seed. In general, however, an overriding method may use all 64 bits of the long argument as a seed value.

[In certain early versions of Java, the setSeed method failed to reset the value of haveNextNextGaussian to false; this flaw could lead to failure to produce repeatable behavior.]

21.9.7 protected int next(int bits)

The general contract of next is that it returns an int value and if the argument bits is between 1 and 32 (inclusive), then that many low-order bits of the returned value will be (approximately) independently chosen bit values, each of which is (approximately) equally likely to be 0 or 1.

The method next is implemented by class Random as follows:

synchronized protected int next(int bits) {
    seed = (seed * 0x5DEECE66DL + 0xBL) & ((1L << 48) - 1);
    return (int)(seed >>> (48 - bits));
}

This is a linear congruential pseudorandom number generator, as defined by D. H. Lehmer and described by Donald E. Knuth in The Art of Computer Programming, Volume 2: Seminumerical Algorithms, section 3.2.1.

21.9.8 public int nextInt()

The general contract of nextInt is that one int value is pseudorandomly generated and returned. All [image] possible int values are produced with (approximately) equal probability.

The method setSeed is implemented by class Random as follows:

public int nextInt() {  return next(32); }

21.9.9 public long nextLong()

The general contract of nextLong is that one long value is pseudorandomly generated and returned. All [image] possible long values are produced with (approximately) equal probability.

The method setSeed is implemented by class Random as follows:

public long nextLong() {
    return ((long)next(32) << 32) + next(32);
}

21.9.10 public float nextFloat()

The general contract of nextFloat is that one float value, chosen (approximately) uniformly from the range 0.0f (inclusive) to 1.0f (exclusive), is pseudorandomly generated and returned. All [image] possible float values of the form [image], where m is a positive integer less than [image], are produced with (approximately) equal probability.

The method setSeed is implemented by class Random as follows:

public float nextFloat() {
    return next(24) / ((float)(1 << 24));
}

The hedge "approximately" is used in the foregoing description only because the next method is only approximately an unbiased source of independently chosen bits. If it were a perfect source or randomly chosen bits, then the algorithm shown would choose float values from the stated range with perfect uniformity.

[In early versions of Java, the result was incorrectly calculated as:

    return next(30) / ((float)(1 << 30));

This might seem to be equivalent, if not better, but in fact it introduced a slight nonuniformity because of the bias in the rounding of floating-point numbers: it was slightly more likely that the low-order bit of the significand would be 0 than that it would be 1.]

21.9.11 public double nextDouble()

The general contract of nextDouble is that one double value, chosen (approximately) uniformly from the range 0.0d (inclusive) to 1.0d (exclusive), is pseudorandomly generated and returned. All [image] possible float values of the form [image], where m is a positive integer less than [image], are produced with (approximately) equal probability.

The method setSeed is implemented by class Random as follows:

public double nextDouble() {
    return (((long)next(26) << 27) + next(27))
                / (double)(1L << 53);
}

The hedge "approximately" is used in the foregoing description only because the next method is only approximately an unbiased source of independently chosen bits. If it were a perfect source or randomly chosen bits, then the algorithm shown would choose double values from the stated range with perfect uniformity.

[In early versions of Java, the result was incorrectly calculated as:

    return (((long)next(27) << 27) + next(27))
                / (double)(1L << 54);

This might seem to be equivalent, if not better, but in fact it introduced a large nonuniformity because of the bias in the rounding of floating-point numbers: it was three times as likely that the low-order bit of the significand would be 0 than that it would be 1! This nonuniformity probably doesn't matter much in practice, but we strive for perfection.]

21.9.12 public double nextGaussian()

The general contract of nextGaussian is that one double value, chosen from (approximately) the usual normal distribution with mean 0.0 and standard deviation 1.0, is pseudorandomly generated and returned.

The method setSeed is implemented by class Random as follows:

synchronized public double nextGaussian() {
    if (haveNextNextGaussian) {
        haveNextNextGaussian = false;
        return nextNextGaussian;
    } else {
        double v1, v2, s;
        do {
            v1 = 2 * nextDouble() - 1; 	// between -1.0 and 1.0
            v2 = 2 * nextDouble() - 1; 	// between -1.0 and 1.0
            s = v1 * v1 + v2 * v2;
        } while (s >= 1);
        double norm = Math.sqrt(-2 * Math.log(s)/s);
        nextNextGaussian = v2 * norm;
        haveNextNextGaussian = true;
        return v1 * norm;
    }
}

This uses the polar method of G. E. P. Box, M. E. Muller, and G. Marsaglia, as described by Donald E. Knuth in The Art of Computer Programming, Volume 2: Seminumerical Algorithms, section 3.4.1, subsection C, algorithm P. Note that it generates two independent values at the cost of only one call to Math.log and one call to Math.sqrt.

. . . who can tell what may be the event? . . .
The mind of the multitude is left at random . . .
—Thomas Paine, Common Sense (1776), Appendix A


21.10 The Class java.util.StringTokenizer

The StringTokenizer class provides a way to break a String into tokens. The tokenizing method used by this class is much simpler than the one used by the class java.io.StreamTokenizer. For example, a StringTokenizer does not distinguish among identifiers, numbers, and quoted strings; moreover, it does not recognize and skip comments.

A StringTokenizer can serve as an Enumeration (§21.1).

public class StringTokenizer implements Enumeration {
    public StringTokenizer(String str, String delim,
        boolean returnTokens);
    public StringTokenizer(String str, String delim);
    public StringTokenizer(String str);
    public boolean hasMoreTokens();
    public String nextToken();
    public String nextToken(String delim);
    public boolean hasMoreElements();
    public Object nextElement();
    public int countTokens();
}

A StringTokenizer simply divides characters into classes: delimiters and other characters. The tokenizer behaves in one of two ways, depending on whether it was created with returnTokens having the value true or false.

If returnTokens is false, delimiter characters merely serve to separate tokens of interest. A token is thus a maximal sequence of consecutive characters that are not delimiters.

If returnTokens is true, delimiter characters are themselves considered to be tokens of interest. A token is thus either one delimiter character or a maximal sequence of consecutive characters that are not delimiters.

A StringTokenizer internally maintains a current position within the String to be tokenized. Some operations advance this current position past the characters processed.

A token is returned by taking a substring (§20.12.32) of the string that was used to create the StringTokenizer.

21.10.1 public StringTokenizer(String str, String delim,
boolean returnTokens)

This constructor initializes a newly created StringTokenizer so that it will recognize tokens within the given string str. All characters in the string delim will be considered delimiters. The argument returnTokens specifies whether delimiter characters themselves are to be considered tokens.

21.10.2 public StringTokenizer(String str, String delim)

This constructor initializes a newly created StringTokenizer so that it will recognize tokens within the given string str. All characters in the string delim will be considered delimiters. Delimiter characters themselves will not be treated as tokens.

21.10.3 public StringTokenizer(String str)

This constructor initializes a newly created StringTokenizer so that it will recognize tokens within the given string str. All whitespace characters (§20.5.19) will be considered delimiters. Delimiter characters themselves will not be treated as tokens.

21.10.4 public boolean hasMoreTokens()

The result is true if and only if there is at least one token in the string after the current position. If this method returns true, then a subsequent call to nextToken with no argument will successfully return a token.

21.10.5 public String nextToken()

The next token in the string after the current position is returned. The current position is advanced beyond the recognized token.

21.10.6 public String nextToken(String delim)

First, the set of characters considered to be delimiters by this StringTokenizer is changed to be the characters in the string delim. Then the next token in the string after the current position is returned. The current position is advanced beyond the recognized token.

21.10.7 public boolean hasMoreElements()

This method has exactly the same behavior as hasMoreTokens (§21.10.4). It is provided so that a StringTokenizer can serve as an Enumeration (§21.1).

21.10.8 public Object nextElement()

This method has exactly the same behavior as nextToken (§21.10.5). It is provided so that a StringTokenizer can serve as an Enumeration (§21.1).

21.10.9 public int countTokens()

The result is the number of tokens in the string after the current position, using the current set of delimiter characters. The current position is not advanced.


21.11 The Class java.util.Vector

A Vector, like an array, contains items that can be accessed using an integer index. However, the size of a Vector can grow and shrink as needed to accommodate adding and removing items after the Vector has been created.

public class Vector implements Cloneable {
    protected Object[] elementData;
    protected int elementCount;
    protected int capacityIncrement;
    public Vector(int initialCapacity, int capacityIncrement);
    public Vector(int initialCapacity);
    public Vector();
    public final String toString();
    public Object clone();
    public final Object elementAt(int index)
        throws IndexOutOfBoundsException;
    public final void setElementAt(Object obj, int index)
        throws IndexOutOfBoundsException;
    public final Object firstElement()
        throws NoSuchElementException;
    public final Object lastElement()
        throws NoSuchElementException;
    public final void addElement(Object obj);
    public final void insertElementAt(Object obj, int index)
        throws IndexOutOfBoundsException;
    public final boolean removeElement(Object obj);
    public final void removeElementAt(int index)
        throws IndexOutOfBoundsException;
    public final void removeAllElements();
    public final boolean isEmpty();
    public final int size();
    public final void setSize(int newSize);
    public final int capacity();
    public final void ensureCapacity(int minCapacity);
    public final void trimToSize();
    public final void copyInto(Object anArray[])
        throws IndexOutOfBoundsException;
    public final Enumeration elements();
    public final boolean contains(Object elem);
    public final int indexOf(Object elem);
    public final int indexOf(Object elem, int index)
        throws IndexOutOfBoundsException;
    public final int lastIndexOf(Object elem);
    public final int lastIndexOf(Object elem, int index)
        throws IndexOutOfBoundsException;
}

21.11.1 protected Object[] elementData;

Internally, a Vector keeps its elements in an array that is at least large enough to contain all the elements.

21.11.2 protected int elementCount;

This field holds the number of items currently in this Vector object. Components elementData[0] through elementData[elementCount-1] are the actual items.

21.11.3 protected int capacityIncrement;

When the method ensureCapacity (§21.11.22) must increase the size of the data array in the field elementData (by creating a new array), it increases the size by at least the amount in capacityIncrement; but if capacityIncrement is zero, then it at least doubles the size of the data array.

21.11.4 public Vector(int initialCapacity, int capacityIncrement)

This constructor initializes a newly created Vector so that its internal data array has size initialCapacity and its standard capacity increment is the value of capacityIncrement. Initially, the Vector contains no items.

21.11.5 public Vector(int initialCapacity)

This constructor initializes a newly created Vector so that its internal data array has size initialCapacity and its standard capacity increment is zero. Initially, the Vector contains no items.

21.11.6 public Vector()

This constructor initializes a newly created Vector so that its internal data array has size 10 and its standard capacity increment is zero. Initially the Vector contains no items.

21.11.7 public final String toString()

This Vector is represented in string form as a list of its items, enclosed in ASCII square brackets and separated by the ASCII characters ", " (comma and space). The toString method is used to convert the items to strings; a null reference is rendered as the string "null".

The example fragment:

Vector v = new Vector();
v.addElement("Canberra");
v.addElement("Cancun");
v.addElement("Canandaigua");
System.out.println(v.toString());

produces the output:

[Canberra, Cancun, Canandaigua]

Overrides the toString method of Object (§20.1.2).

21.11.8 public Object clone()

A copy of this Vector is constructed and returned. The copy will contains a reference to a clone of the internal data array, not a reference to the original internal data array of this Vector.

Overrides the clone method of Object (§20.1.5).

21.11.9 public final Object elementAt(int index)
throws IndexOutOfBoundsException

The item of this Vector with the specified index is returned.

If the index is negative or not less than the current size of this Vector, an IndexOutOfBoundsException is thrown.

21.11.10 public final void setElementAt(Object obj, int index)
throws IndexOutOfBoundsException

The item of this Vector with the specified index is replaced with obj, so that obj is now the item at the specified index within this Vector.

If the index is negative or not less than the current size of this Vector, an IndexOutOfBoundsException is thrown.

21.11.11 public final Object firstElement()
throws NoSuchElementException

If this Vector is empty, a NoSuchElementException is thrown. Otherwise, the first item (the item at index 0) is returned.

21.11.12 public final Object lastElement()
throws NoSuchElementException

If this Vector is empty, a NoSuchElementException is thrown. Otherwise, the last item (the item at index size()-1) is returned.

21.11.13 public final void addElement(Object obj)

The size of this Vector is increased by 1 and obj becomes the new last item.

21.11.14 public final void insertElementAt(Object obj, int index)
throws IndexOutOfBoundsException

The size of this Vector is increased by 1 and obj becomes the new item at the specified index. Any item in this Vector that was previously at index k is first moved to index k+1 if and only if k is not less than index.

21.11.15 public final boolean removeElement(Object obj)

If this Vector contains an occurrence of obj, then the first (lowest-indexed) such occurrence is removed, as if by the method removeElementAt (§21.11.16), and true is returned. If this Vector contains no occurrence of obj, this Vector is not modified and false is returned.

21.11.16 public final void removeElementAt(int index)
throws IndexOutOfBoundsException

The size of this Vector is decreased by 1 and the item at the specified index is removed from this Vector. Any item in this Vector that was previously at index k is first moved to index k-1 if and only if k is greater than index.

21.11.17 public final void removeAllElements()

All elements are removed from this Vector, making it empty.

21.11.18 public final boolean isEmpty()

The result is true if and only if this Vector is empty, that is, its size is zero.

21.11.19 public final int size()

The size of this Vector (the number of items it currently contains) is returned.

21.11.20 public final void setSize(int newSize)

The size of this Vector is changed to newSize. If the new size is smaller than the old size, then items are removed from the end and discarded. If the new size is larger than the old size, then the new items are set to null.

21.11.21 public final int capacity()

The current capacity of this Vector (the length of its internal data array, kept in the field elementData) is returned.

21.11.22 public final void ensureCapacity(int minCapacity)

If the current capacity of this Vector is less than minCapacity, then its capacity is increased by replacing its internal data array, kept in the field elementData (§21.11.1), with a larger one. The size of the new data array will be the old size plus capacityIncrement (§21.11.3), unless the value of capacityIncrement is nonpositive, in which case the new capacity will be twice the old capacity; but if this new size is still smaller than minCapacity, then the new capacity will be minCapacity.

21.11.23 public final void trimToSize()

If the capacity of this Vector is larger than its current size (§21.11.19), then the capacity is changed to equal the size by replacing its internal data array, kept in the field elementData, with a smaller one.

21.11.24 public final void copyInto(Object anArray[])
throws IndexOutOfBoundsException

All the items in this Vector are copied into the array anArray. The item at index k in this Vector is copied into component k of anArray. If the length of anArray is smaller than the size of this Vector, an IndexOutOfBoundsException is thrown.

21.11.25 public final Enumeration elements()

An Enumeration (§21.1) is returned that will generate all items in this Vector. The first item generated is the item at index 0, then the item at index 1, and so on.

21.11.26 public final boolean contains(Object elem)

The result is true if and only if some item in this Vector is the same as elem, as determined by the equals method (§20.1.3).

21.11.27 public final int indexOf(Object elem)

If an item equal to elem is in this Vector, then the index of the first such occurrence is returned, that is, the smallest value k such that:

elem.equals(elementData[k])

is true. If no such item occurs in this Vector, then -1 is returned.

21.11.28 public final int indexOf(Object elem, int index)
throws IndexOutOfBoundsException

If an item equal to elem is in this Vector at position k or higher, then the index of the first such occurrence is returned, that is, the smallest value k such that:

elem.equals(elementData[k]) && (k >= index)

is true. If no such item occurs in this Vector, then -1 is returned.

21.11.29 public final int lastIndexOf(Object elem)

If an item equal to elem is in this Vector, then the index of the last such occurrence is returned, that is, the largest value k such that:

elem.equals(elementData[k])

is true. If no such item occurs in this Vector, then -1 is returned.

21.11.30 public final int lastIndexOf(Object elem, int index)
throws IndexOutOfBoundsException

If an item equal to elem is in this Vector at position k or lower, then the index of the last such occurrence is returned, that is, the largest value k such that:

elem.equals(elementData[k]) && (k <= index)

is true. If no such item occurs in this Vector, then -1 is returned.


21.12 The Class java.util.Stack

. . . and from the stack a thin blue wreath of smoke
Curled through the air across the ripening oats . . .
—Oscar Wilde, Charmides (1881)

The class Stack extends Vector with five operations that allow a vector to be treated as a stack. The usual push and pop operations are provided, as well as a method to peek at the top item on the stack, a method to test for whether the stack is empty, and a method to search the stack for an item and discover how far it is from the top.

public class Stack extends Vector {
    public Object push(Object item);
    public Object pop() throws EmptyStackException;
    public Object peek() throws EmptyStackException;
    public boolean empty();
    public int search(Object o);
}

When a stack is first created, it contains no items.

21.12.1 public Object push(Object item)

The item is pushed onto the top of this stack. This has exactly the same effect as:

addElement(item)

See method addElement of Vector (§21.11.13).

21.12.2 public Object pop() throws EmptyStackException

If the stack is empty, an EmptyStackException is thrown. Otherwise, the topmost item (last item of the Vector) is removed and returned.

21.12.3 public Object peek() throws EmptyStackException

If the stack is empty, an EmptyStackException is thrown. Otherwise, the topmost item (last item of the Vector) is returned but not removed.

21.12.4 public boolean empty()

The result is true if and only if the stack contains no items.

21.12.5 public int search(Object o)

If the object o occurs as an item in this Stack, this method returns the distance from the top of the stack of the occurrence nearest the top of the stack; the topmost item on the stack is considered to be at distance 1. The equals method (§20.1.3) is used to compare o to the items in this Stack.

. . . And overhead in circling listlessness
The cawing rooks whirl round the frosted stacks . . .
—Oscar Wilde, Humanitad (1881)


21.13 The Class java.util.EmptyStackException

A EmptyStackException is thrown to indicate an attempt to pop (§21.12.2) or peek (§21.12.3) an empty Stack object.

public class EmptyStackException extends RuntimeException {
    public EmptyStackException();
}

21.13.1 public EmptyStackException()

This constructor initializes a newly created EmptyStackException with null as its error message string.


21.14 The Class java.util.NoSuchElementException

A NoSuchElementException is thrown to indicate that another element was requested from an Enumeration object that has no more elements to supply. See method nextElement of interface Enumeration (§21.1.2).

public class NoSuchElementException extends RuntimeException {
    public NoSuchElementException();
    public NoSuchElementException(String s);
}

21.14.1 public NoSuchElementException()

This constructor initializes a newly created NoSuchElementException with null as its error message string.

21.14.2 public NoSuchElementException(String s)

This constructor initializes a newly created NoSuchElementException by saving a reference to the error message string s for later retrieval by the getMessage method (§20.22.3).


 22. The Package java.io

CHAPTER 22

The Package java.io

Input and output in Java is organized around the concept of streams. A stream is a sequence of items, usually 8-bit bytes, read or written over the course of time.

In the java.io package, all input is done through subclasses of the abstract class InputStream, and all output is done through subclasses of the abstract class OutputStream. The one exception to this rule is the class RandomAccessFile, which handles files that allow random access and perhaps intermixed reading and writing of the file.

For an input stream, the source of data might be a file, a String, an array of bytes, or bytes written to an output stream (typically by another thread). There are also "filter input streams" that take data from another input stream and transform or augment the data before delivering it as input. For example, a LineNumberInputStream passes bytes through verbatim but counts line terminators as they are read.

For an output stream, the sink of data might be a file, an array of bytes, or a buffer to be read as an input stream (typically by another thread). There are also "filter output streams" that transform or augment data before writing it to some other output stream.

An instance of class File represents a path name (a string) that might identify a particular file within a file system. Certain operations on the file system, such as renaming and deleting files, are done by this class rather than through streams.

An instance of class FileDescriptor represents an abstract indication of a particular file within a file system; such file descriptors are created internally by the Java I/O system.

There are two interfaces, DataInput and DataOutput, that support the transfer of data other than bytes or characters, such as long integers, floating-point numbers and strings. The class DataInputStream implements DataInput; the class DataOutputStream implements DataOutput; and RandomAccessFile implements both DataInput and DataOutput.

The class StreamTokenizer provides some simple support for parsing bytes or characters from an input stream into tokens such as identifiers, numbers, and strings, optionally ignoring comments and optionally recognizing or ignoring line terminators.

The hierarchy of classes defined in package java.io is as follows. (Classes whose names are shown here in boldface are in package java.io; the others are in package java.lang and are shown here to clarify subclass relationships.)

Object	§20.1
    interface DataInput	§22.1
    interface DataOutput	§22.2
    InputStream	§22.3
        FileInputStream	§22.4
        PipedInputStream	§22.5
        ByteArrayInputStream	§22.6
        StringBufferInputStream	§22.7
        SequenceInputStream	§22.8
        FilterInputStream	§22.9
            BufferedInputStream	§22.10
            DataInputStream	§22.11
            LineNumberInputStream	§22.12
            PushBackInputStream	§22.13
    StreamTokenizer	§22.14
    OutputStream	§22.15
        FileOutputStream	§22.16
        PipedOutputStream	§22.17
        ByteArrayOutputStream	§22.18
        FilterOutputStream	§22.19
            BufferedOutputStream	§22.20
            DataOutputStream	§22.21
            PrintStream	§22.22
    RandomAccessFile	§22.23
    File	§22.24
    interface FileNameFilter	§22.25
    FileDescriptor	§22.26
    Throwable	§20.22
        Exception
            IOException	§22.27
                EOFException	§22.28
                FileNotFoundException	§22.29
                InterruptedIOException	§22.30
                UTFDataFormatException	§22.31


22.1 The Interface java.io.DataInput

The DataInput interface provides for reading bytes from a binary stream and reconstructing from them data in any of the Java primitive types. There is also a facility for reconstructing a String from data in Java modified UTF-8 format.

The DataOutput interface (§22.2) supports the creation of binary output data suitable for reading back in through the DataInput interface.

The DataInput interface is implemented by classes DataInputStream (§22.11) and RandomAccessFile (§22.23).

public interface DataInput {
    public void readFully(byte[] b)
        throws IOException, NullPointerException;
    public void readFully(byte[] b, int off, int len)
        throws IOException, NullPointerException,
            IndexOutOfBoundsException;
    public int skipBytes(int n) throws IOException;
    public boolean readBoolean() throws IOException;
    public byte readByte() throws IOException;
    public int readUnsignedByte() throws IOException;
    public short readShort() throws IOException;
    public int readUnsignedShort() throws IOException;
    public char readChar() throws IOException;
    public int readInt() throws IOException;
    public long readLong() throws IOException;
    public float readFloat() throws IOException;
    public double readDouble() throws IOException;
    public String readLine() throws IOException;
    public String readUTF() throws IOException;
    public final static String readUTF(DataInput in)
        throws IOException;
}

It is generally true of all the reading routines in this interface that if end of file is reached before the desired number of bytes has been read, an EOFException (which is a kind of IOException) is thrown. If any byte cannot be read for any reason other than end of file, an IOException other than EOFException is thrown. In particular, an IOException may be thrown if the input stream has been closed (§22.3.6).

22.1.1 public void readFully(byte[] b)
throws IOException, NullPointerException;

The general contract of readFully(b) is that it reads some bytes from an input stream and stores them into the buffer array b. The number of bytes read is equal to the length of b.

This method blocks until one of the following conditions occurs:

  • b.length bytes of input data are available, in which case a normal return is made.
  • End of file is detected, in which case an EOFException is thrown.
  • An I/O error occurs, in which case an IOException other than EOFException is thrown.

If b is null, a NullPointerException is thrown.

If b.length is zero, then no bytes are read. Otherwise, the first byte read is stored into element b[0], the next one into b[1], and so on.

If an exception is thrown from this method, then it may be that some but not all bytes of b have been updated with data from the input stream.

22.1.2 public void readFully(byte[] b, int off, int len)
throws IOException, NullPointerException,
IndexOutOfBoundsException

The general contract of readFully(b, off, len) is that it reads len bytes from an input stream.

This method blocks until one of the following conditions occurs:

  • len bytes of input data are available, in which case a normal return is made.
  • End of file is detected, in which case an EOFException is thrown.
  • An I/O error occurs, in which case an IOException other than EOFException is thrown.

If b is null, a NullPointerException is thrown.

If off is negative, or len is negative, or off+len is greater than the length of the array b, then an IndexOutOfBoundsException is thrown.

If len is zero, then no bytes are read. Otherwise, the first byte read is stored into element b[off], the next one into b[off+1], and so on. The number of bytes read is, at most, equal to len.

If an exception is thrown from this method, then it may be that some but not all bytes of b in positions off through off+len-1 have been updated with data from the input stream.

22.1.3 public int skipBytes(int n) throws IOException

The general contract of skipBytes is that it makes an attempt to skip over n bytes of data from the input stream, discarding the skipped bytes. However, it may skip over some smaller number of bytes, possibly zero. This may result from any of a number of conditions; reaching end of file before n bytes have been skipped is only one possibility. This method never throws an EOFException. The actual number of bytes skipped is returned.

22.1.4 public boolean readBoolean() throws IOException;

The general contract of readBoolean is that it reads one input byte and returns true if that byte is nonzero, false if that byte is zero.

This method is suitable for reading the byte written by the writeBoolean method of interface DataOutput (§22.2.4).

22.1.5 public byte readByte() throws IOException

The general contract of readByte is that it reads and returns one input byte. The byte is treated as a signed value in the range -128 through 127, inclusive.

This method is suitable for reading the byte written by the writeByte method of interface DataOutput (§22.2.5).

22.1.6 public int readUnsignedByte() throws IOException

The general contract of readUnsignedByte is that it reads one input byte, zero- extends it to type int, and returns the result, which is therefore in the range 0 through 255.

This method is suitable for reading the byte written by the writeByte method of interface DataOutput (§22.2.5) if the argument to writeByte was intended to be a value in the range 0 through 255.

22.1.7 public short readShort() throws IOException

The general contract of readShort is that it reads two input bytes and returns a short value. Let a be the first byte read and b be the second byte. The value returned is:

(short)((a << 8) | (b & 0xff))

This method is suitable for reading the bytes written by the writeShort method of interface DataOutput (§22.2.6).

22.1.8 public int readUnsignedShort() throws IOException

The general contract of readUnsignedShort is that it reads two input bytes and returns an int value in the range 0 through 65535. Let a be the first byte read and b be the second byte. The value returned is:

(((a & 0xff) << 8) | (b & 0xff))

This method is suitable for reading the bytes written by the writeShort method of interface DataOutput (§22.2.6) if the argument to writeShort was intended to be a value in the range 0 through 65535.

22.1.9 public char readChar() throws IOException

The general contract of readChar is that it reads two input bytes and returns a char value. Let a be the first byte read and b be the second byte. The value returned is:

(char)((a << 8) | (b & 0xff))

This method is suitable for reading bytes written by the writeChar method of interface DataOutput (§22.2.7).

22.1.10 public int readInt() throws IOException

The general contract of readInt is that it reads four input bytes and returns an int value. Let a be the first byte read, b be the second byte, c be the third byte, and d be the fourth byte. The value returned is:

(((a & 0xff) << 24) | ((b & 0xff) << 16) |
  ((c & 0xff) <<    8) | (d & 0xff))

This method is suitable for reading bytes written by the writeInt method of interface DataOutput (§22.2.8).

22.1.11 public long readLong() throws IOException

The general contract of readLong is that it reads eight input bytes and returns a long value. Let a be the first byte read, b be the second byte, c be the third byte, d be the fourth byte, e be the fifth byte, f be the sixth byte, g be the seventh byte, and h be the eighth byte. The value returned is:

(((long)(a & 0xff) << 56) |
  ((long)(b & 0xff) << 48) |
  ((long)(c & 0xff) <<  40) |
  ((long)(d & 0xff) << 32) |
  ((long)(e & 0xff) <<  24) |
  ((long)(f & 0xff) << 16) |
  ((long)(g & 0xff) <<    8) |
  ((long)(h & 0xff)))

This method is suitable for reading bytes written by the writeLong method of interface DataOutput (§22.2.9).

22.1.12 public float readFloat() throws IOException

The general contract of readFloat is that it reads four input bytes and returns a float value. It does this by first constructing an int value in exactly the manner of the readInt method (§22.1.10), then converting this int value to a float in exactly the manner of the method Float.intBitsToFloat (§20.9.23).

This method is suitable for reading bytes written by the writeFloat method of interface DataOutput (§22.2.10).

22.1.13 public double readDouble() throws IOException

The general contract of readDouble is that it reads eight input bytes and returns a double value. It does this by first constructing a long value in exactly the manner of the readlong method (§22.1.11), then converting this long value to a double in exactly the manner of the method Double.longBitsToDouble (§20.10.22).

This method is suitable for reading bytes written by the writeDouble method of interface DataOutput (§22.2.11).

22.1.14 public String readLine() throws IOException

The general contract of readLine is that it reads successive bytes, converting each byte separately into a character, until it encounters a line terminator or end of file; the characters read are then returned as a String. Note that because this method processes bytes, it does not support input of the full Unicode character set.

If end of file is encountered before even one byte can be read, then null is returned. Otherwise, each byte that is read is converted to type char by zero-extension. If the character '\n' is encountered, it is discarded and reading ceases. If the character '\r' is encountered, it is discarded and, if the following byte converts to the character '\n', then that is discarded also; reading then ceases. If end of file is encountered before either of the characters '\n' and '\r' is encountered, reading ceases. Once reading has ceased, a String is returned that contains all the characters read and not discarded, taken in order. Note that every character in this string will have a value less than \u0100, that is, (char)256.

22.1.15 public String readUTF() throws IOException

The general contract of readUTF is that it reads a representation of a Unicode character string encoded in Java modified UTF-8 format; this string of characters is then returned as a String.

First, two bytes are read and used to construct an unsigned 16-bit integer in exactly the manner of the readUnsignedShort method (§22.1.8). This integer value is called the UTF length and specifies the number of additional bytes to be read. These bytes are then converted to characters by considering them in groups. The length of each group is computed from the value of the first byte of the group. The byte following a group, if any, is the first byte of the next group.

If the first byte of a group matches the bit pattern 0xxxxxxx (where x means "may be 0 or 1"), then the group consists of just that byte. The byte is zero-extended to form a character.

If the first byte of a group matches the bit pattern 110xxxxx, then the group consists of that byte a and a second byte b. If there is no byte b (because byte a was the last of the bytes to be read), or if byte b does not match the bit pattern 10xxxxxx, then a UTFDataFormatException is thrown. Otherwise, the group is converted to the character:

(char)(((a & 0x1F) << 6) | (b & 0x3F))

If the first byte of a group matches the bit pattern 1110xxxx, then the group consists of that byte a and two more bytes b and c. If there is no byte c (because byte a was one of the last two of the bytes to be read), or either byte b or byte c does not match the bit pattern 10xxxxxx, then a UTFDataFormatException is thrown. Otherwise, the group is converted to the character:

(char)(((a & 0x0F) << 12) | ((b & 0x3F) << 6) | (c & 0x3F))

If the first byte of a group matches the pattern 1111xxxx or the pattern 10xxxxxx, then a UTFDataFormatException is thrown.

If end of file is encountered at any time during this entire process, then an EOFException is thrown.

After every group has been converted to a character by this process, the characters are gathered, in the same order in which their corresponding groups were read from the input stream, to form a String, which is returned.

The writeUTF method of interface DataOutput (§22.2.14) may be used to write data that is suitable for reading by this method.


22.2 The Interface java.io.DataOutput

The DataOutput interface provides for converting data from any of the Java primitive types to a series of bytes and writing these bytes to a binary stream. There is also a facility for converting a String into Java modified UTF-8 format and writing the resulting series of bytes.

The DataInput interface (§22.1) can be used to read in and reconstruct Java data from the binary output data produced by the DataOutput interface.

The DataOutput interface is implemented by classes DataOutputStream (§22.21) and RandomAccessFile (§22.23).

public interface DataOutput {
    public void write(int b) throws IOException;
    public void write(byte[] b)
        throws IOException, NullPointerException;
    public void write(byte[] b, int off, int len)
        throws IOException, NullPointerException,
            IndexOutOfBoundsException;
    public void writeBoolean(boolean v) throws IOException;
    public void writeByte(int v) throws IOException;
    public void writeShort(int v) throws IOException;
    public void writeChar(int v) throws IOException;
    public void writeInt(int v) throws IOException;
    public void writeLong(long v) throws IOException;
    public void writeFloat(float v) throws IOException;
    public void writeDouble(double v) throws IOException;
    public void writeBytes(String s)
        throws IOException, NullPointerException;
    public void writeChars(String s)
        throws IOException, NullPointerException;
    public void writeUTF(String s)
        throws IOException, NullPointerException;
}

For all the methods in this interface that write bytes, it is generally true that if a byte cannot be written for any reason, an IOException is thrown.

22.2.1 public void write(int b) throws IOException

The general contract for write is that one byte is written to the output stream. The byte to be written is the eight low-order bits of the argument b. The 24 high-order bits of b are ignored.

22.2.2 public void write(byte[] b)
throws IOException, NullPointerException

The general contract for write is that all the bytes in array b are written, in order, to the output stream.

If b is null, a NullPointerException is thrown.

If b.length is zero, then no bytes are written. Otherwise, the byte b[0] is written first, then b[1], and so on; the last byte written is b[b.length-1].

22.2.3 public void write(byte[] b, int off, int len)
throws IOException, NullPointerException, IndexOutOfBoundsException

The general contract for write is that len bytes from array b are written, in order, to the output stream.

If b is null, a NullPointerException is thrown.

If off is negative, or len is negative, or off+len is greater than the length of the array b, then an IndexOutOfBoundsException is thrown.

If len is zero, then no bytes are written. Otherwise, the byte b[off] is written first, then b[off+1], and so on; the last byte written is b[off+len-1].

22.2.4 public void writeBoolean(boolean v) throws IOException

The general contract for writeBoolean is that one byte is written to the output stream. If the argument v is true, the value (byte)1 is written; if v is false, the value (byte)0 is written.

The byte written by this method may be read by the readBoolean method of interface DataInput (§22.1.4), which will then return a boolean equal to v.

22.2.5 public void writeByte(int v) throws IOException

The general contract for writeByte is that one byte is written to the output stream to represent the value of the argument. The byte to be written is the eight low- order bits of the argument b. The 24 high-order bits of b are ignored. (This means that writeByte does exactly the same thing as write for an integer argument.)

The byte written by this method may be read by the readByte method of interface DataInput (§22.1.5), which will then return a byte equal to (byte)v.

22.2.6 public void writeShort(int v) throws IOException

The general contract for writeShort is that two bytes are written to the output stream to represent the value of the argument. The byte values to be written, in the order shown, are:

(byte)(0xff & (v >> 8))
(byte)(0xff & v)

The bytes written by this method may be read by the readShort method of interface DataInput (§22.1.7), which will then return a short equal to (short)v.

22.2.7 public void writeChar(int v) throws IOException

The general contract for writeChar is that two bytes are written to the output stream to represent the value of the argument. The byte values to be written, in the order shown, are:

(byte)(0xff & (v >> 8))
(byte)(0xff & v)

The bytes written by this method may be read by the readChar method of interface DataInput (§22.1.9), which will then return a char equal to (char)v.

22.2.8 public void writeInt(int v) throws IOException

The general contract for writeInt is that four bytes are written to the output stream to represent the value of the argument. The byte values to be written, in the order shown, are:

(byte)(0xff & (v >> 24))
(byte)(0xff & (v >> 16))
(byte)(0xff & (v >>    8))
(byte)(0xff & v)

The bytes written by this method may be read by the readInt method of interface DataInput (§22.1.10), which will then return an int equal to v.

22.2.9 public void writeLong(long v) throws IOException

The general contract for writeLong is that four bytes are written to the output stream to represent the value of the argument. The byte values to be written, in the order shown, are:

(byte)(0xff & (v >> 56))
(byte)(0xff & (v >> 48))
(byte)(0xff & (v >> 40))
(byte)(0xff & (v >> 32))
(byte)(0xff & (v >> 24))
(byte)(0xff & (v >> 16))
(byte)(0xff & (v >>    8))
(byte)(0xff & v)

The bytes written by this method may be read by the readLong method of interface DataInput (§22.1.11), which will then return a long equal to v.

22.2.10 public void writeFloat(float v) throws IOException

The general contract for writeFloat is that four bytes are written to the output stream to represent the value of the argument. It does this as if it first converts this float value to an int in exactly the manner of the Float.floatToIntBits method (§20.9.22) and then writes the int value in exactly the manner of the writeInt method (§22.2.8).

The bytes written by this method may be read by the readFloat method of interface DataInput (§22.1.12), which will then return a float equal to v.

22.2.11 public void writeDouble(double v) throws IOException

The general contract for writeDouble is that eight bytes are written to the output stream to represent the value of the argument. It does this as if it first converts this double value to a long in exactly the manner of the Double.doubleToLongBits method (§20.10.21) and then writes the long value in exactly the manner of the writeLong method (§22.2.9).

The bytes written by this method may be read by the readDouble method of interface DataInput (§22.1.13), which will then return a double equal to v.

22.2.12 public void writeBytes(String s)
throws IOException, NullPointerException

The general contract for writeBytes is that for every character in the string s, taken in order, one byte is written to the output stream.

If s is null, a NullPointerException is thrown.

If s.length is zero, then no bytes are written. Otherwise, the character s[0] is written first, then s[1], and so on; the last character written is s[s.length-1]. For each character, one byte is written, the low-order byte, in exactly the manner of the writeByte method (§22.2.5). The high-order eight bits of each character in the string are ignored.

22.2.13 public void writeChars(String s)
throws IOException, NullPointerException

The general contract for writeChars is that every character in the string s is written, in order, to the output stream, two bytes per character.

If s is null, a NullPointerException is thrown.

If s.length is zero, then no characters are written. Otherwise, the character s[0] is written first, then s[1], and so on; the last character written is s[s.length-1]. For each character, two bytes are actually written, high-order byte first, in exactly the manner of the writeChar method (§22.2.7).

22.2.14 public void writeUTF(String s)
throws IOException, NullPointerException

The general contract for writeUTF is that two bytes of length information are written to the output stream, followed by the Java modified UTF representation of every character in the string s.

If s is null, a NullPointerException is thrown.

Each character in the string s is converted to a group of one, two, or three bytes, depending on the value of the character.

If a character c is in the range '\u0001' through '\u007f', it is represented by one byte:

(byte)c

If a character c is '\u0000' or is in the range '\u0080' through '\u07ff', then it is represented by two bytes, to be written in the order shown:

(byte)(0xc0 | (0x1f & (c >> 6)))
(byte)(0x80 | (0x3f & c))

If a character c is in the range '\u0800' through '\uffff', then it is represented by three bytes, to be written in the order shown:

(byte)(0xc0 | (0x0f & (c >> 12)))
(byte)(0x80 | (0x3f & (c >>    6)))
(byte)(0x80 | (0x3f & c))

First, the total number of bytes needed to represent all the characters of s is calculated. If this number is larger than 65535, then a UTFDataFormatError is thrown. Otherwise, this length is written to the output stream in exactly the manner of the writeShort method (§22.2.6); after this, the one-, two-, or three-byte representation of each character in the string s is written.

The bytes written by this method may be read by the readUTF method of interface DataInput (§22.1.15), which will then return a String equal to s.


22.3 The Class java.io.InputStream

An input stream makes input bytes available from some source.

public abstract class InputStream {
    public abstract int read() throws IOException;
    public int read(byte[] b)
    throws IOException, NullPointerException;
    public int read(byte[] b, int off, int len)
        throws IOException, NullPointerException,
            IndexOutOfBoundsException;
    public long skip(long n) throws IOException;
    public int available() throws IOException;
    public void close() throws IOException;
    public void mark(int readlimit);
    public void reset() throws IOException;
    public boolean markSupported();
}

22.3.1 public abstract int read() throws IOException

The general contract of read is that it reads one byte from the input stream. The byte is returned as an integer in the range 0 to 255 (0x00-0xff). If no byte is available because the stream is at end of file, the value -1 is returned.

This method blocks until input data is available, end of file is detected, or an exception is thrown.

If the byte cannot be read for any reason other than end of file, an IOException is thrown. In particular, an IOException is thrown if the input stream has been closed (§22.3.6).

22.3.2 public int read(byte[] b)
throws IOException, NullPointerException

The general contract of read(b) is that it reads some number of bytes from the input stream and stores them into the buffer array b. The number of bytes actually read is returned as an integer.

This method blocks until input data is available, end of file is detected, or an exception is thrown.

If b is null, a NullPointerException is thrown.

If the length of b is zero, then no bytes are read and 0 is returned; otherwise, there is an attempt to read at least one byte. If no byte is available because the stream is at end of file, the value -1 is returned; otherwise, at least one byte is read and stored into b.

The first byte read is stored into element b[0], the next one into b[1], and so on. The number of bytes read is, at most, equal to the length of b. Let k be the number of bytes actually read; these bytes will be stored in elements b[0] through b[k-1], leaving elements b[k] through b[b.length-1] unaffected.

If the first byte cannot be read for any reason other than end of file, then an IOException is thrown. In particular, an IOException is thrown if the input stream has been closed (§22.15.5).

The read(b) method for class InputStream has the same effect as:

read(b, 0, b.length)

22.3.3 public int read(byte[] b, int off, int len)
throws IOException, NullPointerException,
IndexOutOfBoundsException

The general contract of read(b, off, len) is that it reads some number of bytes from the input stream and stores them into the buffer array b. An attempt is made to read as many as len bytes, but a smaller number may be read, possibly zero. The number of bytes actually read is returned as an integer.

This method blocks until input data is available, end of file is detected, or an exception is thrown.

If b is null, a NullPointerException is thrown.

If off is negative, or len is negative, or off+len is greater than the length of the array b, then an IndexOutOfBoundsException is thrown.

If len is zero, then no bytes are read and 0 is returned; otherwise, there is an attempt to read at least one byte. If no byte is available because the stream is at end of file, the value -1 is returned; otherwise, at least one byte is read and stored into b.

The first byte read is stored into element b[off], the next one into b[off+1], and so on. The number of bytes read is, at most, equal to len. Let k be the number of bytes actually read; these bytes will be stored in elements b[off] through b[off+k-1], leaving elements b[off+k] through b[off+len-1] unaffected.

In every case, elements b[0] through b[off] and elements b[off+len] through b[b.length-1] are unaffected.

If the first byte cannot be read for any reason other than end of file, then an IOException is thrown. In particular, an IOException is thrown if the input stream has been closed (§22.15.5).

The read(b, off, len) method for class InputStream simple calls the method read() repeatedly. If the first such call results in an IOException, that exception is returned from the call to the read(b, off, len) method. If any subsequent call to read() results in a IOException, the exception is caught and treated as if it were end of file; the bytes read up to that point are stored into b and the number of bytes read before the exception occurred is returned.

22.3.4 public long skip(long n) throws IOException

The general contract of skip is that it makes an attempt to skip over n bytes of data from the input stream, discarding the skipped bytes. However, it may skip over some smaller number of bytes, possibly zero. This may result from any of a number of conditions; reaching end of file before n bytes have been skipped is only one possibility. The actual number of bytes skipped is returned.

22.3.5 public int available() throws IOException

The general contract of available is that it returns an integer k; the next caller of a method for this input stream, which might be the same thread or another thread, can then expect to be able to read or skip up to k bytes without blocking (waiting for input data to arrive).

The available method for class InputStream always returns 0.

22.3.6 public int close() throws IOException

The general contract of close is that it closes the input stream. A closed stream cannot perform input operations and cannot be reopened.

The close method for class InputStream does nothing and simply returns.

22.3.7 public void mark(int readlimit)

The general contract of mark is that, if the method markSupported returns true, the stream somehow remembers all the bytes read after the call to mark and stands ready to supply those same bytes again if and whenever the method reset is called. However, the stream is not required to remember any data at all if more than readlimit bytes are read from the stream before reset is called.

The mark method for class InputStream does nothing.

22.3.8 public void reset() throws IOException

The general contract of reset is:

  • If the method markSupported returns true, then:
    • If the method mark has not been called since the stream was created, or the number of bytes read from the stream since mark was last called is larger than the argument to mark at that last call, then an IOException might be thrown.
    • If such an IOException is not thrown, then the stream is reset to a state such that all the bytes read since the most recent call to mark (or since the start of the file, if mark has not been called) will be resupplied to subsequent callers of the read method, followed by any bytes that otherwise would have been the next input data as of the time of the call to reset.
  • If the method markSupported returns false, then:
    • The call to reset may throw an IOException.
    • If an IOException is not thrown, then the stream is reset to a fixed state that depends on the particular type of the input stream and how it was created. The bytes that will be supplied to subsequent callers of the read method depend on the particular type of the input stream.

The method reset for class InputStream always throws an IOException.

22.3.9 public boolean markSupported()

The general contract of markSupported is that if it returns true, then the stream supports the mark (§22.3.7) and reset (§22.3.8) operations. For any given instance of InputStream, this method should consistently return the same truth value whenever it is called.

The markSupported method for class InputStream returns false.


22.4 The Class java.io.FileInputStream

A file input stream obtains input bytes from a file in a file system. What files are available depends on the host environment.

public class FileInputStream extends InputStream  {
    public FileInputStream(String path)
        throws SecurityException, FileNotFoundException;
    public FileInputStream(File file)
        throws SecurityException, FileNotFoundException;
    public FileInputStream(FileDescriptor fdObj)
        throws SecurityException;
    public native int read() throws IOException;
    public int read(byte[] b)
        throws IOException, NullPointerException;
    public int read(byte[] b, int off, int len)
        throws IOException, NullPointerException,
            IndexOutOfBoundsException;
    public native long skip(long n) throws IOException;
    public native int available() throws IOException;
    public native void close() throws IOException;
    public final FileDescriptor getFD() throws IOException;
    protected void finalize() throws IOException;
}

22.4.1 public FileInputStream(String path)
throws SecurityException, FileNotFoundException

This constructor initializes a newly created FileInputStream by opening a connection to an actual file, the file named by the path name path in the file system. A new FileDescriptor object is created to represent this file connection.

First, if there is a security manager, its checkRead method (§20.17.19) is called with the path argument as its argument.

If the actual file cannot be opened, a FileNotFoundException is thrown.

22.4.2 public FileInputStream(File file)
throws SecurityException, FileNotFoundException

This constructor initializes a newly created FileInputStream by opening a connection to an actual file, the file named by the File object file in the file system. A new FileDescriptor object is created to represent this file connection.

First, if there is a security manager, its checkRead method (§20.17.19) is called with the path represented by the file argument as its argument.

If the actual file cannot be opened, a FileNotFoundException is thrown.

22.4.3 public FileInputStream(FileDescriptor fdObj)
throws SecurityException

This constructor initializes a newly created FileInputStream by using the file descriptor fdObj, which represents an existing connection to an actual file in the file system.

First, if there is a security manager, its checkRead method (§20.17.18) is called with the file descriptor fdObj as its argument.

22.4.4 public final FileDescriptor getFD() throws IOException

This method returns the FileDescriptor object (§22.26) that represents the connection to the actual file in the file system being used by this FileInputStream.

22.4.5 public int read() throws IOException;

The byte for this operation is read from the actual file with which this file input stream is connected.

Implements the read method of InputStream (§22.3.1).

22.4.6 public int read(byte[] b)
throws IOException, NullPointerException

Bytes for this operation are read from the actual file with which this file input stream is connected.

Overrides the read method of InputStream (§22.3.2).

22.4.7 public int read(byte[] b, int off, int len)
throws IOException, NullPointerException, IndexOutOfBoundsException

Bytes for this operation are read from the actual file with which this file input stream is connected.

Overrides the read method of InputStream (§22.3.3).

22.4.8 public long skip(long n) throws IOException

Bytes for this operation are read from the actual file with which this file input stream is connected.

Overrides the skip method of InputStream (§22.3.4).

22.4.9 public int available() throws IOException

Overrides the available method of InputStream (§22.3.5).

22.4.10 public void close() throws IOException

This file input stream is closed and may no longer be used for reading bytes.

Overrides the close method of InputStream (§22.3.6).

22.4.11 protected void finalize() throws IOException

A FileInputStream uses finalization to clean up the connection to the actual file.


22.5 The Class java.io.PipedInputStream

A piped input stream should be connected to a piped output stream; the piped input stream then provides whatever data bytes are written to the piped output stream. Typically, data is read from a PipedInputStream object by one thread and data is written to the corresponding PipedOutputStream (§22.17) by some other thread. Attempting to use both objects from a single thread is not recommended, as it may deadlock the thread. The piped input stream contains a buffer, decoupling read operations from write operations, within limits.

public class PipedInputStream extends InputStream {
    public PipedInputStream (PipedOutputStream src)
        throws IOException;
    public PipedInputStream ();
    public void connect(PipedOutputStream src)
        throws IOException;
    public int read()  throws IOException;
    public int read(byte[] b, int off, int len)
        throws IOException, NullPointerException,
            IndexOutOfBoundsException;
    public void close() throws IOException;
}

22.5.1 public PipedInputStream(PipedOutputStream src)
throws IOException

This constructor initializes a newly created PipedInputStream so that it is connected to the piped output stream src. Data bytes written to src will then be available as input from this stream.

22.5.2 public PipedInputStream()

This constructor initializes a newly created PipedInputStream so that it is not yet connected. It must be connected to a PipedOutputStream before being used.

22.5.3 public void connect(PipedOutputStream src)
throws IOException

The connect method causes this piped input stream to be connected to the piped output stream src. If this object is already connected to some other piped output stream, an IOException is thrown.

If src is an unconnected piped output stream and snk is an unconnected piped input stream, they may be connected by either the call:

snk.connect(src)

or the call:

src.connect(snk)

The two calls have the same effect.

22.5.4 public int read() throws IOException

If a thread was providing data bytes to the connected piped output stream, but the thread is no longer alive, then an IOException is thrown.

Implements the read method of InputStream (§22.3.1).

22.5.5 public int read(byte[] b, int off, int len)
throws IOException, NullPointerException, IndexOutOfBoundsException

If a thread was providing data bytes to the connected piped output stream, but the thread is no longer alive, then an IOException is thrown.

Overrides the read method of InputStream (§22.3.3).

22.5.6 public void close() throws IOException

This piped input stream is closed and may no longer be used for reading bytes.

Overrides the close method of InputStream (§22.3.6).


22.6 The Class java.io.ByteArrayInputStream

A ByteArrayInputStream contains an internal buffer that contains bytes that may be read from the stream. An internal counter keeps track of the next byte to be supplied by the read method. See also StringBufferInputStream (§22.7).

public class ByteArrayInputStream extends InputStream {
    protected byte[] buf;
    protected int pos;
    protected int count;
    public ByteArrayInputStream(byte[] buf);
    public ByteArrayInputStream(byte[] buf,
            int offset, int length);
    public int read()
        throws NullPointerException, IndexOutOfBoundsException;
    public int read(byte[] b, int off, int len)
        throws NullPointerException, IndexOutOfBoundsException;
    public long skip(long n);
    public int available();
    public void reset();
}

22.6.1 protected byte[] buf;

An array of bytes that was provided by the creator of the stream. Elements buf[0] through buf[count-1] are the only bytes that can ever be read from the stream; element buf[pos] is the next byte to be read.

22.6.2 protected int pos;

This value should always be nonnegative and not larger than the value of count. The next byte to be read from this stream will be buf[pos].

22.6.3 protected int count;

This value should always be nonnegative and not larger than the length of buf. It is one greater than the position of the last byte within buf that can ever be read from this stream.

22.6.4 public ByteArrayInputStream(byte[] buf)

This constructor initializes a newly created ByteArrayInputStream so that it uses buf as its buffer array. The initial value of pos is 0 and the initial value of count is the length of buf.

22.6.5 public ByteArrayInputStream(byte[] buf,
int offset, int length)

This constructor initializes a newly created ByteArrayInputStream so that it uses buf as its buffer array. The initial value of pos is offset and the initial value of count is offset+len.

Note that if bytes are simply read from the resulting input stream, elements buf[pos] through buf[pos+len-1] will be read; however, if a reset operation (§22.6.10) is performed, then bytes buf[0] through buf[pos-1] will then become available for input.

22.6.6 public int read()
throws NullPointerException, IndexOutOfBoundsException

If pos equals count, then -1 is returned to indicate end of file. Otherwise, the value buf[pos]&0xff is returned; just before the return, pos is incremented by 1.

Implements the read method of InputStream (§22.3.1).

22.6.7 public int read(byte[] b, int off, int len)
throws NullPointerException, IndexOutOfBoundsException

If pos equals count, then -1 is returned to indicate end of file. Otherwise, the number k of bytes read is equal to the smaller of len and count-pos. If k is positive, then bytes buf[pos] through buf[pos+k-1] are copied into b[off] through b[off+k-1] in the manner performed by System.arraycopy (§20.18.16). The value k is added into pos and k is returned.

Overrides the read method of InputStream (§22.3.3).

22.6.8 public long skip(long n)

The actual number k of bytes to be skipped is equal to the smaller of n and count-pos. The value k is added into pos and k is returned.

Overrides the skip method of InputStream (§22.3.4).

22.6.9 public int available()

The quantity count-pos is returned.

Overrides the available method of InputStream (§22.3.5).

22.6.10 public void reset()

The value of pos is set to 0.

Overrides the reset method of InputStream (§22.3.8).


22.7 The Class java.io.StringBufferInputStream

A StringBufferInputStream contains an internal buffer that contains bytes that may be read from the stream. An internal counter keeps track of the next byte to be supplied by the read method. See also ByteArrayInputStream (§22.6).

public class StringBufferInputStream extends InputStream {
    protected String buffer;
    protected int pos;
    protected int count;
    public StringBufferInputStream(String s)
        throws NullPointerException;
    public int read();
    public int read(byte[] b, int off, int len)
        throws NullPointerException, IndexOutOfBoundsException;
    public long skip(long n);
    public int available();
    public void reset();
}

Note that bytes read from a StringBufferInputStream are the low-order eight bits of each character in the string; the high-order eight bits of each character are ignored.

22.7.1 protected String buffer;

A String that was provided by the creator of the stream. Elements buffer[0] through buffer[count-1] are the only bytes that can ever be read from this stream; element buffer[pos] is the next byte to be read.

22.7.2 protected int pos;

This value should always be nonnegative and not larger than the value of count. The next byte to be read from this stream will be buffer[pos].

22.7.3 protected int count;

This value equals the length of buffer. It is the number of bytes of data in buffer that can ever be read from this stream.

22.7.4 public StringBufferInputStream(String s)
throws NullPointerException

This constructor initializes a newly created StringBufferInputStream so that it uses s as its buffer array. The initial value of pos is 0 and the initial value of count is the length of buffer.

22.7.5 public int read()

If pos equals count, then -1 is returned to indicate end of file. Otherwise, the value buffer[pos]&0xff is returned; just before the return, 1 is added to pos.

Implements the read method of InputStream (§22.3.1).

22.7.6 public int read(byte[] b, int off, int len)
throws NullPointerException, IndexOutOfBoundsException

If pos equals count, then -1 is returned to indicate end of file. Otherwise, the number k of bytes read is equal to the smaller of len and count-pos. If k is positive, then bytes buffer[pos] through buffer[pos+k-1] are copied into b[off] through b[off+k-1] in the manner performed by System.arraycopy (§20.18.16). The value k is added into pos and k is returned.

Overrides the read method of InputStream (§22.3.3).

22.7.7 public long skip(long n)

The actual number k of bytes to be skipped is equal to the smaller of n and count-pos. The value k is added into pos and k is returned.

Overrides the skip method of InputStream (§22.3.4).

22.7.8 public int available()

The quantity count-pos is returned.

Overrides the available method of InputStream (§22.3.5).

22.7.9 public void reset()

The value of pos is set to 0.

Overrides the reset method of InputStream (§22.3.8).


22.8 The Class java.io.SequenceInputStream

A SequenceInputStream represents the logical concatenation of other input streams. It starts out with an ordered collection of input streams and reads from the first one until end of file is reached, whereupon it reads from the second one, and so on, until end of file is reached on the last of the contained input streams.

public class SequenceInputStream extends InputStream {
    public SequenceInputStream(Enumeration e);
    public SequenceInputStream(InputStream s1, InputStream s2);
    public int read() throws IOException;
    public int read(byte[] buf, int pos, int len)
        throws IOException, NullPointerException,
            IndexOutOfBoundsException;
    public void close() throws IOException;
}

22.8.1 public SequenceInputStream(Enumeration e)

This constructor initializes a newly created SequenceInputStream by remembering the argument, which must be an Enumeration (§21.1) that produces objects whose run-time type is InputStream (§22.3). The input streams that are produced by the enumeration will be read, in order, to provide the bytes to be read from this SequenceInputStream. After each input stream from the enumeration is exhausted, it is closed by calling its close method.

22.8.2 public SequenceInputStream(InputStream s1,
InputStream s2)

This constructor initializes a newly created SequenceInputStream by remembering the two arguments, which will be read in order, first s1 and then s2, to provide the bytes to be read from this SequenceInputStream.

22.8.3 public int read() throws IOException

Implements the read method of InputStream (§22.3.1).

22.8.4 public int read(byte[] buf, int pos, int len)
throws IOException, NullPointerException, IndexOutOfBoundsException

Overrides the read method of InputStream (§22.3.3).

22.8.5 public void close() throws IOException

This SequenceInputStream is closed. A closed SequenceInputStream cannot perform input operations and cannot be reopened.

If this stream was created from an enumeration, all remaining elements are requested from the enumeration and closed before the close method returns.

Overrides the close method of InputStream (§22.3.6).


22.9 The Class java.io.FilterInputStream

A FilterInputStream contains some other input stream, which it uses as its basic source of data, possibly transforming the data along the way or providing additional functionality. The class FilterInputStream itself simply overrides all methods of InputStream with versions that pass all requests to the contained input stream. Subclasses of FilterInputStream may further override some of these methods and may also provide additional methods and fields.

public class FilterInputStream extends InputStream {
    protected InputStream in;
    protected FilterInputStream(InputStream in);
    public int read() throws IOException;
    public int read(byte[] b)
        throws IOException, NullPointerException;
    public int read(byte[] b, int off, int len)
        throws IOException, NullPointerException,
            IndexOutOfBoundsException;
    public long skip(long n) throws IOException;
    public int available() throws IOException;
    public void close() throws IOException;
    public void mark(int readlimit);
    public void reset() throws IOException;
    public boolean markSupported();
}

22.9.1 protected InputStream in;

The input stream to be filtered.

22.9.2 protected FilterInputStream(InputStream in)

This constructor initializes a newly created FilterInputStream by assigning the argument in to the field this.in so as to remember it for later use.

22.9.3 public int read() throws IOException

This method simply performs in.read() and returns the result.

Implements the read method of InputStream (§22.3.1).

22.9.4 public int read(byte[] b)
throws IOException, NullPointerException

This method simply performs the call read(b, 0, b.length) and returns the result. It is important that it does not do in.read(b) instead; certain subclasses of FilterInputStream depend on the implementation strategy actually used.

Overrides the read method of InputStream (§22.3.2).

22.9.5 public int read(byte[] b, int off, int len)
throws IOException, NullPointerException, IndexOutOfBoundsException

This method simply performs in.read(b, off, len) and returns the result.

Overrides the read method of InputStream (§22.3.3).

22.9.6 public long skip(long n) throws IOException

This method simply performs in.skip() and returns the result.

Overrides the skip method of InputStream (§22.3.4).

22.9.7 public int available() throws IOException

This method simply performs in.available() and returns the result.

Overrides the available method of InputStream (§22.3.5).

22.9.8 public void close() throws IOException

This method simply performs in.close().

Overrides the close method of InputStream (§22.3.6).

22.9.9 public void mark(int readlimit)

This method simply performs in.mark().

Overrides the mark method of InputStream (§22.3.7).

22.9.10 public void reset() throws IOException

This method simply performs in.reset().

Overrides the reset method of InputStream (§22.3.8).

22.9.11 public boolean markSupported()

This method simply performs in.markSupported() and returns whatever value is returned from that invocation.

Overrides the markSupported method of InputStream (§22.3.9).


22.10 The Class java.io.BufferedInputStream

A BufferedInputStream adds functionality to another input stream-namely, the ability to buffer the input and to support the mark and reset methods. When the BufferedInputStream is created, an internal buffer array is created. As bytes from the stream are read or skipped, the internal buffer is refilled as necessary from the contained input stream, many bytes at a time. The mark operation remembers a point in the input stream and the reset operation causes all the bytes read since the most recent mark operation to be reread before new bytes are taken from the contained input stream.

public class BufferedInputStream extends FilterInputStream {
    protected byte[] buf;
    protected int count = 0;
    protected int pos = 0;
    protected int markpos = -1;
    protected int marklimit = 0;
    public BufferedInputStream(InputStream in);
    public BufferedInputStream(InputStream in, int size);
    public int read() throws IOException;
    public int read(byte[] b)
        throws IOException, NullPointerException;
    public int read(byte[] b, int off, int len)
        throws IOException, NullPointerException,
            IndexOutOfBoundsException;
    public long skip(long n) throws IOException;
    public int available() throws IOException;
    public void mark(int readlimit);
    public void reset() throws IOException;
    public boolean markSupported();
}

22.10.1 protected byte[] buf;

The internal buffer array. When necessary, it may be replaced by another array of a different size.

22.10.2 protected int count = 0;

This value is always in the range 0 through buf.length; elements buf[0] through buf[count-1] contain buffered input data obtained from the underlying input stream.

22.10.3 protected int pos = 0;

This value is always in the range 0 through count. If it is less than count, then buf[pos] is the next byte to be supplied as input; if it is equal to count, then the next read or skip operation will require more bytes to be read from the contained input stream.

22.10.4 protected int markpos = -1;

This value is always in the range -1 through pos. If there is no marked position in the input stream, this field is -1. If there is a marked position in the input stream, then buf[markpos] is the first byte to be supplied as input after a reset operation. If markpos is not -1, then all bytes from positions buf[markpos] through buf[pos-1] must remain in the buffer array (though they may be moved to another place in the buffer array, with suitable adjustments to the values of count, pos, and markpos); they may not be discarded unless and until the difference between pos and markpos exceeds marklimit.

22.10.5 protected int marklimit;

Whenever the difference between pos and markpos exceeds marklimit, then the mark may be dropped by setting markpos to -1.

22.10.6 public BufferedInputStream(InputStream in)

This constructor initializes a newly created BufferedInputStream by saving its argument, the input stream in, for later use. An internal buffer array is created and stored in buf.

22.10.7 public BufferedInputStream(InputStream in, int size)

This constructor initializes a newly created BufferedInputStream by saving its argument, the input stream in, for later use. An internal buffer array of length size is created and stored in buf.

22.10.8 public int read() throws IOException

See the general contract of the read method of InputStream (§22.3.1).

Overrides the read method of FilterInputStream (§22.9.3).

22.10.9 public int read(byte[] b)
throws IOException, NullPointerException

See the general contract of the read method of InputStream (§22.3.2).

Overrides the read method of FilterInputStream (§22.9.4).

22.10.10 public int read(byte[] b, int off, int len)
throws IOException, NullPointerException, IndexOutOfBoundsException

See the general contract of the read method of InputStream (§22.3.3).

Overrides the read method of FilterInputStream (§22.9.5).

22.10.11 public long skip(long n) throws IOException

See the general contract of the skip method of InputStream (§22.3.4).

Overrides the skip method of FilterInputStream (§22.9.6).

22.10.12 public int available() throws IOException

See the general contract of the available method of InputStream (§22.3.5).

Overrides the available method of FilterInputStream (§22.9.7).

22.10.13 public void mark(int readlimit)

The field marklimit is set equal to the argument and markpos is set equal to pos

Overrides the mark method of FilterInputStream (§22.9.9).

22.10.14 public void reset() throws IOException

See the general contract of the reset method of InputStream (§22.3.8).

If markpos is -1 (no mark has been set or the mark has been invalidated), an IOException is thrown. Otherwise, pos is set equal to markpos.

Overrides the reset method of FilterInputStream (§22.9.10).

22.10.15 public boolean markSupported()

This method returns true (a BufferedInputStream always supports mark).

Overrides the markSupported method of FilterInputStream (§22.9.11).


22.11 The Class java.io.DataInputStream

A data input stream provides facilities for reading bytes from an input source and interpreting specific character sequences as representing data of diverse types.

public class DataInputStream extends FilterInputStream
        implements DataInput {
    public DataInputStream(InputStream in);
    public final void readFully(byte[] b)
        throws IOException, NullPointerException;
    public final void readFully(byte[] b, int off, int len)
        throws IOException, NullPointerException,
            IndexOutOfBoundsException;
    public final int skipBytes(int n) throws IOException;
    public final boolean readBoolean() throws IOException;
    public final byte readByte() throws IOException;
    public final int readUnsignedByte() throws IOException;
    public final short readShort() throws IOException;
    public final int readUnsignedShort() throws IOException;
    public final char readChar() throws IOException;
    public final int readInt() throws IOException;
    public final long readLong() throws IOException;
    public final float readFloat() throws IOException;
    public final double readDouble() throws IOException;
    public final String readLine() throws IOException;
    public final String readUTF() throws IOException;
    public final static String readUTF(DataInput in)
        throws IOException;
}

22.11.1 public DataInputStream(InputStream in)

This constructor initializes a newly created DataInputStream by saving its argument, the input stream in, for later use.

22.11.2 public final void readFully(byte[] b)
throws IOException, NullPointerException

See the general contract of the readFully method of DataInput (§22.1.1).

Bytes for this operation are read from the contained input stream.

22.11.3 public final void readFully(byte[] b, int off, int len)
throws IOException, NullPointerException, IndexOutOfBoundsException

See the general contract of the readFully method of DataInput (§22.1.2).

Bytes for this operation are read from the contained input stream.

22.11.4 public final int skipBytes(int n) throws IOException

See the general contract of the skipBytes method of DataInput (§22.1.3).

Bytes for this operation are read from the contained input stream.

22.11.5 public final boolean readBoolean() throws IOException

See the general contract of the readBoolean method of DataInput (§22.1.4).

The byte for this operation is read from the contained input stream.

22.11.6 public final byte readByte() throws IOException

See the general contract of the readByte method of DataInput (§22.1.5).

The byte for this operation is read from the contained input stream.

22.11.7 public final int readUnsignedByte() throws IOException

See the general contract of the readUnsignedByte method of DataInput (§22.1.6).

The byte for this operation is read from the contained input stream.

22.11.8 public final short readShort() throws IOException

See the general contract of the readShort method of DataInput (§22.1.7).

Bytes for this operation are read from the contained input stream.

22.11.9 public final int readUnsignedShort() throws IOException

See the general contract of the readUnsignedShort method of DataInput (§22.1.8).

Bytes for this operation are read from the contained input stream.

22.11.10 public final char readChar() throws IOException

See the general contract of the readChar method of DataInput (§22.1.9).

Bytes for this operation are read from the contained input stream.

22.11.11 public final int readInt() throws IOException

See the general contract of the readInt method of DataInput (§22.1.10).

Bytes for this operation are read from the contained input stream.

22.11.12 public final long readLong() throws IOException

See the general contract of the readLong method of DataInput (§22.1.11).

Bytes for this operation are read from the contained input stream.

22.11.13 public final float readFloat() throws IOException

See the general contract of the readFloat method of DataInput (§22.1.12).

Bytes for this operation are read from the contained input stream.

22.11.14 public final double readDouble() throws IOException

See the general contract of the readDouble method of DataInput (§22.1.13).

Bytes for this operation are read from the contained input stream.

22.11.15 public final String readLine() throws IOException

See the general contract of the readLine method of DataInput (§22.1.14).

Bytes for this operation are read from the contained input stream.

22.11.16 public final String readUTF() throws IOException

See the general contract of the readUTF method of DataInput (§22.1.15).

Bytes for this operation are read from the contained input stream.

22.11.17 public final static String readUTF(DataInput in)
throws IOException

The readUTF method reads from the stream in a representation of a Unicode character string encoded in Java modified UTF-8 format; this string of characters is then returned as a String. The details of the modified UTF-8 representation are exactly the same as for the readUTF method of DataInput (§22.1.15).


22.12 The Class java.io.LineNumberInputStream

A LineNumberInputStream adds functionality to another input stream, namely the ability to count lines. When the LineNumberInputStream is created, the line number counter is set to zero. As bytes from the stream are read or skipped, the counter is incremented whenever a line terminator (\n, \r, or \r\n) is encountered. Such line terminators are also converted to a single '\n' character. The method getLineNumber returns the current value of the counter, and the method setLineNumber sets the counter to a given integer value. If the contained input stream supports the mark operation, then so does the LineNumberInputStream; the mark operation remembers the line number counter and the reset operation sets the counter to the value remembered by the mark operation.

public class LineNumberInputStream extends FilterInputStream {
    public LineNumberInputStream(InputStream in);
    public int read() throws IOException;
    public int read(byte[] b)
        throws IOException, NullPointerException;
    public int read(byte[] b, int off, int len)

        throws IOException, NullPointerException,
            IndexOutOfBoundsException;
    public long skip(long n) throws IOException;
    public int available() throws IOException;
    public void mark(int readlimit);
    public void reset() throws IOException;
    public int getLineNumber();
    public void setLineNumber(int lineNumber);
}

22.12.1 public LineNumberInputStream(InputStream in)

This constructor initializes a newly created LineNumberInputStream by saving its argument, the input stream in, for later use.

22.12.2 public int read() throws IOException

See the general contract of the read method of InputStream (§22.3.1).

As bytes are read from the contained input stream, line terminators are recognized and counted. For each line terminator recognized in the contained input stream, a single character '\n' is returned.

Overrides the read method of FilterInputStream (§22.9.3).

22.12.3 public int read(byte[] b)
throws IOException, NullPointerException

See the general contract of the read method of InputStream (§22.3.2).

As bytes are read from the contained input stream, line terminators are recognized and counted. For each line terminator recognized in the contained input stream, a single character '\n' is returned.

Overrides the read method of FilterInputStream (§22.9.4).

22.12.4 public int read(byte[] b, int off, int len)
throws IOException, NullPointerException, IndexOutOfBoundsException

See the general contract of the read method of InputStream (§22.3.3).

As bytes are read from the contained input stream, line terminators are recognized and counted. For each line terminator recognized in the contained input stream, a single character '\n' is returned.

Overrides the read method of FilterInputStream (§22.9.5).

22.12.5 public long skip(long n) throws IOException

See the general contract of the skip method of InputStream (§22.3.4).

As bytes are read from the contained input stream, line terminators are recognized and counted. Each line terminator recognized in the contained input stream is considered to be a single byte skipped, even if it is the sequence \r\n.

Overrides the skip method of FilterInputStream (§22.9.6).

22.12.6 public int available() throws IOException

See the general contract of the available method of InputStream (§22.3.5).

Note that if the contained input stream is able to supply k input characters without blocking, the LineNumberInputStream can guarantee only to provide [image] characters without blocking, because the k characters from the contained input stream might consist of [image] \r\n pairs, which will be converted to just [image] '\n' characters.

Overrides the available method of FilterInputStream (§22.9.7).

22.12.7 public void mark(int readlimit)

See the general contract of the mark method of InputStream (§22.3.7).

Marking a point in the input stream remembers the current line number as it would be returned by getLineNumber (§22.12.9).

Overrides the mark method of FilterInputStream (§22.9.9).

22.12.8 public void reset() throws IOException

See the general contract of the reset method of InputStream (§22.3.8).

Resetting the input stream to a previous point also resets the line number to the value it had at the marked point.

Overrides the reset method of FilterInputStream (§22.9.10).

22.12.9 public int getLineNumber()

The current line number is returned. This quantity depends on k, the number of line terminators encountered since the most recent occurrence of one of the following three kinds of events:

  • If a call to the setLineNumber method was most recent, let n be the argument that was given to setLineNumber; then the current line number is [image].
  • If a call to the reset method was most recent, let m be the line number that had been remembered by mark; then the current line number is [image].
  • If creation of the LineNumberInputStream was most recent (that is, neither of the other kinds of event have occurred), then the current line number is k.

These rules imply that the current line number is 0 as the characters of the first line are read, and becomes 1 after the line terminator for the first line has been read.

22.12.10 public void setLineNumber(int lineNumber)

The current line number is set equal to the argument.


22.13 The Class java.io.PushbackInputStream

A PushbackInputStream adds functionality to another input stream, namely the ability to "push back" or "unread" one byte. This is useful in situations where it is convenient for a fragment of code to read an indefinite number of data bytes that are delimited by a particular byte value; after reading the terminating byte, the code fragment can "unread" it, so that the next read operation on the input stream will reread the byte that was pushed back. For example, bytes representing the characters constituting an identifier might be terminated by a byte representing an operator character; a method whose job is to read just an identifier can read until it sees the operator and then push the operator back to be re-read.

public class PushbackInputStream extends FilterInputStream {
    protected int	 pushBack = -1;
    public PushbackInputStream(InputStream in);
    public int read() throws IOException;
    public int read(byte[] bytes, int offset, int length)
        throws IOException, NullPointerException,
            IndexOutOfBoundsException;
    public void unread(int ch) throws IOException;
    public int available() throws IOException;
    public boolean markSupported();
}

22.13.1 protected int pushBack = -1;

If this field has a nonnegative value, it is a byte that was pushed back. If this field is -1, there is currently no pushed-back byte.

22.13.2 public PushbackInputStream(InputStream in)

This constructor initializes a newly created PushbackInputStream by saving its argument, the input stream in, for later use. Initially, there is no pushed-back byte (the field pushBack is initialized to -1).

22.13.3 public int read() throws IOException

See the general contract of the read method of InputStream (§22.3.1).

If pushBack is not -1, the value of pushBack is returned and pushBack is set to -1. Otherwise, a byte is obtained from the contained input stream.

Overrides the read method of FilterInputStream (§22.9.3).

22.13.4 public int read(byte[] bytes, int offset, int length) throws IOException, NullPointerException, IndexOutOfBoundsException

See the general contract of the read method of InputStream (§22.3.3).

If pushBack is not -1, it is used as an input byte (and pushBack is set to -1) before any bytes are read from the contained input stream.

Overrides the read method of FilterInputStream (§22.9.5).

22.13.5 public void unread(int b) throws IOException

If pushBack is not -1, an IOException is thrown (it is not permitted to push back more than one byte). Otherwise, the byte value b is pushed back by assigning b to pushBack.

22.13.6 public int available() throws IOException

See the general contract of the available method of InputStream (§22.3.1).

This method first calls the available method of the contained input stream. If pushBack is -1, the result is returned; otherwise, the result plus 1 is returned.

Overrides the available method of FilterInputStream (§22.9.7).

22.13.7 public boolean markSupported()

This method returns false (a PushbackInputStream does not support mark).


22.14 The Class java.io.StreamTokenizer

A StreamTokenizer takes an input stream and parses it into "tokens," allowing the tokens to be read one at a time. The parsing process is controlled by a table and a number of flags that can be set to various states, allowing recognition of identifiers, numbers, quoted strings, and comments in a standard style.

public class StreamTokenizer {
    public static final int TT_EOF = -1;
    public static final int TT_EOL = '\n';
    public static final int TT_NUMBER = -2;
    public static final int TT_WORD = -3;
    public int ttype;
    public String sval;
    public double nval;
    public StreamTokenizer (InputStream in);
    public void resetSyntax();
    public void wordChars(int low, int hi);
    public void whitespaceChars(int low, int hi);
    public void ordinaryChars(int low, int hi);
    public void ordinaryChar(int ch);
    public void commentChar(int ch);
    public void quoteChar(int ch);
    public void parseNumbers();
    public void eolIsSignificant(boolean flag);
    public void slashStarComments(boolean flag);
    public void slashSlashComments(boolean flag);
    public void lowerCaseMode(boolean flag);
    public int nextToken() throws IOException;
    public void pushBack();
    public int lineno();
    public String toString();
}

Each byte read from the input stream is regarded as a character in the range '\u0000' through '\u00FF'. The character value is used to look up five possible attributes of the character: whitespace, alphabetic, numeric, string quote, and comment character (a character may have more than one of these attributes, or none at all). In addition, there are three flags controlling whether line terminators are to be recognized as tokens, whether Java-style end-of-line comments that start with // should be recognized and skipped, and whether Java-style "traditional" comments delimited by /* and */ should be recognized and skipped. One more flag controls whether all the characters of identifiers are converted to lowercase.

Here is a simple example of the use of a StreamTokenizer. The following code merely reads all the tokens in the standard input stream and prints an identification of each one. Changes in the line number are also noted.

import java.io.StreamTokenizer;
import java.io.IOException;

class Tok {
    public static void main(String[] args) {
        StreamTokenizer st = new StreamTokenizer(System.in);
        st.ordinaryChar('/');
        int lineNum = -1;
        try {
            for (int tokenType = st.nextToken();
                    tokenType != StreamTokenizer.TT_EOF;
                    tokenType = st.nextToken()) {
                int newLineNum = st.lineno();
                if (newLineNum != lineNum) {
                    System.out.println("[line " + newLineNum
                                            + "]");
                    lineNum = newLineNum;
                }
                switch(tokenType) {
                case StreamTokenizer.TT_NUMBER:
                    System.out.println("the number " + st.nval);
                    break;
                case StreamTokenizer.TT_WORD:
                    System.out.println("identifier " + st.sval);
                    break;
                default:
                    System.out.println("  operator "
                                            + (char)tokenType);
                }
            }
        } catch (IOException e) {
            System.out.println("I/O failure");
        }
    }
}

If the input stream contains this data:

10 LET A = 4.5
20 LET B = A*A
30 PRINT A, B

then the resulting output is:

[line 1]
the number 10.0
identifier LET
identifier A
  operator =
the number 4.5
[line 2]
the number 20.0
identifier LET
identifier B
  operator =
identifier A
  operator *
identifier A
[line 3]
the number 30.0
identifier PRINT
identifier A
  operator ,
identifier B

22.14.1 public static final int TT_EOF = -1;

A constant that indicates end of file was reached.

22.14.2 public static final int TT_EOL = '\n';

A constant that indicates that a line terminator was recognized.

22.14.3 public static final int TT_NUMBER = -2;

A constant that indicates that a number was recognized.

22.14.4 public static final int TT_WORD = -3;

A constant that indicates that a word (identifier) was recognized.

22.14.5 public int ttype;

The type of the token that was last recognized by this StreamTokenizer. This will be TT_EOF, TT_EOL, TT_NUMBER, TT_WORD, or a nonnegative byte value that was the first byte of the token (for example, if the token is a string token, then ttype has the quote character that started the string).

22.14.6 public String sval;

If the value of ttype is TT_WORD or a string quote character, then the value of sval is a String that contains the characters of the identifier or of the string (without the delimiting string quotes). For all other types of tokens recognized, the value of sval is null.

22.14.7 public double nval;

If the value of ttype is TT_NUMBER, then the value of nval is the numerical value of the number.

22.14.8 public StreamTokenizer(InputStream in)

This constructor initializes a newly created StreamTokenizer by saving its argument, the input stream in, for later use. The StreamTokenizer is also initialized to the following default state:

  • All byte values 'A' through 'Z', 'a' through 'z', and 0xA0 through 0xFF are considered to be alphabetic.
  • All byte values 0x00 through 0x20 are considered to be whitespace.
  • '/' is a comment character.
  • Single quote '\'' and double quote '"' are string quote characters.
  • Numbers are parsed.
  • End of line is not significant.
  • // comments and /* comments are not recognized.

22.14.9 public void resetSyntax()

The syntax table for this StreamTokenizer is reset so that every byte value is "ordinary"; thus, no character is recognized as being a whitespace, alphabetic, numeric, string quote, or comment character. Calling this method is therefore equivalent to:

ordinaryChars(0x00, 0xff)

The three flags controlling recognition of line terminators, // comments, and /* comments are unaffected.

22.14.10 public void wordChars(int low, int hi)

The syntax table for this StreamTokenizer is modified so that every character in the range low through hi has the "alphabetic" attribute.

22.14.11 public void whitespaceChars(int low, int hi)

The syntax table for this StreamTokenizer is modified so that every character in the range low through hi has the "whitespace" attribute.

22.14.12 public void ordinaryChars(int low, int hi)

The syntax table for this StreamTokenizer is modified so that every character in the range low through hi has no attributes.

22.14.13 public void ordinaryChar(int ch)

The syntax table for this StreamTokenizer is modified so that the character ch has no attributes.

22.14.14 public void commentChar(int ch)

The syntax table for this StreamTokenizer is modified so that the character ch has the "comment character" attribute.

22.14.15 public void quoteChar(int ch)

The syntax table for this StreamTokenizer is modified so that the character ch has the "string quote" attribute.

22.14.16 public void parseNumbers()

The syntax table for this StreamTokenizer is modified so that each of the twelve characters

0 1 2 3 4 5 6 7 8 9 . -

has the "numeric" attribute.

22.14.17 public void eolIsSignificant(boolean flag)

This StreamTokenizer henceforth recognizes line terminators as tokens if and only if the flag argument is true.

22.14.18 public void slashStarComments(boolean flag)

This StreamTokenizer henceforth recognizes and skips Java-style "traditional" comments, which are delimited by /* and */ and do not nest, if and only if the flag argument is true.

22.14.19 public void slashSlashComments(boolean flag)

This StreamTokenizer henceforth recognizes and skips Java-style end-of-line comments that start with // if and only if the flag argument is true.

22.14.20 public void lowerCaseMode(boolean flag)

This StreamTokenizer henceforth converts all the characters in identifiers to lowercase if and only if the flag argument is true.

22.14.21 public int nextToken() throws IOException

If the previous token was pushed back (§22.14.22), then the value of ttype is returned, effectively causing that same token to be reread.

Otherwise, this method parses the next token in the contained input stream. The type of the token is returned; this same value is also made available in the ttype field, and related data may be made available in the sval and nval fields.

First, whitespace characters are skipped, except that if a line terminator is encountered and this StreamTokenizer is currently recognizing line terminators, then the type of the token is TT_EOL.

If a numeric character is encountered, then an attempt is made to recognize a number. If the first character is '-' and the next character is not numeric, then the '-' is considered to be an ordinary character and is recognized as a token in its own right. Otherwise, a number is parsed, stopping before the next occurrence of '-', the second occurrence of '.', the first nonnumeric character encountered, or end of file, whichever comes first. The type of the token is TT_NUMBER and its value is made available in the field nval.

If an alphabetic character is encountered, then an identifier is recognized, consisting of that character and all following characters up to, but not including, the first character that is neither alphabetic nor numeric, or up to end of file, whichever comes first. The characters of the identifier may be converted to lowercase if this StreamTokenizer is in lowercase mode.

If a comment character is encountered, then all subsequent characters are skipped and ignored, up to but not including the next line terminator or end of file. Then another attempt is made to recognize a token. If this StreamTokenizer is currently recognizing line terminators, then a line terminator that ends a comment will be recognized as a token in the same manner as any other line terminator in the contained input stream.

If a string quote character is encountered, then a string is recognized, consisting of all characters after (but not including) the string quote character, up to (but not including) the next occurrence of that same string quote character, or a line terminator, or end of file. The usual escape sequences (§3.10.6) such as \n and \t are recognized and converted to single characters as the string is parsed.

If // is encountered and this StreamTokenizer is currently recognizing // comments, then all subsequent characters are skipped and ignored, up to but not including the next line terminator or end of file. Then another attempt is made to recognize a token. (If this StreamTokenizer is currently recognizing line terminators, then a line terminator that ends a comment will be recognized as a token in the same manner as any other line terminator in the contained input stream.)

If /* is encountered and this StreamTokenizer is currently recognizing /* comments, then all subsequent characters are skipped and ignored, up to and including the next occurrence of */ or end of file. Then another attempt is made to recognize a token.

If none of the cases listed above applies, then the only other possibility is that the first non-whitespace character encountered is an ordinary character. That character is considered to be a token and is stored in the ttype field and returned.

22.14.22 public void pushBack()

Calling this method "pushes back" the current token; that is, it causes the next call to nextToken to return the same token that it just provided. Note that this method does not restore the line number to its previous value, so if the method lineno is called after a call to pushBack but before the next call to nextToken, an incorrect line number may be returned.

22.14.23 public int lineno()

The number of the line on which the current token appeared is returned. The first token in the input stream, if not a line terminator, is considered to appear on line 1. A line terminator token is considered to appear on the line that it precedes, not on the line it terminates; thus, the first line terminator in the input stream is considered to be on line 2.

22.14.24 public String toString()

The current token and the current line number are converted to a string of the form:

"Token[x], line m"

where m is the current line number in decimal form and x depends on the type of the current token:

  • If the token type is TT_EOF, then x is "EOF".
  • If the token type is TT_EOL, then x is "EOL".
  • If the token type is TT_WORD, then x is the current value of sval (§22.14.6).
  • If the token type is TT_NUMBER, then x is "n=" followed by the result of converting the current value of nval (§22.14.7) to a string (§20.10.15).

Overrides the toString method of Object (§20.1.2).


22.15 The Class java.io.OutputStream

An output stream accepts output bytes and sends them to some sink.

public abstract class OutputStream {
    public abstract void write(int b) throws IOException;
    public void write(byte[] b)
        throws IOException, NullPointerException;
    public void write(byte[] b, int off, int len)
        throws IOException, NullPointerException,
            IndexOutOfBoundsException;
    public void flush() throws IOException;
    public void close() throws IOException;
}

22.15.1 public abstract void write(int b) throws IOException

The general contract for write is that one byte is written to the output stream. The byte to be written is the eight low-order bits of the argument b. The 24 high-order bits of b are ignored.

If the byte cannot be written for any reason, an IOException is thrown. In particular, an IOException may be thrown if the output stream has been closed (§22.15.5).

22.15.2 public void write(byte[] b)
throws IOException, NullPointerException

The general contract for write(b) is that it should have exactly the same effect as the call write(b, 0, b.length) (§22.15.3).

The write(b) method for class OutputStream in fact makes such a call.

22.15.3 public void write(byte[] b, int off, int len)
throws IOException, NullPointerException, IndexOutOfBoundsException

The general contract for write(b, off, len) is that some of the bytes in the array b are written to the output stream as if one at a time, in order; element b[off] is the first byte written and b[off+len-1] is the last byte written by this operation.

If b is null, a NullPointerException is thrown.

If off is negative, or len is negative, or off+len is greater than the length of the array b, then an IndexOutOfBoundsException is thrown.

If the byte cannot be written for any reason, an IOException is thrown. In particular, an IOException is thrown if the output stream has been closed (§22.15.5).

The write(b, off, len) method for class OutputStream simply calls the method write (§22.15.1) repeatedly, once for each byte in b to be written.

22.15.4 public void flush() throws IOException

The general contract of flush is that calling it is an indication that, if any bytes previously written have been buffered by the implementation of the output stream, such bytes should immediately be written to their intended destination.

The flush method for class OutputStream does nothing and simply returns.

22.15.5 public void close() throws IOException

The general contract of close is that it closes the output stream. A closed stream cannot perform output operations and cannot be reopened.

The close method for class OutputStream does nothing and simply returns.


22.16 The Class java.io.FileOutputStream

A file output stream writes output bytes to a file in a file system. What files are available or may be created depends on the host environment.

public class FileOutputStream extends OutputStream {
    public FileOutputStream(String path)
        throws SecurityException, FileNotFoundException;
    public FileOutputStream(File file)
        throws SecurityException, FileNotFoundException;
    public FileOutputStream(FileDescriptor fdObj)
        throws SecurityException;
    public void write(int b) throws IOException;
    public void write(byte[] b)
        throws IOException, NullPointerException;
    public void write(byte[] b, int off, int len)
        throws IOException, NullPointerException,
            IndexOutOfBoundsException;
    public void close() throws IOException;
    public final FileDescriptor getFD() throws IOException;
    protected void finalize() throws IOException;
}

22.16.1 public FileOutputStream(String path)
throws SecurityException, FileNotFoundException

This constructor initializes a newly created FileOutputStream by opening a connection to an actual file, the file named by the path name path in the file system. A new FileDescriptor object is created to represent this file connection.

First, if there is a security manager, its checkWrite method (§20.17.21) is called with the path argument as its argument.

If the actual file cannot be opened, a FileNotFoundException is thrown.

22.16.2 public FileOutputStream(File file)
throws SecurityException, FileNotFoundException

This constructor initializes a newly created FileOutputStream by opening a connection to an actual file, the file named by file in the file system. A new FileDescriptor object is created to represent this file connection.

First, if there is a security manager, its checkWrite method (§20.17.21) is called with the path represented by the file argument as its argument.

If the actual file cannot be opened, a FileNotFoundException is thrown.

22.16.3 public FileOutputStream(FileDescriptor fdObj)
throws SecurityException

This constructor initializes a newly created FileOutputStream by using the file descriptor fdObj, which represents an existing connection to an actual file in the file system.

First, if there is a security manager, its checkWrite method (§20.17.20) is called with the file descriptor fdObj argument as its argument.

22.16.4 public final FileDescriptor getFD() throws IOException

This method returns the FileDescriptor object (§22.26) that represents the connection to the actual file in the file system being used by this FileOutputStream.

22.16.5 public void write(int b) throws IOException

The byte for this operation is written to the actual file to which this file output stream is connected.

Implements the write method of OutputStream (§22.15.1).

22.16.6 public void write(byte[] b)
throws IOException, NullPointerException

Bytes for this operation are written to the actual file to which this file output stream is connected.

Overrides the write method of OutputStream (§22.15.2).

22.16.7 public void write(byte[] b, int off, int len)
throws IOException, NullPointerException, IndexOutOfBoundsException

Bytes for this operation are written to the actual file to which this file output stream is connected.

Overrides the write method of OutputStream (§22.15.3).

22.16.8 public void close() throws IOException

This file output stream is closed and may no longer be used for writing bytes.

Overrides the close method of OutputStream (§22.15.5).

22.16.9 protected void finalize() throws IOException

A FileOutputStream uses finalization to clean up the connection to the actual file.


22.17 The Class java.io.PipedOutputStream

A piped output stream should be connected to a piped input stream; the piped input stream then provides whatever data bytes are written to the piped output stream. Typically, data is written to a PipeOutputStream object by one thread and data is read from the corresponding PipedInputStream (§22.5) by some other thread. Attempting to use both objects from a single thread is not recommended, as it may deadlock the thread.

public class PipedOutputStream extends OutputStream {
    public PipedOutputStream(PipedInputStream snk)
        throws IOException;
    public PipedOutputStream();
    public void connect(PipedInputStream snk)
        throws IOException;
    public void write(int b) throws IOException;
    public void write(byte[] b, int off, int len)
        throws IOException, NullPointerException,
            IndexOutOfBoundsException;
    public void close() throws IOException;
}

22.17.1 public PipedOutputStream(PipedInputStream snk)
throws IOException

This constructor initializes a newly created PipedOutputStream so that it is connected to the piped input stream snk. Data bytes written to this stream will then be available as input from snk.

22.17.2 public PipedOutputStream()

This constructor initializes a newly created PipedOutputStream so that it is not yet connected. It must be connected to a PipedInputStream before being used.

22.17.3 public void connect(PipedInputStream snk)
throws IOException

The connect method causes this piped output stream to be connected to the piped input stream snk. If this object is already connected to some other piped input stream, an IOException is thrown.

If snk is an unconnected piped input stream and src is an unconnected piped output stream, they may be connected by either the call:

src.connect(snk)

or the call:

snk.connect(src)

The two calls have the same effect.

22.17.4 public void write(int b) throws IOException

If a thread was reading data bytes from the connected piped input stream, but the thread is no longer alive, then an IOException is thrown.

Implements the write method of OutputStream (§22.15.1).

22.17.5 public void write(byte[] b, int off, int len)
throws IOException, NullPointerException, IndexOutOfBoundsException

If a thread was reading data bytes from the connected piped input stream, but the thread is no longer alive, then an IOException is thrown.

Overrides the write method of OutputStream (§22.15.3).

22.17.6 public void close() throws IOException

This piped output stream is closed and may no longer be used for writing bytes.

Overrides the close method of OutputStream (§22.15.5).


22.18 The Class java.io.ByteArrayOutputStream

A ByteArrayOutputStream contains an internal buffer that accumulates all the bytes written to the stream since its creation or the most recent call to the reset method. At any point, the bytes written to the stream so far may be retrieved in the form of an array of bytes or a String. The bytes written so far may also be copied to some other output stream. The size method returns the number of characters written so far.

public class ByteArrayOutputStream extends OutputStream {
    protected byte[] buf;
    protected int count;
    public ByteArrayOutputStream();
    public ByteArrayOutputStream(int size);
    public void write(int b);
    public void write(byte[] b, int off, int len)
        throws NullPointerException, IndexOutOfBoundsException;
    public int size();
    public void reset();
    public byte[] toByteArray();
    public String toString();
    public String toString(int hibyte);
    public void writeTo(OutputStream out) throws IOException;
}

22.18.1 protected byte[] buf;

An internal array of bytes. Elements buf[0] through buf[count-1] are the bytes that have been written to the stream since its creation or the last reset (§22.18.8) operation.

22.18.2 protected int count;

This value should always be nonnegative. It is the number of bytes that have been written to the stream since its creation or the last reset (§22.18.8) operation.

22.18.3 public ByteArrayOutputStream()

This constructor initializes a newly created ByteArrayOutputStream so that its internal buffer array has length 32.

22.18.4 public ByteArrayOutputStream(int size)

This constructor initializes a newly created ByteArrayOutputStream so that its internal buffer array has length size. This matters only for reasons of efficiency; the buffer array is replaced by a larger one whenever necessary to accommodate additional bytes written to the stream.

22.18.5 public void write(int b)

One byte is added on the internal buffer. The byte to be added is the eight low- order bits of the argument n. The 24 high-order bits of n are ignored.

Implements the write method of OutputStream (§22.15.1).

22.18.6 public void write(byte[] b, int off, int len)
throws NullPointerException, IndexOutOfBoundsException

Elements b[off] through b[off+len-1] are appended to the internal buffer.

If b is null, a NullPointerException is thrown.

If off is negative, or len is negative, or off+len is greater than the length of the array b, then an IndexOutOfBoundsException is thrown.

Overrides the write method of OutputStream (§22.15.3).

22.18.7 public int size()

The current value of count is returned.

22.18.8 public void reset()

The internal variable count is reset to zero, thereby logically discarding all bytes written to the stream so far. However, the internal buffer array, which may be quite large, remains as it is.

22.18.9 public byte[] toByteArray()

A new array of bytes is created and returned. Its length is equal to the current value of count. Its initial contents are copies of the bytes written to the stream so far-that is, elements 0 through count-1 of buf.

22.18.10 public String toString()

A new String is created and returned. Its length is equal to the current value of count. Its initial contents are copies of the bytes written to the stream so far-that is, elements 0 through count-1 of buf, zero-extended to produce characters. Thus, tostring() has the same effect as toString(0) (§22.18.11).

Overrides the toString method of Object (§20.1.2).

22.18.11 public String toString(int hibyte)

A new array of bytes is created and returned. Its length is equal to the current value of count. Its initial contents are copies of the bytes written to the stream so far-that is, elements 0 through count-1 of buf-with hibyte supplying the high-order eight bits of each character. Thus, character k of the result is equal to:

((hibyte & 0xff) << 8) | (buf[k] & 0xff)

See the String constructor that accepts a hibyte argument (§20.12.6).

22.18.12 public void writeTo(OutputStream out) throws IOException

The current contents of the internal buffer are written to the output stream out by the call:

out.write(buf, 0, count)

Note that if out is the same as this, the effect is simply to append to the buffer a copy of its current contents, thereby doubling the number of buffered bytes. This may not be a particularly useful effect; the point is merely that the operation does terminate, having had a sensible effect, rather than running off into an endless loop.


22.19 The Class java.io.FilterOutputStream

A FilterOutputStream contains some other output stream, which it uses as its basic sink of data, possibly transforming the data along the way or providing additional functionality. The class FilterOutputStream itself simply overrides all methods of OutputStream with versions that pass all requests to the contained output stream. Subclasses of FilterOutputStream may further override some of these methods and may also provide additional methods and fields.

public class FilterOutputStream extends OutputStream {
    protected OutputStream out;
    public FilterOutputStream(OutputStream out);
    public void write(int b) throws IOException;
    public void write(byte[] b)
        throws IOException, NullPointerException;
    public void write(byte[] b, int off, int len)

        throws IOException, NullPointerException,
            IndexOutOfBoundsException;
    public void flush() throws IOException;
    public void close() throws IOException;
}

22.19.1 protected OutputStream out;

The output stream to be filtered.

22.19.2 public FilterOutputStream(OutputStream out)

This constructor initializes a newly created FilterInputStream by assigning the argument out to the field this.out so as to remember it for later use.

22.19.3 public void write(int b) throws IOException

This method simply performs out.write(b).

Implements the abstract write method of OutputStream (§22.15.1).

22.19.4 public void write(byte[] b)
throws IOException, NullPointerException

This method simply performs out.write(b).

Overrides the write method of OutputStream (§22.15.2).

22.19.5 public void write(byte[] b, int off, int len)
throws IOException, NullPointerException, IndexOutOfBoundsException

This method simply performs out.write(b, off, len).

Overrides the write method of OutputStream (§22.15.3).

22.19.6 public void flush() throws IOException

This method simply performs out.flush().

Overrides the flush method of OutputStream (§22.15.4).

22.19.7 public void close() throws IOException

This method simply performs out.close().

Overrides the close method of OutputStream (§22.15.5).


22.20 The Class java.io.BufferedOutputStream

A BufferedOutputStream adds functionality to another output stream, namely the ability to buffer the output. When the BufferedOutputStream is created, an internal buffer array is created. As bytes are written to the stream, they are stored in the internal buffer, which is flushed as necessary, thereby performing output to the contained output stream in large blocks rather than a byte at a time.

public class BufferedOutputStream extends FilterOutputStream {
    protected byte[] buf;
    protected int count;
    public BufferedOutputStream(OutputStream out);
    public BufferedOutputStream(OutputStream out, int size);
    public void write(int b) throws IOException;
    public void write(byte[] b)
        throws IOException, NullPointerException;
    public void write(byte[] b, int off, int len)
        throws IOException, NullPointerException,
            IndexOutOfBoundsException;
    public void flush() throws IOException;
}

22.20.1 protected byte[] buf;

The internal buffer array.

22.20.2 protected int count;

This value is always in the range 0 through buf.length; elements buf[0] through buf[count-1] contain valid byte data.

22.20.3 public BufferedOutputStream(OutputStream out)

This constructor initializes a newly created BufferedOutputStream by saving its argument, the input stream out, for later use. An internal buffer array is created and stored in buf.

22.20.4 public BufferedOutputStream(OutputStream out, int size)

This constructor initializes a newly created BufferedOutputStream by saving its argument, the input stream out, for later use. An internal buffer array of length size is created and stored in buf.

22.20.5 public void write(int b) throws IOException

See the general contract of the write method of OutputStream (§22.15.1).

Overrides the write method of FilterOutputStream (§22.19.3).

22.20.6 public void write(byte[] b)
throws IOException, NullPointerException

See the general contract of the write method of OutputStream (§22.15.2).

Overrides the write method of FilterOutputStream (§22.19.4).

22.20.7 public void write(byte[] b, int off, int len)
throws IOException, NullPointerException, IndexOutOfBoundsException

See the general contract of the write method of OutputStream (§22.15.3).

Overrides the write method of FilterOutputStream (§22.19.5).

22.20.8 public void flush() throws IOException

See the general contract of the flush method of OutputStream (§22.15.4).

Overrides the flush method of FilterOutputStream (§22.19.6).


22.21 The Class java.io.DataOutputStream

A data output stream provides facilities for converting data of diverse types into character sequence of specific formats that are then sent to some output stream.

public class DataOutputStream extends FilterOutputStream
        implements DataOutput {
    protected int written;
    public DataOutputStream(OutputStream out);
    public void write(int b) throws IOException;
    public void write(byte[] b, int off, int len)
        throws IOException, NullPointerException,
            IndexOutOfBoundsException;
    public void flush() throws IOException;
    public final void writeBoolean(boolean v) throws IOException;
    public final void writeByte(int v) throws IOException;
    public final void writeShort(int v) throws IOException;
    public final void writeChar(int v) throws IOException;
    public final void writeInt(int v) throws IOException;
    public final void writeLong(long v) throws IOException;
    public final void writeFloat(float v) throws IOException;
    public final void writeDouble(double v) throws IOException;
    public final void writeBytes(String s)
        throws IOException, NullPointerException;
    public final void writeChars(String s)
        throws IOException, NullPointerException;
    public final void writeUTF(String str)
        throws IOException, NullPointerException;
    public final int size();
}

22.21.1 protected int written;

This field contains the number of bytes written to the stream so far.

22.21.2 public DataOutputStream(OutputStream out)

This constructor initializes a newly created DataOutputStream by saving its argument, the output stream out, for later use. The counter written is set to zero.

22.21.3 public void write(int b) throws IOException

The byte for this operation (the low eight bits of the argument b) is written to the contained output stream. If no exception is thrown, the counter written is incremented by 1.

Implements the write method of OutputStream (§22.15.1).

22.21.4 public void write(byte[] b, int off, int len)
throws IOException, NullPointerException, IndexOutOfBoundsException

Bytes for this operation are written to the contained output stream. If no exception is thrown, the counter written is incremented by len.

Overrides the write method of OutputStream (§22.15.3).

22.21.5 public void flush() throws IOException

The contained output stream is flushed.

Overrides the flush method of OutputStream (§22.15.4).

22.21.6 public final void writeBoolean(boolean v)
throws IOException

See the general contract of the writeBoolean method of DataOutput (§22.2.4).

The byte for this operation is written to the contained output stream. If no exception is thrown, the counter written is incremented by 1.

22.21.7 public final void writeByte(int v) throws IOException

See the general contract of the writeByte method of DataOutput (§22.2.5).

The byte for this operation is written to the contained output stream. If no exception is thrown, the counter written is incremented by 1.

22.21.8 public final void writeShort(int v) throws IOException

See the general contract of the writeShort method of DataOutput (§22.2.6).

Bytes for this operation are written to the contained output stream. If no exception is thrown, the counter written is incremented by 2.

22.21.9 public final void writeChar(int v) throws IOException

See the general contract of the writeChar method of DataOutput (§22.2.7).

Bytes for this operation are written to the contained output stream. If no exception is thrown, the counter written is incremented by 2.

22.21.10 public final void writeInt(int v) throws IOException

See the general contract of the writeInt method of DataOutput (§22.2.8).

Bytes for this operation are written to the contained output stream. If no exception is thrown, the counter written is incremented by 4.

22.21.11 public final void writeLong(long v) throws IOException

See the general contract of the writeLong method of DataOutput (§22.2.9).

Bytes for this operation are written to the contained output stream. If no exception is thrown, the counter written is incremented by 8.

22.21.12 public final void writeFloat(float v) throws IOException

See the general contract of the writeFloat method of DataOutput (§22.2.10).

Bytes for this operation are written to the contained output stream. If no exception is thrown, the counter written is incremented by 4.

22.21.13 public final void writeDouble(double v) throws IOException

See the general contract of the writeDouble method of DataOutput (§22.2.11).

Bytes for this operation are written to the contained output stream. If no exception is thrown, the counter written is incremented by 8.

22.21.14 public final void writeBytes(String s)
throws IOException, NullPointerException, IndexOutOfBoundsException

See the general contract of the writeBytes method of DataOutput (§22.2.12).

Bytes for this operation are written to the contained output stream. If no exception is thrown, the counter written is incremented by the length of s.

22.21.15 public final void writeChars(String s)
throws IOException, NullPointerException, IndexOutOfBoundsException

See the general contract of the writeChars method of DataOutput (§22.2.13).

Bytes for this operation are written to the contained output stream. If no exception is thrown, the counter written is incremented by twice the length of s.

22.21.16 public final void writeUTF(String str)
throws IOException, NullPointerException, IndexOutOfBoundsException

See the general contract of the writeUTF method of DataOutput (§22.2.14).

Bytes for this operation are written to the contained output stream. If no exception is thrown, the counter written is incremented by the total number of bytes written to the output stream. This will be at least two plus the length of s, and at most two plus thrice the length of s.

22.21.17 public final int size()

The size method returns the current value of the counter written, the number of bytes written to the stream so far.


22.22 The Class java.io.PrintStream

A PrintStream adds functionality to another output stream-namely, the ability to print representations of various data values conveniently. Two other features are provided as well. Unlike other output streams, a PrintStream never throws an IOException; instead, exceptional situations merely set an internal flag that can be tested by the checkError method. Optionally, a PrintStream can be created so as to "autoflush"; this means that after an array of bytes is written, or after a single byte equal to '\n' is written, the flush method is automatically invoked.

public class PrintStream extends FilterOutputStream {
    public PrintStream(OutputStream out);
    public PrintStream(OutputStream out, boolean autoflush);
    public void write(int b);
    public void write(byte[] b, int off, int len)
        throws NullPointerException, IndexOutOfBoundsException;
    public void flush();
    public void close();
    public boolean checkError();
    public void print(Object obj);
    public void print(String s);
    public void print(char[] s) throws NullPointerException;
    public void print(char c);
    public void print(int i);
    public void print(long l);
    public void print(float f);
    public void print(double d);
    public void print(boolean b);
    public void println();
    public void println(Object obj);
    public void println(String s);
    public void println(char[] s) throws NullPointerException;
    public void println(char c);
    public void println(int i);
    public void println(long l);
    public void println(float f);
    public void println(double d);
    public void println(boolean b);
}

22.22.1 public PrintStream(OutputStream out)

This constructor initializes a newly created PrintStream by saving its argument, the output stream out, for later use. This stream will not autoflush.

22.22.2 public PrintStream(OutputStream out, boolean autoflush)

This constructor initializes a newly created PrintStream by saving its argument, the output stream out, for later use. This stream will autoflush if and only if autoflush is true.

22.22.3 public void write(int b)

See the general contract of the write method of OutputStream (§22.15.1).

Overrides the write method of FilterOutputStream (§22.19.3).

22.22.4 public void write(byte[] b, int off, int len)
throws NullPointerException, IndexOutOfBoundsException

See the general contract of the write method of OutputStream (§22.15.3).

Overrides the write method of FilterOutputStream (§22.19.5).

22.22.5 public void flush()

See the general contract of the flush method of OutputStream (§22.15.4).

Overrides the flush method of FilterOutputStream (§22.19.6).

22.22.6 public void close()

See the general contract of the close method of OutputStream (§22.15.5).

Overrides the close method of FilterOutputStream (§22.19.7).

22.22.7 public boolean checkError()

The result is true if and only if this output stream has ever encountered any kind of trouble-that is, if any operation on the contained output stream has ever resulted in an IOException other than an InterruptedIOException. If an operation on the contained output stream throws an InterruptedIOException, then the PrintStream class converts the exception back to an interrupt by doing:

Thread.currentThread().interrupt();

or the equivalent.

22.22.8 public void print(Object obj)

The low-order bytes of the characters in the String that would be produced by String.valueOf(obj) (§20.12.38) are written, in order, to the contained output stream in exactly the manner of the write method (§22.22.3).

22.22.9 public void print(String s)

The low-order bytes of the characters in the string s are written, in order, to the contained output stream in exactly the manner of the write method (§22.22.3). If s is null, then the low-order bytes of the four characters n, u, l, l are written to the contained output stream.

22.22.10 public void print(char[] s) throws NullPointerException

The low-order bytes of the characters in the character array s are written, in order, to the contained output stream in exactly the manner of the write method (§22.22.3).

If s is null, a NullPointerException is thrown.

22.22.11 public void print(boolean b)

The low-order bytes of the characters in the String that would be produced by String.valueOf(b) (§20.12.41) as a string are written, in order, to the contained output stream in exactly the manner of the write method (§22.22.3).

22.22.12 public void print(char c)

The low-order byte of the character c is written to the contained output stream in exactly the manner of the write method (§22.22.3).

22.22.13 public void print(int i)

The low-order bytes of the characters in the String that would be produced by String.valueOf(i) (§20.12.43) as a string are written, in order, to the contained output stream in exactly the manner of the write method (§22.22.3).

22.22.14 public void print(long l)

The low-order bytes of the characters in the String that would be produced by String.valueOf(l) (§20.12.44) as a string are written, in order, to the contained output stream in exactly the manner of the write method (§22.22.3).

22.22.15 public void print(float f)

The low-order bytes of the characters in the String that would be produced by String.valueOf(f) (§20.12.45) as a string are written, in order, to the contained output stream in exactly the manner of the write method (§22.22.3).

22.22.16 public void print(double d)

The low-order bytes of the characters in the String that would be produced by String.valueOf(d) (§20.12.46) as a string are written, in order, to the contained output stream in exactly the manner of the write method (§22.22.3).

22.22.17 public void println()

The low-order byte of the newline character '\n' is written to the contained output stream in exactly the manner of the write method (§22.22.3).

22.22.18 public void println(Object obj)

This is exactly the same as print(obj) (§22.22.8) followed by writing the low- order byte of the newline character '\n' to the contained output stream.

22.22.19 public void println(String s)

This is exactly the same as print(s) (§22.22.9) followed by writing the low- order byte of the newline character '\n' to the contained output stream.

22.22.20 public void println(char[] s) throws NullPointerException

This is exactly the same as print(s) (§22.22.10) followed by writing the low- order byte of the newline character '\n' to the contained output stream.

If s is null, a NullPointerException is thrown.

22.22.21 public void println(boolean b)

This is exactly the same as print(b) (§22.22.11) followed by writing the low- order byte of the newline character '\n' to the contained output stream.

22.22.22 public void println(char c)

This is exactly the same as print(c) (§22.22.12) followed by writing the low- order byte of the newline character '\n' to the contained output stream.

22.22.23 public void println(int i)

This is exactly the same as print(i) (§22.22.13) followed by writing the low- order byte of the newline character '\n' to the contained output stream.

22.22.24 public void println(long l)

This is exactly the same as print(l) (§22.22.14) followed by writing the low- order byte of the newline character '\n' to the contained output stream.

22.22.25 public void println(float f)

This is exactly the same as print(f) (§22.22.15) followed by writing the low- order byte of the newline character '\n' to the contained output stream.

22.22.26 public void println(double d)

This is exactly the same as print(d) (§22.22.16) followed by writing the low- order byte of the newline character '\n' to the contained output stream.


22.23 The Class java.io.RandomAccessFile

A random access file behaves like a large array of bytes stored in the file system. There is a kind of cursor, or index into the implied array, called the file pointer; input operations read bytes starting at the file pointer and advance the file pointer past the bytes read. If the random access file is created in read/write mode, then output operations are also available; output operations write bytes starting at the file pointer and advance the file pointer past the bytes written. Output operations that write past the current end of the implied array cause the array to be extended. The file pointer can be read by the getFilePointer method and set by the seek method.

public class RandomAccessFile implements DataOutput, DataInput {
    public RandomAccessFile(String path, String mode)
        throws SecurityException, IOException,
            IllegalArgumentException;
    public RandomAccessFile(File file, String mode)
        throws SecurityException, IOException,
            IllegalArgumentException;
    public final FileDescriptor getFD() throws IOException;
    public native long getFilePointer() throws IOException;
    public native void seek(long pos) throws IOException;
    public native long length() throws IOException;
    public native void close() throws IOException;
    public native int read() throws IOException;
    public int read(byte[] b)
        throws IOException, NullPointerException;
    public int read(byte[] b, int off, int len)
        throws IOException, NullPointerException,
            IndexOutOfBoundsException;
    // The methods that implement interface DataInput:
    public final void readFully(byte[] b)
        throws IOException, NullPointerException;
    public final void readFully(byte[] b, int off, int len)
        throws IOException, NullPointerException,
            IndexOutOfBoundsException;
    public int skipBytes(int n) throws IOException;
    public final boolean readBoolean() throws IOException;
    public final byte readByte() throws IOException;
    public final int readUnsignedByte() throws IOException;
    public final short readShort() throws IOException;
    public final int readUnsignedShort() throws IOException;
    public final char readChar() throws IOException;
    public final int readInt() throws IOException;
    public final long readLong() throws IOException;
    public final float readFloat() throws IOException;
    public final double readDouble() throws IOException;
    public final String readLine() throws IOException;
    public final String readUTF() throws IOException;
    // The methods that implement interface DataOutput:
    public native void write(int b) throws IOException;
    public void write(byte[] b)
        throws IOException, NullPointerException;
    public void write(byte[] b, int off, int len)
        throws IOException, NullPointerException,
            IndexOutOfBoundsException;
    public final void writeBoolean(boolean v) throws IOException;
    public final void writeByte(int v) throws IOException;
    public final void writeShort(int v) throws IOException;
    public final void writeChar(int v) throws IOException;
    public final void writeInt(int v) throws IOException;
    public final void writeLong(long v) throws IOException;
    public final void writeFloat(float v) throws IOException;
    public final void writeDouble(double v) throws IOException;
    public final void writeBytes(String s) throws IOException;
    public final void writeChars(String s) throws IOException;
    public final void writeUTF(String str) throws IOException;
}

It is generally true of all the reading routines in this class that if end of file is reached before the desired number of bytes has been read, an EOFException (which is a kind of IOException) is thrown. If any byte cannot be read for any reason other than end of file, an IOException other than EOFException is thrown. In particular, an IOException may be thrown if the stream has been closed (§22.23.7).

22.23.1 public RandomAccessFile(String path, String mode)
throws SecurityException, IOException, IllegalArgumentException

This constructor initializes a newly created RandomAccessFile by opening a connection to an actual file, the file named by the path name path in the file system. A new FileDescriptor object is created to represent this file connection.

First, if there is a security manager, its checkRead method (§20.17.19) is called with the path argument as its argument.

Next, if mode is "rw" and there is a security manager, its checkWrite method (§20.17.21) is called with the path argument as its argument.

If mode is "rw", then the file may be both read and written. If mode is "r", then the file may be read but may not be written (every write method for this object will simply throw an IOException). If mode is not "r" or "rw", then this constructor throws an IllegalArgumentException.

22.23.2 public RandomAccessFile(File file, String mode)
throws SecurityException, IOException, IllegalArgumentException

This constructor initializes a newly created RandomAccessFile by opening a connection to an actual file, the file named by file in the file system. A new FileDescriptor object is created to represent this file connection.

First, if there is a security manager, its checkRead method (§20.17.19) is called with the path represented by the file argument as its argument.

Next, if mode is "rw" and there is a security manager, its checkWrite method (§20.17.21) is called with the path represented by the file argument as its argument.

If mode is "rw", then the file may be both read and written. If mode is "r", then the file may be read but may not be written (every write method for this object will simply throw an IOException). If mode is not "r" or "rw", then this constructor throws an IllegalArgumentException.

22.23.3 public final FileDescriptor getFD() throws IOException

This method returns the FileDescriptor object (§22.26) that represents the connection to the actual file in the file system being used by this RandomAccessFile.

22.23.4 public long getFilePointer() throws IOException

The current file pointer for this random access file is returned. An IOException is thrown if the file pointer cannot be read for any reason.

22.23.5 public void seek(long pos) throws IOException

The file pointer for this random access file is set to pos, which is a position within the file, measured in bytes. Position 0 is the start of the file. An IOException is thrown if pos is less than zero or greater than the length of the file, or if the file pointer cannot be set for any other reason.

22.23.6 public long length() throws IOException

The length of this random access file, measured in bytes, is returned.

An IOException is thrown if the length cannot be read for any reason.

22.23.7 public void close() throws IOException

This random access file is closed. A closed random access file cannot perform input or output operations and cannot be reopened.

22.23.8 public int read() throws IOException

This method reads one byte from the random access file. The byte is returned as an integer in the range 0 to 255 (0x00-0xff). If no byte is available because the file pointer is at end of file, the value -1 is returned.

If the byte cannot be read for any reason other than end of file, an IOException is thrown. In particular, an IOException is thrown if the input stream has been closed (§22.23.7).

Although RandomAccessFile is not a subclass of InputStream, this method behaves in exactly the same way as the read method of InputStream (§22.3.1).

22.23.9 public int read(byte[] b)
throws IOException, NullPointerException

Although RandomAccessFile is not a subclass of InputStream, this method behaves in exactly the same way as the read method of InputStream (§22.3.2).

22.23.10 public int read(byte[] b, int off, int len)
throws IOException, NullPointerException, IndexOutOfBoundsException

Although RandomAccessFile is not a subclass of InputStream, this method behaves in exactly the same way as the read method of InputStream (§22.3.3).

22.23.11 public final void readFully(byte[] b)
throws IOException, NullPointerException

See the general contract of the readFully method of DataInput (§22.1.1).

Bytes for this operation are read from the random access file, starting at the current file pointer.

22.23.12 public final void readFully(byte[] b, int off, int len) throws IOException, NullPointerException, IndexOutOfBoundsException

See the general contract of the readFully method of DataInput (§22.1.2).

Bytes for this operation are read from the random access file, starting at the current file pointer.

22.23.13 public int skipBytes(int n) throws IOException

See the general contract of the skipBytes method of DataInput (§22.1.3).

Bytes for this operation are read from the random access file, starting at the current file pointer.

22.23.14 public final boolean readBoolean() throws IOException

See the general contract of the readBoolean method of DataInput (§22.1.4).

The byte for this operation is read from the random access file, starting at the current file pointer.

22.23.15 public final byte readByte() throws IOException

See the general contract of the readByte method of DataInput (§22.1.5).

The byte for this operation is read from the random access file, starting at the current file pointer.

22.23.16 public final int readUnsignedByte() throws IOException

See the general contract of the readUnsignedByte method of DataInput (§22.1.6).

The byte for this operation is read from the random access file, starting at the current file pointer.

22.23.17 public final short readShort() throws IOException

See the general contract of the readShort method of DataInput (§22.1.7).

Bytes for this operation are read from the random access file, starting at the current file pointer.

22.23.18 public final int readUnsignedShort() throws IOException

See the general contract of the readUnsignedShort method of DataInput (§22.1.8).

Bytes for this operation are read from the random access file, starting at the current file pointer.

22.23.19 public final char readChar() throws IOException

See the general contract of the readChar method of DataInput (§22.1.9).

Bytes for this operation are read from the random access file, starting at the current file pointer.

22.23.20 public final int readInt() throws IOException

See the general contract of the readInt method of DataInput (§22.1.10).

Bytes for this operation are read from the random access file, starting at the current file pointer.

22.23.21 public final long readLong() throws IOException

See the general contract of the readLong method of DataInput (§22.1.11).

Bytes for this operation are read from the random access file, starting at the current file pointer.

22.23.22 public final float readFloat() throws IOException

See the general contract of the readFloat method of DataInput (§22.1.12).

Bytes for this operation are read from the random access file, starting at the current file pointer.

22.23.23 public final double readDouble() throws IOException

See the general contract of the readDouble method of DataInput (§22.1.13).

Bytes for this operation are read from the random access file, starting at the current file pointer.

22.23.24 public final String readLine() throws IOException

See the general contract of the readLine method of DataInput (§22.1.14).

Bytes for this operation are read from the random access file, starting at the current file pointer.

22.23.25 public final String readUTF() throws IOException

See the general contract of the readUTF method of DataInput (§22.1.15).

Bytes for this operation are read from the random access file, starting at the current file pointer.

22.23.26 public void write(int b) throws IOException;

See the general contract of the write method of DataOutput (§22.2.1).

The byte for this operation is written to the random access file, starting at the current file pointer.

22.23.27 public void write(byte[] b)
throws IOException, NullPointerException

See the general contract of the write method of DataOutput (§22.2.2).

Bytes for this operation are written to the random access file, starting at the current file pointer.

22.23.28 public void write(byte[] b, int off, int len)
throws IOException, NullPointerException, IndexOutOfBoundsException

See the general contract of the write method of DataOutput (§22.2.3).

Bytes for this operation are written to the random access file, starting at the current file pointer.

22.23.29 public final void writeBoolean(boolean v)
throws IOException

See the general contract of the writeBoolean method of DataOutput (§22.2.4).

The byte for this operation is written to the random access file, starting at the current file pointer.

22.23.30 public final void writeByte(int v) throws IOException

See the general contract of the writeByte method of DataOutput (§22.2.5).

The byte for this operation is written to the random access file, starting at the current file pointer.

22.23.31 public final void writeShort(int v) throws IOException

See the general contract of the writeShort method of DataOutput (§22.2.6).

Bytes for this operation are written to the random access file, starting at the current file pointer.

22.23.32 public final void writeChar(int v) throws IOException

See the general contract of the writeChar method of DataOutput (§22.2.7).

Bytes for this operation are written to the random access file, starting at the current file pointer.

22.23.33 public final void writeInt(int v) throws IOException

See the general contract of the writeInt method of DataOutput (§22.2.8).

Bytes for this operation are written to the random access file, starting at the current file pointer.

22.23.34 public final void writeLong(long v) throws IOException

See the general contract of the writeLong method of DataOutput (§22.2.9).

Bytes for this operation are written to the random access file, starting at the current file pointer.

22.23.35 public final void writeFloat(float v) throws IOException

See the general contract of the writeFloat method of DataOutput (§22.2.10).

Bytes for this operation are written to the random access file, starting at the current file pointer.

22.23.36 public final void writeDouble(double v)
throws IOException

See the general contract of the writeDouble method of DataOutput (§22.2.11).

Bytes for this operation are written to the random access file, starting at the current file pointer.

22.23.37 public final void writeBytes(String s) throws IOException

See the general contract of the writeBytes method of DataOutput (§22.2.12).

Bytes for this operation are written to the random access file, starting at the current file pointer.

22.23.38 public final void writeChars(String s) throws IOException

See the general contract of the writeChars method of DataOutput (§22.2.13).

Bytes for this operation are written to the random access file, starting at the current file pointer.

22.23.39 public final void writeUTF(String str) throws IOException

See the general contract of the writeUTF method of DataOutput (§22.2.14).

Bytes for this operation are written to the random access file, starting at the current file pointer.


22.24 The Class java.io.File

A File object contains a path, which is a character string that can be used to identify a file within a file system. A path is assumed to consist of two parts, the directory and the file name, separated by the last occurrence within the path of a particular character known as the separator character. Some methods provide access to parts of the path string; other methods operate on the file that is identified by the path string. The details of such operations on files are to some extent dependent on the implementation of the host file system. The File class is designed to provide a set of abstract operations that are reasonably portable across otherwise incompatible file systems.

public class File {
    public static final String separator =
        System.getProperty("file.separator");
    public static final char separatorChar =
        separator.charAt(0);
    public static final String pathSeparator =
        System.getProperty("path.separator");
    public static final char pathSeparatorChar =
        pathSeparator.charAt(0);
    public File(String path) throws NullPointerException;
    public File(String dirname, String name)
        throws NullPointerException
    public File(File dir, String name)
        throws NullPointerException
    public String toString();
    public boolean equals(Object obj);
    public int hashCode();
    public String getName();
    public String getPath();
    public String getAbsolutePath();
    public String getParent();
    public native boolean isAbsolute();
    public boolean exists() throws SecurityException;
    public boolean canRead() throws SecurityException;
    public boolean canWrite() throws SecurityException;
    public boolean isFile() throws SecurityException;
    public boolean isDirectory() throws SecurityException;
    public long lastModified() throws SecurityException;
    public long length() throws SecurityException;
    public boolean mkdir() throws SecurityException;
    public boolean mkdirs() throws SecurityException;
    public String[] list() throws SecurityException;
    public String[] list(FilenameFilter filter)
        throws SecurityException;
    public boolean delete() throws SecurityException;
    public boolean renameTo(File dest) throws SecurityException;
}

22.24.1 public static final String separator = System.getProperty("file.separator");

This string should consist of a single character, whose value is also available in the field separatorChar; the string is provided merely for convenience.

22.24.2 public static final char separatorChar = separator.charAt(0);

The last occurrence of this character in a path string is assumed to separate the directory part of the path from the file name part of the path. On UNIX systems this character is typically '/'.

22.24.3 public static final String pathSeparator = System.getProperty("path.separator");

This string should consist of a single character, whose value is also available in the field pathSeparatorChar; the string is provided merely for convenience.

22.24.4 public static final char pathSeparatorChar = pathSeparator.charAt(0);

The first occurrence of this character in a string is sometimes assumed to separate a host name from a path name. On UNIX systems this character is typically ':'.

22.24.5 public File(String path) throws NullPointerException

This constructor initializes a newly created File so that it represents the path indicated by the argument path.

If the path is null, a NullPointerException is thrown.

22.24.6 public File(String dirname, String name)
throws NullPointerException

This constructor initializes a newly created File so that it represents the path whose directory part is specified by the argument dirname and whose file name part is specified by the argument name. If the dirname argument is null, the name is used as the path; otherwise the concatenation of dirname, the separatorChar (§22.24.2), and the name is used as the path.

If the name is null, a NullPointerException is thrown.

22.24.7 public File(File dir, String name)
throws NullPointerException

This constructor initializes a newly created File so that it represents the path whose directory part is specified by the File object dir and whose file name part is specified by the argument name.

If the name is null, a NullPointerException is thrown.

22.24.8 public String toString()

The result is a String equal to the path represented by this File object.

Overrides the toString method of Object (§20.1.2).

22.24.9 public boolean equals(Object obj)

The result is true if and only if the argument is not null and is a File object that represents the same path as this File object. In other words, two File objects are equal if and only if the strings returned by the getPath method (§22.24.12) are equal.

Overrides the equals method of Object (§20.1.3).

22.24.10 public int hashCode()

The hash code of this File object is equal to the exclusive OR of the hash code of its path string and the decimal value 1234321:

this.getPath().hashcode() ^ 1234321

Overrides the hashCode method of Object (§20.1.4).

22.24.11 public String getName()

If the path string contains the separatorChar character (§22.24.2), this method returns the substring of the path that follows the last occurrence of the separator character; otherwise, the entire path string is returned.

22.24.12 public String getPath()

The result is a String equal to the path represented by this File object.

22.24.13 public String getAbsolutePath()

The result is a String equal to the result of converting to "absolute form" the path represented by this File object.

22.24.14 public String getParent()

If the path has a parent directory, a String representing the path of that parent directory is returned; otherwise, null is returned.

22.24.15 public boolean isAbsolute()

The result is true if and only if the path represented by the File object is in absolute form, indicating a complete name that starts from the root of the directory hierarchy, rather than a name relative to some implied directory.

22.24.16 public boolean exists() throws SecurityException

First, if there is a security manager, its checkRead method (§20.17.19) is called with the path represented by this File object as its argument.

The result is true if and only if the file system actually contains a file that is specified by the path of the File object.

22.24.17 public boolean canRead() throws SecurityException

First, if there is a security manager, its checkRead method (§20.17.19) is called with the path represented by this File object as its argument.

The result is true if and only if both of the following are true:

  • The file system actually contains a file specified by the path of the File object.
  • The file so specified can be read.

22.24.18 public boolean canWrite() throws SecurityException

First, if there is a security manager, its checkWrite method (§20.17.21) is called with the path represented by this File object as its argument.

The result is true if and only if both of the following are true:

  • The file system actually contains a file specified by the path of the File object.
  • The file so specified can be written.

22.24.19 public boolean isFile() throws SecurityException

First, if there is a security manager, its checkRead method (§20.17.19) is called with the path represented by this File object as its argument.

The result is true if and only if both of the following are true:

  • The file system actually contains a file specified by the path of the File object.
  • The file so specified is a data file rather than a directory.

22.24.20 public boolean isDirectory() throws SecurityException

First, if there is a security manager, its checkRead method (§20.17.19) is called with the path represented by this File object as its argument.

The result is true if and only if both of the following are true:

  • The file system actually contains a file specified by the path of the File object.
  • The file so specified is a directory rather than a data file.

22.24.21 public long lastModified() throws SecurityException

First, if there is a security manager, its checkRead method (§20.17.19) is called with the path represented by this File object as its argument.

An abstract modification time is returned. If two values returned by this method are compared, whether for the same file or for two different files, the smaller value represents an earlier modification time. Abstract modification times do not necessarily bear any relationship, even monotonicity, to times returned by the method System.currentTimeMillis (§20.18.6).

22.24.22 public long length() throws SecurityException

First, if there is a security manager, its checkRead method (§20.17.19) is called with the path represented by this File object as its argument.

The length of the file, measured in bytes, is returned.

22.24.23 public boolean mkdir() throws SecurityException

First, if there is a security manager, its checkWrite method (§20.17.21) is called with the path represented by this File object as its argument.

An attempt is made to create the directory specified by the path represented by this File object; the result is true if and only if the creation operation succeeds.

22.24.24 public boolean mkdirs() throws SecurityException

First, if there is a security manager, its checkRead method (§20.17.19) is called with the path represented by this File object as its argument.

If the directory name represented by this File object has a parent directory name (§22.24.14), an attempt is first made to create the parent directory; if this attempt fails, the result is false. Otherwise, once the parent directory has been determined to exist, or if the path has no parent, an attempt is made to create the directory specified by this File object. The result is true if and only if the creation operation succeeds.

22.24.25 public String[] list() throws SecurityException

First, if there is a security manager, its checkRead method (§20.17.19) is called with the path represented by this File object as its argument.

If the path represented by this File object does not correspond to a directory in the file system, then null is returned. Otherwise, an array of strings is returned, one for each file in the directory (on UNIX systems, the names "." and ".." are not included). Each string is a file name, not a complete path. There is no guarantee that the strings will appear in any particular order within the array; for example, they are not guaranteed to appear in alphabetical order.

22.24.26 public String[] list(FilenameFilter filter)
throws SecurityException

First, if there is a security manager, its checkRead method (§20.17.19) is called with the path represented by this File object as its argument.

If the path represented by this File object does not correspond to a directory in the file system, then null is returned. Otherwise, an array of strings is returned, one for each file in the directory (on UNIX systems, the names "." and ".." are not included) whose name satisfies the given filter. Each string is a file name, not a complete path. There is no guarantee that the strings will appear in any particular order within the array; for example, they are not guaranteed to appear in alphabetical order. A file name satisfies the filter if and only if the value true results when the accept method (§22.25.1) of the filter is called with this File object and the name as arguments.

22.24.27 public boolean renameTo(File dest)
throws SecurityException

First, if there is a security manager, its checkWrite method (§20.17.21) is called twice, first with the path represented by this File object as its argument and again with the path of dest as its argument.

An attempt is made to rename the file specified by the path represented by this File object to the name specified by dest; the result is true if and only if the renaming operation succeeds.

22.24.28 public boolean delete() throws SecurityException

First, if there is a security manager, its checkDelete method (§20.17.22) is called with the path represented by this File object as its argument.

An attempt is made to delete the file specified by the path represented by this File object; the result is true if and only if the deletion operation succeeds.


22.25 The Interface java.io.FilenameFilter

The list method (§22.24.26) of class File requires, as an argument, an object that implements the FilenameFilter interface. The only purpose of such an object is to provide a method accept that decides which files should appear in the generated directory listing.

public interface FilenameFilter {
    public boolean accept(File dir, String name);
}

22.25.1 public boolean accept(File dir, String name)

This method should return true if and only if the given file named name in the directory dir is to appear in the final list of files generated by the list method (§22.24.26) of class File.


22.26 The Class java.io.FileDescriptor

A FileDescriptor is an opaque representation of a connection to an actual file in a file system, or to a network socket, or to another source or sink of bytes. The main practical use for a file descriptor is to create a FileInputStream (§22.4.3) or FileOutputStream (§22.16.3) to contain it.

public final class FileDescriptor {
    public static final FileDescriptor in = ...;
    public static final FileDescriptor out = ...;
    public static final FileDescriptor err = ...;
    public boolean valid();
}

22.26.1 public static final FileDescriptor in = ...

A file descriptor for the standard input stream. Usually, this file descriptor is not used directly, but rather the input stream known as System.in (§20.18.1).

22.26.2 public static final FileDescriptor out = ...

A file descriptor for the standard output stream. Usually, this file descriptor is not used directly, but rather the output stream known as System.out (§20.18.2).

22.26.3 public static final FileDescriptor err = ...

A file descriptor for the standard error output stream. Usually, this file descriptor is not used directly, but rather the output stream known as System.err (§20.18.3).

22.26.4 public boolean valid()

If this FileDescriptor is valid (represents an active connection to a file or other active I/O connection), then the result is true. Otherwise, the result is false.


22.27 The Class java.io.IOException

The class IOException is the general class of exceptions produced by failed or interrupted input/output operations. Subclasses of IOException include:

EOFException
FileNotFoundException
InterruptedIOException
UTFDataFormatException
public class IOException extends Exception {
    public IOException();
    public IOException(String s);
}

22.27.1 public IOException()

This constructor initializes a newly created IOException with null as its error message string.

22.27.2 public IOException(String s)

This constructor initializes a newly created IOException by saving a reference to the error message string s for later retrieval by the getMessage method (§20.22.3).


22.28 The Class java.io.EOFException

An EOFException is thrown to indicate that an input operation has encountered end of file. Note that some Java input operations react to end of file by returning a distinguished value (such as -1) rather than by throwing an exception.

public class EOFException extends IOException {
    public EOFException();
    public EOFException(String s);
}

22.28.1 public EOFException()

This constructor initializes a newly created EOFException with null as its error message string.

22.28.2 public EOFException(String s)

This constructor initializes a newly created EOFException by saving a reference to the error message string s for later retrieval by the getMessage method (§20.22.3).


22.29 The Class java.io.FileNotFoundException

A FileNotFoundException is thrown to indicate that no actual file could be opened for a specified path name. See constructors FileInputStream (§22.4.1, §22.4.2) and FileOutputStream (§22.16.1, §22.16.2).

public class FileNotFoundException extends IOException {
    public FileNotFoundException();
    public FileNotFoundException(String s);
}

22.29.1 public FileNotFoundException()

This constructor initializes a newly created FileNotFoundException with null as its error message string.

22.29.2 public FileNotFoundException(String s)

This constructor initializes a newly created FileNotFoundException by saving a reference to the error message string s for later retrieval by the getMessage method (§20.22.3).


22.30 The Class java.io.InterruptedIOException

An InterruptedIOException is thrown to indicate that an input or output transfer has been terminated because the thread performing it was interrupted. The field bytesTransferred indicates how many bytes were successfully transferred before the interruption occurred.

public class InterruptedIOException extends IOException {
    public int bytesTransferred = 0;
    public InterruptedIOException();
    public InterruptedIOException(String s);
}

22.30.1 public int bytesTransferred = 0;

The number of bytes that had been transferred by the I/O operation before the operation was interrupted.

22.30.2 public InterruptedIOException()

This constructor initializes a newly created InterruptedIOException with null as its error message string.

22.30.3 public InterruptedIOException(String s)

This constructor initializes a newly created InterruptedIOException by saving a reference to the error message string s for later retrieval by the getMessage method (§20.22.3).


22.31 The Class java.io.UTFDataFormatException

A UTFDataFormatException is thrown to indicate that a problem occurred in converting data from Java modified UTF-8 format. See method readUTF of DataInput (§22.1.15).

public class UTFDataFormatException extends IOException {
    public UTFDataFormatException();
    public UTFDataFormatException(String s);
}

22.31.1 public UTFDataFormatException()

This constructor initializes a newly created UTFDataFormatException with null as its error message string.

22.31.2 public UTFDataFormatException(String s)

This constructor initializes a newly created UTFDataFormatException by saving a reference to the error message string s for later retrieval by the getMessage method (§20.22.3).


Copyright © 1997 Sun Microsystems, Inc. "Java" is a trademark of Sun Microsystems, Inc. This document is covered by the full copyright and trademark declarations in The Java Language Specification. This document is excerpted from the fourth printing of The Java Programming Language by Ken Arnold and James Gosling, Addison-Wesley, 1996, ISBN 0-201-63455-4.

Appendix D

Changes for Java 1.1

No unmet needs exist and...current unmet needs that are being met will continue to be met.

-- Transportation Commission on Unmet Transit Needs, California

A newer version of Java has arrived since the original publication of this book. Called the Java 1.1 Platform (hereafter simply "Java 1.1"), it adds some language features, a few packages, and many classes to existing packages. The goals of Java 1.1 are to support internationalization better, fix the incongruities of the original abstract window toolkit package (java.awt, or just "AWT" for short), complete functionality that was missing or impoverished, and add several useful packages. This book does not cover AWT, so we do not cover it in this appendix.

This appendix does summarizes the other changes. For extensive changes, especially those having to do with new classes and packages, you will have to use the reference documentation shipped with your Java 1.1 system to supplement this appendix. The section titles in this appendix correspond to the chapters of this book where the new features would appear.

D.1 Classes

D.1.1 Inner Classes

 Classes and interfaces can be nested inside other classes. Such classes, called inner classes, should be ones that exist only to support the work of the class in which they nest. For example, the sole purpose of the SortMetrics class on page 75 is to return multiple values from the metrics method of the SortDouble class. It is a good candidate to be an inner class:

    abstract class SortDouble {
    static final class SortMetrics implements Cloneable {
        // ... the rest of SortMetrics (see page 75)
    }
    // ... the rest of SortDouble (see page 73)
    }

An inner class name is qualified by its enclosing class. In this case, the proper name of SortMetrics is SortDouble.SortMetrics, and so its declaration in SimpleSortDouble on page 76 would be

    SortDouble.SortMetrics metrics = bsort.sort(testData);
Inner classes and interfaces can use the same access modifiers as other members of a class. A class that was used only in internal data structures might be marked private; one intended only for use by subclasses would be protected. Inner classes can also be public or package accessible.

The example above declares SortMetrics as static. An inner class that is not static has an implicit reference to its enclosing object, which is the object that created the inner class object. This reference is useful because many inner classes are strongly tied to particular objects, and need to access their fields. For example, the class EnumerateWhichChars on page 222 is used to implement the Enumeration interface for the WhichChars class, and could be nicely rewritten to look like this:

    public class WhichChars {
    private BitSet used = new BitSet();     // in original
    private class Enumerate implements Enumeration {
        private int pos = 0;
        private int setSize = used.size();

        public boolean hasMoreElements() {
        while (pos < setSize && !used.get(pos))
            pos++;
        return (pos < setSize);
        }

        public Object nextElement()
        throws NoSuchElementException
        {
        if (hasMoreElements())
            return new Character((char)pos++);
        else
            throw new NoSuchElementException();
        }
    }

    public Enumeration characters() {       // from page 223
        return new Enumerate();
    }
    }

We use the shorter class name Enumerate because the class is already nested inside WhichChars, so EnumerateWhichChars would be redundant. The class is private so that even other classes in the package can't use the type directly-it is purely an implementation detail of the WhichChars class.

In the original code on page 222, used was passed as a parameter to the class's constructor, which stored the reference in a field of its own called bits. Here the code for Enumerate directly accesses the field used of its enclosing object. When resolving identifiers, the inner class's enclosing object (also called its enclosing instance) is searched for fields and methods after the class's own this. Because Enumerate does not have a field named used, the identifier used in the inner class refers to the enclosing object's field of that name. The enclosing object for an inner class is the this reference of the method that created the inner class object. In our example above, when an Enumerate object is created inside a particular WhichChar object, the Enumerate object's enclosing object is set to be the this reference of the WhichChar method that created it. This means you cannot create an instance of a non-static inner class in a static context (inside a static method, a static block, or as an initializer for a static field).

You can get a reference to an enclosing object using its class name. For example, code in an Enumerator object could get a reference to its enclosing object using WhichChar.this.

D.1.2 New Uses for final

Method parameters and local variables can be declared final. If you do not expect to change the value of a parameter or variable inside the method, you can declare it final to let the compiler enforce that. The compiler can also optimize uses of a final parameter or variable since it knows the value will never change.

The final-ness of a parameter is not part of the method signature-it is simply a detail of the implementation. A subclass can override a method and add or drop any final parameter modifiers you wish. You can also add or drop final modifiers in a method's parameters without causing any harm to existing compiled code that uses that method. The final declaration does not show up in the documentation generated from doc comments.

You can defer initialization of a final field or variable, as long as you initialize it before it is used and assign a value to it exactly once. The compiler will check for proper assignment, as will the verifier before code is executed. Deferred initialization can be useful when the proper value can only be calculated by a loop or other code that is hard or impossible to encode in a variable initializer, such as code that throws exceptions that must be caught and handled.

D.1.3 Object Initializers

You can have arbitrary blocks of code that are executed after the superclass constructor is executed, but before the class's own constructor body is executed. Such blocks are analogous to static blocks described on page 44, except the keyword static is left off.

D.2 Extending Classes

D.2.1 Anonymous Classes

 When you are writing simple subclasses or implementations of interfaces, creating a bunch of classes for each trivial class can be awkward. Anonymous classes are a convenient short form of inner classes that have no name, only an implementation that is specified right along with the new. Suppose you want to create a simple Observer object (see page 233) that keeps a history of the events stored in a field of your object. The following would do this directly and simply:

    private Vector history = new Vector();

    public void watch(Observable o) {
    o.addObserver(new Observer() {
        public void update(Observable o, Object arg) {
        history.addElement(arg);
        }
    });
    }

The addObserver has an embedded new of an anonymous class that implements the Observer interface, implicitly extending Object. This anonymous class implements update by adding an element to the enclosing object's history vector. The compiler creates an unnamed (hence "anonymous") class that overrides update as specified. The end of the anonymous class declaration is the end of the allocation expression started by the new. Here we simply close off the call to addObserver with a closing parenthesis.

An anonymous class can extend a class instead of implementing an interface, in which case it is an unnamed subtype of that class. Such a new can invoke any superclass constructor. Anonymous classes cannot have their own constructors.

Anonymous classes are a quick, terse subclassing tool that is useful in certain situations, such as creating several types of AWT buttons, each with its own small action, or creating simple Runnable objects. Unfortunately, they share a common failing of many terseness features-it is trivial to write code that is torture to read. You should use of anonymous classes only for tiny classes that override one, or at most two, methods, with a total of four lines of code or fewer. Otherwise people who read your code can become confused trying to keep track of what piece of which class's method's code they are reading, and what the outer context is. Use this tool sparingly. When it's good, it's very, very good. When it's not, it's awful.

D.2.2 New Hashing Method

The default implementation of Object.hashCode is to return keys that are likely to be different for different objects. As described on page 64, many classes override both hashCode and equals to provide different notions of equality. However, sometimes you need the original notion of equality, in which all objects are different, even for an object that usually is used with a broader notion. You can use == to test if two objects are the same, but you will need to use System.identityHashCode to hash the objects, since it preserves the default implementation of hashCode in which all objects are considered different.

D.3 Tokens, Operators, and Expressions

Documentation comments ("doc comments") contain @ tags (such as @author and @see) that are not documented in this book. The new @deprecated tag has particular meaning-it marks a class, interface, field, or method as not recommended for continued use. Existing code that uses the deprecated entity will still compile and run, but the compiler will generate a warning, suggesting that you update your code to avoid that entity. You should follow that recommendation.

To have this effect on a type or a member of a type, the @deprecated tag must be at the beginning of a doc comment line (ignoring white space and any * character). This is the only place in the entire Java language where the contents of a comment affect the generated code. The @deprecated tag should always refer readers to the preferred replacement(s). For example

    /**
      * @deprecated	This call has been replaced with dwishm
      * @see dwishm
      */
    public void dwim() { /*...*/ }
The transient keyword, marked as "unused" on page 93, now has defined meaning; see Section D.5.2.

You can initialize the contents of an array when you new it. For example, the following would be a flexible way to create an array of strings:

    String[] martians = new String[] {
                "Gidney", "Cloyd"
            };

D.4 Threads

 The interruption mechanism briefly described on pages 173-174 as future functionality has been implemented in Java 1.1. See those pages for more details.

D.5 I/O

D.5.1 Internationalization

 Many new I/O classes have been added to handle full internationalized character issues. The original classes really worked only with ISO-Latin-1 8-bit characters (notice that InputStream.read, for example, returned eight bits, not sixteen, in its int). The most specific change is that PrintStream is now a deprecated class, since it thinks only in terms of ISO-Latin-1. The new class is called PrintWriter, and provides all the methods of PrintStream except those for writing raw bytes. Existing code that uses the print and println methods of PrintStream will have the output translated to the local character set. (To prevent a massive outpouring of deprecation warnings, only the constructors of PrintStream are deprecated.)

The autoflushing of PrintStream described on page 199 has been cleaned up. If autoflush is turned on, any newline anywhere in the output causes a flush, as does any write of a byte array. If autoflush is off, no automatic flushing is done.

PrintWriter is a subclass of the abstract Writer class, which is the parallel to OutputStream for classes that understand internationalization. The Reader abstract class is the parallel to InputStream. There are several new Reader and Writer classes for internationalized I/O.

The fields System.in, System.out, and System.err are final in Java 1.1 for security reasons, so code that modifies these fields (like that shown on page 197) will not work.

The new package java.text includes many classes useful for parsing and producing internationalized text. It includes classes for date and number formatting, comparing and sorting strings in a locale-sensitive way, splitting up native language text, and other locale-related I/O.

D.5.2 Object Serialization

The streams ObjectInputStream and ObjectOutputStream help you read and write entire objects and object graphs. Objects written to an ObjectOutputStream using writeObject generate a stream of bytes that, when read by an ObjectInputStream with readObject, create a full copy of the original objects. The process of creating such a stream of bytes is called serialization. Serialized copies are deep-you can serialize an entire graph of objects, and when you deserialize the generated bytes, you will get a full copy of the original graph. If two or more objects refer to a particular object in the original graph, a deserialized copy will have copies of those two or more objects that refer to a copy of that same particular object.

The byte stream encodes the state of the serialized object, including private fields. Therefore any serializable object can have the values of its private fields examined by someone who serializes the object and reads the generated bytes. Some programmers view private fields as secret, and would not be pleased to have values exposed in this way. For this reason, objects are not serializable unless they implement the Serializable interface. Serializable is an empty interface that simply marks the object as one that can be serialized. The default serialization mechanism just writes the non-static, non-transient fields of an object. You can override this by providing readObject and writeObject methods.

A class that instead implements the interface Externalizable-a subinterface of Serializable-is serializable but must provide custom readExternal and writeExternal methods; the default serialization will not be used.

D.6 Utilities

D.6.1 Resource Localization

 Several new utilities have been added for localization. A new Locale class describes particular locales to define a user's preferred language and other properties. A ResourceBundle superclass is provided to customize a set of resources (such as messages that might be displayed to the user) based on the user's preferred locale. Some subtypes of ResourceBundle are provided: ListResourceBundle, an abstract class that provides a simple implementation of ResourceBundle to which you must simply provide the list of resources and keys for each resource, and PropertyResourceBundle, which uses files that contain the keyed resources.

D.6.2 Dates and Times

The functionality of the Date class has been split up into a richer system that can cope with varying reckonings of time. A Date object now only represents a particular moment in time with millisecond granularity. Its other constructors and methods previously performed two other duties: formatting strings and viewing a moment in time as year, month, day, hour, minute, and second values. All these methods are deprecated in favor of:

  • an abstract Calendar class for handling various ways of marking time
  • an abstract TimeZone class that represents time zone offsets and other adjustments, such as daylight savings time
  • an abstract java.text.DateFormat class that defines how one can parse and format date strings

These abstract classes allow flexibility, but almost everyone will need to work with Gregorian dates that are used in most of the world and in international commerce, so Java 1.1 also provides:

  • a GregorianCalendar class
  • a SimpleTimeZone class for use with GregorianCalendar
  • a java.text.SimpleDateFormat class that parses and formats Gregorian dates For example, the following program uses a GregorianCalendar to print out the current year:

    class CurrentYear {
    public static void main(String[] args) {
        GregorianCalendar now = new GregorianCalendar();
        int year = now.get(Calendar.YEAR);
        System.out.println("The year is " + year);
    }
    }

D.7 Programming with Types

D.7.1 Reflection

 The package java.lang.reflect provides a reflection mechanism for Java. This is a tool for examining classes fully. A Class object can now return a list of all the public methods and fields of the related class. You can use the Method objects returned to invoke methods, and the Field objects to get and set field values. A Class object can also return a list of all members, including non-public ones, but security restrictions usually prevent doing this.

You should avoid the temptation to use reflection when other tools more natural to the language would suffice. If you are accustomed to using function pointers in another language, for example, you might think that using Method objects are a natural replacement, but usually an object-oriented tool-such as an interface that is implemented by objects that perform the needed action-is better. Reflection is intended for use by language tools such as debuggers and class browsers.

D.7.2 Wrapper Classes

Two new wrapper classes have been added: Short and Byte. These are subtypes of Number. A new Void class has also been added for completeness, and is used by the reflection methods to represent void return types.

D.7.3 Getting the Class Object for a Named Class

You can get the Class object for a given type with a new use of the class keyword:

    Class threadClass = Thread.class;
    Class intClass = int.class;
    Class voidClass = void.class;

D.8 Native Methods

 The API for writing C implementations of Java methods is now completely different. The mapping has been regularized, and is less tied to a particular implementation of the Java Virtual Machine. The general comments about native method mappings in Appendix A are still valid, but the specific details described, while still supported, are strongly deprecated. The new Java Native Interface (JNI) is much easier to learn and to use.

D.9 New Packages

Java 1.1 has several new packages:

  • java.beans-Java Beans are software components that allow unrelated developers to write and ship Java components that can be composed together by end-user tools.
  • java.math-This package provides tools for mathematical manipulations. Currently a BigInteger class provides arbitrary-precision integer arithmetic, and BigDecimal provides arbitrary-precision decimal arithmetic.
  • java.rmi-Remote Method Invocation (RMI) allows you to create objects whose methods can be invoked by objects running in other Virtual Machines, including Virtual Machines running on other hosts. Because Java code can be downloaded and run securely, RMI lets you pass subtypes of the declared method parameters, and return subtypes of the declared type of the remote method. This allows you to pass object behavior as well as simple values. RMI provides remote procedure calls with a Java flavor and benefits.
  • java.security-This package and its subpackages provide some basic interfaces and classes for security-related operations, such as authentication, authorization, signed data, and encryption.
  • java.sql-This package provides tools for using relational databases.
  • java.text-This package provides text internationalization tools, such as date parsing and number formatting.
  • java.util.zip-You can use these classes for handling ZIP files.


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.