Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
The com.ms.wfc.app package contains many classes that provide WFC application services. Many of these operations belong to the Application object itself. These operations have mostly to do with creating threads, starting the application, handling application events, and so on. Because understanding Java threads is important, it is discussed in its own section, .
Other operations that qualify as application services pertain to those provided by the Win32 operating system. These include accessing the Windows registry, accessing Clipboard data, and retrieving system information, among other operations.
Starting and Quitting an Application
The method starts a WFC application. This is typically placed in the main method of the Form-based class that constitutes the main application form. Application.run has overloaded methods that take either no parameters or one parameter specifying the form class that represents the main window of the application. For example, the following is a typical form of this call:
public static void main(String args[])
{
Application.run(new MyMainWindow());
}
If a form is passed to the run method, the form's visible property is automatically set to true, and an onClosed event handler is added to the form. The onClosed event handler calls the method when the form is closed. If no form is passed, the application runs until is called, shutting down all threads and windows on the application, or until exitThread is called, shutting down just the application's current thread.
Handling Application Events
You use the Application object to assign event handlers for five different events that occur in the context of the application: applicationExit, idle, settingChange, systemShutdown, and threadException. The following addOn methods can be called to define event handlers for these events.
All these "addOn" methods have reciprocal "removeOn" methods to remove the event handler.
Accessing System Information
The Win32 system contains a large amount of information that is accessible to a WFC application or component. Most of this access is through classes in the com.ms.wfc.app package. Much of this information is stored in the Windows registry and accessed through the and classes. Other system information, such as Windows display element sizes, operating system settings, network availability, and the hardware capabilities, are accessed using static methods in the ****class. System time is available using the class.
This section provides an overview of how a WFC application can access this system information.
Windows Registry Information
The RegistryKey class in the com.ms.wfc.app package contains methods to access the Windows system registry. Use the methods in this class to create and delete subkeys, to get the count and names of subkeys for the current key, and to retrieve, set, and delete values assigned to subkeys.
The class contains fields holding objects that represent the root keys of the registry (those starting with HKEY_). (Root RegistryKey objects can also be instantiated using the getBaseKey method.) Methods can be called on any RegistryKey object to enumerate and manipulate keys and key values in the subkey tree below the root object. For example, the following code obtains an array of subKey names under the HKEY_CURRENT_USER key and the number of names in that array:
int subKeyCount;
String[] subKeyNames;
subKeyNames = Registry.CURRENT_USER.getSubKeyNames();
subKeyCount = Registry.CURRENT_USER.getSubKeyCount();
Similarly, any subkey can be retrieved or set given its path, and subkey value names and data can be retrieved or set given the value name. The following example shows retrieving the most recently used file names in Visual Studio and displaying them in an edit box:
String path; // Holds the path name.
String[] valueNames; // Holds array of MRU file names in the key.
int valueCount; // The number of MRU file names in valueNames.
path = new String("Software\\Microsoft\\VisualStudio\\6.0\\FileMRUList");
RegistryKey subKey = registry.CURRENT_USER.getSubKey( path );
// Get the file names and the number of file names.
valueNames = subKey.getValueNames();
valueCount = subKey.getValueCount();
if (valueCount > 0)
for (int i = 0; i < valueCount; ++i){
// Get the value, which is the actual file name.
String value = new String((String)subKey.getValue(valueNames[i]));
// Concatenate the name ("1", "2", etc.) with the file name value.
String valString = new String(valueNames[i] + " " + value);
// Add this to the edit box.
edit1.setText(edit1.getText()+ valString +"\r\n");
}
You can also create new keys, using the createSubKey method and set values in that key using the setValue method.
Locale Information
Locale information provides details about the language and regional settings on the user's computer. There are many characteristics about a language or region that are stored. These include the character set, international telephone codes, how monetary information is displayed, which calendar is used, the measurement system, and so on.
This information is typically set using the Regional Settings dialog box in Control Panel, but it is also available programmatically. In WFC this access is provided through the methods in the class and through the many subclasses of Locale that contain field constants that pertain to Locale methods. For details about setting and retrieving this information, see the methods in the Locale class.
Time Information
Another category of system information is time. The class provides a Time object that has many capabilities, including capturing system time: the default constructor creates a Time object with the system date and time. Beyond retrieving system time information, the Time object is useful for doing many other things, such as comparing Date and Time objects, converting the time to various formats, and storing a Time object for later retrieval.
Time objects, once created, cannot be altered. However, the Time class provides many methods for creating new objects with offset time (such as addSeconds, addMinutes, addHours, addDays, and addYears). Also, there are many methods for retrieving just one of the properties of a Time object, such as the second, minute, hour, day, and so forth.
The Time object in WFC stores time as the number of hundred-nanosecond units since Jan 1, 100ad. The maximum value that can be stored in a WFC Time object is Dec 31, 10,000ad. Converting WFC Time objects to other formats (Strings, Variants, SYSTEMTIME, and so on) can cause loss of accuracy, and not all formats can store this wide of a range.
Do not confuse the Time class with another com.ms.wfc.app class called . Timer is actually a control; however, it is not in the com.ms.wfc.ui package because it does not have a user interface.
Performing Clipboard and Drag-and-Drop Operations
The drag-and-drop feature in WFC is based on the Win32 (OLE) model, which implements a shortcut for copying and pasting data. When you use the Clipboard, you must perform several steps involving selecting the data, choosing Cut or Copy from the context menu, moving to the destination file, window, or application, and choosing Paste from the context menu. (The origin of the data is called the source and the destination is called the target.)
The drag-and-drop feature removes the necessity of using the context menu. Instead, it uses the action of pressing the left mouse button to capture the selected data in the source and releasing the button in the target to drop it. Drag-and-drop operations can transfer any data that can be placed on the Clipboard; consequently, the data formats for drag and drop are the same as those of the Clipboard. Data formats specify, for example, whether the data is text, bitmap, HTML, .wav, and so on. The ****class contains fields pertaining to each of the Clipboard formats. These field names (such as CF_TEXT) come straight from the Win32 constant names.
The data for Clipboard and drag-and-drop operations is stored in a com.ms.wfc.app class called , which implements the interface. IDataObject defines methods for setting and retrieving the data, getting a list of data formats in the data object, and querying for the existence a specific data format.
To programmatically place data on and retrieve it from the Clipboard, use the static methods in . Clipboard.setDataObject takes an IDataObject****and places it on the Windows Clipboard; Clipboard.getDataObject returns an IDataObject from the Clipboard. The target must make sure that the data format on the Clipboard is one that it can use. To do this, it should query the data object with the method, passing it a data format that it can accept; getDataPresent returns true if this type of data is present.
Implementing a Drop Source
For any WFC control component (based on com.ms.wfc.ui.Control), the method is called to start the operation. This is typically done in response to the user's moving the mouse with the left button pressed. Therefore, the code is placed in a mouseMove event handler where the object is checked to see if the left button is down, indicating the start of a drag operation. For example, the following is an event handler for a list box control containing file names:
private void listFiles_mouseMove(Object source, MouseEvent e)
{
//if the left button is down, do the drag/drop
if(this.getMouseButtons()==MouseButton.LEFT)
{
String data = (String)listFiles.getSelectedItem();
listFiles.doDragDrop( data, DragDropEffect.ALL);
}
}
The doDragDrop method takes the data to be transferred and a object. The DragDropEffect class contains the following constants that can be combined using the bitwise OR for the intended mode of the drag-and-drop operation.
The target that receives the data in the drag-drop operation receives the dragDrop event, which contains this DragDropEffect object, so it can easily determine the intent of the operation.
Implementing a Drop Target
The drop part of the drag-and-drop operation is handled as an event. The Control class provides the event handler infrastructure for these drag-and-drop events: dragDrop, dragEnter, dragLeave, and dragOver. You can use the following methods to specify handlers for these events.
All these "addOn" methods have reciprocal "removeOn" methods to remove the event handler. As with all event handler addOn and removeOn methods in WFC, these methods take a delegate (in this case, ) that is created with the name of your handler method. For example, the following line adds the txtFile_dragDrop method as a dragDrop event handler:
txtFile.addOnDragDrop(new DragEventHandler(this.txtFile_dragDrop));
Of all the drag-and-drop events, the dragDrop event is the most commonly handled. Regardless of which of these events is handled, the code in the handler must do at least three things. It must first determine if it can accept the data format, and if so, it must then copy the data and optionally display it (or provide some user interface feedback that the data was dropped).
All data and information is passed in the event. This contains, among other fields, a data field and an effect field. The field contains an object that supports that has methods to retrieve the data and the data formats and to query for the existence of a specific format.
Therefore, the handler must first call method with a format it will accept and then determine whether it holds that data type. If so, it can then call the ****method (passing in that data type) and retrieve the data. How the data is displayed is up to that control. The following example illustrates an edit control dragDrop event handler that displays text data dropped to it.
private void txtFile_dragDrop(Object source, DragEvent e)
{
// If text is in the object, write it into the edit control.
if (e.data.getDataPresent(DataFormats.CF_TEXT))
{
String filename=(String)e.data.getData(DataFormats.CF_TEXT);
txtFile.setText(filename);
}
}